docs: Add SAUL-TEE system reference + update wiring diagram

- docs/SAUL-TEE-SYSTEM-REFERENCE.md: authoritative architecture doc for
  the new 4-wheel wagon. Covers ESP32-S3 BALANCE (Waveshare LCD 1.28,
  QMI8658, SN65HVD230 CAN), ESP32-S3 IO (TBS Crossfire, ELRS, BTS7960,
  NFC/baro/ToF, WS2812), inter-board UART protocol (460800 baud,
  [0xAA][len][type][payload][crc8]), CAN IDs (VESCs 68/56, Orin
  0x300-0x303 cmd / 0x400-0x401 telemetry), RC channel map, power
  architecture, safety systems, and firmware layout.

- docs/wiring-diagram.md: banner pointing to new reference doc;
  old Mamba F722S UART summary marked OBSOLETE.

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

CLAUDE.md

@@ -1,22 +1,18 @@
 # SaltyLab Firmware — Agent Playbook
 
 ## Project
-**SAUL-TEE** — 4-wheel wagon (870×510×550 mm, 23 kg).
+Self-balancing two-wheeled robot: **two ESP32 boards** (BALANCE + IO), hoverboard hub motors, Jetson Orin for AI/SLAM.
-Two ESP32-S3 boards + Jetson Orin via CAN. Full spec: `docs/SAUL-TEE-SYSTEM-REFERENCE.md`
 
-| Board | Role |
+> ⚠️ **ARCHITECTURE CHANGE (2026-04-03):** ESP32 BALANCE (ESP32) and ESP32 IO are NO LONGER USED.
-|-------|------|
+> Replaced by: **ESP32 BALANCE** (PID loop) + **ESP32 IO** (motors/sensors/comms).
-| **ESP32-S3 BALANCE** | QMI8658 IMU, PID balance, CAN→VESC (L:68 / R:56), GC9A01 LCD (Waveshare Touch LCD 1.28) |
+> The `src/` and `include/` ESP32 BALANCE firmware is legacy/archived — do not extend it.
-| **ESP32-S3 IO** | TBS Crossfire RC, ELRS failover, BTS7960 motors, NFC/baro/ToF, WS2812 |
+> New firmware goes in `esp32/` — pin assignments and framework details TBD pending max.
-| **Jetson Orin** | AI/SLAM, CANable2 USB→CAN, cmds 0x300–0x303, telemetry 0x400–0x401 |
-
-> **Legacy:** `src/` and `include/` = archived STM32 HAL — do not extend. New firmware in `esp32/`.
 
 ## Team
 | Agent | Role | Focus |
 |-------|------|-------|
-| **sl-firmware** | Embedded Firmware Lead | ESP32-S3, ESP-IDF, QMI8658, CAN/UART protocol, BTS7960 |
+| **sl-firmware** | Embedded Firmware Lead | ESP32 firmware, balance loop, I/O drivers, PlatformIO |
-| **sl-controls** | Control Systems Engineer | PID tuning, IMU fusion, balance loop, safety |
+| **sl-controls** | Control Systems Engineer | PID tuning, IMU sensor fusion, real-time control loops, safety systems |
 | **sl-perception** | Perception / SLAM Engineer | Jetson Orin, RealSense D435i, RPLIDAR, ROS2, Nav2 |
 
 ## Status

TEAM.md

@@ -1,13 +1,15 @@
 # SaltyLab — Ideal Team
 
 ## Project
-**SAUL-TEE** — 4-wheel wagon (870×510×550 mm, 23 kg).
+Self-balancing two-wheeled robot using **two ESP32 boards** (BALANCE + IO), hoverboard hub motors, Jetson Orin for AI/SLAM.
-Two ESP32-S3 boards (BALANCE + IO) + Jetson Orin. See `docs/SAUL-TEE-SYSTEM-REFERENCE.md`.
+
+> ⚠️ **ARCHITECTURE CHANGE (2026-04-03):** ESP32 BALANCE (ESP32) and ESP32 IO retired.
+> Replaced by ESP32 BALANCE (PID loop) + ESP32 IO (motors/sensors/comms).
 
 ## Current Status
-- **Hardware:** ESP32-S3 BALANCE (Waveshare Touch LCD 1.28, CH343 USB) + ESP32-S3 IO (bare devkit, JTAG USB)
+- **Hardware:** ESP32 BALANCE + ESP32 IO replacing STM32 FC — details from max incoming
-- **Firmware:** ESP-IDF/PlatformIO target; legacy `src/` STM32 HAL archived
+- **Firmware:** ESP32 firmware TBD; legacy STM32 code in `src/` is archived
-- **Comms:** UART 460800 baud inter-board; CANable2 USB→CAN for Orin; CAN 500 kbps to VESCs (L:68 / R:56)
+- **STM32 legacy (archived):** USB CDC bug was STM32-specific — no longer applies
 
 ---
 

docs/AGENTS.md

@@ -2,29 +2,37 @@
 
 You're working on **SaltyLab**, a self-balancing two-wheeled indoor robot. Read this entire file before touching anything.
 
-## ⚠️ ARCHITECTURE — SAUL-TEE (finalised 2026-04-04)
+## ⚠️ ARCHITECTURE CHANGE — 2026-04-03
 
