Fixo Controller

Reference for the Fixo controller, which compiles robot hardware configuration into purpose-built firmware via embedded LLVM/Clang.

Design Note

Fixo firmware contains zero runtime configuration overhead: no config parser, no dynamic arrays, no type dispatch. Every actuator type, pin number, and sensor configuration is a compile-time constant. The optimizer eliminates all dead code paths, producing the smallest and fastest possible binary for the exact hardware configuration.

Overview

Fixo is the controller in OctoMY™. It bakes the entire hardware configuration into firmware as C++ template parameters and compiles it via embedded LLVM/Clang. The earlier runtime-config path (Fluxo / ArduMY) and Servotor32 binding were retired in 2026.

The trade-off is a rebuild+reflash cycle on every configuration change — acceptable because LLVM compilation takes seconds and the flash cycle is approximately 5 seconds for a typical binary.

See Why Fixo for the design rationale, and the Fixo data model for the type vocabulary used below (FixoPreset, FixoStanza, FixoActuatorType, etc.).

Supported hardware

Compilation backends

The harness backend compiles the same template code but links against Qt stubs instead of AVR register code. Virtual servos, motors, and sensors appear as widgets in the controller UI.

Actuator types

Fixo supports the same actuator types as Actuators:

Each actuator can optionally declare additional pins for limit switches, incremental encoders, tachometers, and position feedback sensors.

Sensor types

Lobes

Fixo compiles lobe logic directly into the firmware as C++ template code. Built-in lobes:

Each FixoLobeType carries a placement capability — board-only, native-only, or both — that determines whether the lobe runs in the firmware (compiled into the AVR ELF) or on the node (loaded from the matched native .so via dlopen). See the Lobes reference for placement details and the per-lobe input/output port lists.

Capabilities

FixoController declares the following capability flags:

Build workflow

FixoRuntime (see the FixoRuntime reference) drives the build / inject / start lifecycle. Triggers:

Build pipeline

1. Source generation — FirmwareGenerator::generateFromPreset() synthesises C++ source from the active FixoPreset.
2. Compilation — FixoBuildManager invokes the embedded LLVM/Clang to produce both an AVR ELF (board-side) and a native .so (node-side).
3. Size check — FirmwareSizeInfo validates that the AVR ELF fits in the target board's flash.
4. Cache — FixoFirmwareCache content-addresses the compiled artefacts by BLAKE3 hash so unchanged presets don't recompile.
5. Inject — FirmwareFlasher writes the AVR ELF to the board via stk500v2 over serial.
6. Load — FirmwareRuntime dlopens the native .so (when present) into the Agent process; the runtime opens the numex serial link and starts ticking the firmware.

Firmware size visualization

The preset editor exposes a live size bar driven by FirmwareSizeInfo:

Configuration persistence

Fixo configuration lives in fixo.json files, not in the legacy fixo/* agent settings. See the Fixo Books reference for how presets, types, and templates are stored, and the fixo.json schema reference for the file format.

A typical layout:

<personality>/fixo/
  presets/
    rc-car.fixo.json
    hexy-explorer.fixo.json
  actuator-types/   # custom types (built-ins live in libfixo's qrc)
  sensor-types/
  lobe-types/
  stanza-templates/
  preset-templates/

Files are discovered recursively by FixoLibrary::scan(); routing by fixoType field places each into the matching Fixo*Book.

UI surface

Fixo's UI lives in the Fixo Studio activity (see the Fixo Studio reference). The Studio is the entry point for:

• Preset Manager — list / create / duplicate / import / export presets, plus the From template wizard
• Preset Editor — edit a preset's actuators, sensors, stanzas, board
• Type managers — actuator / sensor / lobe / board / stanza-template / preset-template
• Type editors — open a type for inline pin / source / placement editing

The retired multi-screen "BoardSelect → Configure → Build → Dashboard" widget has been replaced by the Studio + a per-preset FixoRuntime view. The Studio runs on Hub, Agent, or Remote (each node can author and share presets); only "set as active runtime" is Agent-specific.

Source code