Skip to content

MCU wire protocol ​

The host ↔ MCU protocol lives in crates/protocol. The crate is no_std, allocation-free and forbid(unsafe_code), so the same message definitions and framing code run on the firmware, the virtual MCU and the host.

Framing ​

text
COBS( postcard(message) ‖ crc16_le ) ‖ 0x00
LayerPurpose
postcardCompact, versionable binary encoding of the message
CRC-16/CCITT-FALSEDetects corrupted frames. Polynomial 0x1021, init 0xFFFF, no reflection, no xorout; check value 0x29B1 for "123456789". Appended little-endian
COBSRemoves all zero bytes, so 0x00 can delimit frames and the receiver can resynchronise after garbage
ConstantValue
PROTOCOL_VERSION1 — bumped on any incompatible change
MAX_PAYLOAD224 bytes (message + CRC, before COBS)
MAX_AXES8 per MCU

The streaming decoder yields one result per delimiter: a message, or one of TooLarge, Cobs, Crc, Decode (intact frame that does not decode, e.g. a version mismatch) or Truncated. CRC failures are counted in telemetry as crc_errors.

Transports: USB CDC-ACM on the boards, TCP for the out-of-process simulator, and an in-process duplex for the in-process virtual MCU.

Host → MCU ​

Every host frame is HostFrame { seq: u32, msg: HostMsg }. seq increases monotonically and is echoed in Ack / Nack.

MessagePurposeIdempotent
IdentifyRequest Identityyes
ClockSync { host_time_us }Clock-sync probe → ClockSyncReplyyes
HeartbeatKeep-alive for the communication watchdogyes
SetWatchdog { timeout_ms }Configure the watchdogyes
ConfigureAxis(AxisConfig)Per-axis limits, max rate, stop deceleration, inversions. Rejected while the axis movesyes
Enable { axis } / Disable { axis }Drive enable; disable is immediate, no deceleration
QueueSegment(Segment)Append a motion segmentno — never blindly retransmitted
Home(HomeParams)Start homing → HomingDone
SetPosition { axis, steps }Overwrite the position of an idle axis
StopDiscard queue, decelerate at stop_decel; drives stay on
EmergencyStopHalt and disable all drives immediately; latch EmergencyStop
ResetFaultClear a latched fault. Never resumes motion; drives stay off
QueryStatusRequest an immediate Statusyes

AxisConfig (all in MCU units): axis, min_steps, max_steps, max_rate (hard step-rate ceiling, steps/s), stop_decel (steps/s²), invert_dir, invert_endstop. The engine sets max_rate to 105 % of max_velocity × steps_per_unit.

Segment and HomeParams are described in Motion pipeline.

MCU → host ​

McuFrame { seq: u32, msg: McuMsg }

MessageMeaning
Identityprotocol_version, firmware_version (major, minor, patch), target, board, build_hash (first 4 bytes), capabilities (bitmask), axes, queue_capacity
ClockSyncReply { host_time_us, mcu_time_us }Clock-sync answer
Ack { seq }Command accepted
Nack { seq, reason }Command refused: UnknownAxis, QueueFull, InvalidState, InvalidParams, SoftLimit, Faulted, Busy
Statusmcu_time_us, fault, queue_depth, and per axis: position_steps, velocity, enabled, moving, homing, endstop
Fault { code, axis }A fault latched: CommunicationLost, QueueUnderrun, SegmentLate, LimitHit, SoftLimit, HomingFailed, EmergencyStop, StepRateExceeded
HomingDone { axis, position_steps }Homing finished

Capability bits ​

BitName
1 << 0stepper.step_dir
1 << 1endstop
1 << 2watchdog
1 << 3encoder.quadrature
1 << 4gpio.input
1 << 5gpio.output
1 << 6servo.pwm

Connection sequence ​

text
host                                         MCU
 │── Identify ───────────────────────────────▶│
 │◀────────────────────────────── Identity ───│  check protocol version, board id, capabilities
 │── ClockSync × 8 ──────────────────────────▶│
 │◀────────────────────── ClockSyncReply × 8 ─│  keep the sample with the lowest RTT
 │── SetWatchdog ────────────────────────────▶│
 │── ConfigureAxis, SetPosition 0 (per axis) ▶│
 │◀─────────────────────────────────── Ack ───│
 │── Heartbeat every 100 ms ────────────────▶ │  engine: initializing → disabled

The engine refuses an MCU whose protocol version differs, whose board id differs from the configuration, or that lacks a capability the configuration requires.

Retry rules ​

  • Idempotent configuration messages may be retried.
  • Motion segments are never retransmitted. If an ACK times out (500 ms), the timeout surfaces as an error and the engine stops safely, rather than risk a duplicated segment.

Apache-2.0 OR MIT. Not a certified safety system — always use an independent hardware E-stop.