-Full hardware spec: `docs/SAUL-TEE-SYSTEM-REFERENCE.md` — **read it before writing firmware.**
+**ESP32 BALANCE (ESP32) and ESP32 IO are NO LONGER USED.**
 
-| Board | Role |
+New hardware:
-|-------|------|
+- **ESP32 BALANCE** — PID balance loop (replaces FC)
-| **ESP32-S3 BALANCE** | Waveshare Touch LCD 1.28 (CH343 USB). QMI8658 IMU, PID loop, CAN→VESC L(68)/R(56), GC9A01 LCD |
+- **ESP32 IO** — motors, sensors, comms
-| **ESP32-S3 IO** | Bare devkit (JTAG USB). TBS Crossfire RC (UART0), ELRS failover (UART2), BTS7960 motors, NFC/baro/ToF, WS2812, buzzer/horn/headlight/fan |
+
-| **Jetson Orin** | CANable2 USB→CAN. Cmds on 0x300–0x303, telemetry on 0x400–0x401 |
+The `src/` and `include/` ESP32/STM32 HAL firmware is **legacy/archived**. Do not extend it.
+All new firmware targets the ESP32 boards in `esp32/`. Pin assignments and framework TBD — await details from max.
+
+## Project Overview
+
+A hoverboard-based balancing robot with two compute layers:
+1. **ESP32 BALANCE** — PID balance loop. IMU + balance PID, safety-critical layer.
+2. **ESP32 IO** — motors, sensors, comms layer.
+3. **Jetson Orin** — AI brain. ROS2, SLAM, person tracking. Not safety-critical.
 
 ```
-Jetson Orin ──CANable2──► CAN 500kbps ◄───────────────────────┐
+Jetson (speed+steer)  ←→  ELRS RC (kill switch)
-                                │                               │
+         │
-                         ESP32-S3 BALANCE ←─UART 460800─► ESP32-S3 IO
+         ▼
-                         (QMI8658, PID loop)              (BTS7960, RC, sensors)
+   ESP32 BALANCE (IMU, PID balance loop)
-                                │ CAN 500kbps
+         │
-                      ┌─────────┴──────────┐
+         ▼
-                 VESC Left (ID 68)    VESC Right (ID 56)
+   ESP32 IO (motor drivers, sensors, comms)
+         │
+         ▼
+   Hoverboard ESC (FOC) → 2× 8" hub motors
 ```
 
-Frame: `[0xAA][LEN][TYPE][PAYLOAD][CRC8]`  
-Legacy `src/` STM32 HAL code is **archived — do not extend.**
-
 ## ⚠️ SAFETY — READ THIS OR PEOPLE GET HURT
 
 This is not a toy. 8" hub motors + 36V battery can crush fingers, break toes, and launch the frame. Every firmware change must preserve these invariants:

docs/SALTYLAB.md

@@ -1,6 +1,11 @@
-# SAUL-TEE — Self-Balancing Wagon Robot 🔬
+# SaltyLab — Self-Balancing Indoor Bot 🔬
 
-Four-wheel wagon (870×510×550 mm, 23 kg). Full spec: `docs/SAUL-TEE-SYSTEM-REFERENCE.md`
+Two-wheeled, self-balancing robot for indoor AI/SLAM experiments.
+
+> ⚠️ **ARCHITECTURE CHANGE (2026-04-03):** ESP32 BALANCE (ESP32) and ESP32 IO are retired.
+> New compute stack: **ESP32 BALANCE** (PID loop) + **ESP32 IO** (motors/sensors/comms).
+> Sections below referencing the Drone FC / ESP32 / GEPRC GEP-F7 are historical.
+> Await updated spec from max before writing new firmware.
 
 ## ⚠️ SAFETY — TOP PRIORITY
 

docs/SAUL-TEE-SYSTEM-REFERENCE.md

@@ -1,222 +1,444 @@
-# SAUL-TEE System Reference — SaltyLab ESP32 Architecture
+# SAUL-TEE — System Reference
-*Authoritative source of truth for hardware, pins, protocols, and CAN assignments.*
+**Rev A — 2026-04-04**
-*Spec from hal@Orin, 2026-04-04.*
+_Authoritative architecture reference for all agents. Source: hal (Orin), max._
 
 ---
 
-## Overview
+## 1. Robot Overview
 
-| Board | Role | MCU | USB chip |
+| Parameter | Value |
-|-------|------|-----|----------|
+|-----------|-------|
-| **ESP32-S3 BALANCE** | PID balance loop, CAN→VESCs, LCD display | ESP32-S3 | CH343 USB-serial |
+| **Name** | SAUL-TEE |
-| **ESP32-S3 IO** | RC input, motor drivers, sensors, LEDs, peripherals | ESP32-S3 | JTAG USB (native) |
+| **Config** | 4-wheel wagon (replaces 2-wheel self-balancing bot) |
+| **Dimensions** | 870 × 510 × 550 mm (L × W × H) |
+| **Mass** | ~23 kg |
+| **Drive** | 4× hub motors via 2× VESC 6.7 (dual channel each) |
+| **Power** | 36V battery bus |
+| **AI brain** | Jetson Orin Nano Super (25W) |
+| **CAN bus** | 500 kbps, CANable 2.0 USB↔CAN on Orin |
 
