docs: scaffold polisher-control foundation

docs/00-start-here.md

@@ -0,0 +1,33 @@
+# Start Here — Cédric Build Brief
+
+## Mission
+
+Build the machine-side control stack for the Fullum swing-arm polisher so Normand can run manual polishing sessions safely while producing clean telemetry for the rest of the software suite.
+
+## v1 priority order
+
+1. Safety/interlocks and deterministic state machine.
+2. Manual mode from the touchscreen / host UI.
+3. Stable host↔Teensy setpoint + telemetry protocol.
+4. KWR75B-CAN force/torque acquisition and stale-frame detection.
+5. Table/arm encoder acquisition and synchronized timestamps.
+6. ODrive spindle command/telemetry path.
+7. Run/manual logs and `/data/` file layout.
+8. Controller-job intake dry-run for future program execution.
+
+## Mental model
+
+The host says: "run these approved setpoints and log what happens."
+
+The Teensy says: "accepted/rejected, here is measured reality, here are events/faults."
+
+Neither side invents polishing strategy.
+
+## Ask Nick for
+
+- protocol notes;
+- firmware module breakdowns;
+- test checklists;
+- telemetry schema clarifications;
+- state-machine/safety edge cases;
+- concise implementation notes in `docs/nick-generated/`.

docs/01-ecosystem-boundaries.md

@@ -0,0 +1,48 @@
+# Ecosystem Boundaries
+
+## polisher-sim
+
+Owns planning intelligence:
+- metrology ingestion;
+- mirror state and residuals;
+- removal prediction;
+- dwell/preset planning;
+- calibration and uncertainty;
+- campaign reports.
+
+## polisher-post
+
+Owns translation and validation:
+- schema validation;
+- machine capability checks;
+- unit normalization;
+- segmentation;
+- packaging `controller-job.v1`;
+- run-log normalization back into analysis format.
+
+## polisher-control
+
+Owns machine execution:
+- state machine;
+- manual mode;
+- setpoint execution;
+- force loop interface;
+- telemetry;
+- alarms/interlocks;
+- pause/resume/abort;
+- run/manual-session logs;
+- operator workflow.
+
+## Shared contracts
+
+Own schemas and names that must not drift silently:
+- `controller-job.v1`;
+- `run-log.v1`;
+- `manual-session-log.v1`;
+- `machine-capabilities.v1`;
+- telemetry channel names;
+- event/alarm codes.
+
+## Boundary rule
+
+If you are about to add planning, optimization, calibration, or metrology interpretation to this repo, stop and ask Antoine. That likely belongs upstream.

docs/02-v1-scope.md

@@ -0,0 +1,30 @@
+# v1 Scope
+
+## In scope
+
+- Manual mode with live operator setpoints.
+- Full safety/interlock handling.
+- Host↔Teensy command/telemetry protocol.
+- KWR75B-CAN force/torque sensor integration.
+- Table and arm encoder acquisition.
+- ODrive S1 + M8325s spindle control/telemetry path.
+- Force actuator command path and tool-weight compensation.
+- Synchronized telemetry at >=100 Hz.
+- Manual-session logs and raw telemetry CSV.
+- USB SSD `/data/` storage layout.
+- `status.json` machine summary.
+- Controller-job validation path for future use.
+
+## Explicitly not in v1
+
+- Figuring strategy.
+- Metrology import/interpretation.
+- Calibration updates.
+- Autonomous optimization.
+- Powered Zero-G/admittance manipulation mode.
+- Remote control of the machine.
+- Multi-pass orchestration inside the controller.
+
+## First success condition
+
+A real manual polishing session can be run safely, and the resulting telemetry/logs are coherent enough for Antoine to analyze downstream.

docs/03-architecture.md

