Antoine/Polisher-Control
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add spindle direction selection contract

Browse Source
This commit is contained in:
Nick Hermes
2026-06-02 15:40:16 +00:00
parent 02d9323c43
commit beeb521ca7
21 changed files with 689 additions and 133 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/04-host-teensy-protocol-v1.md
View File

@@ -36,6 +36,15 @@ Requirements:
- `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:

3
docs/05-telemetry-channel-spec-v1.md
View File

@@ -34,6 +34,8 @@ spindle_motor_temp_c
arm_angle_linearized_deg
table_rpm_setpoint
spindle_rpm_setpoint
spindle_direction_setpoint
spindle_direction_actual
force_actuator_cmd
estop_active
interlock_state
@@ -50,6 +52,7 @@ fz_contact_n
- 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.
- Spindle RPM remains a non-negative magnitude; spindle direction is logged separately as `cw` / `ccw` rather than encoded as signed RPM.
## CSV baseline

3
docs/07-manual-mode-workflow.md
View File

@@ -16,6 +16,7 @@
- force N
- table RPM
- spindle RPM
- spindle rotation direction: clockwise (`cw`) or counter-clockwise (`ccw`) as viewed from above the toolhead looking down toward the mirror/tool contact
- optional force modulation harmonic/amplitude/phase
7. Operator presses Start.
8. Host sends `MANUAL_START`.
@@ -27,6 +28,6 @@
- Manual mode cannot start with stale geometry.
- Manual mode uses the same safety/interlocks as job mode.
- Every setpoint change is logged.
- Every setpoint change is logged, including spindle direction changes.
- Telemetry always runs while force/motion is active.
- Tool removal uses the documented mechanical sequence; no powered Zero-G in v1.

3
docs/09-acceptance-checklist.md
View File

@@ -16,6 +16,7 @@ This checklist condenses the current P11 firmware/control spec for implementatio
- [ ] Force PID tracks setpoint within agreed commissioning tolerance.
- [ ] Force modulation uses live table encoder angle.
- [ ] Table and spindle RPM follow commands.
- [ ] Toolhead spindle direction follows clockwise/counter-clockwise operator/job selection and is logged explicitly.
- [ ] Pause time excluded from segment polishing time.
## Telemetry
@@ -39,7 +40,7 @@ This checklist condenses the current P11 firmware/control spec for implementatio
## Manual mode
- [ ] `MANUAL` reachable from `IDLE`.
- [ ] Live setpoint adjustment works.
- [ ] Live setpoint adjustment works for force, table RPM, spindle RPM, spindle direction, and optional modulation.
- [ ] Geometric gate blocks stale geometry.
- [ ] Setpoint changes are timestamped events.
- [ ] Manual-session log emitted on exit.

6
docs/LLM_CONTEXT.md
View File

@@ -141,7 +141,7 @@ Program execution exists as a contract scaffold and future path, but the v1 prod
### v1 must include
- `MANUAL` state reachable from `IDLE` only.
- Operator live controls for force, table RPM, spindle RPM, and optional force modulation.
- 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.
@@ -214,7 +214,7 @@ Shop-floor sequence:
- `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, optional modulation.
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.
@@ -263,6 +263,8 @@ Shop-floor sequence:
- `force_setpoint_n`
- `table_rpm_setpoint`
- `spindle_rpm_setpoint`
- `spindle_direction_setpoint`
- `spindle_direction_actual`
- `force_actuator_cmd`
- `estop_active`
- `interlock_state`

95
docs/nick-generated/2026-06-02-spindle-direction-selection.md Normal file
View File