-**Robot form factor:** 4-wheel wagon — 870 × 510 × 550 mm, ~23 kg
+> ⚠️ **ARCHITECTURE CHANGE (2026-04-03):** Mamba F722S / STM32F722 / BlackPill are retired.
-**Power:** 36 V LiPo, DC-DC → 5 V and 12 V rails
+> New embedded stack: **ESP32-S3 BALANCE** + **ESP32-S3 IO** (see §2–3 below).
-**Orin connection:** CANable2 USB → 500 kbps CAN (same bus as VESCs)
 
 ---
 
-## ESP32-S3 BALANCE
+## 2. ESP32-S3 BALANCE Board
 
-### Board
+### Hardware
-Waveshare ESP32-S3 Touch LCD 1.28
+| Item | Detail |
-- GC9A01 round 240×240 LCD
+|------|--------|
-- CST816S capacitive touch
+| **Module** | Waveshare ESP32-S3 Touch LCD 1.28 |
-- QMI8658 6-axis IMU (accel + gyro, SPI)
+| **MCU** | ESP32-S3 (dual-core 240 MHz, 512KB SRAM, 8MB flash, 8MB PSRAM) |
-- CH343 USB-to-serial chip
+| **USB** | CH343G USB-UART bridge (UART0 / GPIO43 TX, GPIO44 RX) |
+| **Display** | 1.28" round GC9A01 240×240 LCD (SPI) |
+| **Touch** | CST816S capacitive touch (I2C) |
+| **IMU** | QMI8658 6-axis (gyro + accel), I2C on-board |
+| **CAN transceiver** | SN65HVD230, external, wired to ESP32-S3 TWAI peripheral |
 
-### Pin Assignments
+### Role
+- Runs the **PID balance / drive loop** (or stability assist for wagon mode)
+- Reads QMI8658 IMU at high rate for tilt / attitude
+- Sends drive commands to VESCs over **500 kbps CAN** (VESC native protocol)
+- Receives high-level velocity commands from Orin over CAN (0x300–0x303)
+- Publishes telemetry to Orin over CAN (0x400–0x401)
+- Bridges ESP32-IO sensor data over **inter-board UART** @ 460800 baud
 
-| Function | GPIO | Notes |
+### On-Board Pin Map (fixed by Waveshare PCB)
-|----------|------|-------|
-| **QMI8658 IMU (SPI)** | | |
-| SCK | IO39 | |
-| MOSI | IO38 | |
-| MISO | IO40 | |
-| CS | IO41 | |
-| INT1 | IO42 | data-ready interrupt |
-| **GC9A01 LCD (shares SPI bus)** | | |
-| CS | IO12 | |
-| DC | IO11 | |
-| RST | IO10 | |
-| BL | IO9 | PWM backlight |
-| **CST816S Touch (I2C)** | | |
-| SDA | IO4 | |
-| SCL | IO5 | |
-| INT | IO6 | |
-| RST | IO7 | |
-| **CAN — SN65HVD230 transceiver** | | 500 kbps |
-| TX | IO43 | → SN65HVD230 TXD |
-| RX | IO44 | ← SN65HVD230 RXD |
-| **Inter-board UART (to IO board)** | | 460800 baud |
-| TX | IO17 | |
-| RX | IO18 | |
 
-### Responsibilities
+| Signal | GPIO | Notes |
-- Read QMI8658 @ 1 kHz (SPI, INT1-driven)
+|--------|------|-------|
-- Complementary filter → pitch angle
+| LCD SCLK | 10 | GC9A01 SPI clock |
-- PID balance loop (configurable Kp / Ki / Kd)
+| LCD MOSI | 11 | GC9A01 SPI data |
-- Send VESC speed commands via CAN (ID 68 = left, ID 56 = right)
+| LCD CS | 9 | GC9A01 chip select |
-- Receive Orin velocity+mode commands via CAN (0x300–0x303)
+| LCD DC | 8 | GC9A01 data/cmd |
-- Receive IO board status (arming, RC, faults) via UART protocol
+| LCD BL | 2 | Backlight PWM |
-- Drive GC9A01 LCD: pitch, speed, battery %, error state
+| Touch SDA | 6 | CST816S / I2C-0 |
-- Enforce tilt cutoff at ±25°; IWDG 50 ms timeout
+| Touch SCL | 7 | CST816S / I2C-0 |
-- Publish telemetry on CAN 0x400–0x401 at 10 Hz
+| Touch INT | 5 | Active-low interrupt |
+| Touch RST | 4 | Active-low reset |
+| IMU SDA | 6 | QMI8658 shares I2C-0 |
+| IMU SCL | 7 | QMI8658 shares I2C-0 |
+| IMU INT1 | 3 | Data-ready interrupt |
+| CH343 USB TX | 43 | UART0 TX (USB serial) |
+| CH343 USB RX | 44 | UART0 RX (USB serial) |
+
+### External Wiring (user-soldered, confirm with calipers/multimeter)
+
+| Signal | GPIO | Notes |
+|--------|------|-------|
+| CAN TX | **TBD** | → SN65HVD230 D pin; use free header GPIO |
+| CAN RX | **TBD** | ← SN65HVD230 R pin; use free header GPIO |
+| Inter-board UART TX | **TBD** | → ESP32-IO UART RX @ 460800 |
+| Inter-board UART RX | **TBD** | ← ESP32-IO UART TX @ 460800 |
+
+> ⚠️ **Verify GPIO assignments in `esp32/balance/src/config.h` before writing firmware.**
+
+### QMI8658 Details
+| Item | Value |
+|------|-------|
+| I2C address | 0x6A (SA0 pin low) or 0x6B (SA0 high) |
+| Gyro full-scale | ±2048 °/s (configurable ±16/32/64/128/256/512/1024/2048) |
+| Accel full-scale | ±16 g (configurable ±2/4/8/16) |
+| Output data rate | Up to 7174.4 Hz |
+| Interface | I2C or SPI (board routes I2C) |
 
 ---
 