@@ -0,0 +1,64 @@
+# Architecture
+
+## Runtime split
+
+### Host controller — Python on RPi/PC
+
+Responsibilities:
+- operator workflow and manual-mode UI integration;
+- state machine orchestration;
+- controller-job intake validation;
+- geometry gate;
+- setpoint command stream;
+- telemetry capture;
+- logs, manifests, hashes, status file;
+- slow watchdogs and data export.
+
+### Teensy firmware — C++ on Teensy 4.x
+
+Responsibilities:
+- inner loop around ~1 kHz;
+- KWR75B-CAN F/T receive path;
+- encoder acquisition;
+- force PID output;
+- table/spindle/actuator command outputs;
+- fast safety checks;
+- heartbeat supervision;
+- telemetry frames at >=100 Hz;
+- ACK/NACK and event/fault frames.
+
+## State machine
+
+Current accepted state names:
+
+```text
+IDLE
+JOB_LOADED
+READY
+RUNNING
+PAUSED
+ABORTING
+COMPLETED
+ABORTED
+FAULTED
+MANUAL
+```
+
+Important rules:
+- `FAULTED` exits only through explicit operator reset.
+- `JOB_LOADED -> READY` requires operator acknowledge.
+- `IDLE -> MANUAL` is allowed only with no job loaded.
+- Illegal transitions are errors and events, never silent ignores.
+- Manual mode uses the same safety/interlocks as job mode.
+
+## Manual mode sequence
+
+1. Machine starts in `IDLE`.
+2. Operator opens Manual Mode.
+3. Host enforces the geometric gate.
+4. Host sends `MANUAL_START` to Teensy.
+5. Teensy ACKs or NACKs with a machine-readable reason.
+6. Host sends live `SETPOINT` updates.
+7. Teensy emits telemetry and events.
+8. Operator stops; host sends `MANUAL_STOP`.
+9. Host writes manual-session log and artifacts.

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

@@ -0,0 +1,60 @@
+# 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.

docs/05-telemetry-channel-spec-v1.md

@@ -0,0 +1,56 @@
+# Telemetry Channel Spec v1
+
+## Core channels — required at >=100 Hz
+
+```text
+timestamp_us
+table_angle_deg
+arm_angle_deg
+fz_n
+mx
+my
+mz
+spindle_rpm_actual
+table_rpm_actual
+arm_amplitude_deg_derived
+arm_center_deg_derived
+machine_state
+force_setpoint_n
+```
+
+## Strongly recommended channels
+
+```text
+fx_n
+fy_n
+ft_status
+z_servo_iq_v
+z_brake_engaged
+spindle_drive_state
+spindle_drive_error
+spindle_bus_voltage_v
+spindle_iq_a
+spindle_motor_temp_c
+arm_angle_linearized_deg
+table_rpm_setpoint
+spindle_rpm_setpoint
+force_actuator_cmd
+estop_active
+interlock_state
+mode
+fz_raw_n
+fz_contact_n
+```
+
+## Principles
+
+- One monotonic Teensy timestamp source.
+- Raw values, not only filtered values.
+- Commanded and actual values are both present.
+- Sensor validity is explicit; never substitute fake good values.
+- Gaps are detectable from timestamps.
+- Header names are stable because downstream analysis will depend on them.
+
+## CSV baseline
+
+First-write compatibility format is CSV. Later processing may produce Parquet/downsampled traces, but raw CSV must be preserved during commissioning.

docs/06-event-alarm-codes-v1.md

@@ -0,0 +1,46 @@
+# Event and Alarm Codes v1
+
+Status: draft canonical table for implementation.
+
+## Hard-stop faults — reset required
+
+- `ESTOP_ACTIVATED`
+- `FORCE_OVER_LIMIT`
+- `ENCODER_LOST`
+- `DRIVE_FAULT`
+- `FT_SENSOR_INVALID`
+
+## Recoverable pauses / warnings
+
+- `FORCE_UNDER_LIMIT`
+- `SPINDLE_RPM_DEVIATION`
+- `TABLE_RPM_DEVIATION`
+- `HOST_COMMS_TIMEOUT`
+- `ARM_GEOMETRY_DIVERGENCE`
+
+## Refused transitions / blocked starts
+
+- `GEOMETRY_NOT_VALIDATED`
+- `ARM_HANDLING_INTERLOCK`
+- `WRONG_ARTIFACT_TYPE`
+- `SCHEMA_VALIDATION_FAILED`
+- `WRONG_MACHINE_ID`
+- `CONTROLLER_VERSION_MISMATCH`
+- `UNSUPPORTED_CAPABILITY`
+- `ILLEGAL_TRANSITION`
+
+## Event fields
+
+Every event should include:
+
+```json
+{
+  "timestamp": "ISO-8601 or host monotonic mapping",
+  "code": "GEOMETRY_NOT_VALIDATED",
+  "severity": "info|warning|critical",
+  "state": "IDLE|MANUAL|...",
+  "detail": "short machine-readable or operator-readable detail"
+}
+```
+
+Do not use free text as the only control signal. Human messages are for UI; codes are for software.

docs/07-manual-mode-workflow.md

