Controller link faults reference

When the serial link between the agent and the microcontroller board fails, every probe is classified into exactly one of the categories below. The category code appears in the FixoRuntimeActivity event log so you can recognise the failure class at a glance.

This page enumerates every category that the agent can produce. For a walkthrough on fixing these, see the Troubleshoot controller link how-to.

The agent never voluntarily abandons the link. As long as the Connect toggle is on, the retry loop keeps probing — every few seconds, indefinitely, with exponential backoff and jitter. A categorised fault is informational: it tells you why this probe failed, not that we've given up.

Tier A — Pre-open

The operating system refused to hand the agent a usable serial port. Coloured amber (Warning) in the event log.

A1 — No device

The path you target (e.g. /dev/ttyACM0) doesn't exist on disk.

• Cause: USB unplugged, board not enumerating, kernel module missing.
• Typical fix: plug the cable in. The agent picks the link up automatically once the path reappears.

A2 — Permission denied

The device node is there but your user account can't open it.

• Cause: missing membership in the OS group that owns serial devices.
• Typical fix (Linux): sudo usermod -aG dialout "$USER", then log out and back in.

A5 — I/O error (other)

Catch-all for any other OS-level open failure — driver bugs, hot-unplug races, "device or resource busy" (another process holds the port). The message text carries the kernel's errno string.

Tier B — Post-open

The agent owns the port; the firmware isn't speaking the expected protocol. Coloured red (Error).

B1 — No bytes

PING was written; zero bytes came back inside the response budget (default 500 ms).

• Common causes: AVR mid-reset (first probe after open), blank board, baud mismatch.
• Self-healing case: when the elapsed time since open is under ~2.2 s, this is reclassified as C1 (bootloader window).

B2 — Bytes received, no numex frame

Bytes came back, but they don't parse as the numex protocol the agent speaks.

• Cause: wrong firmware on the board (a foreign Arduino sketch), baud mismatch, or partial frame stuck in the middle of a write.
• Typical fix: flash the correct firmware via FixoStudio.

B3 — Numex protocol-version mismatch

The PONG frame parsed, but its version field disagrees with what the host supports. Usually happens after a half-completed OTA.

B4 — Config-hash mismatch

The firmware reports it's running content-hash X; the host expects Y. The link is up — actuator and sensor data still flow — but the firmware on the board doesn't match the active preset. The runtime status badge reads wrong firmware instead of Connected.

B5 — Firmware-reported error

The STATUS frame carries a non-zero error code (sensor init failed, missing lobe, watchdog triggered, etc.). The decoded error name appears in the log message.

B6 — Mid-session drop

The link was up — at least one previous probe succeeded — and then the port suddenly closed.

• Causes: USB unplugged mid-session, system suspend, cable jiggle, USB hub power glitch.

Tier C — Transient

Recoverable timing artefacts. Not user-actionable — they self-heal on the next probe. Coloured plain (Info).

C1 — Bootloader window

The first probe after port-open returned no bytes, and the elapsed time since open is under the ~2.2 s Optiboot window. This is the AVR's auto-reset behaviour after DTR pulse; the firmware hasn't finished booting yet. The next probe usually succeeds.

C2 — Slow reply

PONG arrived but the round-trip time exceeded the slow-reply threshold (default 250 ms). The link is healthy, just slow — often a USB-2 hub or a busy CPU. Sampled at most once per minute per (preset, hash) to keep the log readable.

Tier D — Configuration

Something is missing that the agent needs before it can probe at all. Coloured plain (Info). Tier-D faults emit once on entry and once on resolution — they don't coalesce.

D1 — No port selected

Connect is on, but no serial port is configured.

• Recovery: the device detector picks up new USB-serial nodes automatically; alternatively open FixoWizard to pick one.

D2 — No active preset

Connect is on, but no preset is active — there's no firmware to drive. Open FixoStudio (or FixoWizard) and pick a preset.

Coalescing

The retry loop produces many identical events while a fault persists. To keep the event log readable, identical (category, detail) pairs within a 30 s window collapse into a single ConnectionFaultCoalesced entry with a count and a duration:

[22:38:09] A  A1  port "ttyACM0" not present — is the controller plugged in?  (×7 in 23 s)

When the 30 s window closes without another same-key event, the counter resets; the next failure starts a fresh count=1 ConnectionFault entry.

When the link is healthy

The runtime status panel shows Connected; the event log gains periodic PingReplied rows (every successful PONG) and FirmwareReplied rows (sampled at most once per minute). The absence of category-prefixed A, B, C, or D rows for a sustained period is the canonical "all is well" signal.