-## ESP32-S3 IO
+## 3. ESP32-S3 IO Board
 
-### Board
+### Hardware
-Bare ESP32-S3 devkit (JTAG USB)
+| Item | Detail |
+|------|--------|
+| **Module** | ESP32-S3 bare dev board (JTAG USB) |
+| **MCU** | ESP32-S3 (dual-core 240 MHz) |
+| **USB** | Built-in USB-JTAG/Serial (no external bridge) |
 
-### Pin Assignments
+### Role
+- All **physical I/O**: motors, RC, sensors, indicators, accessories
+- TBS Crossfire primary RC (UART0)
+- ELRS failover RC (UART2)
+- BTS7960 half-bridge motor drivers (4-wheel PWM drive)
+- NFC, barometer, ToF range sensors (I2C)
+- WS2812B LED strip
+- Horn, headlight, cooling fan, buzzer
 
-| Function | GPIO | Notes |
+### Pin Map
-|----------|------|-------|
-| **TBS Crossfire RC — UART0 (primary)** | | |
-| RX | IO44 | CRSF frames from Crossfire RX |
-| TX | IO43 | telemetry to Crossfire TX |
-| **ELRS failover — UART2** | | active if CRSF absent >100 ms |
-| RX | IO16 | |
-| TX | IO17 | |
-| **BTS7960 Motor Driver — Left** | | |
-| RPWM | IO1 | forward PWM |
-| LPWM | IO2 | reverse PWM |
-| R_EN | IO3 | right enable |
-| L_EN | IO4 | left enable |
-| **BTS7960 Motor Driver — Right** | | |
-| RPWM | IO5 | |
-| LPWM | IO6 | |
-| R_EN | IO7 | |
-| L_EN | IO8 | |
-| **I2C bus** | | |
-| SDA | IO11 | |
-| SCL | IO12 | |
-| NFC (PN532 or similar) | I2C | |
-| Barometer (BMP280/BMP388) | I2C | |
-| ToF (VL53L0X/VL53L1X) | I2C | |
-| **WS2812B LEDs** | | |
-| Data | IO13 | |
-| **Outputs** | | |
-| Horn / buzzer | IO14 | PWM tone |
-| Headlight | IO15 | PWM or digital |
-| Fan | IO16 | (if ELRS not fitted on UART2) |
-| **Inputs** | | |
-| Arming button | IO9 | active-low, hold 3 s to arm |
-| Kill switch sense | IO10 | hardware estop detect |
-| **Inter-board UART (to BALANCE board)** | | 460800 baud |
-| TX | IO18 | |
-| RX | IO21 | |
 
-### Responsibilities
+| Signal | GPIO | Protocol | Notes |
-- Parse CRSF frames (TBS Crossfire, primary)
+|--------|------|----------|-------|
-- Parse ELRS frames (failover, activates if no CRSF for >100 ms)
+| **TBS Crossfire RX** UART TX | 43 | CRSF @ 420000 baud | Telemetry out to TBS TX module |
-- Drive BTS7960 left/right PWM motor drivers
+| **TBS Crossfire RX** UART RX | 44 | CRSF @ 420000 baud | UART0 — RC frames in |
-- Read NFC, barometer, ToF via I2C
+| **ELRS failover** UART TX | **TBD** | CRSF @ 420000 baud | UART2 |
-- Drive WS2812B LEDs (armed/fault/idle patterns)
+| **ELRS failover** UART RX | **TBD** | CRSF @ 420000 baud | UART2 |
-- Control horn, headlight, fan, buzzer
+| **Inter-board UART TX** | **TBD** | Binary @ 460800 | → BALANCE UART RX |
-- Manage arming: hold button 3 s while upright → send ARM to BALANCE
+| **Inter-board UART RX** | **TBD** | Binary @ 460800 | ← BALANCE UART TX |
-- Monitor kill switch input → immediate motor off + FAULT frame
+| **BTS7960 — FL** RPWM | **TBD** | PWM | Front-left forward |
-- Forward RC + sensor data to BALANCE via binary UART protocol
+| **BTS7960 — FL** LPWM | **TBD** | PWM | Front-left reverse |
-- Report faults and RC-loss upstream
+| **BTS7960 — FL** R_EN | **TBD** | GPIO | Enable H |
+| **BTS7960 — FL** L_EN | **TBD** | GPIO | Enable H |
+| **BTS7960 — FR** RPWM | **TBD** | PWM | Front-right forward |
+| **BTS7960 — FR** LPWM | **TBD** | PWM | Front-right reverse |
+| **BTS7960 — FR** R_EN | **TBD** | GPIO | Enable H |
+| **BTS7960 — FR** L_EN | **TBD** | GPIO | Enable H |
+| **BTS7960 — RL** RPWM | **TBD** | PWM | Rear-left forward |
+| **BTS7960 — RL** LPWM | **TBD** | PWM | Rear-left reverse |
+| **BTS7960 — RL** R_EN | **TBD** | GPIO | Enable H |
+| **BTS7960 — RL** L_EN | **TBD** | GPIO | Enable H |
+| **BTS7960 — RR** RPWM | **TBD** | PWM | Rear-right forward |
+| **BTS7960 — RR** LPWM | **TBD** | PWM | Rear-right reverse |
+| **BTS7960 — RR** R_EN | **TBD** | GPIO | Enable H |
+| **BTS7960 — RR** L_EN | **TBD** | GPIO | Enable H |
+| **I2C SDA** | **TBD** | I2C | NFC + baro + ToF shared bus |
+| **I2C SCL** | **TBD** | I2C | NFC + baro + ToF shared bus |
+| **WS2812B data** | **TBD** | RMT | LED strip |
+| **Horn** | **TBD** | GPIO/PWM | MOSFET or relay |
+| **Headlight** | **TBD** | GPIO/PWM | MOSFET |
+| **Fan** | **TBD** | PWM | ESC/electronics cooling |
+| **Buzzer** | **TBD** | GPIO/PWM | Piezo or active buzzer |
+
+> ⚠️ **TBD pin assignments** — to be confirmed in `esp32/io/src/config.h` once wiring is set.
+
+### I2C Peripherals
+
+| Device | Address | Function |
+|--------|---------|----------|
+| NFC module | 0x24 (PN532) or 0x28 | NFC tag read/write |
+| Barometer | 0x76 (BMP280/BMP388) | Altitude + temp |
+| ToF range | 0x29 (VL53L0X) or 0x52 (VL53L4CD) | Proximity/obstacle |
 
 ---
 
