feat(firmware): Mini firmware as mini/ variant on the root stewart-core (#30)

* feat(firmware): bring Mini firmware in as the `mini/` variant on the root stewart-core

Fold the standalone Mini-6DOF firmware into this repo as a second build-time
firmware variant alongside `Controller/`, both sharing the single root
`stewart-core` submodule. Source files copied in (not a subtree/submodule of
Mini-6DOF). Part of the firmware-unification effort (6dof/FIRMWARE_UNIFICATION.md,
DECISIONS 2026-07-18).

Variant map
- `Controller/` = normal (full system): MCPWM step/dir -> AASD-15A; PCBv1 ESP32 /
  PCBv2 ESP32-S3; W5500 Ethernet.
- `mini/`       = mini (desktop): LEDC PWM -> hobby servos; analog 50 Hz,
  runtime-switchable to digital 250 Hz via SERVO:RATE.
- Both point at ../stewart-core (single source of truth = atan2f).

Changes
- Copy Mini-6DOF `Controller/` tree into `mini/` (main/, include/, CMakeLists.txt,
  partitions.csv, sdkconfig.defaults, embedded demo .m6p). Excludes .git, build/,
  generated sdkconfig, and the mini's own components/stewart-core submodule.
- Rewire `mini/CMakeLists.txt` to the root submodule via
  `set(EXTRA_COMPONENT_DIRS ".../stewart-core")`, mirroring Controller/. The mini's
  `main/CMakeLists.txt` already PRIV_REQUIRES stewart-core; it now resolves to the
  root component. No `components/stewart-core` reference remains.
- Advance the root `stewart-core` submodule e5ef989 -> a820e74 (origin/main head:
  "feat(mca): add output-stage intensity + per-axis gain/invert, schema v6").
  Required: the mini Phase-3 firmware calls mcaGetIntensity / mcaSetAxisGain /
  mcaApplyOutputStage and MotionCueingConfig.axis_gain/axis_invert, which the old
  pin predates. Per the locked decision these cue params live in the SHARED core.
- Copy mini 3D parts into `cad/mini/` (servo mount, seat rails, pcb mount).
- Add `firmware/README.md` (variant map + build) and rewrite `mini/README.md`
  (variant framing, hardware/pinout/geometry, servo-rate profile, commands).
  Both document the config-follows-flashed-features direction (FINGERPRINT
  advertises caps; app/bridge derive config) and the deferred Controller/->normal/
  + firmware/common/ refactor.

Build-verified on ESP-IDF v5.5 (both reach "Project build complete" with fresh bins):
- mini      -> esp32   -> mini_6dof.bin
- Controller -> esp32s3 -> stewart_platform.bin (unchanged by the submodule bump)

Not done here (deliberately): Mini-6DOF not archived; no hardware flashed; no
handshake re-architecture; no Controller/->normal/ + firmware/common/ move.

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

* refactor(firmware): move variant map to root FIRMWARE.md; add mini CI job + close trigger gaps

Address coordinator review on the firmware-unification PR:

- Move firmware/README.md -> repo-root FIRMWARE.md (variant map lives next to
  mini/ and Controller/); remove the lonely firmware/ directory. Fix all
  relative links (../ prefixes) now that it sits at the root.
- Drop mini/build-esp-idf.ps1 (redundant with the 6dof-esp-build skill);
  mini/README.md now points at the skill for headless builds.
- CI (.github/workflows/ci.yml): add a "Build Mini Firmware (ESP-IDF)" job that
  builds mini/ for esp32 (mirrors the ESP32-S3 Controller job: recursive
  submodules, esp-idf-ci-action v5.5.2, uploads mini_6dof.* artifacts).
- Broaden path triggers so a shared-core bump can't slip past CI:
  * ci.yml (firmware + SIL): add mini/**, stewart-core (submodule gitlink),
    and the workflow file itself.
  * unit_tests.yml (C math tests): add stewart-core — the math under test now
    lives in the submodule, so a bump must retrigger the tests. This is the
    exact gap that let the e5ef989->a820e74 bump go unverified.

Re-verified: mini esp32 build still reaches "Project build complete" with a fresh
mini_6dof.bin. App/SIL tests confirmed 47/47 against a820e74 by the coordinator.

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

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: knaufinator

.github/workflows/ci.yml

@@ -7,12 +7,18 @@ on:
       - 'v*.*.*'
     paths:
       - 'Controller/**'
+      - 'mini/**'
       - 'app/**'
+      - 'stewart-core'          # shared submodule gitlink — a bump must trigger firmware + SIL
+      - '.github/workflows/ci.yml'
   pull_request:
     branches: [ phoenix, main ]
     paths:
       - 'Controller/**'
+      - 'mini/**'
       - 'app/**'
+      - 'stewart-core'          # shared submodule gitlink — a bump must trigger firmware + SIL
+      - '.github/workflows/ci.yml'
 
 jobs:
   version:
@@ -115,6 +121,50 @@ jobs:
             partition-table-*.bin
           retention-days: 90
 
+  mini-firmware-build:
+    name: Build Mini Firmware (ESP-IDF)
+    needs: version
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          submodules: 'recursive'   # root stewart-core supplies the shared math
+
+      - name: Install ESP-IDF prerequisites
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y git wget flex bison gperf python3 python3-pip python3-venv \
+            cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0
+
+      - name: Set up ESP-IDF and Build
+        uses: espressif/esp-idf-ci-action@v1
+        with:
+          esp_idf_version: v5.5.2
+          target: esp32
+          path: 'mini'
+          command: idf.py build
+
+      - name: Package mini firmware with version
+        run: |
+          VERSION="${{ needs.version.outputs.version }}"
+          cp mini/build/mini_6dof.bin "mini-firmware-${VERSION}.bin"
+          cp mini/build/mini_6dof.elf "mini-firmware-${VERSION}.elf"
+          cp mini/build/bootloader/bootloader.bin "mini-bootloader-${VERSION}.bin"
+          cp mini/build/partition_table/partition-table.bin "mini-partition-table-${VERSION}.bin"
+
+      - name: Upload mini firmware artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: mini-firmware-${{ needs.version.outputs.version }}
+          path: |
+            mini-firmware-*.bin
+            mini-firmware-*.elf
+            mini-bootloader-*.bin
+            mini-partition-table-*.bin
+          retention-days: 90
+
   desktop-app-build:
     name: Build Desktop App (CMake)
     needs: version

.github/workflows/unit_tests.yml

@@ -8,6 +8,7 @@ on:
       - 'Controller/main/AxisScaling.cpp'
       - 'Controller/main/MotionCueing.cpp'
       - 'Controller/include/**'
+      - 'stewart-core'          # shared submodule gitlink — the math under test lives here now
       - 'tests/**'
       - '.github/workflows/unit_tests.yml'
   pull_request:
@@ -17,6 +18,7 @@ on:
       - 'Controller/main/AxisScaling.cpp'
       - 'Controller/main/MotionCueing.cpp'
       - 'Controller/include/**'
+      - 'stewart-core'          # shared submodule gitlink — the math under test lives here now
       - 'tests/**'
       - '.github/workflows/unit_tests.yml'
 

FIRMWARE.md

@@ -0,0 +1,79 @@
+# Firmware variants
+
+This repo carries **one firmware codebase in two build-time variants**, both sharing the single
+[`stewart-core`](stewart-core) submodule at the repo root (IK / AxisScaling / MotionCueing —
+the single source of truth, canonical `atan2f`). The variant is selected at build time via the
+IDF target + the actuator backend; the shared motion pipeline (COBS transport, playback, CueTask,
+command handler, NVS config) is identical.
+
+| Variant | Directory | Actuator backend | Boards / MCU | Servo rate | Build |
+|---------|-----------|------------------|--------------|-----------|-------|
+| **normal** (full system) | [`Controller/`](Controller) | MCPWM step/dir → AASD-15A AC servos (MCP23S17 SPI expander on PCBv1; direct GPIO on PCBv2). W5500 Ethernet. | PCBv1 = ESP32, PCBv2 = ESP32-S3 | 250 Hz cue loop | `set-target esp32`\|`esp32s3` |
+| **mini** (desktop) | [`mini/`](mini) | LEDC PWM → hobby servos | ESP32 DevKitC | analog 50 Hz (runtime-switchable to digital 250 Hz via `SERVO:RATE`) | `set-target esp32` |
+
+Both directories are project-level ESP-IDF projects that point at the root submodule with
+`set(EXTRA_COMPONENT_DIRS "${CMAKE_CURRENT_LIST_DIR}/../stewart-core")` and resolve it through
+`PRIV_REQUIRES stewart-core` in their `main/CMakeLists.txt`. There is **no per-variant copy** of
+the core math and **no `components/stewart-core` submodule** inside either variant.
+
+```
+<repo root>/
+├── Controller/       normal (full-system) firmware variant  → ../stewart-core
+├── mini/             mini (desktop) firmware variant         → ../stewart-core
+├── stewart-core      single shared submodule (IK/AxisScaling/MotionCueing)
+├── cad/mini/         mini 3D-printed parts (servo mounts, seat rails)
+├── app/              desktop SIL/HIL simulator (also consumes stewart-core)
+├── bridge/           Linux HIL bridge service
+├── pcb/  tests/  docs/
+```
+
+## Building
+
+Requires ESP-IDF v5.5. Fetch the shared core first:
+
+```bash
+git submodule update --init --recursive
+```
+
+```bash
+# mini variant
+cd mini && idf.py set-target esp32 && idf.py build
+
+# normal variant — PCBv2 (ESP32-S3)
+cd Controller && idf.py set-target esp32s3 && idf.py build
+# normal variant — PCBv1 (ESP32)
+cd Controller && idf.py set-target esp32 && idf.py build
+```
+
+Per-variant hardware notes, pinouts, and serial commands: [`mini/README.md`](mini/README.md)
+and [`Controller/README.md`](Controller/README.md).
+
+On this machine, both variants build headlessly via the **`6dof-esp-build`** skill
+(`idf_build.ps1`), which encodes the ESP-IDF env setup.
+
+## Config-follows-flashed-features (direction)
+
+The intended architecture: **nothing about a device's capabilities is hardcoded per connection.**
+Build-time feature flags determine the flashed feature set; the device then **advertises what it is**
+via the FINGERPRINT handshake (variant, PCB version, actuator type, servo mode, axis count,
+`caps=raw`, partition/OTA presence, …); the app / Linux bridge / Android client **derive** the
+UI / config / param-set from that report. FINGERPRINT already reports `platform=…` and `caps=raw`;
+extending it to the full capability set is the follow-up. **The handshake is not being
+re-architected now** — this section only records the direction.
+
+## Planned follow-up refactor (NOT done here)
+
+The current layout adds `mini/` as a sibling of the existing `Controller/`, the lowest-risk first
+step. The intended end state groups by variation and factors the shared firmware out:
+
+```
+firmware/
+├── common/          transport, playback, CueTask, motion pipeline, command handler, config
+└── variants/
+    ├── normal/      (today's Controller/)
+    └── mini/        (today's mini/)
+```
+
+Deferred deliberately: moving `Controller/` → `normal/` and extracting `firmware/common/` is
+disruptive to the app's CMake wiring and CI, so it is a separate follow-up once both variants are
+proven in-tree. Do not fold it into this change.

cad/mini/Lower Seat Rail.stl

@@ -0,0 +1,19 @@
+# ESP-IDF CMakeLists.txt for Mini-6DOF Controller
+# PWM servo variant of the Stewart Platform controller
+cmake_minimum_required(VERSION 3.16)
+
+# Support both ESP32 and ESP32-S3
+# set(SUPPORTED_TARGETS esp32 esp32s3)
+
+# Shared IK / AxisScaling / MotionCueing come from the SINGLE stewart-core submodule
+# at the repo root (single source of truth = atan2f), consumed as an out-of-tree
+# component — mirrors Controller/CMakeLists.txt. The mini/ variant does NOT carry its
+# own components/stewart-core; the root submodule provides the `stewart-core` component
+# that main/CMakeLists.txt PRIV_REQUIRES.
+set(EXTRA_COMPONENT_DIRS "${CMAKE_CURRENT_LIST_DIR}/../stewart-core")
+
+# Include ESP-IDF build system
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+
+# Define the project
+project(mini_6dof)

cad/mini/Seat Rail.stl

@@ -0,0 +1,149 @@
+# `mini/` — Mini-6DOF Firmware Variant
+
+Desktop-scale **mini** variant of the Stewart-platform firmware: an **ESP32** driving
+**6 hobby servos via LEDC PWM**. This is one of two firmware variants in this repo — see
+[`../FIRMWARE.md`](../FIRMWARE.md) for the variant map. Both variants share the
+single [`stewart-core`](../stewart-core) submodule at the repo root (IK / AxisScaling /
+MotionCueing — single source of truth).
+
+| | This variant (`mini/`) | `Controller/` (normal) |
+|---|---|---|
+| **Role** | desktop / dev / education | full-scale motion sim |
+| **MCU** | ESP32 (DevKitC) | ESP32 (PCBv1) / ESP32-S3 (PCBv2) |
+| **Actuator** | LEDC PWM → hobby servos | MCPWM step/dir → AASD-15A AC servos |
+| **Servo rate** | analog 50 Hz (runtime-switchable to digital 250 Hz via `SERVO:RATE`) | 250 Hz cue loop |
+| **Wireless** | BLE (Android phone-as-controller) | W5500 Ethernet / WiFi |
+| **Workspace** | ~30 mm | ~350 mm |
+
+> This tree was migrated from the standalone **Mini-6DOF** repo (its `Controller/`, Phase-3
+> firmware) into the main app repo as part of the firmware-unification effort. The mini's former
+> `components/stewart-core` submodule was dropped in favor of the root submodule.
+
+## Build
+
+Requires ESP-IDF v5.5 (matches the rest of the repo).
+
+```bash
+# from repo root, one-time: fetch the shared core
+git submodule update --init --recursive
+
+cd mini
+idf.py set-target esp32   # first time only
+idf.py build
+idf.py -p COM6 flash monitor
+```
+
+`mini/CMakeLists.txt` points at the root submodule via
+`set(EXTRA_COMPONENT_DIRS "${CMAKE_CURRENT_LIST_DIR}/../stewart-core")` (mirrors
+`Controller/CMakeLists.txt`); `main/CMakeLists.txt` resolves it through `PRIV_REQUIRES stewart-core`.
+
+On this machine, the headless build is driven by the **`6dof-esp-build`** skill
+(`idf_build.ps1 -ProjDir mini -Clean`), which encodes the ESP-IDF v5.5 env setup that avoids the
+MSYS/venv/stderr traps. CI builds it the same way (see the "Build Mini Firmware" job in
+`.github/workflows/ci.yml`).
+
+## Project structure
+
+```
+mini/
+├── main/
+│   ├── main.cpp              # app_main, CueTask, SOURCE modes, command API, LEDC servo output
+│   ├── CobsTransport.cpp     # COBS-framed serial transport (CH_DATA18 / CH_DATA_RAW / CH_CMD)
+│   ├── BleTransport.cpp      # BLE GATT server (motion + accel characteristics)
+│   ├── helpers.cpp           # mapfloat / rate-limit utilities
+│   ├── laps123_moderate.m6p  # baked 50 Hz motion-cued laps 1-3 (EMBED_FILES) for boot demo
+│   └── CMakeLists.txt        # component build (PRIV_REQUIRES stewart-core)
+├── include/                  # BleTransport.h, CobsTransport.h, cobs.h, helpers.h, version.h, debug_uart.h
+├── partitions.csv            # 4 MB no-OTA table: 2 MB app + raw seq partition
+├── sdkconfig.defaults        # ESP32 config
+└── CMakeLists.txt            # project-level, wires EXTRA_COMPONENT_DIRS → ../stewart-core
+```
+
+IK / AxisScaling / MotionCueing are **not** in this tree — they come from `../stewart-core`.
+The only mini-specific code is the LEDC servo backend + BLE transport + pin map.
+
+## Hardware
+
+- **MCU**: ESP32 DevKitC (original ESP32 — not ESP32-S3)
+- **Servos**: 6 × hobby servos (SG90/MG996R class; ordering Feetech/ANNIMOS DS3218 for the digital upgrade)
+- **PWM**: LEDC at 50 Hz (analog default), 16-bit resolution
+- **Pulse range**: 800–2200 µs (center 1500 µs)
+- **Power**: dedicated **5 V 8 A** servo rail (do not run servos off USB)
+- **Servo enable**: GPIO 27 controls the servo-rail power relay/MOSFET
+
+### Servo pinout
+
+| Servo | GPIO | LEDC ch | Inverted |
+|-------|------|---------|----------|
+| 0 | 15 | 0 | Yes |
+| 1 | 14 | 1 | No |
+| 2 | 4  | 2 | Yes |
+| 3 | 32 | 3 | No |
+| 4 | 33 | 4 | Yes |
+| 5 | 5  | 5 | No |
+
+| Function | GPIO |
+|----------|------|
+| Servo enable | 27 |
+| E-Stop | 22 |
+
+Inverted servos are mounted mirrored; the firmware applies the sign flip automatically.
+
+### Platform geometry (mm)
+
+| Param | Value | Description |
+|-------|-------|-------------|
+| RD | 15.75 | Base radius |
+| PD | 16.00 | Platform radius |
+| L1 | 7.25 | Servo horn length |
+| L2 | 28.50 | Connecting rod length |
+| H | 25.517 | Neutral platform height |
+| θ_r | 10° | Base rotation angle |
+| θ_p | 30° | Platform rotation angle |
+
+3D-printed mounts + seat rails are in [`../cad/mini/`](../cad/mini).
+
+## Servo rate profile (analog / digital)
+
+The firmware supports **both** an analog 50 Hz carrier (SG90/MG996R class — default) and a digital
+250 Hz carrier (DS3218 class), runtime-switchable via `SERVO:RATE` (persisted in NVS). `SERVO:RATE`
+sets the LEDC carrier and `cueLoopHz` together, so a servo swap needs no reflash. Staying on analog
+50 Hz now; the digital-servo swap later flips the profile to 250 Hz and unlocks the high-fidelity
+mini cue loop. See `6dof/MINI_SERVO_UPGRADE.md` for the servo spec.
+
+## Communication
+
+- **Serial**: COBS-framed over USB — `CH_DATA18` (0x06, baked 18-byte motion), `CH_DATA_RAW`
+  (0x07, raw 6×float32 live telemetry), `CH_CMD` (0x02, ASCII commands). Legacy 15-byte
+  `0xAA/0x55` binary + CSV also accepted.
+- **BLE**: GATT server (device name `Mini6DOF`) — Motion char `0xFF01` (12 B, 6×uint16 LE),
+  Accel char `0xFF03` (24 B, 6×float32 LE) for phone-as-controller.
+
+### Selected serial commands
+
+| Command | Description |
+|---------|-------------|
+| `VERSION?` / `FINGERPRINT?` | Version + identity handshake (reports `platform=mini-6dof`, `caps=raw`) |
+| `CONFIG?` / `CONFIG:key=value` | Geometry dump / set (auto-recomputes axis scales) |
+| `SCALE?` / `BITS?` / `BITS:N` | Axis scales / input bit depth |
+| `SERVO:RATE=...` | Analog 50 Hz ↔ digital 250 Hz profile (NVS-persisted) |
+| `SERVO:CENTER=c0..c5` / `SERVO:PULSE=v` | Servo center + pulse-per-radian calibration |
+| `SOURCE:OFF\|DEMO\|LIVE` | Motion source select (`OFF` homes = one-tap kill) |
+| `PLAY:BOOT=0\|1` | Disable/enable boot auto-play (runtime, no reflash) |
+| `ZERO` / `ESTOP:SOFT` / `DBG:1`\|`DBG:0` | Home / soft e-stop / debug toggle |
+
+Runtime serial control without reflashing: see the `6dof-mini-serial` skill.
+
+## Config-follows-flashed-features (direction)
+
+The intended architecture is that **nothing about a device's capabilities is hardcoded per
+connection** — the device advertises what it is (variant, PCB version, actuator type, servo mode,
+axis count, `caps=raw`, partition/OTA presence) via the **FINGERPRINT handshake**, and the app /
+Linux bridge / Android client **derive** their UI/config/param-set from that report. Build-time
+feature flags determine the flashed feature set → the firmware reports it at runtime → the config
+follows. FINGERPRINT already reports `platform=mini-6dof` and `caps=raw`; extending it to the full
+capability set is the follow-up (the handshake is **not** being re-architected now).
+
+## License
+
+MIT — see [`../LICENSE`](../LICENSE).

cad/mini/Servo Motor Mount.stl

@@ -0,0 +1,59 @@
+#ifndef BLE_TRANSPORT_H
+#define BLE_TRANSPORT_H
+
+#ifdef ENABLE_BLE
+
+#include <stdbool.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Initialize BLE GATT server with a custom motion data service.
+ *
+ * Service UUID:  4210xxxx-0001-1000-8000-00805f9b34fb
+ * Motion RX characteristic (0xFF01): writable, receives 12-byte binary payloads
+ * Status TX characteristic (0xFF02): notify, sends status/telemetry
+ * Accel  RX characteristic (0xFF03): writable, receives 24-byte accel packets
+ *
+ * @param process_packet  Callback for each valid 12-byte binary payload
+ * @return true on success
+ */
+bool ble_transport_init(void (*process_packet)(const uint8_t *payload));
+
+/**
+ * Register callback for accelerometer/gyro data packets.
+ * Called when 24 bytes (6 x float32 LE) arrive on the accel characteristic.
+ * Data order: [accel_x, accel_y, accel_z, gyro_x, gyro_y, gyro_z]
+ * Units: m/s² for accel, rad/s for gyro (Android TYPE_ACCELEROMETER + TYPE_GYROSCOPE)
+ *
+ * @param process_accel  Callback receiving pointer to 6 floats
+ */
+void ble_transport_set_accel_callback(void (*process_accel)(const float *data));
+
+/**
+ * Returns true when a BLE client is connected.
+ */
+bool ble_transport_connected(void);
+
+/**
+ * Get BLE connection state as string.
+ */
+const char* ble_transport_state_str(void);
+
+/**
+ * Send notification data to connected BLE client (for telemetry).
+ * @param data  Pointer to data bytes
+ * @param len   Length of data
+ * @return 0 on success
+ */
+int ble_transport_notify(const uint8_t *data, uint16_t len);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // ENABLE_BLE
+#endif // BLE_TRANSPORT_H