Polisher-Control/README.md

# Polisher-Control

Machine-side execution stack for the Fullum / GigaBIT swing-arm polisher.

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:

```text
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;
- CubeMars AK60-6 V1.1 KV80 spindle actuator 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

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

## Repository map

```text
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. Source-refresh: 2026-07-06 for Raspberry Pi 5, AK60, and ordered BiSS-C encoders. 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.