This repository is for Cédric's implementation work on the controller, firmware, manual-mode UI support, telemetry, safety/interlocks, and run artifacts. It is aligned with the broader Polisher Software Suite:

polisher-sim   -> planning / digital twin / calibration / metrology intelligence
polisher-post  -> validation + packaging of controller-safe jobs
polisher-control -> safe machine execution + telemetry + operator workflow
shared contracts -> schemas, logs, machine capabilities, provenance

v1 finish line

Normand can operate the polisher manually from the touchscreen, with:

safe force/table/spindle control, including clockwise/counter-clockwise toolhead rotation selection;
KWR75B-CAN force/torque sensor integration;
ODrive S1 + M8325s spindle drive integration;
Teensy-side fast safety and setpoint/telemetry loop;
host-side state machine, logs, status, and data export;
synchronized telemetry at >=100 Hz;
manual-session logs usable by polisher-sim / polisher-post later;
safety/interlocks enforced and visible in logs.

What this repo must NOT become

polisher-control does not own optical strategy. It must not interpret interferograms, optimize polishing passes, learn calibration parameters, or invent correction programs. Those decisions belong upstream in polisher-sim and polisher-post.

The controller should be boring, deterministic, auditable, and conservative.

Start here

Read docs/LLM_CONTEXT.md if you are Cédric's LLM/coding assistant or need a compact project brief.
Read docs/00-start-here.md.
Read docs/02-v1-scope.md.
Review the state machine and safety rules in docs/03-architecture.md.
Use docs/11-feature-request-intake.md before adding new features.
Use docs/08-commissioning-checklist.md during hardware bring-up.
Track implementation using ROADMAP.md.

Repository map

firmware/teensy/        Teensy 4.1 firmware scaffold and protocol/telemetry structs
host/                   Python host-controller scaffold for RPi/PC side
shared/schemas/         Contract schemas mirrored from the current software suite
shared/machine/         Fullum-alpha machine capability profile draft
docs/                   Cédric-facing implementation docs and checklists
docs/nick-generated/    Nick-generated source-grounded guidance notes
scripts/                Utility/validation scripts
tests/                  Host-side contract/state-machine tests

Current source alignment

Generated: 2026-05-26. This foundation is a repo scaffold and implementation aid, not a replacement for the approved P11 source specifications. If this repo and the source specs disagree, ask Antoine before changing architecture, safety, telemetry contracts, or scope.