@@ -0,0 +1,95 @@
---
title: Feature Intake — Toolhead Spindle Direction Selection
status: draft
requested_by: Antoine Letarte / Normand Fullum
generated_by: Nick / Hermes
project: P11-Polisher-Fullum
repo: polisher-control
source_truth: false
created: 2026-06-02
privacy: technical-only
---
# Feature Intake — Toolhead Spindle Direction Selection
## 1. Requested behavior
Normand wants the operator to select the toolhead/tool spindle rotation direction between clockwise and counter-clockwise.
The operator-facing control belongs in manual mode first, and the same field should be carried in future controller-job segments so program execution does not require a protocol/schema redesign.
## 2. Classification
- [x] Execution feature in `polisher-control`
- [x] Contract feature touching schemas/protocol/telemetry/logs
- [ ] Planning/intelligence feature that belongs upstream
- [ ] Safety/scope feature requiring Antoine approval beyond this explicit request
Rationale: the controller is not deciding polishing strategy. It is executing/logging an operator- or job-selected spindle direction. Because this changes the host↔Teensy payload and controller-job/log shape, it is also a contract feature.
## 3. Operator-visible behavior
- Manual UI exposes a spindle direction selector next to spindle RPM.
- Allowed values are:
- `cw` — clockwise
- `ccw` — counter-clockwise
- Physical convention: direction is viewed from above the toolhead looking down toward the mirror/tool contact.
- Default for existing/manual startup can be `cw` unless Antoine/Cédric chooses another default.
- Any direction change while running is logged as a timestamped setpoint event.
## 4. Affected layers
- Host controller: normalize/validate direction aliases and include direction in manual setpoints/log events.
- Teensy firmware: accept direction in `MANUAL_START`, `SETPOINT`, and future `SEGMENT_START`; map to ODrive command sign.
- Host ↔ Teensy protocol: add `spindle_direction` / `commanded_spindle_direction` enum values `cw` / `ccw`.
- Telemetry channels: add `spindle_direction_setpoint` and `spindle_direction_actual` as recommended channels.
- Run/manual-session logs: record direction separately from RPM; RPM remains a non-negative magnitude.
- Machine capability profile: advertise `supported_spindle_directions: ["cw", "ccw"]`.
- Shared schemas: add direction fields to job/controller-job/run-log contracts.
- Tests: assert stable enum values, schema fields, and telemetry channel presence.
## 5. Safety implications
- Direction must not be inferred from signed RPM; use explicit enum plus non-negative RPM magnitude.
- Direction reversal while spindle is moving should be ramped/handled safely by firmware/ODrive implementation. The scaffold currently defines the contract; Cédric should decide whether live reversal is allowed directly or requires ramp-to-zero before applying the new direction.
- ODrive sign mapping is a commissioning item: firmware must be configured so UI `cw`/`ccw` matches physical observed tool rotation.
Safety decision:
- [x] No new optical strategy or autonomous behavior.
- [x] Implementation should add a safe reversal rule before hardware use.
## 6. Contract implications
- New controller-job segment field: `commanded_spindle_direction` enum `cw|ccw`.
- New planning job pass field: `spindle_direction` enum `cw|ccw`.
- New run-log commanded fields: `spindle_direction`.
- New capability field: `supported_spindle_directions`.
- New telemetry context channels: `spindle_direction_setpoint`, `spindle_direction_actual`.
## 7. Acceptance checks
- [x] Host contract tests for enum values and alias normalization.
- [x] Schema field test for `commanded_spindle_direction`.
- [x] Telemetry channel test for direction channels.
- [ ] Firmware compile/build check once Cédric maps this into Teensy/ODrive code.
- [ ] Bench test confirms UI `cw` physically rotates clockwise by the documented convention.
- [ ] Bench test confirms UI `ccw` physically rotates counter-clockwise by the documented convention.
- [ ] Bench test confirms live reversal behavior is safe or blocked until spindle reaches zero.
## 8. Open questions
- Cédric: confirm the ODrive command/sign mapping and whether live direction reversal requires ramp-to-zero.
- Antoine/Normand: confirm the physical viewing convention: current draft uses “viewed from above the toolhead looking down toward the mirror/tool contact.”
## 9. Implementation notes
Initial scaffold update created on branch `docs/nick-llm-context-20260602`:
- `host/polisher_control/contracts.py`
- `host/polisher_control/telemetry_channels.py`
- `tests/test_spindle_direction_contract.py`
- `shared/schemas/*.schema.json`
- `shared/schemas/examples/*.json`
- `shared/machine/fullum-alpha.capabilities.v1.json`
- affected docs/checklists

3
docs/reference/source-map.md
View File

@@ -4,7 +4,8 @@ This repo foundation is derived from the current P11 / Fullum polisher-control p
Primary source documents:
- Fullum Polisher — Machine Control & Firmware Specification v1
- `software-suite/control/firmware/Fullum-Polisher-Machine-Control-Firmware-Spec-Report.md` / `.pdf` — Cédric-facing report wrapper.
- `software-suite/control/firmware/Fullum-Polisher-Machine-Control-Firmware-Spec-v1.md` — transcluded implementation spec body.
- Controller / Bridge / Digital Twin Architecture Plan
- polisher-control — System Definition
- polisher-control — Roadmap