Polisher-Control/docs/LLM_CONTEXT.md

title, status, requested_by, generated_by, project, repo, source_truth, created, privacy

title	status	requested_by	generated_by	project	repo	source_truth	created	privacy
Polisher-Control LLM Context Pack	draft	Antoine Letarte	Nick / Hermes	P11-Polisher-Fullum	polisher-control	false	2026-06-02	technical-only

Polisher-Control LLM Context Pack

Purpose

This file is the first prompt/context file to give to Cédric's LLM or coding assistant when working in this repository.

It condenses the approved technical direction for polisher-control into one implementation-oriented context pack. It is an aid for coding and design discussions, not the authority itself.

If this file conflicts with the source specs or with Antoine's explicit direction, stop and ask Antoine before changing architecture, telemetry contracts, safety behavior, or v1 scope.

Scope / non-scope

In scope for polisher-control

polisher-control is the machine-side execution layer. It owns:

• Teensy firmware and hard-real-time loop.
• Raspberry Pi / host controller and touchscreen/manual workflow.
• Host ↔ Teensy protocol.
• Force setpoint execution and closed-loop Fz control.
• Table/spindle/arm-drive command interfaces.
• KWR75B-CAN force/torque acquisition.
• ODrive S1 + M8325s spindle integration.
• State machine, pause/resume/abort, faults, alarms, interlocks.
• Telemetry, event logs, manual-session logs, run artifacts, and /data/ layout.
• Conservative machine capability descriptor.

Explicitly out of scope

Do not implement or infer:

• Optical figuring strategy.
• Interferometer/metrology interpretation.
• Dwell-map optimization or pass planning.
• Preston coefficient calibration or learning logic.
• Autonomous correction decisions.
• Controller-side replanning.
• Silent mutation of upstream setpoints.
• Remote control of the machine without a physically present operator.

Core rule: the controller executes approved setpoints safely; it does not decide polishing strategy.

Source references

Use repo docs first for implementation, then the source specs if there is ambiguity.

Repo implementation docs

