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`

## 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.