70 lines
1.8 KiB
Markdown
70 lines
1.8 KiB
Markdown
# 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.
|