• README.md — repository overview and v1 finish line.
• AGENTS.md — repo rules for LLM/coding agents.
• ROADMAP.md — implementation roadmap.
• docs/00-start-here.md — Cédric build brief.
• docs/01-ecosystem-boundaries.md — polisher-sim / polisher-post / polisher-control split.
• docs/02-v1-scope.md — v1 delivery boundary.
• docs/03-architecture.md — host/firmware architecture, state machine, safety posture.
• docs/04-host-teensy-protocol-v1.md — protocol requirements and message set.
• docs/05-telemetry-channel-spec-v1.md — telemetry channels and rates.
• docs/06-event-alarm-codes-v1.md — event/alarm codes.
• docs/07-manual-mode-workflow.md — touchscreen manual workflow.
• docs/08-commissioning-checklist.md — bring-up checklist.
• docs/09-acceptance-checklist.md — pass/fail criteria.
• docs/10-open-questions-for-cedric.md — implementation questions to close.
• shared/schemas/*.schema.json — contract schemas mirrored into this repo.
• shared/machine/fullum-alpha.capabilities.v1.json — draft capability profile.

Upstream source-truth docs

These live in Antoine's P11 project vault and outrank this generated context pack:

• /home/papa/obsidian-vault/2-Projects/P11-Polisher-Fullum/_curation/CONTEXT.md
• /home/papa/obsidian-vault/2-Projects/P11-Polisher-Fullum/README.md
• /home/papa/obsidian-vault/2-Projects/P11-Polisher-Fullum/software-suite/control/firmware/Fullum-Polisher-Machine-Control-Firmware-Spec-v1.md
• /home/papa/obsidian-vault/2-Projects/P11-Polisher-Fullum/05-Implementation/Controller-Bridge-Digital-Twin-Architecture-Plan.md
• /home/papa/obsidian-vault/2-Projects/P11-Polisher-Fullum/05-Implementation/Polisher-Control/00-Polisher-Control-System.md
• /home/papa/obsidian-vault/2-Projects/P11-Polisher-Fullum/05-Implementation/Polisher-Control/01-Polisher-Control-Roadmap.md

Architecture summary

polisher-sim
  planning / digital twin / metrology / calibration / process intelligence
        ↓
polisher-post
  validation / machine-capability checks / controller-job packaging / log import
        ↓
polisher-control
  safe deterministic machine execution / telemetry / operator workflow
        ↓
run logs + manual telemetry return upstream for analysis and calibration

polisher-sim

Owns the question: what should be done next?

It may ingest interferometer maps, model removal, plan passes, estimate uncertainty, calibrate machine-specific behavior, and produce frozen job packages. It must not drive hardware directly.

polisher-post

Owns the question: how do we express the approved plan safely for this machine?

It validates schemas, checks machine capabilities, normalizes units, records translation losses, and emits controller-safe controller-job.v1 packages.

polisher-control

Owns the question: how do we execute these approved setpoints safely now?

It runs the machine, enforces safety, records exact reality, and exports artifacts. It must be boring, predictable, auditable, and conservative.

v1 finish line

The v1 finish line is:

Normand can operate the polisher manually from the touchscreen, producing clean synchronized telemetry, with safety enforced.

Program execution exists as a contract scaffold and future path, but the v1 production surface is manual operation.

v1 priority order

1. Safety/interlocks and deterministic state machine.
2. Manual mode from touchscreen / host UI.
3. Stable host ↔ Teensy setpoint and telemetry protocol.
4. KWR75B-CAN force/torque acquisition and stale-frame detection.
5. Table/arm encoder acquisition and synchronized timestamps.
6. ODrive S1 + M8325s spindle command/telemetry path.
7. Run/manual logs and /data/ file layout.
8. Controller-job intake dry-run for future program execution.

v1 must include

• MANUAL state reachable from IDLE only.
• Operator live controls for force, table RPM, spindle RPM, spindle rotation direction (cw/ccw), and optional force modulation.
• Mandatory geometric gate before MANUAL or RUNNING.
• Full telemetry at ≥100 Hz with a single Teensy monotonic timestamp source.
• Manual-session log emitted on exit.
• Same safety/interlocks in manual mode as job mode.
• KWR75B-CAN sensor status and stale-frame watchdog.
• Tool-weight compensation using a configured fz_tool_weight_offset_n.
• Mechanical safe-removal workflow for the tool/head.

v1 must not include unless Antoine explicitly reopens it

• Powered Zero-G / admittance manipulation mode.
• Controller-side optical strategy.
• Controller-side calibration/learning.
• Remote control of the machine.
• Autonomous multi-pass orchestration.
• Metrology import/interpretation in the controller.

Hardware basis to preserve

These are current project facts unless Antoine/source specs supersede them:

• Real-time controller: Teensy 4.1.
• Host: Raspberry Pi 4 + touchscreen.
• Primary process force sensor: Kunwei KWR75B-CAN, dedicated CAN link to Teensy through isolated transceiver.
• Table encoder: RLS Artos DHR 162 mm, 20-bit absolute, SSI/RS422 basis.
• Arm encoder: RLS Orbis BR10, 14-bit absolute, SSI/RS422 basis.
• Spindle: ODrive S1 + M8325s 100KV, v1 velocity control, CAN 2.0B at 1 Mbps preferred.
• Z/force actuator: counterweight-biased AutomationDirect SV2L-210B servo with SV2A-2150 drive, torque/current mode to confirm.
• Z brake: NC 24 VDC electromagnetic brake; engages on E-stop or power loss.
• Safety relay: Pilz PNOZ X1 or Banner XS26-2 still needs final selection.
• Powered Zero-G is not part of v1.

State machine context

Required states:

• IDLE
• JOB_LOADED
• READY
• RUNNING
• PAUSED
• ABORTING
• COMPLETED
• ABORTED
• FAULTED
• MANUAL

Rules:

• FAULTED exits only through explicit operator reset.
• Illegal transitions are rejected and logged.
• Every transition emits an event.
• JOB_LOADED → READY requires explicit operator acknowledge.
• IDLE → MANUAL requires the geometric gate.
• Cannot enter MANUAL with a job loaded.
• Cannot load a job while in MANUAL.
• A fault in MANUAL transitions to FAULTED.

Manual mode workflow

Shop-floor sequence:

1. Hardware HOA selector in Auto so Teensy/RPi are active.
2. Operator mechanically sets arm amplitude and center on the machine.
3. Operator opens Manual Mode on touchscreen.
4. UI presents mandatory geometric gate for:
   • r_menante
   • L_menee
   • R_tool
   • configured_arm_amplitude_deg
   • configured_arm_center_deg
5. Operator confirms each value; no skip path.
6. Operator enters initial force, table RPM, spindle RPM, spindle rotation direction (cw/ccw), optional modulation.
7. Host sends MANUAL_START; Teensy ACK/NACKs.
8. Telemetry begins at ≥100 Hz.
9. Operator adjusts live setpoints; each change is logged as an event.
10. Operator presses Stop; host sends MANUAL_STOP.
11. Machine ramps down, returns to IDLE, and writes manual-session-log.v1 + telemetry CSV.

Telemetry contract

Principles

• One monotonic Teensy clock anchors all telemetry.
• Raw values are logged; filtering/analysis happens upstream.
• Commanded/setpoint and actual/measured values stay distinct.
• Sensor faults are explicit: validity flags, NaN, sentinel, or event/alarm.
• Missing samples must be detectable from timestamps.
• Header/channel names must remain stable; future tools will key off them.

Core required channels at ≥100 Hz

• 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

Strongly recommended channels

• 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
• force_setpoint_n
• table_rpm_setpoint
• spindle_rpm_setpoint
• spindle_direction_setpoint
• spindle_direction_actual
• force_actuator_cmd
• estop_active
• interlock_state
• mode

Host ↔ Teensy protocol context

The protocol is a setpoint/telemetry protocol, not G-code.

Host → Teensy messages

• HEARTBEAT
• SEGMENT_START
• SETPOINT
• PAUSE
• RESUME
• ABORT
• MANUAL_START
• MANUAL_STOP
• ESTOP

Teensy → Host messages

• ACK
• NACK
• TELEMETRY
• EVENT
• SEGMENT_DONE
• ABORT_COMPLETE

Protocol requirements

• Version on every frame.
• Robust framing; do not rely on timing gaps.
• CRC-16 or CRC-32 on every frame.
• Every host command receives ACK or NACK.
• NACK reason is machine-readable, not free text only.
• Deterministic parsing; no UI text parsing in the firmware protocol.
• Safety messages bounded-latency and robust to single-frame loss.

Safety/interlock context

Safety is layered:

• Hardware safety: E-stop circuit, safety relay, brake, drive enables. Independent of software.
• Teensy fast safety: force limits, encoder loss, F/T sensor stale/invalid, drive faults, watchdog response.
• Host slow safety: state integrity, RPM deviations, segment/manual session orchestration, logging, UI gates.

Hard-stop faults include:

• ESTOP_ACTIVATED
• FORCE_OVER_LIMIT
• ENCODER_LOST
• DRIVE_FAULT
• FT_SENSOR_INVALID

Warnings/recoverable pauses include:

• FORCE_UNDER_LIMIT
• SPINDLE_RPM_DEVIATION
• TABLE_RPM_DEVIATION
• HOST_COMMS_TIMEOUT

Refused transition / gate reasons include:

• GEOMETRY_NOT_VALIDATED
• ARM_HANDLING_INTERLOCK if final lock/cam-nut feedback exists.

Force control and tool handling

• Force PID closes on the compensated contact force path.
• Store fz_tool_weight_offset_n for the installed tool/head configuration.
• Keep raw force available for diagnostics as fz_raw_n where practical.
• Compute compensated contact force as:

fz_contact_n = fz_raw_n - fz_tool_weight_offset_n

• If only one canonical force channel is emitted, document that fz_n means compensated contact force and include the offset in session/run metadata.
• Do not implement a powered Zero-G state in v1.

Mechanical safe tool-removal workflow:

1. Stop active manual/job operation.
2. Command force to zero and stop table, spindle, and arm drive.
3. Confirm compensated force is near zero.
4. Confirm machine is in IDLE or stopped manual condition.
5. Engage/verify swing arm or arc mechanical lock.
6. Remove cam arm nut to free arm rotation.
7. Move arm aside by hand.
8. Remove tool from blank by hand.
9. Reinstall/seat tool, restore mechanical configuration, and rerun the geometric gate before software-controlled motion.

Run artifacts and data layout

Write run data to USB SSD, not the RPi SD card.

Baseline layout:

/data/
├── runs/
│   └── run-*/
│       ├── run-log.v1.json
│       ├── telemetry.csv
│       ├── telemetry-derived.parquet
│       ├── segment-stats.json
│       ├── dwell-map.npz
│       ├── work-map.npz
│       ├── anomaly-windows/
│       └── manifest.json
├── manual/
│   └── manual-*/
│       ├── manual-session-log.v1.json
│       ├── telemetry.csv
│       ├── telemetry-derived.parquet
│       ├── segment-stats.json
│       ├── dwell-map.npz
│       ├── work-map.npz
│       └── manifest.json
├── capabilities/
│   └── machine-capabilities.v1.json
└── status.json

