Troubleshoot the controller link

The "controller link" is the serial cable between your agent (the computer running OctoMY™) and the microcontroller board that drives the actuators. When the Connect toggle in the agent's Runtime Status panel shows Connecting… and won't settle on Connected, this guide walks you through the most likely causes.

Quick reality check

The agent never gives up on the link while Connect is on. A blinking Connecting… toggle means we're still trying — every few seconds, in the background. If the underlying problem resolves (you plug the board back in, the firmware finishes booting, the USB driver recovers), the link will re-establish on its own. You don't have to click anything.

My controller says "Connecting…" — what now?

Open FixoRuntimeActivity (the runtime status detail view) and look at the event log. Every failed reconnection attempt produces a categorised entry there. The category code (A1, B4, etc.) tells you which class the problem belongs to:

• A — Pre-open: the operating system won't give us a usable serial port at all.
• B — Post-open: the port is ours but the firmware isn't answering the way we expect.
• C — Transient: a recoverable timing artefact; it resolves on the next attempt without any action from you.
• D — Configuration: a required setting (port, preset) is missing; nothing will happen until you fill it in.

Each tier is colour-coded in the log (amber for A, red for B, plain for C and D).

For the full enumeration see Controller link faults reference.

A1 — port "ttyACM0" not present

The device path you were connected to has disappeared from disk.

Causes:

1. USB unplugged. The most common one — check the cable.
2. Power-cycled board. Some boards re-enumerate as a new device node (e.g. /dev/ttyACM1 instead of /dev/ttyACM0) when they reboot. The agent waits for the new node to appear and re-connects automatically.
3. Kernel module missing. Rare — the AVR USB-serial driver (cdc-acm) ships with every modern Linux kernel. If your distro stripped it down, install the right kernel package.

The retry loop keeps probing in the background. As soon as the device node reappears, the link comes up.

A2 — permission denied opening "ttyACM0"

The device node is there but your user can't open it. On Linux, serial ports live in the dialout (Debian/Ubuntu) or uucp (Arch/Fedora) group; non-members get EACCES on open.

Fix:

sudo usermod -aG dialout "$USER"

Then log out and back in — group membership is picked up at login time. After the next login the agent picks up the link automatically.

A5 — failed to open "ttyACM0": …

A catch-all for OS-level open failures the agent can't classify more precisely. The message text is whatever the kernel returned. Common causes:

• Device or resource busy. Another process holds the port — often a stale instance of the agent itself, avrdude from a recent flash, or a terminal emulator. Kill the holder and the retry loop reconnects.
• I/O error. Cable jiggle, USB controller hiccup. Usually self-heals.

B1 — no reply from controller

The port is yours. The agent sent a PING but got nothing back.

Causes:

1. AVR mid-reset. Opening a Linux serial port pulses DTR, which the Arduino auto-reset circuit turns into a chip reset. The first probe after open is almost always B1; the next probe 1-2 seconds later usually succeeds. (Inside the boot window we log this as C1 instead — see below.)
2. No firmware. Brand-new board, or the flash got wiped. Re-flash via FixoStudio (the build/inject workflow).
3. Wrong baud rate. Almost never — we hard-code 115200. If you're using a custom firmware, double-check the baud rate matches.

B2 — received N bytes but no numex frame

We got bytes back, but they didn't parse as the numex protocol the agent speaks. Either the wrong firmware is on the board (someone flashed a different Arduino sketch), or the bytes are garbled.

Fix: flash the correct firmware via FixoStudio. The flash flow takes care of resetting + re-handshaking.

B6 — link to controller lost

The link was up — at least one previous probe succeeded — and then the port closed mid-session. Causes:

• USB cable jiggle.
• Laptop went to sleep / hibernate.
• Power glitch on the board (browned-out USB hub).

The retry loop kicks back in. Plug the cable in cleanly and the link comes back.

D1 — no port selected

The agent has a preset to drive, but no serial port to talk to over. Two paths:

1. Plug a board in. The agent's device detector spots new USB-serial nodes automatically and offers them.
2. Open FixoWizard. Step through the wizard to pick a board and confirm the port.

D2 — connect requested but no active preset

You toggled Connect on, but no preset is active yet — there's no firmware definition for the agent to flash + run. Open FixoStudio (or FixoWizard for a guided flow) and pick a preset.

When nothing else works

• Click Connect off, then on. Resets the retry counter and forces an immediate probe.
• Try a different USB cable. Charge-only cables don't carry data; you need a data cable.
• Try a different USB port. Some USB-3 controllers are flaky with low-speed devices.
• Reset the board manually. The reset button on the board forces a clean boot; the agent picks up the link on the next probe.

If you've worked through everything above and the link still won't come up, capture the last 30 seconds of the event log and file a bug. The categorised entries make it easy for us to see exactly which probe is failing and at which layer.