Polisher-Control/docs/04-host-teensy-protocol-v1.md

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

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.