-## Inter-Board Binary Protocol (UART @ 460800 baud)
+## 4. Inter-Board UART Protocol (BALANCE ↔ IO)
+
+### Link Parameters
+| Parameter | Value |
+|-----------|-------|
+| Baud rate | 460800 |
+| Format | 8N1 |
+| Direction | Full-duplex |
+
+### Frame Format
 
 ```
-[0xAA][LEN][TYPE][PAYLOAD × LEN bytes][CRC8]
+Byte 0:   0xAA          (start-of-frame magic)
+Byte 1:   LEN           (payload length in bytes, uint8)
+Byte 2:   TYPE          (message type, uint8)
+Byte 3…N: PAYLOAD       (LEN bytes)
+Byte N+1: CRC8          (CRC-8/MAXIM over bytes 1..N)
 ```
-- `0xAA` — start byte
-- `LEN` — payload length in bytes (uint8)
-- `TYPE` — message type (uint8)
-- `CRC8` — CRC-8/MAXIM over TYPE + PAYLOAD bytes
 
-### IO → BALANCE Messages
+### Message Types (draft — confirm in firmware)
 
-| TYPE | Name | Payload | Description |
+| Type | Direction | Payload | Description |
-|------|------|---------|-------------|
+|------|-----------|---------|-------------|
-| 0x01 | RC_CMD | int16 throttle, int16 steer, uint8 flags | flags: bit0=armed, bit1=kill |
+| 0x01 | IO → BAL | `[ch1:u16][ch2:u16]…[ch16:u16][flags:u8]` | RC channels (16× uint16, 1000–2000 µs) + status flags |
-| 0x02 | SENSOR | uint16 tof_mm, int16 baro_delta_pa, uint8 nfc_present | |
+| 0x02 | IO → BAL | `[sensor_id:u8][value:f32]` | Sensor reading (ToF, baro, etc.) |
-| 0x03 | FAULT | uint8 fault_flags | bit0=rc_loss, bit1=motor_fault, bit2=estop |
+| 0x03 | IO → BAL | `[nfc_uid:u8×7][len:u8]` | NFC tag detected |
+| 0x10 | BAL → IO | `[leds:u8][horn:u8][light:u8][fan:u8][buzz:u8]` | Actuator commands |
+| 0x11 | BAL → IO | `[state:u8][pitch:f32][speed:f32]` | Status for LED animations |
+| 0xFF | both | `[uptime_ms:u32]` | Heartbeat (watchdog reset) |
 
-### BALANCE → IO Messages
+> Frame types are **draft** — refer to `esp32/shared/protocol.h` for authoritative definitions.
 
-| TYPE | Name | Payload | Description |
+### CRC-8 Polynomial
-|------|------|---------|-------------|
+```
-| 0x10 | STATE | int16 pitch_x100, int16 pid_out, uint8 error_state | |
+Poly: 0x31 (CRC-8/MAXIM, also called CRC-8/1-Wire)
-| 0x11 | LED_CMD | uint8 pattern, uint8 r, uint8 g, uint8 b | |
+Init: 0x00
-| 0x12 | BUZZER | uint8 tone_id, uint16 duration_ms | |
+RefIn/RefOut: true
+XorOut: 0x00
+```
 
 ---
 
-## CAN Bus — 500 kbps
+## 5. CAN Bus
 
-### Node Assignments
+### Bus Parameters
+| Parameter | Value |
+|-----------|-------|
+| Bit rate | 500 kbps |
+| Topology | Single bus; all nodes share CANH/CANL + GND |
+| Termination | 120 Ω at each end of the bus |
+| Orin interface | CANable 2.0 USB↔CAN → `/dev/canable0` (or `can0` after `ip link`) |
 