@@ -0,0 +1,32 @@
+# Manual Mode Workflow
+
+## Operator flow
+
+1. Hardware HOA selector in Auto.
+2. Machine in `IDLE`.
+3. Operator selects Manual Mode.
+4. UI presents the geometric gate:
+   - `r_menante`
+   - `L_menee`
+   - `R_tool`
+   - configured arm amplitude
+   - configured arm center
+5. Operator confirms values.
+6. Operator enters setpoints:
+   - force N
+   - table RPM
+   - spindle RPM
+   - optional force modulation harmonic/amplitude/phase
+7. Operator presses Start.
+8. Host sends `MANUAL_START`.
+9. Operator may adjust setpoints live.
+10. Operator presses Stop.
+11. Host writes the manual-session log, telemetry CSV, events, manifest, and status.
+
+## Hard rules
+
+- Manual mode cannot start with stale geometry.
+- Manual mode uses the same safety/interlocks as job mode.
+- Every setpoint change is logged.
+- Telemetry always runs while force/motion is active.
+- Tool removal uses the documented mechanical sequence; no powered Zero-G in v1.

docs/08-commissioning-checklist.md

@@ -0,0 +1,45 @@
+# Commissioning Checklist
+
+## Bench — no machine motion
+
+- [ ] Host can open serial link to Teensy.
+- [ ] HEARTBEAT / ACK / NACK verified.
+- [ ] Bad CRC/frame rejected with NACK or ignored safely.
+- [ ] State machine illegal transitions logged.
+- [ ] Telemetry frames parse at expected rate.
+
+## Sensor bring-up
+
+- [ ] KWR75B-CAN isolated CAN wiring verified.
+- [ ] CAN bit rate confirmed.
+- [ ] Vendor frame map decoded into Fx/Fy/Fz/Mx/My/Mz/status.
+- [ ] F/T stale-frame watchdog tested.
+- [ ] Table encoder angle stable and monotonic.
+- [ ] Arm encoder angle stable.
+
+## Drive bring-up
+
+- [ ] ODrive runtime interface selected and documented.
+- [ ] ODrive enable/disable/fault reset path verified.
+- [ ] Spindle RPM command and actual feedback verified.
+- [ ] Z force actuator command path verified with safe limits.
+- [ ] Brake engaged feedback verified if installed.
+
+## Safety
+
+- [ ] E-stop hard circuit tested independent of software state.
+- [ ] Force over-limit response tested.
+- [ ] Encoder-loss response tested.
+- [ ] Drive-fault response tested.
+- [ ] Host timeout -> pause -> abort behavior tested.
+- [ ] FAULTED requires explicit reset.
+
+## Manual run
+
+- [ ] Geometric gate blocks stale/missing geometry.
+- [ ] Manual start succeeds after valid geometry.
+- [ ] Force/table/spindle setpoints ramp smoothly.
+- [ ] Live setpoint changes are logged.
+- [ ] Telemetry CSV has required header and >=100 Hz samples.
+- [ ] Manual-session log includes setpoint history and actual summary.
+- [ ] Artifacts are saved under `/data/manual/{session_id}/`.

docs/09-acceptance-checklist.md

@@ -0,0 +1,53 @@
+# Acceptance Checklist
+
+This checklist condenses the current P11 firmware/control spec for implementation tracking.
+
+## Input contract
+
+- [ ] Accepts `controller-job.v1` only.
+- [ ] Rejects `job.v1` and malformed input.
+- [ ] Runs 4-gate intake validation.
+- [ ] Rejects wrong `machine_id`.
+- [ ] Rejects incompatible `controller_version` or unsupported capability.
+
+## Execution
+
+- [ ] Sequential segment execution exists for future job mode.
+- [ ] Force PID tracks setpoint within agreed commissioning tolerance.
+- [ ] Force modulation uses live table encoder angle.
+- [ ] Table and spindle RPM follow commands.
+- [ ] Pause time excluded from segment polishing time.
+
+## Telemetry
+
+- [ ] Core channels logged at >=100 Hz.
+- [ ] Single monotonic timestamp source.
+- [ ] Commanded and actual values both present.
+- [ ] Sensor faults are detectable.
+- [ ] CSV parseable by standard tools.
+
+## State machine and safety
+
+- [ ] All accepted states/transitions implemented.
+- [ ] Illegal transitions logged.
+- [ ] Operator acknowledge cannot be bypassed.
+- [ ] E-stop all-stop independent of software state.
+- [ ] Interlocks implemented with documented thresholds.
+- [ ] Watchdog timeout causes pause, then abort.
+- [ ] `FAULTED` exits only through explicit reset.
+
+## Manual mode
+
+- [ ] `MANUAL` reachable from `IDLE`.
+- [ ] Live setpoint adjustment works.
+- [ ] Geometric gate blocks stale geometry.
+- [ ] Setpoint changes are timestamped events.
+- [ ] Manual-session log emitted on exit.
+- [ ] Safety behavior identical to job mode.
+
+## Data
+
+- [ ] `/data/manual/{session_id}/` and `/data/runs/{run_id}/` layouts respected.
+- [ ] `status.json` maintained.
+- [ ] Hashes/manifests emitted.
+- [ ] Raw telemetry preserved during commissioning.

