docs: scaffold polisher-control foundation

firmware/README.md

@@ -0,0 +1,12 @@
+# Firmware
+
+Teensy 4.x firmware owns the fast loop:
+
+- sensor acquisition;
+- force PID;
+- command output;
+- fast safety/interlocks;
+- host heartbeat supervision;
+- telemetry/event emission.
+
+Use `firmware/teensy/` as the first implementation target.

firmware/teensy/README.md

@@ -0,0 +1,17 @@
+# Teensy Firmware Scaffold
+
+Suggested starting point: Teensy 4.1 using PlatformIO/Arduino framework.
+
+Core modules to implement:
+
+- protocol framing + CRC;
+- message decode/encode;
+- state machine mirror / safety state;
+- KWR75B-CAN decoder via isolated CAN transceiver;
+- table and arm encoder readers;
+- force PID and actuator output;
+- ODrive command/telemetry path;
+- telemetry packet builder;
+- fast interlocks and watchdogs.
+
+The included `src/main.cpp` is intentionally minimal. Replace with real modules as hardware decisions close.

firmware/teensy/include/polisher_protocol.h

@@ -0,0 +1,31 @@
+#pragma once
+#include <stdint.h>
+
+enum class MessageType : uint8_t {
+    HEARTBEAT = 1,
+    MANUAL_START = 2,
+    SETPOINT = 3,
+    MANUAL_STOP = 4,
+    SEGMENT_START = 5,
+    PAUSE = 6,
+    RESUME = 7,
+    ABORT = 8,
+    ESTOP = 9,
+    ACK = 100,
+    NACK = 101,
+    TELEMETRY = 102,
+    EVENT = 103,
+    SEGMENT_DONE = 104,
+    ABORT_COMPLETE = 105,
+};
+
+enum class NackReason : uint16_t {
+    NONE = 0,
+    BAD_CRC = 1,
+    BAD_VERSION = 2,
+    ILLEGAL_TRANSITION = 3,
+    GEOMETRY_NOT_VALIDATED = 4,
+    SAFETY_INTERLOCK_ACTIVE = 5,
+    UNSUPPORTED_COMMAND = 6,
+    VALUE_OUT_OF_RANGE = 7,
+};

firmware/teensy/include/polisher_telemetry.h

@@ -0,0 +1,28 @@
+#pragma once
+#include <stdint.h>
+
+struct FT_LoadSample {
+    float Fx;
+    float Fy;
+    float Fz;
+    float Mx;
+    float My;
+    float Mz;
+    uint32_t status;
+};
+
+struct TelemetrySample {
+    uint64_t timestamp_us;
+    float table_angle_deg;
+    float arm_angle_deg;
+    float fz_n;
+    float mx;
+    float my;
+    float mz;
+    float spindle_rpm_actual;
+    float table_rpm_actual;
+    float arm_amplitude_deg_derived;
+    float arm_center_deg_derived;
+    uint8_t machine_state;
+    float force_setpoint_n;
+};

firmware/teensy/platformio.ini

@@ -0,0 +1,9 @@
+[env:teensy41]
+platform = teensy
+board = teensy41
+framework = arduino
+monitor_speed = 115200
+build_flags =
+    -D POLISHER_CONTROL_PROTOCOL_VERSION=1
+lib_deps =
+    tonton81/FlexCAN_T4

firmware/teensy/src/main.cpp

@@ -0,0 +1,30 @@
+#include <Arduino.h>
+#include "polisher_protocol.h"
+#include "polisher_telemetry.h"
+
+static constexpr uint32_t HEARTBEAT_LED_MS = 500;
+uint32_t lastLedToggleMs = 0;
+bool ledState = false;
+
+void setup() {
+    pinMode(LED_BUILTIN, OUTPUT);
+    Serial.begin(115200);
+    // TODO: initialize protocol parser, CAN, encoders, drive I/O, watchdogs.
+}
+
+void loop() {
+    const uint32_t now = millis();
+    if (now - lastLedToggleMs >= HEARTBEAT_LED_MS) {
+        lastLedToggleMs = now;
+        ledState = !ledState;
+        digitalWrite(LED_BUILTIN, ledState ? HIGH : LOW);
+    }
+
+    // TODO v1 loop order:
+    // 1. Read host frames and validate CRC/version.
+    // 2. Read KWR75B-CAN and encoder inputs.
+    // 3. Update state/safety/watchdogs.
+    // 4. Compute setpoint ramp and force PID.
+    // 5. Apply actuator/drive outputs.
+    // 6. Emit telemetry >=100 Hz and events on transitions/faults.
+}