-| Node | CAN ID | Role |
+### Node Addresses
-|------|--------|------|
-| VESC Left motor | **68** | Receives speed/duty via VESC CAN protocol |
-| VESC Right motor | **56** | Receives speed/duty via VESC CAN protocol |
-| ESP32-S3 BALANCE | — | Sends VESC commands; publishes telemetry |
-| Jetson Orin (CANable2) | — | Sends velocity commands; receives telemetry |
 
-### Frame Table
+| Node | CAN ID / Role |
+|------|--------------|
+| VESC left motor | ID **68** (0x44) — FSESC 6.7 Pro Mini Dual, left channel |
+| VESC right motor | ID **56** (0x38) — FSESC 6.7 Pro Mini Dual, right channel |
+| ESP32-S3 BALANCE | transmits telemetry 0x400–0x401; receives Orin cmds 0x300–0x303 |
+| Orin (CANable2) | transmits cmds 0x300–0x303; receives telemetry 0x400–0x401 |
 
-| CAN ID | Direction | Description | Rate |
+### Orin → Robot Command Frames (0x300–0x303)
-|--------|-----------|-------------|------|
+
-| 0x300 | Orin → BALANCE | Velocity cmd: int16 speed_mmps, int16 steer_mrad | 20 Hz |
+| CAN ID | DLC | Payload | Description |
-| 0x301 | Orin → BALANCE | PID tuning: float Kp, float Ki, float Kd (3×4B IEEE-754) | on demand |
+|--------|-----|---------|-------------|
-| 0x302 | Orin → BALANCE | Mode: uint8 (0=off, 1=balance, 2=manual, 3=estop) | on demand |
+| **0x300** | 8 | `[speed:i16][steer:i16][mode:u8][flags:u8][_:u16]` | Drive command (speed/steer ±1000, mode byte) |
-| 0x303 | Orin → BALANCE | Config: uint16 tilt_limit_x100, uint16 max_speed_mmps | on demand |
+| **0x301** | 1 | `[arm:u8]` | Arm/disarm (0x01 = arm, 0x00 = disarm) |
-| 0x400 | BALANCE → Orin | Telemetry A: int16 pitch_x100, int16 pid_out, int16 speed_mmps, uint8 state | 10 Hz |
+| **0x302** | 8 | `[kp:f16][ki:f16][kd:f16][_:u16]` | PID update (half-float) |
-| 0x401 | BALANCE → Orin | Telemetry B: int16 vesc_l_rpm, int16 vesc_r_rpm, uint16 battery_mv, uint8 faults | 10 Hz |
+| **0x303** | 1 | `[0xE5]` | Emergency stop (magic byte, cuts all motors) |
+
+### Robot → Orin Telemetry Frames (0x400–0x401)
+
+| CAN ID | DLC | Payload | Description |
+|--------|-----|---------|-------------|
+| **0x400** | 8 | `[pitch:f16][speed:f16][yaw_rate:f16][state:u8][flags:u8]` | Attitude + drive state |
+| **0x401** | 4 | `[vbat:u16][fault_code:u8][rssi:i8]` | Battery voltage (mV), fault, RC RSSI |
+
+### VESC Native CAN (standard VESC protocol)
+
+ESP32-S3 BALANCE sends VESC commands using the standard VESC CAN protocol:
+
+| Frame type | CAN ID formula | Notes |
+|------------|---------------|-------|
+| SET_DUTY | `(0x00 << 8) | VESC_ID` | Duty cycle −1.0..+1.0 × 100000 |
+| SET_CURRENT | `(0x01 << 8) | VESC_ID` | Current in mA |
+| SET_RPM | `(0x03 << 8) | VESC_ID` | Electrical RPM |
+| SET_CURRENT_BRAKE | `(0x02 << 8) | VESC_ID` | Braking current in mA |
+| STATUS_1 | `(0x09 << 8) | VESC_ID` | ERPMs + current + duty (rx) |
+| STATUS_4 | `(0x10 << 8) | VESC_ID` | Temp + input voltage + input current (rx) |
 
 ---
 
-## RC Channel Mapping (TBS Crossfire / ELRS CRSF)
+## 6. RC Channel Mapping
 
-| CH | Function | Range (µs) | Notes |
+### Primary: TBS Crossfire (UART0 on ESP32-IO, CRSF @ 420000 baud)
-|----|----------|------------|-------|
-| 1 | Steer (Roll) | 988–2012 | ±100% → ±max steer |
-| 2 | Throttle (Pitch) | 988–2012 | forward / back speed |
-| 3 | Spare | 988–2012 | |
-| 4 | Spare | 988–2012 | |
-| 5 | ARM switch | <1500=disarm, >1500=arm | SB on TX |
-| 6 | **ESTOP** | <1500=normal, >1500=kill | SC on TX — checked first every loop |
-| 7 | Speed limit | 988–2012 | maps to 10–100% speed cap |
-| 8 | Spare | | |
 
