Extract LeverMixer and reorganize telemetry into package (M3)

Move differential thrust mixing from inline main.py logic into a
dedicated LeverMixer class. Move telemetry.py into telemetry/recorder.py
to establish a telemetry package alongside the planned sdcard sink.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: c0ffee2code

CLAUDE.md

@@ -14,14 +14,15 @@ Test bench for learning flight control systems, built around a Raspberry Pi Pico
 
 ## Development Approach
 
-**Completed:** M1 — Single-axis PI(D) controller with AS5600 encoder, validated on hardware. Lever holds at 0° within ±3°. See `decision/ADR-001-pid-lever-stabilization.md`.
+**Completed:**
+- M1 — Single-axis PI(D) controller with AS5600 encoder, validated on hardware. Lever holds at 0° within ±3°. See `decision/ADR-001-pid-lever-stabilization.md`.
+- M3 — Mixer extraction (`LeverMixer` in `mixer.py`) + telemetry reorganization into `telemetry/` package.
 
 **Current focus:** M2 — Switch PID input from AS5600 to BNO085 IMU. The IMU will be the primary and only control input (as on a real drone). AS5600 becomes telemetry-only ground truth for measuring IMU lag and angle error.
 
 **Roadmap (see README.md for full details):**
 - M2: BNO085 as primary control input (depends on driver work)
 - M2a: Telemetry logging via Adalogger PiCowbell — RTC timestamps + SD card black box (see `decision/ADR-002-telemetry-logging.md`)
-- M3: Mixer abstraction (pure refactor)
 - M4: Cascaded PID — angle loop + rate loop using raw gyro (depends on M2, M2a, M3)
 - M5: Multi-axis control (depends on hardware evolution)
 
@@ -39,6 +40,10 @@ Test bench for learning flight control systems, built around a Raspberry Pi Pico
 
 ```
 ├── main.py              # Entry point - upload to Pico, runs on boot
+├── mixer.py             # LeverMixer — differential thrust for 2-motor lever
+├── telemetry/
+│   ├── recorder.py      # TelemetryRecorder + PrintSink (CSV decimation & output)
+│   └── sdcard.py        # SD card sink (planned)
 ├── AS5600/              # Git submodule: github.com/c0ffee2code/AS5600
 │   └── driver/as5600.py
 ├── BNO085/              # Git submodule: github.com/c0ffee2code/BNO085
@@ -56,6 +61,8 @@ Test bench for learning flight control systems, built around a Raspberry Pi Pico
 
 **Deployment:** Upload the following files to Pico root (flat structure):
 - `main.py`
+- `mixer.py`
+- `telemetry/recorder.py` (deployed as `recorder.py`)
 - `AS5600/driver/as5600.py`
 - `BNO085/driver/bno08x.py` + `BNO085/driver/i2c.py`
 - `DShot/driver/dshot_pio.py` + `DShot/driver/motor_throttle_group.py`

README.md

@@ -34,9 +34,9 @@ Log timestamped data from both sensors + PID internals to SD card via Adalogger
 
 **Depends on:** Adalogger hardware integration, motor pin reassignment (GPIO 4/5 → 6/7).
 
-### M3: Mixer abstraction
+### M3: Mixer abstraction — DONE
 
-Extract `base ± output` motor mapping into a configurable mixer module. Makes code drone-topology-agnostic — swap a mix table to support different frame types (2-motor lever, quadcopter X-frame, etc.).
+Extracted `base ± output` motor mapping into `LeverMixer` class (`mixer.py`). Makes code drone-topology-agnostic — swap a mix table to support different frame types (2-motor lever, quadcopter X-frame, etc.). Also reorganized telemetry into `telemetry/` package.
 
 **Depends on:** M1 (pure code refactor, no hardware dependency).
 
@@ -60,6 +60,10 @@ See [ADR-001, "Test Bench vs Real Drone" section](decision/ADR-001-pid-lever-sta
 
 ```
 ├── main.py              # Entry point — upload to Pico, runs on boot
+├── mixer.py             # LeverMixer — differential thrust for 2-motor lever
+├── telemetry/           # Telemetry recording and output sinks
+│   ├── recorder.py      # TelemetryRecorder + PrintSink
+│   └── sdcard.py        # SD card sink (planned)
 ├── AS5600/              # Git submodule: github.com/c0ffee2code/AS5600
 ├── BNO085/              # Git submodule: github.com/c0ffee2code/BNO085
 ├── DShot/               # Git submodule: github.com/c0ffee2code/DShot
@@ -77,6 +81,8 @@ git clone --recurse-submodules <repo-url>
 
 Upload to Pico root (flat structure):
 - `main.py`
+- `mixer.py`
+- `telemetry/recorder.py` (as `recorder.py`)
 - `AS5600/driver/as5600.py`
 - `BNO085/driver/bno08x.py` + `i2c.py`
 - `DShot/driver/dshot_pio.py` + `motor_throttle_group.py`

main.py

@@ -8,7 +8,8 @@
 from display_pack import (draw_disarmed, draw_arming, draw_ready,
                           draw_stabilizing, draw_error)
 from pid import PID
-from telemetry import TelemetryRecorder
+from recorder import TelemetryRecorder
+from mixer import LeverMixer
 
 # =====================================================
 # Hardware
@@ -45,14 +46,6 @@
 TELEMETRY_SAMPLE_EVERY = const(10)
 
 
-def clamp(value, lo, hi):
-    if value < lo:
-        return lo
-    if value > hi:
-        return hi
-    return value
-
-
 def buttons_by_held():
     """Return True if B+Y are both pressed (active low)."""
     return not btn_B.value() and not btn_Y.value()
@@ -63,6 +56,7 @@ def buttons_by_held():
 # =====================================================
 def main():
     pid = PID(kp=5.0, ki=0.5, kd=0.0, integral_limit=200.0)
+    mixer = LeverMixer(BASE_THROTTLE, THROTTLE_MIN, THROTTLE_MAX)
     telemetry = TelemetryRecorder(TELEMETRY_SAMPLE_EVERY)
     motors = MotorThrottleGroup([MOTOR1_PIN, MOTOR2_PIN], DSHOT_SPEEDS.DSHOT600)
 
@@ -112,8 +106,7 @@ def main():
                 # PID — target is 0°, error = angle (sign verified on hardware)
                 output = pid.compute(angle, dt)
 
-                m1 = clamp(int(BASE_THROTTLE + output), THROTTLE_MIN, THROTTLE_MAX)
-                m2 = clamp(int(BASE_THROTTLE - output), THROTTLE_MIN, THROTTLE_MAX)
+                m1, m2 = mixer.compute(output)
 
                 motors.setThrottle(0, m1)
                 motors.setThrottle(1, m2)

mixer.py

@@ -0,0 +1,16 @@
+class LeverMixer:
+    """Differential thrust mixer for a 2-motor lever."""
+
+    def __init__(self, base, throttle_min, throttle_max):
+        self.base = base
+        self.throttle_min = throttle_min
+        self.throttle_max = throttle_max
+
+    def compute(self, pid_output):
+        """Return (m1, m2) throttle values, clamped to limits."""
+        m1 = self.base + int(pid_output)
+        m2 = self.base - int(pid_output)
+        # clamp
+        m1 = max(self.throttle_min, min(self.throttle_max, m1))
+        m2 = max(self.throttle_min, min(self.throttle_max, m2))
+        return m1, m2