docs/10-open-questions-for-cedric.md

@@ -0,0 +1,28 @@
+# Open Questions for Cédric
+
+## Table interface
+
+- Confirm KBSI-240D opto-isolated interface or replacement.
+- Confirm table encoder transport and transceiver.
+- Confirm whether the table drive or command path changes electrically.
+
+## Spindle / ODrive
+
+- Define ODrive runtime command and telemetry path; CAN 2.0B at 1 Mbps is preferred unless replaced.
+- Define command scaling for velocity, enable/disable, fault reset, and safe stop.
+- Define telemetry subset: actual RPM, drive state/error, DC bus voltage, q-axis current, motor temperature if available.
+- Export final ODrive config with release.
+- Define spindle enable/fault I/O into HOA + safety chain.
+
+## Z-axis / force actuator
+
+- Confirm SV2A-2150 torque/current command mode and scaling.
+- Confirm enable/fault wiring and Iq/current monitor path.
+- Define Z limit-switch / hard-stop wiring into safety chain.
+- Define NC 24 VDC brake coil driver and brake-engaged diagnostic feedback.
+
+## Cross-cutting
+
+- Select safety relay model.
+- Confirm KWR75B-CAN frame map, byte order, scaling, status bits, and update rate.
+- Confirm final serial/protocol wire format.

docs/nick-generated/2026-05-26-polisher-control-foundation.md

@@ -0,0 +1,37 @@
+---
+title: Polisher-Control Repository Foundation
+status: draft
+requested_by: Antoine Letarte
+generated_by: Nick / Hermes
+project: P11-Polisher-Fullum
+repo: polisher-control
+source_truth: false
+created: 2026-05-26
+privacy: technical-only
+---
+
+# Polisher-Control Repository Foundation
+
+## Purpose
+
+Give Cédric a clean starting point for the machine-side control implementation without mixing in upstream planning or private project context.
+
+## What to build first
+
+1. Host↔Teensy protocol and ACK/NACK behavior.
+2. State machine and illegal-transition tests.
+3. KWR75B-CAN receive path and F/T validity/stale-frame watchdog.
+4. Manual mode with geometric gate.
+5. Telemetry CSV and manual-session log.
+6. Safety interlock behavior.
+
+## Key instruction
+
+Manual mode is not a throwaway mode. Manual telemetry is the calibration dataset for the entire future digital-twin loop. Keep channel names, timestamps, setpoint history, and force/angle data stable from the start.
+
+## Acceptance checks
+
+- [ ] Normand can run manual mode safely.
+- [ ] Every session produces telemetry and a manual-session log.
+- [ ] Every fault or rejected command is visible as an event/alarm.
+- [ ] The controller never invents polishing strategy.

docs/nick-generated/README.md

@@ -0,0 +1,15 @@
+# Nick-Generated Notes
+
+This folder is for source-grounded technical notes Nick generates for Cédric.
+
+Rules:
+- technical-only;
+- no invoices/rates/private context/secrets;
+- mark generated notes `source_truth: false`;
+- if a note changes architecture, safety, telemetry contracts, protocol semantics, or v1 scope, ask Antoine before treating it as accepted.
+
+Suggested filename:
+
+```text
+YYYY-MM-DD-short-topic.md
+```

docs/reference/source-map.md

@@ -0,0 +1,17 @@
+# Source Map
+
+This repo foundation is derived from the current P11 / Fullum polisher-control planning context.
+
+Primary source documents:
+
+- Fullum Polisher — Machine Control & Firmware Specification v1
+- Controller / Bridge / Digital Twin Architecture Plan
+- polisher-control — System Definition
+- polisher-control — Roadmap
+- Polisher Software Suite index and shared schema bundle
+
+Source-truth rule:
+
+- These repo docs are implementation aids.
+- Approved P11 source specs and schemas outrank generated summaries.
+- If anything here conflicts with a source spec, ask Antoine before changing technical direction.