-**RC loss:** No valid CRSF frame >100 ms → IO sends FAULT(rc_loss) → BALANCE cuts motors.
+| Channel | Function | Range | Notes |
+|---------|----------|-------|-------|
+| CH1 | Roll / Steer | 1000–2000 µs | Left stick X (mode 2) |
+| CH2 | Pitch / Speed | 1000–2000 µs | Left stick Y |
+| CH3 | Throttle | 1000–2000 µs | Right stick Y |
+| CH4 | Yaw | 1000–2000 µs | Right stick X |
+| CH5 | Arm | 1000 / 2000 µs | 2-pos switch — <1200=DISARM, >1800=ARM |
+| CH6 | Drive mode | 1000/1500/2000 µs | 3-pos: RC / Assisted / Autonomous |
+| CH7 | Speed limit | 1000–2000 µs | Analog knob, scales max speed |
+| CH8 | Aux / Horn | 1000 / 2000 µs | Momentary for horn; held = klaxon |
+
+### Failover: ELRS (UART2 on ESP32-IO, CRSF @ 420000 baud)
+Same channel mapping as TBS Crossfire. IO board switches to ELRS automatically if Crossfire link lost for > 300 ms.
+
+### Failsafe
+- **RC lost > 300 ms**: motors stop, DISARM state, wait for link restoration
+- **Arm switch** must be cycled to DISARM→ARM to re-arm after failsafe
 
 ---
 
-## Safety Invariants
+## 7. Serial Commands (Orin → ESP32-S3 BALANCE via CAN 0x300)
 
-1. **Motors NEVER spin on power-on** — 3 s button hold required while upright
+All high-level commands from the Orin go over CAN. The BALANCE board also accepts direct USB-serial commands on its CH343 port for bench debugging:
-2. **Tilt cutoff ±25°** — immediate motor zero, manual re-arm required
-3. **IWDG 50 ms** — firmware hang → motors cut
-4. **ESTOP RC channel** checked first in every loop iteration
-5. **Orin CAN timeout 500 ms** → revert to RC-only mode
-6. **Speed hard cap** — start at 10%, increase in 10% increments only after stable tethered testing
-7. **Never untethered** until stable for 5+ continuous minutes tethered
-
----
-
-## USB Debug Commands (both boards, serial console)
 
 ```
-help                     list commands
+# Arm / disarm
-status                   print pitch, PID state, CAN stats, UART stats
+ARM
-pid <Kp> <Ki> <Kd>      set PID gains
+DISARM
-arm                      arm (if upright and safe)
+
-disarm                   disarm immediately
+# Set drive (speed -1000..1000, steer -1000..1000)
-estop                    emergency stop (requires re-arm)
+DRIVE <speed> <steer>
-tilt_limit <deg>         set tilt cutoff angle (default 25)
+
-speed_limit <pct>        set speed cap percentage (default 10)
+# Set mode
-can_stats                CAN bus counters (tx/rx/errors/busoff)
+MODE RC           # full RC passthrough
-uart_stats               inter-board UART frame counters
+MODE ASSISTED     # Orin sends velocity, BALANCE does stability
-reboot                   soft reboot
+MODE AUTO         # full autonomous (Orin CAN commands only)
+
+# PID update
+PID <kp> <ki> <kd>
+
+# Emergency stop (same as CAN 0x303)
+ESTOP
+
+# Status query
+STATUS            # returns JSON telemetry line
+
+# IMU calibration
+IMU CAL
 ```
