Host ↔ Teensy Protocol v1 — Working Spec

Status: draft scaffold. Cédric should finalize the exact wire format before implementation locks.

Philosophy

This is a setpoint/telemetry protocol, not G-code.

Requirements:

versioned frames;
length-delimited or COBS-delimited framing;
CRC-16 or CRC-32 on every frame;
deterministic parsing;
ACK/NACK for every command;
machine-readable NACK reason codes;
no text parsing in the control path.

Host → Teensy messages

HEARTBEAT
MANUAL_START
SETPOINT
MANUAL_STOP
SEGMENT_START
PAUSE
RESUME
ABORT
ESTOP

Teensy → Host messages

ACK
NACK
TELEMETRY
EVENT
SEGMENT_DONE
ABORT_COMPLETE

Spindle direction field

MANUAL_START, SETPOINT, and future SEGMENT_START payloads include spindle_direction / commanded_spindle_direction with stable values:

cw — clockwise
ccw — counter-clockwise

Physical convention: direction is observed from above the toolhead looking down toward the mirror/tool contact. The ODrive sign mapping is a commissioning item and must be configured so UI/protocol values match physical rotation. Direction changes are explicit setpoint changes; do not infer direction from a signed RPM. RPM remains a non-negative magnitude.

v1 production subset

Manual v1 only needs:

HEARTBEAT
MANUAL_START
SETPOINT
MANUAL_STOP
ACK / NACK
TELEMETRY
EVENT

But define and parse the future segment messages now so Phase 3 does not require a protocol reset.

Open protocol choices

JSON-lines, MessagePack, or compact binary structs?
CRC-16 vs CRC-32?
COBS framing vs length-prefix + CRC?
Serial baud rate and reconnect behavior?
Whether heartbeat is host-only or bidirectional?

Recommendation: choose the simplest robust format Cédric is comfortable debugging on the bench.

1.8 KiB Raw Blame History