Polisher-Control/docs/nick-generated/2026-06-02-spindle-direction-selection.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
Feature Intake — Toolhead Spindle Direction Selection	draft	Antoine Letarte / Normand Fullum	Nick / Hermes	P11-Polisher-Fullum	polisher-control	false	2026-06-02	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

• Execution feature in polisher-control
• 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:

• No new optical strategy or autonomous behavior.
• 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

• Host contract tests for enum values and alias normalization.
• Schema field test for commanded_spindle_direction.
• 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