For v1 hardware proving, raw full-rate telemetry, run/manual logs, stable filenames, and hashes are mandatory. Derived artifacts may begin as a simple post-run routine but should follow the contract from the start.

Feature request workflow for Antoine/Cédric

When Antoine says he wants to add a feature to polisher-control, classify it before coding:

1. Execution feature — belongs here if it changes host state machine, protocol, firmware, manual workflow, telemetry, safety, or run artifacts.
2. Contract feature — may require parallel changes in shared/schemas, polisher-post, and possibly polisher-sim.
3. Planning/intelligence feature — probably belongs upstream in polisher-sim or polisher-post, not here.
4. Safety/scope feature — requires Antoine approval before implementation if it changes interlocks, limits, fault behavior, telemetry schema, protocol semantics, or v1 scope.

For each proposed feature, capture:

• requested behavior;
• operator-visible behavior;
• affected layers: host / Teensy / protocol / telemetry / schemas / docs / tests;
• safety implications;
• acceptance checks;
• open questions for Antoine or Cédric.

Use docs/11-feature-request-intake.md as the template.

Open implementation questions to keep visible

Current control/firmware-facing questions include:

• Confirm KBSI-240D / table drive command path or replacement.
• Confirm table encoder transport and transceiver choice.
• Define ODrive runtime command/telemetry path, scaling, fault reset, safe stop, and config export.
• Confirm SV2A-2150 torque/current command mapping, enable/fault wiring, current/Iq monitor path.
• Confirm Z limit-switch / hard-stop wiring into safety chain.
• Confirm NC brake coil driver and brake-engaged diagnostic feedback.
• Select safety relay model.
• Confirm KWR75B-CAN frame map, byte order, scaling, status bits, and update rate.

Acceptance mindset

A change is not done because code exists. It is done when the relevant acceptance checks pass:

• state transition tests;
• protocol encode/decode/ACK/NACK tests;
• schema/example validation;
• telemetry channel consistency checks;
• safety gate refusal tests;
• host-side log artifact tests;
• firmware compile/build checks where hardware-specific code is touched;
• commissioning checklist item if hardware integration is involved.

Keep code boring. Prefer explicit rejection over silent assumptions.