+
+---
+
+## 8. System Wiring Diagram
+
+```
+                    ┌──────────────────────────────────────────────────────────┐
+                    │               JETSON ORIN NANO SUPER                     │
+                    │                  (Top plate, 25W)                        │
+                    │                                                          │
+                    │  USB-A ─── CANable 2.0 USB↔CAN (can0, 500 kbps)        │
+                    │  USB-A ─── RealSense D435i (USB 3.1)                   │
+                    │  USB-A ─── RPLIDAR A1M8 (CP2102, 115200)               │
+                    │  USB-C ─── SIM7600A 4G/LTE modem                       │
+                    │  CSI-A ─── 2× IMX219 cameras                           │
+                    │  CSI-B ─── 2× IMX219 cameras                           │
+                    │  40-pin ── ReSpeaker 2-Mic HAT                          │
+                    └──────────────────────┬───────────────────────────────────┘
+                                           │ USB-A
+                                           │ CANable 2.0
+                                           │ 500 kbps CAN
+          ┌────────────────────────────────┴──────────────────────────────────┐
+          │                         CAN BUS (CANH / CANL)                     │
+          │         120Ω ───┤  (all nodes)  ├─── 120Ω                        │
+          └───┬──────────────────────────┬───────────────────┬────────────────┘
+              │                          │                   │
+              ▼                          ▼                   ▼
+  ┌─────────────────────┐   ┌─────────────────────┐   (CAN ID 56/68)
+  │  ESP32-S3 BALANCE   │   │   VESC left  (ID 68)│   VESC right (ID 56)
+  │  Waveshare LCD 1.28 │   │   FSESC 6.7 Pro Mini│
+  │                     │   │   Dual              │
+  │  QMI8658 IMU (I2C)  │   └────────┬────────────┘
+  │  SN65HVD230 (CAN)   │            │  Phase wires
+  │  CH343 USB (debug)  │      ┌─────┴────────────────┐
+  │                     │      │  Hub motors (4×)      │
+  │  UART ─────────────────┐   │  FL / FR / RL / RR   │
+  └─────────────────────┘  │   └──────────────────────┘
+    ↑ 460800 baud binary    │
+    ↓ inter-board protocol  │
+  ┌─────────────────────────┘
+  │  ESP32-S3 IO (bare board)
+  │  JTAG USB (debug)
+  │
+  │  UART0 ── TBS Crossfire RX (CRSF, 420000)
+  │  UART2 ── ELRS receiver (CRSF failover, 420000)
+  │  PWM ──── 4× BTS7960 motor drivers
+  │  I2C ──── NFC + Baro + ToF sensors
+  │  GPIO ─── WS2812B LEDs
+  │  GPIO ─── Horn / Headlight / Fan / Buzzer
+  └─────────────────────────────────────────────
+```
+
+---
+
+## 9. Power Architecture
+
+```
+36V BATTERY
+  │
+  ├── VESCs (36V direct) ──── 4× Hub motors
+  │
+  ├── BTS7960 boards (36V → motor logic 5V via onboard reg)
+  │
+  ├── DC-DC 12V ──── Fan / Headlight / Accessories
+  │
+  └── DC-DC 5V ─┬── Jetson Orin (USB-C PD or barrel)
+                 ├── ESP32-S3 BALANCE (USB 5V or VIN)
+                 ├── ESP32-S3 IO (USB 5V or VIN)
+                 ├── TBS Crossfire RX (5V)
+                 ├── ELRS RX (5V)
+                 ├── WS2812B strip (5V)
+                 ├── RPLIDAR A1M8 (5V via USB)
+                 └── Sensors / NFC / ToF / Baro (3.3V LDO from ESP32)
+```
+
+---
+
+## 10. Device Nodes (Orin)
+
+| Device | Node | Notes |
+|--------|------|-------|
+| CANable 2.0 | `can0` | `ip link set can0 up type can bitrate 500000` |
+| RealSense D435i | `/dev/bus/usb/...` | realsense-ros driver |
+| RPLIDAR A1M8 | `/dev/rplidar` | udev symlink from ttyUSB* |
+| SIM7600A 4G | `/dev/ttyUSB0–2` | AT, PPP, GNSS NMEA |
+| IMX219 cameras | `/dev/video0,2,4,6` | CSI-A: 0/2, CSI-B: 4/6 |
+| ESP32-S3 BAL debug | `/dev/ttyACM0` or `/dev/esp32-balance` | CH343 CDC |
+| ESP32-S3 IO debug | `/dev/ttyACM1` or `/dev/esp32-io` | JTAG/CDC |
+
+---
+
+## 11. Safety Systems
+
+| System | Trigger | Action |
+|--------|---------|--------|
+| **HW kill switch** | Big red button (NC inline with 36V) | Cuts all power instantly |
+| **Tilt cutoff** | `|pitch| > 25°` | Motors off → DISARM, manual re-arm required |
+| **RC failsafe** | No RC frame > 300 ms | Motors off → DISARM |
+| **CAN watchdog** | No Orin heartbeat > 500 ms | Drop to RC-only mode |
+| **ESTOP CAN** | CAN frame 0x303 (magic 0xE5) | Immediate motor off, DISARM |
+| **ESTOP inter-board** | Type 0xFF heartbeat missing > 200 ms | IO board stops BTS7960 enables |
+| **Startup arming** | Cold power-on | Motors NEVER spin; need deliberate ARM |
+
+---
+
+## 12. Firmware Repository Layout
+
+```
+esp32/
+├── balance/          — ESP32-S3 BALANCE firmware (PlatformIO)
+│   ├── src/
+│   │   ├── main.cpp
+│   │   ├── config.h      ← GPIO assignments live here
+│   │   ├── imu_qmi8658.cpp/.h
+│   │   ├── can_vesc.cpp/.h
+│   │   └── protocol.cpp/.h
+│   └── platformio.ini
+├── io/               — ESP32-S3 IO firmware (PlatformIO)
+│   ├── src/
+│   │   ├── main.cpp
+│   │   ├── config.h      ← GPIO assignments live here
+│   │   ├── rc_crsf.cpp/.h
+│   │   ├── motor_bts7960.cpp/.h
+│   │   └── protocol.cpp/.h
+│   └── platformio.ini
+└── shared/
+    └── protocol.h    — inter-board frame types (authoritative)
+
+src/                  — LEGACY STM32 firmware (ARCHIVED — do not extend)
+include/              — LEGACY STM32 headers (ARCHIVED — do not extend)
+```
+
+---
+
+## 13. Open Questions / TBDs
+
+| Item | Owner | Status |
+|------|-------|--------|
+| GPIO assignments for CAN TX/RX on BALANCE board | sl-firmware | **TBD** |
+| GPIO assignments for IO board (all external pins) | sl-firmware | **TBD** |
+| Inter-board protocol message type table (finalized) | sl-firmware | **TBD** |
+| BTS7960 wiring — 4WD vs 2WD mode (all 4 or front 2 only) | max | **TBD** |
+| UWB ESP-NOW receiver — BALANCE or IO board? | sl-uwb + max | **TBD** |
+| VESC CAN IDs confirmed (68/56 left/right) | max | ✅ Confirmed |
+| Robot dimensions 870×510×550 mm, 23 kg | max | ✅ Confirmed |
+
+---
+
+_Last updated: 2026-04-04. Contact max or hal on MQTT for corrections._