seb/saltylab-firmware
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

cleanup: remove all Mamba/F722S/STM32F722/BlackPill refs (sl-mechanical scope) #718

Closed
sl-webui wants to merge 1 commits from sl-mechanical/cleanup-legacy-hw into main
pull from: sl-mechanical/cleanup-legacy-hw
merge into: seb:main
Conversation 0 Commits 1 Files Changed 63 +1328 -1789
63 changed files with 1328 additions and 1789 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit a2c554c232 - Show all commits

24
AUTONOMOUS_ARMING.md
View File

@ -7,11 +7,7 @@ The robot can now be armed and operated autonomously from the Jetson without req
### Jetson Autonomous Arming
- Command: `A\n` (single byte 'A' followed by newline)
<<<<<<< HEAD
- Sent via USB CDC to the ESP32 BALANCE firmware
=======
- Sent via USB Serial (CH343) to the ESP32-S3 firmware
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
- Sent via inter-board UART to the ESP32-S3 BALANCE firmware
- Robot arms after ARMING_HOLD_MS (~500ms) safety hold period
- Works even when RC is not connected or not armed
@ -46,11 +42,11 @@ The robot can now be armed and operated autonomously from the Jetson without req
## Command Protocol
<<<<<<< HEAD
### From Jetson to ESP32 BALANCE (USB CDC)
=======
### From Jetson to ESP32-S3 (USB Serial (CH343))
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
### Inter-board UART Protocol
Communication uses 460800 baud UART with binary framing:
`[0xAA][LEN][TYPE][PAYLOAD][CRC8]`
### From Jetson to ESP32-S3 BALANCE (inter-board UART)
```
A — Request arm (triggers safety hold, then motors enable)
D — Request disarm (immediate motor stop)
@ -60,11 +56,7 @@ H — Heartbeat (refresh timeout timer, every 500ms)
C<spd>,<str> — Drive command: speed, steer (also refreshes heartbeat)
```
<<<<<<< HEAD
### From ESP32 BALANCE to Jetson (USB CDC)
=======
### From ESP32-S3 to Jetson (USB Serial (CH343))
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
### From ESP32-S3 BALANCE to Jetson (inter-board UART)
Motor commands are gated by `bal.state == BALANCE_ARMED`:
- When ARMED: Motor commands sent every 20ms (50 Hz)
- When DISARMED: Zero sent every 20ms (prevents ESC timeout)
@ -145,4 +137,4 @@ When RC is disconnected:
## References
- Issue #512: Remove ELRS arm requirement
- Files: `/src/main.c` (arming logic), `/lib/USB_CDC/src/usbd_cdc_if.c` (CDC commands)
- Files: `esp32/balance/src/main.cpp` (arming logic), inter-board UART protocol (460800 baud, `[0xAA][LEN][TYPE][PAYLOAD][CRC8]`)

31
CLAUDE.md
View File

@ -1,36 +1,17 @@
# SaltyLab Firmware — Agent Playbook
## Project
<<<<<<< HEAD
**SAUL-TEE** — 4-wheel wagon (870×510×550 mm, 23 kg).
Two ESP32-S3 boards + Jetson Orin via CAN. Full spec: `docs/SAUL-TEE-SYSTEM-REFERENCE.md`
| Board | Role |
|-------|------|
| **ESP32-S3 BALANCE** | QMI8658 IMU, PID balance, CAN→VESC (L:68 / R:56), GC9A01 LCD (Waveshare Touch LCD 1.28) |
| **ESP32-S3 IO** | TBS Crossfire RC, ELRS failover, BTS7960 motors, NFC/baro/ToF, WS2812 |
| **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/`.
=======
Self-balancing two-wheeled robot: ESP32-S3 ESP32-S3 BALANCE, hoverboard hub motors, Jetson Orin Nano Super for AI/SLAM.
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
SAUL-TEE 4-wheel wagon robot: ESP32-S3 BALANCE (PID/CAN), ESP32-S3 IO (RC/sensors), Jetson Orin Nano Super (ROS2/SLAM).
## Team
| Agent | Role | Focus |
|-------|------|-------|
<<<<<<< HEAD
| **sl-firmware** | Embedded Firmware Lead | ESP32-S3, ESP-IDF, QMI8658, CAN/UART protocol, BTS7960 |
| **sl-controls** | Control Systems Engineer | PID tuning, IMU fusion, balance loop, safety |
| **sl-perception** | Perception / SLAM Engineer | Jetson Orin, RealSense D435i, RPLIDAR, ROS2, Nav2 |
=======
| **sl-firmware** | Embedded Firmware Lead | ESP-IDF, USB Serial (CH343) debugging, SPI/UART, PlatformIO, DFU bootloader |
| **sl-firmware** | Embedded Firmware Lead | ESP32-S3 firmware (Arduino/IDF), PlatformIO, CAN bus, inter-board UART protocol |
| **sl-controls** | Control Systems Engineer | PID tuning, IMU sensor fusion, real-time control loops, safety systems |
| **sl-perception** | Perception / SLAM Engineer | Jetson Orin Nano Super, RealSense D435i, RPLIDAR, ROS2, Nav2 |
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
| **sl-perception** | Perception / SLAM Engineer | Jetson Orin, RealSense D435i, RPLIDAR, ROS2, Nav2 |
## Status
USB Serial (CH343) TX bug resolved (PR #10 — DCache MPU non-cacheable region + IWDG ordering fix).
USB CDC TX bug resolved (PR #10 — DCache MPU non-cacheable region + IWDG ordering fix).
## Repo Structure
- `projects/saltybot/SALTYLAB.md` — Design doc
@ -48,11 +29,11 @@ USB Serial (CH343) TX bug resolved (PR #10 — DCache MPU non-cacheable region +
| `saltyrover-dev` | Integration — rover variant |
| `saltytank` | Stable — tracked tank variant |
| `saltytank-dev` | Integration — tank variant |
| `main` | Shared code only (IMU drivers, USB Serial (CH343), balance core, safety) |
| `main` | Shared code only (IMU drivers, USB CDC, balance core, safety) |
### Rules
- Agents branch FROM `<variant>-dev` and PR back TO `<variant>-dev`
- Shared/infrastructure code (IMU drivers, USB Serial (CH343), balance core, safety) goes in `main`
- Shared/infrastructure code (IMU drivers, USB CDC, balance core, safety) goes in `main`
- Variant-specific code (motor topology, kinematics, config) goes in variant branches
- Stable branches get promoted from `-dev` after review and hardware testing
- **Current SaltyLab team** works against `saltylab-dev`

65
TEAM.md
View File

@ -1,22 +1,12 @@
# SaltyLab — Ideal Team
## Project
<<<<<<< HEAD
**SAUL-TEE** — 4-wheel wagon (870×510×550 mm, 23 kg).
Two ESP32-S3 boards (BALANCE + IO) + Jetson Orin. See `docs/SAUL-TEE-SYSTEM-REFERENCE.md`.
SAUL-TEE 4-wheel wagon robot using ESP32-S3 BALANCE (PID/CAN master) and ESP32-S3 IO (RC/sensors), with Jetson Orin Nano Super for AI/SLAM.
## Current Status
- **Hardware:** ESP32-S3 BALANCE (Waveshare Touch LCD 1.28, CH343 USB) + ESP32-S3 IO (bare devkit, JTAG USB)
- **Firmware:** ESP-IDF/PlatformIO target; legacy `src/` STM32 HAL archived
- **Comms:** UART 460800 baud inter-board; CANable2 USB→CAN for Orin; CAN 500 kbps to VESCs (L:68 / R:56)
=======
Self-balancing two-wheeled robot using a drone ESP32-S3 BALANCE (ESP32-S3), hoverboard hub motors, and eventually a Jetson Orin Nano Super for AI/SLAM.
## Current Status
- **Hardware:** Assembled — FC, motors, ESC, IMU, battery, RC all on hand
- **Firmware:** Balance PID + hoverboard ESC protocol written, but blocked by USB Serial (CH343) bug
- **Blocker:** USB Serial (CH343) TX stops working when peripheral inits (SPI/UART/GPIO) are added alongside USB on ESP32-S3 — see `legacy/stm32/USB_CDC_BUG.md` for historical context
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
- **Hardware:** Assembled — ESP32-S3 BALANCE + IO, VESCs, IMU, battery, RC all on hand
- **Firmware:** Balance PID + VESC CAN protocol written, ESP32-S3 inter-board UART protocol active
- **Status:** See current bead list for active issues
---
@ -24,30 +14,18 @@ Self-balancing two-wheeled robot using a drone ESP32-S3 BALANCE (ESP32-S3), hove
### 1. Embedded Firmware Engineer (Lead)
**Must-have:**
<<<<<<< HEAD
- Deep ESP32 (Arduino/ESP-IDF) or STM32 HAL experience
- USB OTG FS / CDC ACM debugging (TxState, endpoint management, DMA conflicts)
- SPI + UART + USB coexistence on ESP32
- PlatformIO or bare-metal ESP32 toolchain
- DFU bootloader implementation
=======
- Deep ESP-IDF experience (ESP32-S3 specifically)
- USB Serial (CH343) / UART debugging on ESP32-S3
- SPI + UART + USB coexistence on ESP32-S3
- ESP-IDF / Arduino-ESP32 toolchain
- OTA firmware update implementation
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
- ESP32-S3 firmware (Arduino / ESP-IDF framework)
- PlatformIO toolchain
- CAN bus protocol and VESC CAN integration
- Inter-board UART protocol (460800 baud, binary framed)
- Safety system design (tilt cutoff, watchdog, arming sequences)
**Nice-to-have:**
- ESP32-S3 peripheral coexistence (SPI + UART + USB)
- VESC firmware / VESC Tool experience
- PID control loop tuning for balance robots
- FOC motor control (hoverboard ESC protocol)
- ELRS/CRSF RC protocol
<<<<<<< HEAD
**Why:** The immediate blocker is a USB peripheral conflict. Need someone who's debugged STM32 USB issues before — ESP32 firmware for the balance loop and I/O needs to be written from scratch.
=======
**Why:** The immediate blocker is a USB peripheral conflict on ESP32-S3. Need someone who's debugged ESP32-S3 USB Serial (CH343) issues before — this is not a software logic bug, it's a hardware peripheral interaction issue.
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
**Why:** Core firmware runs on ESP32-S3 BALANCE (PID/CAN master) and ESP32-S3 IO (RC/sensors). Need expertise in ESP32-S3 firmware and CAN bus integration with VESC motor controllers.
### 2. Control Systems / Robotics Engineer
**Must-have:**
@ -57,7 +35,7 @@ Self-balancing two-wheeled robot using a drone ESP32-S3 BALANCE (ESP32-S3), hove
- Safety system design (tilt cutoff, watchdog, arming sequences)
**Nice-to-have:**
- Hoverboard hub motor experience
- VESC motor controller experience
- ELRS/CRSF RC protocol
- ROS2 integration
@ -65,7 +43,7 @@ Self-balancing two-wheeled robot using a drone ESP32-S3 BALANCE (ESP32-S3), hove
### 3. Perception / SLAM Engineer (Phase 2)
**Must-have:**
- Jetson Orin Nano Super / NVIDIA Jetson platform
- Jetson Orin Nano Super / NVIDIA Jetson platform (JetPack 6)
- Intel RealSense D435i depth camera
- RPLIDAR integration
- SLAM (ORB-SLAM3, RTAB-Map, or similar)
@ -83,13 +61,12 @@ Self-balancing two-wheeled robot using a drone ESP32-S3 BALANCE (ESP32-S3), hove
## Hardware Reference
| Component | Details |
|-----------|---------|
<<<<<<< HEAD
| FC | ESP32 BALANCE (ESP32RET6, MPU6000) |
=======
| FC | ESP32-S3 BALANCE (ESP32-S3RET6, QMI8658) |
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
| Motors | 2x 8" pneumatic hoverboard hub motors |
| ESC | Hoverboard ESC (EFeru FOC firmware) |
| BALANCE MCU | ESP32-S3 BALANCE (Waveshare Touch LCD 1.28, QMI8658 IMU) |
| IO MCU | ESP32-S3 IO (RC/sensors/LEDs board) |
| Motors | 2x 8" pneumatic hub motors |
| ESC Left | VESC left (CAN ID 68) |
| ESC Right | VESC right (CAN ID 56) |
| CAN Bridge | CANable 2.0 (Jetson USB → can0, 500 kbps) |
| Battery | 36V pack |
| RC | BetaFPV ELRS 2.4GHz TX + RX |
| AI Brain | Jetson Orin Nano Super + Noctua fan |
@ -100,4 +77,4 @@ Self-balancing two-wheeled robot using a drone ESP32-S3 BALANCE (ESP32-S3), hove
## Repo
- Gitea: https://gitea.vayrette.com/seb/saltylab-firmware
- Design doc: `projects/saltybot/SALTYLAB.md`
- Bug doc: `legacy/stm32/USB_CDC_BUG.md` (archived — STM32 era)
- Archived bug doc: `USB_CDC_BUG.md` (legacy STM32 era)

11
cad/dimensions.scad
View File

@ -14,11 +14,12 @@ motor_axle_flat = 10; // Flat-to-flat if D-shaft
motor_body_dia = 200; // ~8 inches
motor_bolt_circle = 0; // Axle-only mount (clamp style)
// --- Drone FC (30.5mm standard) ---
fc_hole_spacing = 25.5; // GEP-F722 AIO v2 (not standard 30.5!)
fc_hole_dia = 3.2; // M3 clearance
fc_board_size = 36; // Typical FC PCB
fc_standoff_h = 5; // Rubber standoff height
// --- ESP32-S3 BALANCE board (Waveshare Touch LCD 1.28) ---
// ⚠ Confirm hole positions before printing — verify in esp32/balance/src/config.h
mcu_bal_board_w = 40.0; // Waveshare Touch LCD 1.28 PCB approx width (TBD caliper)
mcu_bal_board_d = 40.0; // Waveshare Touch LCD 1.28 PCB approx depth (TBD caliper)
mcu_bal_hole_dia = 3.2; // M3 clearance
mcu_standoff_h = 5; // Standoff height
// --- Jetson Orin Nano Super ---
jetson_w = 100;

29
chassis/ASSEMBLY.md
View File

@ -10,7 +10,7 @@
├─ bumper_bracket(front=+1) ──────────────────────┐
│ │
┌───────┴──────────── Main Deck (640×220×6mm Al) ─────────┴───────┐
│ ← Jetson mount plate (rear/+X) FC mount (front/−X) → │
│ ← Jetson mount plate (rear/+X) MCU mount (front/−X) → │
│ [Battery tray hanging below centre] │
└───┬──────────────────────────────────────────────────────────┬───┘
│ │
@ -56,24 +56,21 @@
3. Fasten 4× M4×12 SHCS. Torque 2.5 N·m.
4. Insert battery pack; route Velcro straps through slots and cinch.
<<<<<<< HEAD
### 7 MCU mount (ESP32 BALANCE + ESP32 IO)
### 7 MCU mount (ESP32-S3 BALANCE + ESP32-S3 IO)
> ⚠️ **ARCHITECTURE CHANGE (2026-04-03):** ESP32 BALANCE retired. Two ESP32 boards replace it.
> Board dimensions and hole patterns TBD — await spec from max before machining mount plate.
> ⚠ Board hole patterns TBD — measure Waveshare Touch LCD 1.28 PCB with calipers and
> update `FC_PITCH` / `FC_MOUNT_SPACING` in all scad files before machining the mount plate.
> Reference: `docs/SAUL-TEE-SYSTEM-REFERENCE.md`.
=======
### 7 FC mount (ESP32-S3 BALANCE)
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
1. Place silicone anti-vibration grommets onto nylon M3 standoffs.
2. Lower ESP32 BALANCE board onto standoffs; secure with M3×6 BHCS. Snug only.
3. Mount ESP32 IO board adjacent — exact placement TBD pending board dimensions.
4. Orient USB connectors toward front of robot for cable access.
1. Place silicone anti-vibration grommets onto M3 nylon standoffs.
2. Lower ESP32-S3 BALANCE board onto standoffs; secure M3×6 BHCS — snug only.
3. Mount ESP32-S3 IO board adjacent — exact layout TBD pending board dimensions.
4. Orient USB-C connectors toward accessible side for field programming/debug.
### 8 Jetson Orin Nano Super mount plate
### 8 Jetson Nano mount plate
1. Press or thread M3 nylon standoffs (8mm) into plate holes.
2. Bolt plate to deck: 4× M3×10 SHCS at deck corners.
3. Set Jetson Orin Nano Super B01 carrier onto plate standoffs; fasten M3×6 BHCS.
3. Set Jetson Nano B01 carrier onto plate standoffs; fasten M3×6 BHCS.
### 9 Bumper brackets
1. Slide 22mm EMT conduit through saddle clamp openings.
@ -95,8 +92,8 @@
| Wheelbase (axle C/L to C/L) | 600 mm | ±1 mm |
| Motor fork slot width | 24 mm | +0.5 / 0 |
| Motor fork dropout depth | 60 mm | ±0.5 mm |
| ESP32 BALANCE hole pattern | TBD — await spec from max | ±0.2 mm |
| ESP32 IO hole pattern | TBD — await spec from max | ±0.2 mm |
| ESP32-S3 BALANCE hole pattern | TBD — caliper Waveshare board | ±0.2 mm |
| ESP32-S3 IO hole pattern | TBD — caliper bare board | ±0.2 mm |
| Jetson hole pattern | 58 × 58 mm | ±0.2 mm |
| Battery tray inner | 185 × 72 × 52 mm | +2 / 0 mm |

31
chassis/BOM.md
View File

@ -41,11 +41,7 @@ PR #7 (`chassis_frame.scad`) used placeholder values. The table below records th
| 3 | Dropout clamp — upper | 2 | 8mm 6061-T6 Al | 90×70mm blank | D-cut bore; `RENDER="clamp_upper_2d"` |
| 4 | Stem flange ring | 2 | 6mm Al or acrylic | Ø82mm disc | One above + one below plate; `RENDER="stem_flange_2d"` |
| 5 | Vertical stem tube | 1 | 38.1mm OD × 1.5mm wall 6061-T6 Al | 1050mm length | 1.5" EMT conduit is a drop-in alternative |
<<<<<<< HEAD
| 6 | MCU standoff M3×6mm nylon | 4 | Nylon | — | ESP32 BALANCE / IO board isolation (dimensions TBD) |
=======
| 6 | FC standoff M3×6mm nylon | 4 | Nylon | — | ESP32-S3 BALANCE vibration isolation |
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
| 6 | MCU standoff M3×6mm nylon | 4 | Nylon | — | ESP32-S3 BALANCE / IO vibration isolation |
| 7 | Ø4mm × 16mm alignment pin | 8 | Steel dowel | — | Dropout clamp-to-plate alignment |
### Battery Stem Clamp (`stem_battery_clamp.scad`) — Part B
@ -73,8 +69,8 @@ PR #7 (`chassis_frame.scad`) used placeholder values. The table below records th
| 9 | Motor fork bracket (L) | 1 | 8mm 6061 aluminium | **Update fork slot to Ø16.51mm before cutting** |
| 10 | Motor fork bracket (R) | 1 | 8mm 6061 aluminium | Mirror of item 9 |
| 11 | Battery tray | 1 | 3mm PETG FDM or 3mm aluminium fold | `chassis_frame.scad` — `battery_tray()` module |
| 12 | FC mount plate / standoffs | 1 set | PETG or nylon FDM | Includes 4× M3 nylon standoffs, 6mm height |
| 13 | Jetson Orin Nano Super mount plate | 1 | 4mm 5052 aluminium or 4mm PETG FDM | B01 58×58mm hole pattern |
| 12 | MCU mount plate / standoffs | 1 set | PETG or nylon FDM | Includes 4× M3 nylon standoffs, 6mm height — hole pattern TBD |
| 13 | Jetson Nano mount plate | 1 | 4mm 5052 aluminium or 4mm PETG FDM | B01 58×58mm hole pattern |
| 14 | Front bumper bracket | 1 | 5mm PETG FDM | Saddle clamps for 22mm EMT conduit |
| 15 | Rear bumper bracket | 1 | 5mm PETG FDM | Mirror of item 14 |
@ -92,23 +88,16 @@ PR #7 (`chassis_frame.scad`) used placeholder values. The table below records th
## Electronics Mounts
> ⚠️ **ARCHITECTURE CHANGE (2026-04-03):** ESP32 BALANCE (ESP32) is retired.
> Replaced by **ESP32 BALANCE** + **ESP32 IO**. Board dimensions and hole patterns TBD — await spec from max.
> ⚠ MCU board dimensions TBD — caliper Waveshare Touch LCD 1.28 and bare ESP32-S3 IO board
> before machining mount holes. See `docs/SAUL-TEE-SYSTEM-REFERENCE.md`.
| # | Part | Qty | Spec | Notes |
|---|------|-----|------|-------|
<<<<<<< HEAD
| 13 | ESP32 BALANCE board | 1 | TBD — mount pattern TBD | PID balance loop; replaces ESP32 BALANCE |
| 13b | ESP32 IO board | 1 | TBD — mount pattern TBD | Motor/sensor/comms I/O |
| 13 | ESP32-S3 BALANCE (Waveshare Touch LCD 1.28) | 1 | ~40×40mm PCB, hole pattern TBD | PID loop + CAN; USB-C toward accessible side |
| 13b | ESP32-S3 IO (bare board) | 1 | TBD PCB size, hole pattern TBD | RC / motor / sensor I/O |
| 14 | Nylon M3 standoff 6mm | 4 | F/F nylon | ESP32 board isolation |
| 15 | Anti-vibration grommet M3 | 4 | Ø6mm silicone | Under ESP32 mount pads |
| 16 | Jetson Orin module | 1 | 69.6×45mm module + carrier | 58×58mm M3 carrier hole pattern |
=======
| 13 | ESP32-S3 ESP32-S3 BALANCE FC | 1 | 36×36mm PCB, 30.5×30.5mm M3 mount | Oriented USB-C port toward front |
| 14 | Nylon M3 standoff 6mm | 4 | F/F nylon | FC vibration isolation |
| 15 | Anti-vibration grommet M3 | 4 | Ø6mm silicone | Under FC mount pads |
| 16 | Jetson Orin Nano Super B01 module | 1 | 69.6×45mm module + carrier | 58×58mm M3 carrier hole pattern |
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
| 16 | Jetson Orin Nano Super | 1 | 69.6×45mm module + carrier | 58×58mm M3 carrier hole pattern |
| 17 | Nylon M3 standoff 8mm | 4 | F/F nylon | Jetson board standoffs |
---
@ -159,8 +148,8 @@ Slide entire carousel up/down the stem with M6 collar bolts loosened. Tighten at
| 26 | M6×60 SHCS | 4 | ISO 4762, SS | Collar clamping bolts |
| 27 | M6 hex nut | 4 | ISO 4032, SS | Captured in collar pockets |
| 28 | M6×12 set screw | 2 | ISO 4026, SS cup-point | Stem height lock (1 per collar half) |
| 29 | M3×10 SHCS | 12 | ISO 4762, SS | ESP32 mount + miscellaneous |
| 30 | M3×6 BHCS | 4 | ISO 4762, SS | ESP32 board bolts (qty TBD pending board spec) |
| 29 | M3×10 SHCS | 12 | ISO 4762, SS | FC mount + miscellaneous |
| 30 | M3×6 BHCS | 4 | ISO 4762, SS | FC board bolts |
| 31 | Axle lock nut (match axle tip thread) | 4 | Flanged, confirm thread | 2 per motor |
| 32 | Flat washer M5 | 32 | SS | |
| 33 | Flat washer M4 | 32 | SS | |

15
chassis/chassis_frame.scad
View File

@ -8,9 +8,9 @@
// Requirements:
// - 600mm wheelbase
// - 2x hoverboard hub motors (170mm OD)
// - ESP32-S3 ESP32-S3 BALANCE FC mount (30.5x30.5mm pattern)
// - ESP32-S3 BALANCE + IO board mounts (TBD hole pattern — see SAUL-TEE-SYSTEM-REFERENCE.md)
// - Battery tray (24V 4Ah — ~180x70x50mm pack)
// - Jetson Orin Nano Super B01 mount plate (100x80mm, M3 holes)
// - Jetson Nano B01 mount plate (100x80mm, M3 holes)
// - Front/rear bumper brackets
// =============================================================================
@ -37,8 +37,9 @@ MOTOR_FORK_H = 80; // mm, total height of motor fork bracket
MOTOR_FORK_T = 8; // mm, fork plate thickness
AXLE_HEIGHT = 310; // mm, axle CL above ground (motor radius + clearance)
// ── FC mount (ESP32-S3 BALANCE — 30.5 × 30.5 mm M3 pattern) ──────────────────────
FC_MOUNT_SPACING = 30.5; // mm, hole pattern pitch
// ── MCU mount (ESP32-S3 BALANCE / IO boards) ─────────────────────────────────
// ⚠ Hole pattern TBD — update before machining. See docs/SAUL-TEE-SYSTEM-REFERENCE.md
FC_MOUNT_SPACING = 0; // TBD — set to actual ESP32-S3 board hole spacing
FC_MOUNT_HOLE_D = 3.2; // mm, M3 clearance
FC_STANDOFF_H = 6; // mm, standoff height
FC_PAD_T = 3; // mm, mounting pad thickness
@ -52,7 +53,7 @@ BATT_FLOOR = 4; // mm, tray floor thickness
BATT_STRAP_W = 20; // mm, Velcro strap slot width
BATT_STRAP_T = 2; // mm, strap slot depth
// ── Jetson Orin Nano Super B01 mount plate ──────────────────────────────────────────────
// ── Jetson Nano B01 mount plate ──────────────────────────────────────────────
// B01 carrier board hole pattern: 58 x 58 mm M3 (inner) + corner pass-throughs
JETSON_HOLE_PITCH = 58; // mm, M3 mounting hole pattern
JETSON_HOLE_D = 3.2; // mm
@ -210,7 +211,7 @@ module battery_tray() {
// ─── FC mount holes helper ────────────────────────────────────────────────────
module fc_mount_holes(z_offset=0, depth=10) {
// ESP32-S3 BALANCE: 30.5×30.5 mm M3 pattern, centred at origin
// ESP32-S3 board M3 pattern, centred at origin — spacing TBD, update FC_MOUNT_SPACING
for (x = [-FC_MOUNT_SPACING/2, FC_MOUNT_SPACING/2])
for (y = [-FC_MOUNT_SPACING/2, FC_MOUNT_SPACING/2])
translate([x, y, z_offset])
@ -247,7 +248,7 @@ module fc_mount_plate() {
}
}
// ─── Jetson Orin Nano Super B01 mount plate ─────────────────────────────────────────────
// ─── Jetson Nano B01 mount plate ─────────────────────────────────────────────
// Positioned rear of deck, elevated on standoffs
module jetson_mount_plate() {
jet_x = 60; // offset toward rear

7
chassis/ip54_BOM.md
View File

@ -104,11 +104,8 @@ IP54-rated enclosures and sensor housings for all-weather outdoor robot operatio
| Component | Thermal strategy | Max junction | Enclosure budget |
|-----------|-----------------|-------------|-----------------|
| Jetson Orin NX | Al pad → lid → fan forced convection | 95 °C Tj | Target ≤ 60 °C case |
<<<<<<< HEAD
| FC (ESP32 BALANCE) | Passive; FC has own EMI shield | 85 °C | <60 °C ambient OK |
=======
| FC (ESP32-S3 BALANCE) | Passive; FC has own EMI shield | 85 °C | <60 °C ambient OK |
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
| ESP32-S3 BALANCE | Passive; mounted on standoffs | 105 °C Tj | <70 °C ambient OK |
| ESP32-S3 IO | Passive; mounted on standoffs | 105 °C Tj | <70 °C ambient OK |
| ESC × 2 | Al pad → lid | 100 °C Tj | Target ≤ 60 °C |
| D435i | Passive; housing vent gap on rear cap | 45 °C surface | — |

9
chassis/prototype_baseplate.scad
View File

@ -65,10 +65,11 @@ CLAMP_ALIGN_D = 4.1; // Ø4 pin
// D-cut bore clearance
DCUT_CL = 0.3;
// FC mount — ESP32-S3 BALANCE 30.5 × 30.5 mm M3
FC_PITCH = 30.5;
// MCU mount — ESP32-S3 BALANCE board (Waveshare Touch LCD 1.28)
// ⚠ FC_PITCH TBD — update before machining. See docs/SAUL-TEE-SYSTEM-REFERENCE.md
FC_PITCH = 0.0; // TBD — ESP32-S3 board hole spacing not yet confirmed
FC_HOLE_D = 3.2;
// FC is offset toward front of plate (away from stem)
// Board is offset toward front of plate (away from stem)
FC_X_OFFSET = -40.0; // mm from plate centre (negative = front/motor side)
// =============================================================================
@ -202,7 +203,7 @@ module base_plate() {
translate([STEM_FLANGE_BC/2, 0, -1])
cylinder(d=M5, h=PLATE_THICK + 2);
// ── FC mount (ESP32-S3 BALANCE 30.5 × 30.5 M3) ────────────────────────
// ── MCU mount (ESP32-S3 BALANCE — hole spacing TBD) ──────────────
for (x = [FC_X_OFFSET - FC_PITCH/2, FC_X_OFFSET + FC_PITCH/2])
for (y = [-FC_PITCH/2, FC_PITCH/2])
translate([x, y, -1])

4
chassis/rover_electronics_bay.scad
View File

@ -10,8 +10,8 @@
// • RPLIDAR A1M8 tower — integrated on lid top
// • Ventilation slots — all 4 walls + lid
//
// Shared mounting patterns (swappable with SaltyLab):
// FC : 30.5 × 30.5 mm M3 (ESP32-S3 BALANCE / Pixhawk)
// Shared mounting patterns:
// MCU : TBD mm M3 (ESP32-S3 BALANCE / IO — see docs/SAUL-TEE-SYSTEM-REFERENCE.md)
// Jetson: 58 × 49 mm M3 (Orin NX / Nano Devkit carrier)
//
// Coordinate: bay centred at origin; Z=0 = deck top face.

10
chassis/saltyrover_chassis_r2.scad
View File

@ -16,8 +16,8 @@
// • D435i front bracket arm
// • Weight target: <2 kg frame (excl. motors/electronics)
//
// Shared SaltyLab patterns (swappable electronics):
// FC : 30.5 × 30.5 mm M3 (ESP32-S3 BALANCE / Pixhawk)
// Shared patterns (swappable electronics):
// MCU : TBD mm M3 (ESP32-S3 BALANCE / IO — see docs/SAUL-TEE-SYSTEM-REFERENCE.md)
// Jetson: 58 × 49 mm M3 (Orin NX / Nano carrier board)
// Stem : Ø25 mm bore (sensor head unchanged)
//
@ -87,9 +87,9 @@ STEM_COLLAR_OD = 50.0;
STEM_COLLAR_H = 20.0; // raised boss height above deck top
STEM_FLANGE_BC = 40.0; // 4× M4 bolt circle for stem adapter
// ── FC mount — ESP32-S3 BALANCE / Pixhawk (30.5 × 30.5 mm M3) ────────────────────
// Shared with SaltyLab — swappable electronics
FC_PITCH = 30.5;
// ── MCU mount — ESP32-S3 BALANCE / IO boards ─────────────────────────────────
// ⚠ FC_PITCH TBD — update before machining. See docs/SAUL-TEE-SYSTEM-REFERENCE.md
FC_PITCH = 0.0; // TBD — ESP32-S3 board hole spacing
FC_HOLE_D = 3.2;
FC_POS_Y = ROVER_L/2 - 65.0; // near front edge

385
docs/AGENTS.md
View File

@ -1,323 +1,184 @@
# AGENTS.md — SaltyLab Agent Onboarding
# AGENTS.md — SAUL-TEE Agent Onboarding
You're working on **SaltyLab**, a self-balancing two-wheeled indoor robot. Read this entire file before touching anything.
You're working on **SAUL-TEE**, a 4-wheel wagon robot. Read this entire file before touching anything.
## ⚠️ ARCHITECTURE — SAUL-TEE (finalised 2026-04-04)
**Full system reference:** `docs/SAUL-TEE-SYSTEM-REFERENCE.md`
<<<<<<< HEAD
Full hardware spec: `docs/SAUL-TEE-SYSTEM-REFERENCE.md` — **read it before writing firmware.**
## Project Overview
| Board | Role |
|-------|------|
| **ESP32-S3 BALANCE** | Waveshare Touch LCD 1.28 (CH343 USB). QMI8658 IMU, PID loop, CAN→VESC L(68)/R(56), GC9A01 LCD |
| **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 |
A 4-wheel wagon robot (870×510×550 mm, 23 kg) with three compute layers:
1. **ESP32-S3 BALANCE** (Waveshare Touch LCD 1.28) — QMI8658 IMU, PID drive / stability loop, CAN bus master for VESCs. Safety-critical layer. Firmware in `esp32/balance/`.
2. **ESP32-S3 IO** (bare board) — RC input (TBS Crossfire + ELRS failover), BTS7960 motor drivers, I2C sensors (NFC/baro/ToF), WS2812 LEDs, accessories. Firmware in `esp32/io/`.
3. **Jetson Orin Nano Super** — AI brain: ROS2, SLAM, Nav2, perception. Sends high-level velocity commands over CAN (0x300–0x303). Receives telemetry on CAN (0x400–0x401).
```
Jetson Orin ──CANable2──► CAN 500kbps ◄───────────────────────┐
│ │
ESP32-S3 BALANCE ←─UART 460800─► ESP32-S3 IO
(QMI8658, PID loop) (BTS7960, RC, sensors)
│ CAN 500kbps
┌─────────┴──────────┐
VESC Left (ID 68) VESC Right (ID 56)
=======
A hoverboard-based balancing robot with two compute layers:
1. **ESP32-S3 BALANCE** — ESP32-S3 BALANCE (ESP32-S3RET6 + MPU6000 IMU). Runs a lean C balance loop at up to 8kHz. Talks UART to the hoverboard ESC. This is the safety-critical layer.
2. **Jetson Orin Nano Super** — AI brain. ROS2, SLAM, person tracking. Sends velocity commands to FC via UART. Not safety-critical — FC operates independently.
Orin (CAN 0x300-0x303) ←→ TBS Crossfire / ELRS (CRSF @ 420000)
│ │
▼ CAN 500kbps │ inter-board UART 460800
ESP32-S3 BALANCE ───────────────── ESP32-S3 IO
QMI8658 IMU BTS7960 × 4 motor drivers
PID loop NFC / baro / ToF (I2C)
SN65HVD230 CAN WS2812 LEDs
│ Horn / headlight / fan / buzzer
▼ CAN 500kbps
VESC left (ID 68) VESC right (ID 56)
│ │
Hub motors FL/RL Hub motors FR/RR
```
Jetson (speed+steer via UART1) ←→ ELRS RC (UART3, kill switch)
│
▼
ESP32-S3 BALANCE (MPU6000 IMU, PID balance)
│
▼ UART2
Hoverboard ESC (FOC) → 2× 8" hub motors
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
```
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:
This is not a toy. 4× hub motors + 36V × high-current VESCs can crush fingers, break toes, and throw the 23 kg frame. Every firmware change must preserve these invariants:
1. **Motors NEVER spin on power-on.** Requires deliberate arming: hold button 3s while upright.
2. **Tilt cutoff at ±25°** — motors to zero, require manual re-arm. No retry, no recovery.
3. **Hardware watchdog (50ms)** — if firmware hangs, motors cut.
4. **RC kill switch** — dedicated ELRS channel, checked every loop iteration. Always overrides.
5. **Jetson UART timeout (200ms)** — if Jetson disconnects, motors cut.
1. **Motors NEVER spin on power-on.** Requires deliberate arming: deliberate ARM command.
2. **RC kill switch** — dedicated ELRS/Crossfire channel, checked every loop iteration. Always overrides.
3. **CAN watchdog** — if no Orin heartbeat for 500 ms, drop to RC-only mode.
4. **ESTOP CAN frame** — 0x303 with magic byte 0xE5 cuts all motors instantly.
5. **Inter-board heartbeat** — if IO board misses BALANCE heartbeat for 200 ms, IO disables all BTS7960 enables.
6. **Speed hard cap** — firmware limit, start at 10%. Increase only after proven stable.
7. **Never test untethered** until PID is stable for 5+ minutes on a tether.
7. **Never test without RC transmitter in hand.**
**If you break any of these, you are removed from the project.**
## Repository Layout
```
<<<<<<< HEAD
firmware/ # Legacy ESP32/STM32 HAL firmware (PlatformIO, archived)
=======
firmware/ # ESP-IDF firmware (PlatformIO)
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
├── src/
│ ├── main.c # Entry point, clock config, main loop
│ ├── icm42688.c # QMI8658-P SPI driver (backup IMU — currently broken)
│ ├── bmp280.c # Barometer driver (disabled)
│ └── status.c # LED + buzzer status patterns
├── include/
│ ├── config.h # Pin definitions, constants
│ ├── icm42688.h
│ ├── mpu6000.h # MPU6000 driver header (primary IMU)
│ ├── hoverboard.h # Hoverboard ESC UART protocol
│ ├── crsf.h # ELRS CRSF protocol
│ ├── bmp280.h
│ └── status.h
├── lib/USB_CDC/ # USB Serial (CH343) stack (serial over USB)
│ ├── src/ # CDC implementation, USB descriptors, PCD config
│ └── include/
└── platformio.ini # Build config
esp32/
├── balance/ — ESP32-S3 BALANCE firmware (PlatformIO)
│ ├── src/
│ │ ├── main.cpp
│ │ ├── config.h ← GPIO assignments — update here first
│ │ ├── 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 — update here first
│ │ ├── rc_crsf.cpp/.h
│ │ ├── motor_bts7960.cpp/.h
│ │ └── protocol.cpp/.h
│ └── platformio.ini
└── shared/
└── protocol.h ← inter-board frame types — authoritative
cad/ # OpenSCAD parametric parts (16 files)
├── dimensions.scad # ALL measurements live here — single source of truth
├── assembly.scad # Full robot assembly visualization
├── motor_mount_plate.scad
├── battery_shelf.scad
├── fc_mount.scad # Vibration-isolated FC mount
├── jetson_shelf.scad
├── esc_mount.scad
├── sensor_tower_top.scad
├── lidar_standoff.scad
├── realsense_bracket.scad
├── bumper.scad # TPU bumpers (front + rear)
├── handle.scad
├── kill_switch_mount.scad
├── tether_anchor.scad
├── led_diffuser_ring.scad
└── esp32c3_mount.scad
src/ — LEGACY STM32 code (ARCHIVED — do not touch)
include/ — LEGACY STM32 headers (ARCHIVED — do not touch)
ui/ # Web UI (Three.js + WebSerial)
└── index.html # 3D board visualization, real-time IMU data
chassis/ — OpenSCAD mechanical parts
├── ASSEMBLY.md — assembly instructions
├── BOM.md — bill of materials
└── *.scad — parametric parts
SALTYLAB.md # Master design doc — architecture, wiring, build phases
SALTYLAB-DETAILED.md # Power budget, weight budget, detailed schematics
PLATFORM.md # Hardware platform reference
docs/
├── SAUL-TEE-SYSTEM-REFERENCE.md ← MASTER REFERENCE — read this
├── AGENTS.md — this file
├── wiring-diagram.md — wiring reference (see SAUL-TEE-SYSTEM-REFERENCE.md)
└── SALTYLAB.md — legacy design doc (historical)
```
## Hardware Quick Reference
<<<<<<< HEAD
### ESP32 BALANCE Flight Controller
### ESP32-S3 BALANCE (Waveshare Touch LCD 1.28)
| Spec | Value |
|------|-------|
| MCU | ESP32RET6 (Cortex-M7, 216MHz, 512KB flash, 256KB RAM) |
=======
### ESP32-S3 BALANCE Flight Controller
| MCU | ESP32-S3, dual-core 240 MHz, 8MB flash, 8MB PSRAM |
| USB | CH343G USB-UART bridge (UART0 / GPIO43 TX, GPIO44 RX) |
| Display | 1.28" round GC9A01 240×240 (SPI, onboard) |
| IMU | QMI8658 6-axis (I2C-0 SDA=GPIO6, SCL=GPIO7, INT=GPIO3) |
| CAN | SN65HVD230 external transceiver (GPIO TBD — see `esp32/balance/src/config.h`) |
| Inter-board UART | UART1 (GPIO TBD) ↔ ESP32-IO @ 460800 baud |
| Spec | Value |
|------|-------|
| MCU | ESP32-S3RET6 (Cortex-M7, 216MHz, 512KB flash, 256KB RAM) |
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
| Primary IMU | MPU6000 (WHO_AM_I = 0x68) |
| IMU Bus | SPI1: PA5=SCK, PA6=MISO, PA7=MOSI, CS=PA4 |
| IMU EXTI | PC4 (data ready interrupt) |
| IMU Orientation | CW270 (Betaflight convention) |
| Secondary IMU | QMI8658-P (on same SPI1, CS unknown — currently non-functional) |
| Betaflight Target | DIAT-MAMBAF722_2022B |
| USB | OTG FS (PA11/PA12), enumerates as /dev/cu.usbmodemSALTY0011 |
| VID/PID | 0x0483/0x5740 |
| LEDs | PC15 (LED1), PC14 (LED2), active low |
| Buzzer | PB2 (inverted push-pull) |
| Battery ADC | PC1=VBAT, PC3=CURR (ADC3) |
| DFU | Hold yellow BOOT button + plug USB (or send 'R' over CDC) |
### ESP32-S3 IO (bare board)
### UART Assignments
| Peripheral | Interface | GPIO |
|------------|-----------|------|
| TBS Crossfire RX | UART0 CRSF @ 420000 | GPIO43 TX / GPIO44 RX |
| ELRS failover RX | UART2 CRSF @ 420000 | TBD |
| BTS7960 FL/FR/RL/RR | PWM + GPIO | TBD — see config.h |
| I2C bus (NFC/baro/ToF) | I2C | TBD |
| WS2812B LEDs | RMT GPIO | TBD |
| Horn / headlight / fan / buzzer | GPIO/PWM | TBD |
| Inter-board UART | UART1 @ 460800 | TBD |
| UART | Pins | Connected To | Baud |
|------|------|-------------|------|
| USART1 | PA9/PA10 | Jetson Orin Nano Super | 115200 |
| USART2 | PA2/PA3 | Hoverboard ESC | 115200 |
| USART3 | PB10/PB11 | ELRS Receiver | 420000 (CRSF) |
| UART4 | — | Spare | — |
| UART5 | — | Spare | — |
> All TBD GPIO assignments are confirmed in `esp32/io/src/config.h`.
### Motor/ESC
### CAN Bus
- 2× 8" pneumatic hub motors (36V, hoverboard type)
- Hoverboard ESC with FOC firmware
- UART protocol: `{0xABCD, int16 speed, int16 steer, uint16 checksum}` at 115200
- Speed range: -1000 to +1000
| Node | CAN ID | Notes |
|------|--------|-------|
| VESC left motor | 68 (0x44) | FSESC 6.7 Pro Mini Dual |
| VESC right motor | 56 (0x38) | FSESC 6.7 Pro Mini Dual |
| Orin → robot cmds | 0x300–0x303 | drive / arm / PID / ESTOP |
| BALANCE → Orin telemetry | 0x400–0x401 | attitude + battery + faults |
### Physical Dimensions (from `cad/dimensions.scad`)
### Physical Dimensions
| Part | Key Measurement |
|------|----------------|
| FC mounting holes | 25.5mm spacing (NOT standard 30.5mm!) |
| FC board size | ~36mm square |
| Hub motor body | Ø200mm (~8") |
| Motor axle | Ø12mm, 45mm long |
| Jetson Orin Nano Super | 100×80×29mm, M2.5 holes at 86×58mm |
| RealSense D435i | 90×25×25mm, 1/4-20 tripod mount |
| RPLIDAR A1 | Ø70×41mm, 4× M2.5 on Ø67mm circle |
| Kill switch hole | Ø22mm panel mount |
| Battery pack | ~180×80×40mm |
| Hoverboard ESC | ~80×50×15mm |
| 2020 extrusion | 20mm square, M5 center bore |
| Frame width | ~350mm (axle to axle) |
| Frame height | ~500-550mm total |
| Target weight | <8kg (current estimate: 7.4kg) |
| Parameter | Value |
|-----------|-------|
| Robot (SAUL-TEE) | 870 × 510 × 550 mm, 23 kg |
| Hub motor axle base OD | Ø16.11 mm (caliper-verified) |
| Hub motor axle D-cut OD | Ø15.95 mm, 13.00 mm flat chord |
| Bearing seat collar | Ø37.8 mm |
| Tire | 10 × 2.125" pneumatic (Ø254 mm) |
| ESP32-S3 BALANCE PCB | ~40×40 mm (TBD — caliper before machining) |
| Orin carrier hole pattern | 58 × 49 mm M3 |
### 3D Printed Parts (16 files in `cad/`)
## Inter-Board Protocol
| Part | Material | Infill |
|------|----------|--------|
| motor_mount_plate (350×150×6mm) | PETG | 80% |
| battery_shelf | PETG | 60% |
| esc_mount | PETG | 40% |
| jetson_shelf | PETG | 40% |
| sensor_tower_top | ASA | 80% |
| lidar_standoff (Ø80×80mm) | ASA | 40% |
| realsense_bracket | PETG | 60% |
| fc_mount (vibration isolated) | TPU+PETG | — |
| bumper front + rear (350×50×30mm) | TPU | 30% |
| handle | PETG | 80% |
| kill_switch_mount | PETG | 80% |
| tether_anchor | PETG | 100% |
| led_diffuser_ring (Ø120×15mm) | Clear PETG | 30% |
| esp32c3_mount | PETG | 40% |
**UART @ 460800 baud, 8N1.** Frame: `[0xAA][LEN][TYPE][PAYLOAD…][CRC8]`
## Firmware Architecture
CRC polynomial: CRC-8/MAXIM (poly 0x31, init 0x00, RefIn/RefOut true).
### Critical Lessons Learned (DON'T REPEAT THESE)
Authoritative message type definitions: `esp32/shared/protocol.h`
1. **SysTick_Handler with HAL_IncTick() is MANDATORY** — without it, HAL_Delay() and every HAL timeout hangs forever. This bricked us multiple times.
<<<<<<< HEAD
2. **DCache breaks SPI on ESP32** — disable DCache or use cache-aligned DMA buffers with clean/invalidate. We disable it.
=======
2. **DCache breaks SPI on ESP32-S3** — disable DCache or use cache-aligned DMA buffers with clean/invalidate. We disable it.
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
3. **`-(int)0 == 0`** — checking `if (-result)` to detect errors doesn't work when result is 0 (success and failure look the same). Always use explicit error codes.
4. **NEVER auto-run untested code on_boot** — we bricked the NSPanel 3x doing this. Test manually first.
5. **USB Serial (CH343) needs ReceivePacket() primed in CDC_Init** — without it, the OUT endpoint never starts listening. No data reception.
### DFU Reboot (Betaflight Method)
The firmware supports reboot-to-DFU via USB command:
1. Send `R` byte over USB Serial (CH343)
2. Firmware writes `0xDEADBEEF` to RTC backup register 0
3. `NVIC_SystemReset()` — clean hardware reset
4. On boot, `checkForBootloader()` (called after `HAL_Init()`) reads the magic
<<<<<<< HEAD
5. If magic found: clears it, remaps system memory, jumps to ESP32 BALANCE bootloader at `0x1FF00000`
=======
5. If magic found: clears it, remaps system memory, jumps to ESP32-S3 bootloader at `0x1FF00000`
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
6. Board appears as DFU device, ready for `dfu-util` flash
### Build & Flash
## Build & Flash
```bash
cd firmware/
python3 -m platformio run # Build
dfu-util -a 0 -s 0x08000000:leave -D .pio/build/f722/firmware.bin # Flash
# ESP32-S3 BALANCE
cd esp32/balance
pio run -t upload # Upload via USB (CH343 serial)
# ESP32-S3 IO
cd esp32/io
pio run -t upload # Upload via USB (JTAG/CDC)
```
Dev machine: mbpm4 (seb@192.168.87.40), PlatformIO project at `~/Projects/saltylab-firmware/`
## Critical Lessons Learned
### Clock Configuration
1. **`-(int)0 == 0`** — checking `if (-result)` doesn't detect a zero error result. Use explicit error codes.
2. **NEVER auto-run untested firmware on boot** — we bricked hardware doing this. Test manually first.
3. **One variable at a time** — never change PID gains and speed limit in the same test session.
4. **QMI8658 data ready** — poll INT pin (GPIO3) or use interrupt; don't poll status register in a tight loop.
5. **CAN bus termination** — 120 Ω at each physical end of the bus. Missing termination = unreliable comms.
```
HSE 8MHz → PLL (M=8, N=432, P=2, Q=9) → SYSCLK 216MHz
PLLSAI (N=384, P=8) → CLK48 48MHz (USB)
APB1 = HCLK/4 = 54MHz
APB2 = HCLK/2 = 108MHz
Fallback: HSI 16MHz if HSE fails (PLL M=16)
```
## Current Status & Known Issues
### Working
- USB Serial (CH343) serial streaming (50Hz JSON: `{"ax":...,"ay":...,"az":...,"gx":...,"gy":...,"gz":...}`)
- Clock config with HSE + HSI fallback
- Reboot-to-DFU via USB 'R' command
- LED status patterns (status.c)
- Web UI with WebSerial + Three.js 3D visualization
### Broken / In Progress
- **QMI8658-P SPI reads return all zeros** — was the original IMU target, but SPI communication completely non-functional despite correct pin config. May be dead silicon. Switched to MPU6000 as primary.
- **MPU6000 driver** — header exists but implementation needs completion
- **PID balance loop** — not yet implemented
- **Hoverboard ESC UART** — protocol defined, driver not written
- **ELRS CRSF receiver** — protocol defined, driver not written
- **Barometer (BMP280)** — I2C init hangs, disabled
### TODO (Priority Order)
1. Get MPU6000 streaming accel+gyro data
2. Implement complementary filter (pitch angle)
3. Write hoverboard ESC UART driver
4. Write PID balance loop with safety checks
5. Wire ELRS receiver, implement CRSF parser
6. Bench test (ESC disconnected, verify PID output)
7. First tethered balance test at 10% speed
8. Jetson UART integration
9. LED subsystem (ESP32-C3)
## Communication Protocols
### Jetson → FC (UART1, 50Hz)
```c
struct { uint8_t header=0xAA; int16_t speed; int16_t steer; uint8_t mode; uint8_t checksum; };
// mode: 0=idle, 1=balance, 2=follow, 3=RC
```
### FC → Hoverboard ESC (UART2, loop rate)
```c
struct { uint16_t start=0xABCD; int16_t speed; int16_t steer; uint16_t checksum; };
// speed/steer: -1000 to +1000
```
### FC → Jetson Telemetry (UART1 TX, 50Hz)
```
T:12.3,P:45,L:100,R:-80,S:3\n
// T=tilt°, P=PID output, L/R=motor commands, S=state (0-3)
```
### FC → USB Serial (CH343) (50Hz JSON)
```json
{"ax":123,"ay":-456,"az":16384,"gx":10,"gy":-5,"gz":3,"t":250,"p":0,"bt":0}
// Raw IMU values (int16), t=temp×10, p=pressure, bt=baro temp
```
## LED Subsystem (ESP32-C3)
ESP32-C3 eavesdrops on FC→Jetson telemetry (listen-only tap on UART1 TX). No extra FC UART needed.
## LED States (WS2812B on ESP32-IO)
| State | Pattern | Color |
|-------|---------|-------|
| Disarmed | Slow breathe | White |
| Arming | Fast blink | Yellow |
| Armed idle | Solid | Green |
| Armed | Solid | Green |
| Turning | Sweep direction | Orange |
| Braking | Flash rear | Red |
| Fault | Triple flash | Red |
| Fault / ESTOP | Triple flash | Red |
| RC lost | Alternating flash | Red/Blue |
## Printing (Bambu Lab)
- **X1C** (192.168.87.190) — for structural PETG/ASA parts
- **A1** (192.168.86.161) — for TPU bumpers and prototypes
- LAN access codes and MQTT details in main workspace MEMORY.md
- **X1C** (192.168.87.190) — structural PETG/ASA parts
- **A1** (192.168.86.161) — TPU bumpers, prototypes
- STL export from OpenSCAD, slice in Bambu Studio
## Rules for Agents
1. **Read SALTYLAB.md fully** before making any design decisions
2. **Never remove safety checks** from firmware — add more if needed
3. **All measurements go in `cad/dimensions.scad`** — single source of truth
4. **Test firmware on bench before any motor test** — ESC disconnected, verify outputs on serial
5. **One variable at a time** — don't change PID and speed limit in the same test
6. **Document what you change** — update this file if you add pins, change protocols, or discover hardware quirks
7. **Ask before wiring changes** — wrong connections can fry the FC ($50+ board)
1. **Read `docs/SAUL-TEE-SYSTEM-REFERENCE.md`** fully before any design or firmware decision
2. **Never remove safety checks** — add more if needed
3. **All mechanical measurements go in `cad/dimensions.scad`** — single source of truth
4. **Test firmware on bench first** — VESCs/BTS7960 disconnected, verify outputs on serial
5. **GPIO assignments live in `config.h`** — change there, not scattered in source
6. **Document hardware quirks here** — if you find a gotcha, add a "Critical Lesson Learned"
7. **Ask before wiring changes** — wrong connections can fry ESP32-S3 boards

16
docs/FACE_LCD_ANIMATION.md
View File

@ -1,10 +1,6 @@
# Face LCD Animation System (Issue #507)
<<<<<<< HEAD
Implements expressive face animations on an ESP32 LCD display with 5 core emotions and smooth transitions.
=======
Implements expressive face animations on an ESP32-S3 LCD display with 5 core emotions and smooth transitions.
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
Implements expressive face animations on the ESP32-S3 BALANCE board LCD display (Waveshare Touch LCD 1.28, GC9A01 1.28" round 240×240) with 5 core emotions and smooth transitions.
## Features
@ -86,13 +82,9 @@ STATUS → Echo current emotion + idle state
- Colors: Monochrome (1-bit) or RGB565
### Microcontroller
<<<<<<< HEAD
- ESP32xx (ESP32 BALANCE)
=======
- ESP32-S3xx (ESP32-S3 BALANCE)
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
- Available UART: USART3 (PB10=TX, PB11=RX)
- Clock: 216 MHz
- ESP32-S3 BALANCE (Waveshare Touch LCD 1.28)
- Receives emotion commands from Orin via CAN (0x300 mode byte) or inter-board UART
- Clock: 240 MHz
## Animation Timing

241
docs/SALTYLAB.md
View File

@ -1,6 +1,6 @@
# 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.
## ⚠️ SAFETY — TOP PRIORITY
@ -11,7 +11,7 @@ Four-wheel wagon (870×510×550 mm, 23 kg). Full spec: `docs/SAUL-TEE-SYSTEM-REF
2. **Software tilt cutoff** — if pitch exceeds ±25° (not 30°), motors go to zero immediately. No retry, no recovery. Requires manual re-arm.
3. **Startup arming sequence** — motors NEVER spin on power-on. Requires deliberate arming: hold button for 3 seconds while robot is upright and stable.
4. **Watchdog timeout** — if FC firmware hangs or crashes, hardware watchdog resets to safe state (motors off) within 50ms.
5. **Current limiting** — hoverboard ESC max current set conservatively. Start low, increase gradually.
5. **Current limiting** — VESC max current set conservatively. Start low, increase gradually.
6. **Tether during development** — ceiling rope/strap during ALL balance testing. No free-standing tests until PID is proven stable for 5+ minutes tethered.
7. **Speed limiting** — firmware hard cap on max speed. Start at 10% throttle, increase in 10% increments only after stable testing.
8. **Remote kill** — Jetson can send emergency stop via UART. If Jetson disconnects (UART timeout >200ms), FC cuts motors automatically.
@ -31,8 +31,9 @@ Four-wheel wagon (870×510×550 mm, 23 kg). Full spec: `docs/SAUL-TEE-SYSTEM-REF
| Part | Status |
|------|--------|
| 2x 8" pneumatic hub motors (36 PSI) | ✅ Have |
| 1x hoverboard ESC (FOC firmware) | ✅ Have |
| 1x Drone FC (ESP32-S3 + QMI8658) | ✅ Have — balance brain |
| 2x VESC FSESC 6.7 Pro Mini Dual (left ID 68, right ID 56) | ✅ Have |
| 1x ESP32-S3 BALANCE (Waveshare Touch LCD 1.28) | ⬜ Need — PID loop + CAN master |
| 1x ESP32-S3 IO (bare board) | ⬜ Need — RC / motor / sensor I/O |
| 1x Jetson Orin Nano Super + Noctua fan | ✅ Have |
| 1x RealSense D435i | ✅ Have |
| 1x RPLIDAR A1M8 | ✅ Have |
@ -47,21 +48,24 @@ Four-wheel wagon (870×510×550 mm, 23 kg). Full spec: `docs/SAUL-TEE-SYSTEM-REF
| 1x Arming button (momentary, with LED) | ⬜ Need |
| 1x Ceiling tether strap + carabiner | ⬜ Need |
| 1x BetaFPV ELRS 2.4GHz 1W TX module | ✅ Have — RC control + kill switch |
| 1x ELRS receiver (matching) | ✅ Have — mounts on FC UART |
| 1x ELRS receiver (matching) | ✅ Have — failover RC on ESP32-IO UART2 |
### ESP32-S3 BALANCE Board Details — Waveshare ESP32-S3 Touch LCD 1.28
- **MCU:** ESP32-S3RET6 (Xtensa LX7 dual-core, 240MHz, 8MB Flash, 512KB SRAM)
- **IMU:** QMI8658 (6-axis, 32kHz gyro, ultra-low noise, SPI) ← the good one!
- **Display:** 1.28" round LCD (GC9A01 driver, 240x240)
- **DFU mode:** Hold BOOT button while plugging USB
- **Firmware:** Custom balance firmware (ESP-IDF / Arduino-ESP32)
- **USB:** USB Serial via CH343 chip
- **UART assignments:**
- UART0 → USB Serial (CH343) → debug/flash
- UART1 → Jetson Orin Nano Super
- UART2 → Hoverboard ESC
- UART3 → ELRS receiver
- UART4/5 → spare
### ESP32-S3 BALANCE (Waveshare Touch LCD 1.28)
- **MCU:** ESP32-S3, dual-core 240 MHz, 8MB flash, 8MB PSRAM
- **Display:** 1.28" round GC9A01 240×240 LCD (face animations)
- **IMU:** QMI8658 6-axis (I2C-0 SDA=GPIO6, SCL=GPIO7) — onboard
- **CAN:** SN65HVD230 external transceiver → 500 kbps CAN to VESCs
- **USB:** CH343G bridge (UART0 GPIO43/44) — programming + debug
- **Firmware:** `esp32/balance/` (PlatformIO, Arduino framework)
- **Role:** PID / stability loop, VESC CAN master, inter-board UART to IO board
### ESP32-S3 IO (bare board)
- **USB:** Built-in JTAG/USB-CDC — programming + debug
- **RC:** TBS Crossfire on UART0 (GPIO43/44), ELRS failover on UART2
- **Drive:** 4× BTS7960 H-bridge drivers for hub motors (GPIO TBD)
- **Sensors:** NFC, barometer, ToF distance (shared I2C, GPIO TBD)
- **Outputs:** WS2812B LEDs (RMT), horn, headlight, fan, buzzer
- **Firmware:** `esp32/io/` (PlatformIO, Arduino framework)
## Architecture
@ -73,60 +77,101 @@ Four-wheel wagon (870×510×550 mm, 23 kg). Full spec: `docs/SAUL-TEE-SYSTEM-REF
│ RealSense │ ← Forward-facing depth+RGB
│ D435i │
├──────────────┤
│ Jetson Orin Nano Super │ ← AI brain: navigation, person tracking
│ │ Sends velocity commands via UART
│ Jetson Orin │ ← AI brain: ROS2, SLAM, Nav2
│ Nano Super │ Sends CAN cmds 0x300–0x303
├──────────────┤
│ Drone FC │ ← Balance brain: IMU + PID @ 8kHz
│ F745+MPU6000 │ Custom firmware, UART out to ESC
│ ESP32-S3 │ ← Balance brain: QMI8658 IMU + PID
│ BALANCE │ CAN master to VESCs (SN65HVD230)
├──────────────┤
│ ESP32-S3 IO │ ← RC (CRSF/ELRS), sensors, LEDs
├──────────────┤
│ Battery 36V │
│ + DC-DCs │
├──────┬───────┤
┌─────┤ ESC (FOC) ├─────┐
│ │ Hoverboard │ │
┌─────┤ VESC Left ├─────┐
│ │ (ID 68) │ │
│ │ VESC Right │ │
│ │ (ID 56) │ │
│ └──────────────┘ │
┌──┴──┐ ┌──┴──┐
│ 8" │ │ 8" │
│ LEFT│ │RIGHT│
│ Hub │ │ Hub │
│motor│ │motor│
└─────┘ └─────┘
```
## Self-Balancing Control — ESP32-S3 BALANCE Board
> For full system architecture, firmware details, and protocol specs, see
> **docs/SAUL-TEE-SYSTEM-REFERENCE.md**
The balance controller runs on the Waveshare ESP32-S3 Touch LCD 1.28 board
(ESP32-S3 BALANCE). It reads the onboard QMI8658 IMU at 8kHz, runs a PID
balance loop, and drives the hoverboard ESC via UART. Jetson Orin Nano Super
sends velocity commands over UART1. ELRS receiver on UART3 provides RC
override and kill-switch capability.
The legacy STM32 firmware (Mamba F722S era) has been archived to
=======
The legacy STM32 firmware (STM32 era) has been archived to
`legacy/stm32/` and is no longer built or deployed.
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
## LED Subsystem (ESP32-C3)
## Self-Balancing Control — Custom Firmware on ESP32-S3 BALANCE
### Architecture
The ESP32-C3 eavesdrops on the FC→Jetson telemetry UART line (listen-only, one wire).
No extra UART needed on the FC — zero firmware change.
```
FC UART1 TX ──┬──→ Jetson RX
└──→ ESP32-C3 RX (listen-only, same wire)
│
└──→ WS2812B strip (via RMT peripheral)
Jetson Orin (CAN 0x300–0x303)
│ - Drive cmd: speed + steer
│ - Arm/disarm, PID tune, ESTOP
▼
ESP32-S3 BALANCE (PlatformIO / Arduino)
│ - Reads QMI8658 IMU @ I2C (GPIO6/7)
│ - Runs PID balance loop
│ - Mixes balance correction + Orin velocity cmd
│ - Sends VESC CAN commands (SN65HVD230, 500 kbps)
│ - Inter-board UART @ 460800 → ESP32-S3 IO
▼
VESC Left (CAN ID 68) VESC Right (CAN ID 56)
│ │
FL + RL hub motors FR + RR hub motors
```
### Telemetry Format (already sent by FC at 50Hz)
### Wiring
```
T:12.3,P:45,L:100,R:-80,S:3\n
^-- State byte: 0=disarmed, 1=arming, 2=armed, 3=fault
Jetson Orin CANable 2.0
──────────── ──────────
USB-A ──→ USB-B
CANH ──→ CAN bus CANH
CANL ──→ CAN bus CANL
ESP32-S3 BALANCE SN65HVD230 transceiver
──────────────── ──────────────────────
CAN TX (GPIO TBD) ──→ D pin
CAN RX (GPIO TBD) ←── R pin
CANH ──→ CAN bus CANH
CANL ──→ CAN bus CANL
ESP32-S3 BALANCE ESP32-S3 IO
──────────────── ───────────
UART1 TX (TBD) ──→ UART1 RX (TBD)
UART1 RX (TBD) ←── UART1 TX (TBD)
GND ──→ GND
TBS Crossfire RX ESP32-S3 IO
──────────────── ───────────
TX ──→ GPIO44 (UART0 RX)
RX ←── GPIO43 (UART0 TX)
GND ──→ GND
5V ←── 5V
```
### PID Tuning
| Param | Starting Value | Notes |
|-------|---------------|-------|
| Kp | 30-50 | Main balance response |
| Ki | 0.5-2 | Drift correction |
| Kd | 0.5-2 | Damping oscillation |
| Loop rate | 1 kHz | QMI8658 data-ready driven (GPIO3 INT) |
| Max tilt | ±25° | Beyond this = cut motors, require re-arm |
| CAN_WATCHDOG_MS | 500 | Drop to RC-only if Orin CAN heartbeat lost |
| max_speed_limit | 10% | Start at 10%, increase after stable testing |
| SPEED_TO_ANGLE_FACTOR | 0.01-0.05 | How much lean per speed unit |
## LED Subsystem (ESP32-S3 IO)
### Architecture
WS2812B LEDs are driven directly by the ESP32-S3 IO board via its RMT peripheral.
The IO board receives robot state over inter-board UART from ESP32-S3 BALANCE.
```
ESP32-S3 BALANCE ──UART 460800──→ ESP32-S3 IO
│
└──RMT──→ WS2812B strip
```
ESP32-C3 parses the `S:` field and `L:/R:` for turn detection.
### LED Patterns
| State | Pattern | Color |
@ -140,25 +185,18 @@ ESP32-C3 parses the `S:` field and `L:/R:` for turn detection.
| Fault | Triple flash | Red |
| RC signal lost | Alternating flash | Red/Blue |
### Turn/Brake Detection (on ESP32-C3)
```
if (L - R > threshold) → turning right
if (R - L > threshold) → turning left
if (L < -threshold && R < -threshold) → braking
```
### Wiring
```
FC UART1 TX pin ──→ ESP32-C3 GPIO RX (e.g. GPIO20)
ESP32-C3 GPIO8 ──→ WS2812B data in
ESC 5V BEC ──→ ESP32-C3 5V + WS2812B 5V
GND ──→ Common ground
ESP32-S3 IO RMT GPIO (TBD) ──→ WS2812B data in
5V bus ──→ WS2812B 5V + ESP32-S3 IO VCC
GND ──→ Common ground
```
### Dev Tools
- **Flashing:** ESP32-S3CubeProgrammer via USB (DFU mode) or SWD
- **IDE:** PlatformIO + ESP-IDF, or ESP32-S3CubeIDE
- **Debug:** SWD via ST-Link (or use FC's USB as virtual COM for printf debug)
- **Flashing BALANCE:** `pio run -t upload` in `esp32/balance/` via CH343G USB
- **Flashing IO:** `pio run -t upload` in `esp32/io/` via JTAG/USB-CDC
- **IDE:** PlatformIO + Arduino framework (ESP32)
- **Debug:** USB serial monitor (`pio device monitor`), logic analyzer on UART/CAN
## Physical Design
@ -173,7 +211,7 @@ GND ──→ Common ground
├───────────┤ ├─────────────────┤
│ Jetson │ ~300mm │ [Jetson] │
├───────────┤ ├─────────────────┤
│ Drone FC │ ~200mm │ [Drone FC] │
│ ESP32-S3 │ ~200mm │ [BALANCE] │
├───────────┤ ├─────────────────┤
│ Battery │ ~100mm │ [Battery] │
│ + ESC │ LOW! │ [ESC+DCDC] │
@ -213,7 +251,8 @@ GND ──→ Common ground
| Sensor tower top | 120×120×10 | ASA 80% | 1 |
| LIDAR standoff | Ø80×80 | ASA 40% | 1 |
| RealSense bracket | 100×50×40 | PETG 60% | 1 |
| FC mount (vibration isolated) | 30×30×15 | TPU+PETG | 1 |
| MCU mount — ESP32-S3 BALANCE | TBD×TBD×15 | TPU+PETG | 1 |
| MCU mount — ESP32-S3 IO | TBD×TBD×15 | PETG | 1 |
| Bumper front | 350×50×30 | TPU 30% | 1 |
| Bumper rear | 350×50×30 | TPU 30% | 1 |
| Handle (for carrying) | 150×30×30 | PETG 80% | 1 |
@ -225,14 +264,14 @@ GND ──→ Common ground
## Software Stack
### Jetson Orin Nano Super
- **OS:** JetPack 4.6.1 (Ubuntu 18.04)
- **ROS2 Humble** (or Foxy) for:
- **OS:** JetPack 6.x (Ubuntu 22.04)
- **ROS2 Humble** for:
- `nav2` — navigation stack
- `slam_toolbox` — 2D SLAM from LIDAR
- `realsense-ros` — depth camera
- `rplidar_ros` — LIDAR driver
- **Person following:** SSD-MobileNet-v2 via TensorRT (~20 FPS)
- **Balance commands:** ROS topic → UART bridge to drone FC
- **Person following:** SSD-MobileNet-v2 via TensorRT (~30+ FPS)
- **Balance commands:** ROS topic → CAN bus → ESP32-S3 BALANCE (CANable 2.0, can0, 500 kbps)
### Modes
1. **Idle** — self-balancing in place, waiting for command
@ -251,33 +290,34 @@ GND ──→ Common ground
- [ ] Install hardware kill switch inline with 36V battery (NC — press to kill)
- [ ] Set up ceiling tether point above test area (rated for >15kg)
- [ ] Clear test area: 3m radius, no loose items, shoes on
- [ ] Set up PlatformIO project for ESP32-S3 (ESP-IDF)
- [ ] Write QMI8658 SPI driver (read gyro+accel, complementary filter)
- [ ] Set up PlatformIO projects for ESP32-S3 BALANCE + IO (`esp32/balance/`, `esp32/io/`)
- [ ] Confirm QMI8658 I2C comms on GPIO6/7 (INT on GPIO3); verify IMU data on serial
- [ ] Write PID balance loop with ALL safety checks:
- ±25° tilt cutoff → disarm, require manual re-arm
- Watchdog timer (50ms hardware WDT)
- Speed limit at 10% (max_speed_limit = 100)
- Arming sequence (3s hold while upright)
- [ ] Write hoverboard ESC UART output (speed+steer protocol)
- [ ] Flash firmware via USB DFU (boot0 jumper on FC)
- [ ] Write ELRS CRSF receiver driver (UART3, parse channels + arm switch)
- [ ] Bind ELRS TX ↔ RX, verify channel data on serial monitor
- [ ] Map radio: CH1=steer, CH2=speed, CH5=arm/disarm switch
- [ ] **Bench test first** — FC powered but ESC disconnected, verify IMU reads + PID output + RC channels on serial monitor
- [ ] Wire FC UART2 → hoverboard ESC UART
- [ ] Build minimal frame: motor plate + battery + ESC + FC
- [ ] Power FC from ESC 5V BEC
- CAN watchdog 500 ms (drop to RC-only if Orin silent)
- Speed limit at 10%
- Arming sequence (deliberate ARM command required on power-on)
- [ ] Write VESC CAN commands (SN65HVD230 transceiver, 500 kbps, IDs 68/56)
- [ ] Flash BALANCE via CH343G USB: `cd esp32/balance && pio run -t upload`
- [ ] Write TBS Crossfire CRSF driver on IO board (UART0 GPIO43/44, 420000 baud)
- [ ] Bind TBS TX ↔ RX, verify channel data on IO board serial monitor
- [ ] Map radio: CH1=steer, CH2=speed, CH5=arm/disarm, CH6=mode
- [ ] Flash IO via JTAG/USB-CDC: `cd esp32/io && pio run -t upload`
- [ ] **Bench test first** — BALANCE powered but VESCs disconnected; verify IMU + PID output + RC channels on serial; no motors spin
- [ ] Wire BALANCE CAN TX/RX → SN65HVD230 → CAN bus → VESCs
- [ ] Build minimal frame: motor plate + battery + VESCs + ESP32-S3 boards
- [ ] Power ESP32s from 5V DC-DC
- [ ] **First balance test — TETHERED, kill switch in hand, 10% speed limit**
- [ ] Tune PID at 10% speed until stable tethered for 5+ minutes
- [ ] Gradually increase speed limit (10% increments, 5 min stable each)
### Phase 2: Brain (Week 2)
- [ ] Mount Jetson + power (DC-DC 5V)
- [ ] Mount Jetson Orin Nano Super + power (DC-DC 5V via USB-C PD)
- [ ] Set up JetPack + ROS2
- [ ] Add Jetson UART RX to FC firmware (receive speed+steer commands)
- [ ] Wire Jetson UART1 → FC UART1
- [ ] Python serial bridge: send speed+steer, read telemetry
- [ ] Test: keyboard teleoperation while balancing
- [ ] Bring up CANable 2.0 on Orin: `ip link set can0 up type can bitrate 500000`
- [ ] Send drive CAN frames (0x300) from Orin → BALANCE firmware receives + acts
- [ ] ROS2 node: subscribe to `/cmd_vel`, publish CAN drive frames
- [ ] Test: keyboard teleoperation via ROS2 while balancing
### Phase 3: Senses (Week 3)
- [ ] Mount RealSense + RPLIDAR
@ -287,10 +327,9 @@ GND ──→ Common ground
### Phase 4: Polish (Week 4)
- [ ] Print proper enclosures, bumpers, diffuser ring
- [ ] Wire ESP32-C3 to FC telemetry TX line (listen-only tap)
- [ ] Flash ESP32-C3: parse telemetry, drive WS2812B via RMT
- [ ] Implement WS2812B LED patterns in ESP32-S3 IO firmware (RMT, state from inter-board UART)
- [ ] Mount LED strip around frame with diffuser
- [ ] Test all LED patterns: disarmed/arming/armed/turning/fault
- [ ] Speaker for audio feedback
- [ ] WiFi status dashboard (ESP32-C3 can serve this too)
- [ ] Emergency stop button
- [ ] Test all LED patterns: disarmed/arming/armed/turning/fault/RC-lost
- [ ] Speaker / buzzer audio feedback (IO board GPIO)
- [ ] WiFi status dashboard (serve from Orin or IO board AP)
- [ ] Emergency stop button wired to IO board GPIO → ESTOP CAN frame 0x303

341
docs/board-viz.html
View File

@ -2,7 +2,7 @@
<html>
<head>
<meta charset="utf-8">
<title>GEPRC GEP-F722-45A AIO — Board Layout (Legacy / Archived)</title>
<title>ESP32-S3 BALANCE — Waveshare Touch LCD 1.28 Pinout</title>
<style>
* { margin: 0; padding: 0; box-sizing: border-box; }
body { background: #1a1a2e; color: #eee; font-family: 'Courier New', monospace; display: flex; flex-direction: column; align-items: center; padding: 20px; }
@ -10,274 +10,219 @@ h1 { color: #e94560; margin-bottom: 5px; font-size: 1.4em; }
.subtitle { color: #888; margin-bottom: 20px; font-size: 0.85em; }
.container { display: flex; gap: 30px; align-items: flex-start; flex-wrap: wrap; justify-content: center; }
.board-wrap { position: relative; }
.board { width: 400px; height: 340px; background: #1a472a; border: 3px solid #333; border-radius: 8px; position: relative; box-shadow: 0 0 20px rgba(0,0,0,0.5); }
.board::before { content: 'GEPRC GEP-F722-45A AIO'; position: absolute; top: 8px; left: 50%; transform: translateX(-50%); color: #fff3; font-size: 10px; letter-spacing: 2px; }
.board { width: 400px; height: 380px; background: #1a472a; border: 3px solid #333; border-radius: 50%; position: relative; box-shadow: 0 0 20px rgba(0,0,0,0.5); display: flex; align-items: center; justify-content: center; }
.board::before { content: 'Waveshare Touch LCD 1.28'; position: absolute; top: 30px; left: 50%; transform: translateX(-50%); color: #fff3; font-size: 9px; letter-spacing: 1px; white-space: nowrap; }
/* Mounting holes */
.mount { width: 10px; height: 10px; background: #111; border: 2px solid #555; border-radius: 50%; position: absolute; }
.mount.tl { top: 15px; left: 15px; }
.mount.tr { top: 15px; right: 15px; }
.mount.bl { bottom: 15px; left: 15px; }
.mount.br { bottom: 15px; right: 15px; }
/* LCD circle */
.lcd { width: 180px; height: 180px; background: #111; border: 3px solid #444; border-radius: 50%; position: absolute; display: flex; align-items: center; justify-content: center; font-size: 9px; color: #64B5F6; text-align: center; line-height: 1.6; }
.lcd-inner { text-align: center; }
/* MCU */
.mcu { width: 80px; height: 80px; background: #222; border: 1px solid #555; position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%); display: flex; align-items: center; justify-content: center; font-size: 9px; color: #aaa; text-align: center; line-height: 1.3; }
.mcu .dot { width: 5px; height: 5px; background: #666; border-radius: 50%; position: absolute; top: 4px; left: 4px; }
/* IMU */
.imu { width: 32px; height: 32px; background: #333; border: 1px solid #e94560; position: absolute; top: 85px; left: 60px; display: flex; align-items: center; justify-content: center; font-size: 7px; color: #e94560; }
.imu::after { content: 'CW90°'; position: absolute; bottom: -14px; color: #e94560; font-size: 8px; white-space: nowrap; }
/* Arrow showing CW90 rotation */
.rotation-arrow { position: absolute; top: 72px; left: 55px; color: #e94560; font-size: 18px; }
/* Pads */
.pad { position: absolute; display: flex; align-items: center; gap: 4px; font-size: 10px; cursor: pointer; }
.pad .dot { width: 12px; height: 12px; border-radius: 50%; border: 2px solid; display: flex; align-items: center; justify-content: center; font-size: 7px; font-weight: bold; }
.pad:hover .label { color: #fff; }
.pad .label { transition: color 0.2s; }
.pad .sublabel { font-size: 8px; color: #888; }
/* UART colors */
.uart1 .dot { background: #2196F3; border-color: #64B5F6; }
.uart2 .dot { background: #FF9800; border-color: #FFB74D; }
.uart3 .dot { background: #9C27B0; border-color: #CE93D8; }
.uart4 .dot { background: #4CAF50; border-color: #81C784; }
.uart5 .dot { background: #F44336; border-color: #EF9A9A; }
/* MCU chip */
.mcu-label { position: absolute; top: 95px; left: 50%; transform: translateX(-50%); font-size: 8px; color: #aaa; text-align: center; white-space: nowrap; }
/* Component dots */
.comp { position: absolute; font-size: 9px; display: flex; align-items: center; gap: 4px; }
.comp .icon { width: 10px; height: 10px; border-radius: 2px; }
/* LED */
.led-blue { position: absolute; width: 8px; height: 8px; background: #2196F3; border-radius: 50%; box-shadow: 0 0 8px #2196F3; top: 45px; right: 50px; }
.led-label { position: absolute; top: 36px; right: 30px; font-size: 8px; color: #64B5F6; }
/* Boot button */
.boot-btn { position: absolute; width: 16px; height: 10px; background: #b8860b; border: 1px solid #daa520; border-radius: 2px; bottom: 45px; right: 40px; }
.boot-label { position: absolute; bottom: 32px; right: 30px; font-size: 8px; color: #daa520; }
.comp { position: absolute; font-size: 9px; color: #ccc; }
/* USB */
.usb { position: absolute; width: 30px; height: 14px; background: #444; border: 2px solid #777; border-radius: 3px; bottom: -3px; left: 50%; transform: translateX(-50%); }
.usb-label { position: absolute; bottom: 14px; left: 50%; transform: translateX(-50%); font-size: 8px; color: #999; }
.usb { position: absolute; width: 36px; height: 14px; background: #444; border: 2px solid #777; border-radius: 3px; bottom: 25px; left: 50%; transform: translateX(-50%); }
.usb-label { position: absolute; bottom: 44px; left: 50%; transform: translateX(-50%); font-size: 8px; color: #999; white-space: nowrap; }
/* Connector pads along edges */
/* Bottom row: T1 R1 T3 R3 */
.pad-t1 { bottom: 20px; left: 40px; }
.pad-r1 { bottom: 20px; left: 80px; }
.pad-t3 { bottom: 20px; left: 140px; }
.pad-r3 { bottom: 20px; left: 180px; }
/* Pin rows */
.pin-row { position: absolute; display: flex; flex-direction: column; gap: 4px; }
.pin { display: flex; align-items: center; gap: 4px; font-size: 10px; }
.pin .dot { width: 10px; height: 10px; border-radius: 50%; border: 2px solid; flex-shrink: 0; }
.pin .name { min-width: 70px; }
.pin .sublabel { font-size: 8px; color: #888; }
/* Right side: T2 R2 */
.pad-t2 { right: 20px; top: 80px; flex-direction: row-reverse; }
.pad-r2 { right: 20px; top: 110px; flex-direction: row-reverse; }
/* Left side pins */
.pins-left { left: 10px; top: 60px; }
.pins-left .pin { flex-direction: row; }
/* Top row: T4 R4 T5 R5 */
.pad-t4 { top: 30px; left: 40px; }
.pad-r4 { top: 30px; left: 80px; }
.pad-t5 { top: 30px; right: 100px; flex-direction: row-reverse; }
.pad-r5 { top: 30px; right: 55px; flex-direction: row-reverse; }
/* Right side pins */
.pins-right { right: 10px; top: 60px; }
.pins-right .pin { flex-direction: row-reverse; text-align: right; }
/* ESC pads (motor outputs - not used) */
.esc-pads { position: absolute; left: 20px; top: 140px; }
.esc-pads .esc-label { font-size: 8px; color: #555; }
/* Colors by function */
.imu .dot { background: #e94560; border-color: #ff6b81; }
.can .dot { background: #FF9800; border-color: #FFB74D; }
.uart .dot { background: #2196F3; border-color: #64B5F6; }
.spi .dot { background: #9C27B0; border-color: #CE93D8; }
.pwr .dot { background: #4CAF50; border-color: #81C784; }
.io .dot { background: #607D8B; border-color: #90A4AE; }
/* Legend */
.legend { background: #16213e; padding: 15px 20px; border-radius: 8px; min-width: 280px; }
.legend { background: #16213e; padding: 15px 20px; border-radius: 8px; min-width: 290px; }
.legend h2 { color: #e94560; font-size: 1.1em; margin-bottom: 10px; border-bottom: 1px solid #333; padding-bottom: 5px; }
.legend-item { display: flex; align-items: center; gap: 8px; margin: 6px 0; font-size: 12px; }
.legend-item .swatch { width: 14px; height: 14px; border-radius: 50%; flex-shrink: 0; }
.legend-item .arrow { color: #888; font-size: 10px; }
.legend-section { margin-top: 12px; padding-top: 8px; border-top: 1px solid #333; }
.legend-section h3 { font-size: 0.9em; color: #888; margin-bottom: 6px; }
/* Orientation guide */
.orient { margin-top: 20px; background: #16213e; padding: 15px 20px; border-radius: 8px; width: 100%; max-width: 710px; }
.orient h2 { color: #4CAF50; font-size: 1.1em; margin-bottom: 10px; }
.orient-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 10px; }
.orient-item { font-size: 12px; padding: 6px 10px; background: #1a1a2e; border-radius: 4px; }
.orient-item .dir { color: #4CAF50; font-weight: bold; }
/* Axis overlay */
.axis { position: absolute; }
.axis-x { top: 50%; right: -60px; color: #F44336; font-size: 12px; font-weight: bold; }
.axis-y { bottom: -30px; left: 50%; transform: translateX(-50%); color: #4CAF50; font-size: 12px; font-weight: bold; }
.axis-arrow-x { position: absolute; top: 50%; right: -45px; transform: translateY(-50%); width: 30px; height: 2px; background: #F44336; }
.axis-arrow-x::after { content: '▶'; position: absolute; right: -12px; top: -8px; color: #F44336; }
.axis-arrow-y { position: absolute; bottom: -20px; left: 50%; transform: translateX(-50%); width: 2px; height: 20px; background: #4CAF50; }
.axis-arrow-y::after { content: '▼'; position: absolute; bottom: -14px; left: -5px; color: #4CAF50; }
.note { margin-top: 15px; color: #888; font-size: 11px; text-align: center; max-width: 710px; }
.note em { color: #e94560; font-style: normal; }
</style>
</head>
<body>
<<<<<<< HEAD
<h1>🤖 GEPRC GEP-F722-45A AIO — SaltyLab Pinout (Legacy / Archived)</h1>
<p class="subtitle">ESP32RET6 + ICM-42688-P | Betaflight target: GEPR-GEPRC_F722_AIO</p>
=======
<h1>🤖 GEPRC GEP-F722-45A AIO — SaltyLab Pinout</h1>
<p class="subtitle">ESP32-S3RET6 + ICM-42688-P | Betaflight target: GEPR-GEPRC_F722_AIO</p>
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
<h1>🤖 ESP32-S3 BALANCE — Waveshare Touch LCD 1.28</h1>
<p class="subtitle">ESP32-S3 240 MHz | QMI8658 IMU | GC9A01 1.28″ LCD | CH343G USB-UART | SN65HVD230 CAN</p>
<div class="container">
<div class="board-wrap">
<div class="board">
<!-- Mounting holes -->
<div class="mount tl"></div>
<div class="mount tr"></div>
<div class="mount bl"></div>
<div class="mount br"></div>
<!-- LCD circle -->
<div class="lcd">
<div class="lcd-inner">GC9A01<br>1.28″ round<br>240×240<br>SPI</div>
</div>
<div class="mcu-label">ESP32-S3<br>240 MHz / 8MB</div>
<!-- MCU -->
<<<<<<< HEAD
<div class="mcu"><div class="dot"></div>ESP32<br>(legacy:<br>F722RET6)</div>
=======
<div class="mcu"><div class="dot"></div>ESP32-S3<br>F722RET6<br>216MHz</div>
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
<!-- IMU -->
<div class="imu">ICM<br>42688</div>
<div class="rotation-arrow">↻</div>
<!-- LED -->
<div class="led-blue"></div>
<div class="led-label">LED PC4</div>
<!-- Boot button -->
<div class="boot-btn"></div>
<div class="boot-label">BOOT 🟡</div>
<!-- USB -->
<!-- USB CH343G -->
<div class="usb-label">USB-A CH343G (UART0 debug/flash)</div>
<div class="usb"></div>
<div class="usb-label">USB-C (DFU)</div>
<!-- UART Pads - Bottom -->
<div class="pad pad-t1 uart1">
<div class="dot">T</div>
<span class="label">T1<br><span class="sublabel">PA9</span></span>
</div>
<div class="pad pad-r1 uart1">
<div class="dot">R</div>
<span class="label">R1<br><span class="sublabel">PA10</span></span>
</div>
<div class="pad pad-t3 uart3">
<div class="dot">T</div>
<span class="label">T3<br><span class="sublabel">PB10</span></span>
</div>
<div class="pad pad-r3 uart3">
<div class="dot">R</div>
<span class="label">R3<br><span class="sublabel">PB11</span></span>
<!-- Left-side pins (onboard fixed) -->
<div class="pin-row pins-left">
<div class="pin imu">
<div class="dot"></div>
<span class="name">GPIO6</span>
<span class="sublabel">IMU SDA (I2C-0)</span>
</div>
<div class="pin imu">
<div class="dot"></div>
<span class="name">GPIO7</span>
<span class="sublabel">IMU SCL (I2C-0)</span>
</div>
<div class="pin imu">
<div class="dot"></div>
<span class="name">GPIO3</span>
<span class="sublabel">QMI8658 INT</span>
</div>
<div class="pin uart">
<div class="dot"></div>
<span class="name">GPIO43</span>
<span class="sublabel">UART0 TX (CH343G)</span>
</div>
<div class="pin uart">
<div class="dot"></div>
<span class="name">GPIO44</span>
<span class="sublabel">UART0 RX (CH343G)</span>
</div>
<div class="pin uart">
<div class="dot"></div>
<span class="name">UART1 TX</span>
<span class="sublabel">Inter-board → IO (TBD)</span>
</div>
<div class="pin uart">
<div class="dot"></div>
<span class="name">UART1 RX</span>
<span class="sublabel">Inter-board ← IO (TBD)</span>
</div>
</div>
<!-- UART Pads - Right -->
<div class="pad pad-t2 uart2">
<span class="label">T2<br><span class="sublabel">PA2</span></span>
<div class="dot">T</div>
<!-- Right-side pins (external) -->
<div class="pin-row pins-right">
<div class="pin can">
<div class="dot"></div>
<span class="name">CAN TX</span>
<span class="sublabel">→ SN65HVD230 D (TBD)</span>
</div>
<div class="pin can">
<div class="dot"></div>
<span class="name">CAN RX</span>
<span class="sublabel">← SN65HVD230 R (TBD)</span>
</div>
<div class="pin spi">
<div class="dot"></div>
<span class="name">LCD SPI</span>
<span class="sublabel">GC9A01 (onboard)</span>
</div>
<div class="pin pwr">
<div class="dot"></div>
<span class="name">5V</span>
<span class="sublabel">USB / ext 5V in</span>
</div>
<div class="pin pwr">
<div class="dot"></div>
<span class="name">3.3V</span>
<span class="sublabel">LDO out</span>
</div>
<div class="pin pwr">
<div class="dot"></div>
<span class="name">GND</span>
<span class="sublabel">Common ground</span>
</div>
</div>
<div class="pad pad-r2 uart2">
<span class="label">R2<br><span class="sublabel">PA3</span></span>
<div class="dot">R</div>
</div>
<!-- UART Pads - Top -->
<div class="pad pad-t4 uart4">
<div class="dot">T</div>
<span class="label">T4<br><span class="sublabel">PC10</span></span>
</div>
<div class="pad pad-r4 uart4">
<div class="dot">R</div>
<span class="label">R4<br><span class="sublabel">PC11</span></span>
</div>
<div class="pad pad-t5 uart5">
<span class="label">T5<br><span class="sublabel">PC12</span></span>
<div class="dot">T</div>
</div>
<div class="pad pad-r5 uart5">
<span class="label">R5<br><span class="sublabel">PD2</span></span>
<div class="dot">R</div>
</div>
<!-- ESC motor pads label -->
<div class="esc-pads">
<div class="esc-label">M1-M4 (unused)<br>PC6-PC9</div>
</div>
<!-- Board axes -->
<div class="axis-arrow-x"></div>
<div class="axis axis-x">X →<br><span style="font-size:9px;color:#888">board right</span></div>
<div class="axis-arrow-y"></div>
<div class="axis axis-y">Y ↓ (board forward = tilt axis)</div>
</div>
</div>
<div class="legend">
<h2>🔌 UART Assignments</h2>
<h2>📌 Pin Assignments</h2>
<div class="legend-item">
<div class="swatch" style="background:#2196F3"></div>
<span><b>USART1</b> T1/R1 → Jetson Orin Nano Super</span>
<div class="swatch" style="background:#e94560"></div>
<span><b>IMU (QMI8658)</b> — I2C-0 SDA=GPIO6, SCL=GPIO7, INT=GPIO3</span>
</div>
<div class="legend-item">
<div class="swatch" style="background:#FF9800"></div>
<span><b>USART2</b> T2 → Hoverboard ESC (TX only)</span>
<span><b>CAN (SN65HVD230)</b> — TX/RX TBD; confirm in <code>esp32/balance/src/config.h</code></span>
</div>
<div class="legend-item">
<div class="swatch" style="background:#2196F3"></div>
<span><b>UART0</b> GPIO43/44 — CH343G USB bridge (debug + flash)</span>
</div>
<div class="legend-item">
<div class="swatch" style="background:#2196F3"></div>
<span><b>UART1</b> TBD — Inter-board @ 460800 baud → ESP32-S3 IO</span>
</div>
<div class="legend-item">
<div class="swatch" style="background:#9C27B0"></div>
<span><b>I2C2</b> T3/R3 → Baro/Mag (reserved)</span>
<span><b>LCD SPI</b> — GC9A01 1.28″ round 240×240 (onboard, fixed pins)</span>
</div>
<div class="legend-item">
<div class="swatch" style="background:#4CAF50"></div>
<span><b>UART4</b> T4/R4 → ELRS RX (CRSF)</span>
</div>
<div class="legend-item">
<div class="swatch" style="background:#F44336"></div>
<span><b>UART5</b> T5/R5 → Debug/spare</span>
<span><b>Power</b> — 5V USB input; 3.3V LDO for logic + sensors</span>
</div>
<div class="legend-section">
<h3>📡 SPI Bus</h3>
<h3>🔌 CAN Bus Topology</h3>
<div class="legend-item">
<span>SPI1: PA5/PA6/PA7 → IMU (CS: <em style="color:#e94560">PA15</em>)</span>
<span>Orin → CANable 2.0 → <b>CANH/CANL</b> (500 kbps)</span>
</div>
<div class="legend-item">
<span>SPI2: PB13-15 → OSD MAX7456</span>
<span>BALANCE: SN65HVD230 on CAN bus</span>
</div>
<div class="legend-item">
<span>SPI3: PB3-5 → Flash W25Q128</span>
<span>VESC Left: ID <b>0x44</b> (68) | VESC Right: ID <b>0x38</b> (56)</span>
</div>
<div class="legend-item">
<span>120 Ω termination at each bus end</span>
</div>
</div>
<div class="legend-section">
<h3>⚡ Other</h3>
<h3>📡 Inter-Board Protocol</h3>
<div class="legend-item">
<span>🔵 LED: PC4 | 📢 Beeper: PC15</span>
<span>UART @ 460800 baud, 8N1</span>
</div>
<div class="legend-item">
<span>🔋 VBAT: PC2 | ⚡ Current: PC1</span>
<span>Frame: <code>[0xAA][LEN][TYPE][PAYLOAD][CRC8]</code></span>
</div>
<div class="legend-item">
<span>💡 LED Strip: PA1 (WS2812)</span>
</div>
<div class="legend-item">
<span>📍 EXTI (IMU data-ready): PA8</span>
<span>Types: see <code>esp32/shared/protocol.h</code></span>
</div>
</div>
</div>
</div>
<div class="orient">
<h2>🧭 IMU Orientation (CW90° from chip to board)</h2>
<div class="orient-grid">
<div class="orient-item"><span class="dir">Board Forward</span> (tilt for balance) = Chip's +Y axis</div>
<div class="orient-item"><span class="dir">Board Right</span> = Chip's -X axis</div>
<div class="orient-item"><span class="dir">Board Pitch Rate</span> = -Gyro X (raw)</div>
<div class="orient-item"><span class="dir">Board Accel Forward</span> = Accel Y (raw)</div>
<div class="legend-section">
<h3>⚡ Safety</h3>
<div class="legend-item"><span>Motors NEVER spin on power-on — ARM required</span></div>
<div class="legend-item"><span>RC kill switch checked every loop</span></div>
<div class="legend-item"><span>CAN watchdog: 500 ms → RC-only mode</span></div>
<div class="legend-item"><span>ESTOP: CAN 0x303 + 0xE5 → all motors off</span></div>
</div>
</div>
</div>
<p class="note">
⚠️ Pad positions are <em>approximate</em> — check the physical board silkscreen for exact locations.
The CW90 rotation is handled in firmware (mpu6000.c). USB-C at bottom edge for DFU flashing.
⚠️ CAN TX/RX GPIO assignments are <em>TBD</em> — confirm in <code>esp32/balance/src/config.h</code> before wiring.
All inter-board UART GPIO also TBD. LCD and IMU pins are fixed by Waveshare hardware.
</p>
</body>

443
docs/wiring-diagram.md
View File

@ -1,212 +1,174 @@
# SaltyLab / SAUL-TEE Wiring Reference
# SAUL-TEE Wiring Reference
> ⚠️ **ARCHITECTURE CHANGE (2026-04-03):** Mamba F722S / STM32 retired.
> New stack: **ESP32-S3 BALANCE** + **ESP32-S3 IO** + VESCs on 500 kbps CAN.
> **Authoritative reference:** [`docs/SAUL-TEE-SYSTEM-REFERENCE.md`](SAUL-TEE-SYSTEM-REFERENCE.md)
> Historical STM32/Mamba wiring below is **obsolete** — retained for reference only.
**Authoritative reference:** [`docs/SAUL-TEE-SYSTEM-REFERENCE.md`](SAUL-TEE-SYSTEM-REFERENCE.md)
This document is a quick-access wiring summary. For pin assignments, CAN frame formats,
RC channel mapping, and serial commands, see the full reference doc.
---
## ~~System Overview~~ (OBSOLETE — see SAUL-TEE-SYSTEM-REFERENCE.md)
## System Block Diagram
```
┌─────────────────────────────────────────────────────────────────────┐
│ ORIN NANO SUPER │
│ (Top Plate — 25W) │
│ │
<<<<<<< HEAD
│ USB-A ──── CANable2 USB-CAN adapter (slcan0, 500 kbps) │
│ USB-A ──── ESP32-S3 IO (/dev/esp32-io, 460800 baud) │
=======
│ USB-C ──── ESP32-S3 CDC (/dev/esp32-bridge, 921600 baud) │
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
│ USB-A1 ─── RealSense D435i (USB 3.1) │
│ USB-A2 ─── RPLIDAR A1M8 (via CP2102 adapter, 115200) │
│ USB-C* ─── SIM7600A 4G/LTE modem (ttyUSB0-2, AT cmds + PPP) │
│ USB ─────── Leap Motion Controller (hand/gesture tracking) │
│ CSI-A ──── ArduCam adapter → 2x IMX219 (front + left) │
│ CSI-B ──── ArduCam adapter → 2x IMX219 (rear + right) │
│ M.2 ───── 1TB NVMe SSD │
│ 40-pin ─── ReSpeaker 2-Mic HAT (I2S + I2C, WM8960 codec) │
│ Pin 8 ──┐ │
│ Pin 10 ─┤ UART fallback to ESP32-S3 BALANCE (ttyTHS0, 460800) │
│ Pin 6 ──┘ GND │
│ │
└─────────────────────────────────────────────────────────────────────┘
│ USB-A (CANable2) │ UART fallback (3 wires)
│ SocketCAN slcan0 │ 460800 baud, 3.3V
│ 500 kbps │
▼ ▼
┌─────────────────────────────────────────────────────────────────────┐
<<<<<<< HEAD
│ ESP32-S3 BALANCE │
│ (Waveshare Touch LCD 1.28, Middle Plate) │
=======
│ ESP32-S3 BALANCE (FC) │
│ (Middle Plate — foam mounted) │
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
│ │
│ CAN bus ──── CANable2 → Orin (primary link, ISO 11898) │
│ UART0 ──── Orin UART fallback (460800 baud, 3.3V) │
│ UART1 ──── VESC Left (CAN ID 56) via UART/CAN bridge │
│ UART2 ──── VESC Right (CAN ID 68) via UART/CAN bridge │
│ I2C ──── QMI8658 IMU (onboard, 6-DOF accel+gyro) │
│ SPI ──── GC9A01 LCD (onboard, 240x240 round display) │
│ GPIO ──── WS2812B LED strip │
│ GPIO ──── Buzzer │
│ ADC ──── Battery voltage divider │
│ │
└─────────────────────────────────────────────────────────────────────┘
│ CAN bus (ISO 11898) │ UART (460800 baud)
│ 500 kbps │
▼ ▼
┌────────────────────────┐ ┌──────────────────────────┐
│ VESC Left (ID 56) │ │ VESC Right (ID 68) │
│ (Bottom Plate) │ │ (Bottom Plate) │
│ │ │ │
│ BLDC hub motor │ │ BLDC hub motor │
│ CAN 500 kbps │ │ CAN 500 kbps │
│ FOC current control │ │ FOC current control │
│ VESC Status 1 (0x900) │ │ VESC Status 1 (0x910) │
│ │ │ │
└────────────────────────┘ └──────────────────────────┘
│ │
LEFT MOTOR RIGHT MOTOR
┌──────────────────────────────────────────────────────────┐
│ 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 (front + left) │
│ CSI-B ─── 2× IMX219 cameras (rear + right) │
│ 40-pin ── ReSpeaker 2-Mic HAT │
└──────────────────────┬───────────────────────────────────┘
│ USB-A → CANable 2.0
│ can0, 500 kbps
┌────────────────────────────────┴──────────────────────────────────┐
│ CAN BUS (CANH / CANL / GND) │
│ 120 Ω ─┤ ├─ 120 Ω │
└───────────┬──────────────────────────────────────────┬────────────┘
│ │
┌───────────┴────────────┐ ┌─────────────┴──────────┐
│ ESP32-S3 BALANCE │ │ VESC left (ID 68) │
│ Waveshare Touch LCD │ │ VESC right (ID 56) │
│ 1.28 — CH343 USB │ │ FSESC 6.7 Pro Mini │
│ │ │ Dual │
│ QMI8658 IMU (I2C) │ └──────┬─────────────────┘
│ SN65HVD230 (CAN) │ │ Phase wires
│ │ ┌────────┴─────────────┐
│ UART ──────────────┐ │ │ Hub motors (4×) │
└────────────────────────┘ │ FL / FR / RL / RR │
↕ 460800 baud binary │ └──────────────────────┘
inter-board proto │
┌───────────────────────┘
│ ESP32-S3 IO (bare board)
│ JTAG USB
│
│ UART0 ── TBS Crossfire RX (CRSF @ 420000)
│ UART2 ── ELRS receiver (CRSF failover @ 420000)
│ PWM ──── 4× BTS7960 H-bridge motor drivers
│ I2C ──── NFC + Barometer + ToF (shared bus)
│ RMT ──── WS2812B LED strip
│ GPIO ─── Horn / Headlight / Fan / Buzzer
└──────────────────────────────────────────────
```
---
## Wire-by-Wire Connections
<<<<<<< HEAD
### 1. Orin <-> ESP32-S3 BALANCE (Primary: CAN Bus via CANable2)
=======
### 1. Orin ↔ FC (Primary: USB Serial (CH343))
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
| From | To | Wire | Notes |
|------|----|------|-------|
| Orin USB-A | CANable2 USB | USB cable | SocketCAN slcan0 @ 500 kbps |
| CANable2 CAN-H | ESP32-S3 BALANCE CAN-H | twisted pair | ISO 11898 differential |
| CANable2 CAN-L | ESP32-S3 BALANCE CAN-L | twisted pair | ISO 11898 differential |
<<<<<<< HEAD
- Interface: SocketCAN `slcan0`, 500 kbps
- Device node: `/dev/canable2` (via udev, symlink to ttyUSBx)
- Protocol: CAN frames --- ORIN_CMD_DRIVE (0x300), ORIN_CMD_MODE (0x301), ORIN_CMD_ESTOP (0x302)
- Telemetry: BALANCE_STATUS (0x400), BALANCE_VESC (0x401), BALANCE_IMU (0x402), BALANCE_BATTERY (0x403)
=======
- Device: `/dev/ttyACM0` → symlink `/dev/esp32-bridge`
- Baud: 921600, 8N1
- Protocol: JSON telemetry (FC→Orin), ASCII commands (Orin→FC)
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
### 2. Orin <-> ESP32-S3 BALANCE (Fallback: Hardware UART)
| Orin Pin | Signal | ESP32-S3 Pin | Notes |
|----------|--------|--------------|-------|
| Pin 8 | TXD0 | GPIO17 (UART0 RX) | Orin TX -> BALANCE RX |
| Pin 10 | RXD0 | GPIO18 (UART0 TX) | Orin RX <- BALANCE TX |
| Pin 6 | GND | GND | Common ground |
- Jetson device: `/dev/ttyTHS0`
- Baud: 460800, 8N1
- Voltage: 3.3V both sides (no level shifter needed)
- Cross-connect: Orin TX -> BALANCE RX, Orin RX <- BALANCE TX
### 3. Orin <-> ESP32-S3 IO (USB Serial)
### 1. Orin ↔ CAN Bus (via CANable 2.0)
| From | To | Notes |
|------|----|-------|
| Orin USB-A | ESP32-S3 IO USB-C | USB cable, /dev/esp32-io |
| Orin USB-A | CANable 2.0 USB | `/dev/canable0` → `can0` |
| CANable CANH | CAN bus CANH | Twisted pair |
| CANable CANL | CAN bus CANL | Twisted pair |
| CANable GND | CAN GND | Common |
- Device node: `/dev/esp32-io` (udev symlink)
- Baud: 460800, 8N1
- Protocol: Binary frames `[0xAA][LEN][TYPE][PAYLOAD][CRC8]`
- Use: IO expansion, GPIO control, sensor polling
Setup: `ip link set can0 up type can bitrate 500000`
### 4. ESP32-S3 BALANCE <-> VESC Motors (CAN Bus)
### 2. ESP32-S3 BALANCE ↔ CAN Bus
| BALANCE Pin | Signal | VESC Pin | Notes |
|-------------|--------|----------|-------|
| GPIO21 | CAN-H | CAN-H | ISO 11898 differential pair |
| GPIO22 | CAN-L | CAN-L | ISO 11898 differential pair |
| GND | GND | GND | Common ground |
| Signal | GPIO | CAN bus |
|--------|------|---------|
| CAN TX | TBD | → SN65HVD230 D pin |
| CAN RX | TBD | ← SN65HVD230 R pin |
- Baud: 500 kbps CAN
- VESC Left: CAN ID 56, VESC Right: CAN ID 68
- Commands: COMM_SET_RPM, COMM_SET_CURRENT, COMM_SET_DUTY
- Telemetry: VESC Status 1 at 50 Hz (RPM, current, duty)
> TBD pins — confirm in `esp32/balance/src/config.h`
### 5. Power Distribution
### 3. ESP32-S3 BALANCE ↔ ESP32-S3 IO (Inter-Board UART)
| Signal | BALANCE GPIO | IO GPIO | Baud |
|--------|-------------|---------|------|
| TX | TBD | TBD (RX) | 460800 |
| RX | TBD (RX) | TBD (TX) | 460800 |
| GND | GND | GND | — |
Frame: `[0xAA][LEN][TYPE][PAYLOAD…][CRC8]` — see `esp32/shared/protocol.h`
### 4. ESP32-S3 IO ↔ TBS Crossfire RX (UART0)
| IO GPIO | Signal | Crossfire pin | Notes |
|---------|--------|---------------|-------|
| GPIO43 | TX | RX | CRSF telemetry to TX module |
| GPIO44 | RX | TX | CRSF RC frames in |
| GND | GND | GND | |
| 5V | — | VCC | Power from 5V bus |
Baud: 420000 (CRSF). Failsafe: disarm after 300 ms without frame.
### 5. ESP32-S3 IO ↔ ELRS Receiver (UART2, failover)
| IO GPIO | Signal | ELRS pin |
|---------|--------|----------|
| TBD | TX | RX |
| TBD | RX | TX |
| GND | GND | GND |
| 5V | — | VCC |
Baud: 420000 (CRSF). Activates automatically if Crossfire link lost >300 ms.
### 6. ESP32-S3 IO ↔ BTS7960 Motor Drivers (4×)
TBD GPIO assignments — see `esp32/io/src/config.h`.
| Signal | Per-driver | Notes |
|--------|-----------|-------|
| RPWM | GPIO TBD | Forward PWM |
| LPWM | GPIO TBD | Reverse PWM |
| R_EN | GPIO TBD | Enable H |
| L_EN | GPIO TBD | Enable H |
| Motor+ / Motor− | Hub motor | 36V via B+ / B− on BTS7960 |
### 7. ESP32-S3 IO I2C Sensors
| Device | I2C Address | Notes |
|--------|-------------|-------|
| NFC (PN532) | 0x24 | NFC tag read/write |
| Barometer (BMP280/388) | 0x76 | Altitude + temp |
| ToF range (VL53L0X) | 0x29 | Proximity/obstacle |
> SDA / SCL GPIOs TBD — confirm in `esp32/io/src/config.h`
### 8. Power Distribution
```
BATTERY (36V) ──┬── VESC Left (36V direct -> BLDC left motor)
├── VESC Right (36V direct -> BLDC right motor)
│
├── 5V BEC/regulator ──┬── Orin (USB-C PD or barrel jack)
│ ├── ESP32-S3 BALANCE (5V via USB-C)
│ ├── ESP32-S3 IO (5V via USB-C)
│ ├── WS2812B LEDs (5V)
│ └── RPLIDAR (5V via USB)
│
└── Battery monitor ──── ESP32-S3 BALANCE ADC (voltage divider)
36V BATTERY
│
├── VESC left (36V) ─── Front-left + Rear-left hub motors
├── VESC right (36V) ─── Front-right + Rear-right hub motors
├── BTS7960 boards (B+/B−) — 36V motor power
│
├── DC-DC 12V ──── Fan / Headlight / Accessories
│
└── DC-DC 5V ─┬── Jetson Orin (USB-C PD)
├── ESP32-S3 BALANCE (USB 5V)
├── ESP32-S3 IO (USB 5V)
├── TBS Crossfire RX (5V)
├── ELRS RX (5V)
├── WS2812B strip (5V)
├── RPLIDAR A1M8 (5V via USB)
└── Sensors (3.3V from ESP32-IO LDO)
```
### 6. Sensors on Orin (USB/CSI)
---
| Device | Interface | Orin Port | Device Node |
|--------|-----------|-----------|-------------|
| RealSense D435i | USB 3.1 | USB-A (blue) | `/dev/bus/usb/...` |
| RPLIDAR A1M8 | USB-UART | USB-A | `/dev/rplidar` |
| IMX219 front+left | MIPI CSI-2 | CSI-A (J5) | `/dev/video0,2` |
| IMX219 rear+right | MIPI CSI-2 | CSI-B (J8) | `/dev/video4,6` |
| 1TB NVMe | PCIe Gen3 x4 | M.2 Key M | `/dev/nvme0n1` |
| CANable2 | USB-CAN | USB-A | `/dev/canable2` -> `slcan0` |
## Orin USB Peripherals
| Device | Interface | Node |
|--------|-----------|------|
| CANable 2.0 | USB-A | `can0` (after `ip link set can0 up type can bitrate 500000`) |
| RealSense D435i | USB 3.1 | `/dev/bus/usb/...` |
| RPLIDAR A1M8 | USB-UART | `/dev/rplidar` |
| SIM7600A 4G | USB | `/dev/ttyUSB0–2` |
| ESP32-S3 BALANCE debug | USB-A (CH343) | `/dev/esp32-balance` |
| ESP32-S3 IO debug | USB-A (JTAG/CDC) | `/dev/esp32-io` |
<<<<<<< HEAD
## FC UART Summary (MAMBA F722S — OBSOLETE)
---
| Interface | Pins | Baud/Rate | Assignment | Notes |
|-----------|------|-----------|------------|-------|
| UART0 | GPIO17=RX, GPIO18=TX | 460800 | Orin UART fallback | 3.3V, cross-connect |
| UART1 | GPIO19=RX, GPIO20=TX | 115200 | Debug serial | Optional |
| CAN (TWAI) | GPIO21=H, GPIO22=L | 500 kbps | CAN bus (VESCs + Orin) | SN65HVD230 transceiver |
| I2C | GPIO4=SDA, GPIO5=SCL | 400 kHz | QMI8658 IMU (addr 0x6B) | Onboard |
| SPI | GPIO36=MOSI, GPIO37=SCLK, GPIO35=CS | 40 MHz | GC9A01 LCD (onboard) | 240x240 round |
| USB CDC | USB-C | 460800 | Orin USB fallback | /dev/esp32-balance |
## CAN Frame ID Map
| CAN ID | Direction | Name | Contents |
|--------|-----------|------|----------|
| 0x300 | Orin -> BALANCE | ORIN_CMD_DRIVE | left_rpm_f32, right_rpm_f32 (8 bytes LE) |
| 0x301 | Orin -> BALANCE | ORIN_CMD_MODE | mode byte (0=IDLE, 1=DRIVE, 2=ESTOP) |
| 0x302 | Orin -> BALANCE | ORIN_CMD_ESTOP | flags byte (bit0=stop, bit1=clear) |
| 0x400 | BALANCE -> Orin | BALANCE_STATUS | pitch x10:i16, motor_cmd:u16, vbat_mv:u16, state:u8, flags:u8 |
| 0x401 | BALANCE -> Orin | BALANCE_VESC | l_rpm x10:i16, r_rpm x10:i16, l_cur x10:i16, r_cur x10:i16 |
| 0x402 | BALANCE -> Orin | BALANCE_IMU | pitch x100:i16, roll x100:i16, yaw x100:i16, ax x100:i16, ay x100:i16, az x100:i16 |
| 0x403 | BALANCE -> Orin | BALANCE_BATTERY | vbat_mv:u16, current_ma:i16, soc_pct:u8 |
| 0x900+ID | VESC Left -> | VESC_STATUS_1 | erpm:i32, current x10:i16, duty x1000:i16 |
| 0x910+ID | VESC Right -> | VESC_STATUS_1 | erpm:i32, current x10:i16, duty x1000:i16 |
VESC Left CAN ID = 56 (0x38), VESC Right CAN ID = 68 (0x44).
=======
## FC UART Summary (ESP32-S3 BALANCE)
| UART | Pins | Baud | Assignment | Notes |
|------|------|------|------------|-------|
| USART1 | PB6=TX, PB7=RX | — | SmartAudio/VTX | Unused in SaltyLab |
| USART2 | PA2=TX, PA3=RX | 26400 | Hoverboard ESC | Binary motor commands |
| USART3 | PB10=TX, PB11=RX | — | Available | Was SBUS default |
| UART4 | PA0=TX, PA1=RX | 420000 | ELRS RX (CRSF) | RC control |
| UART5 | PC12=TX, PD2=RX | 115200 | Debug serial | Optional |
| USART6 | PC6=TX, PC7=RX | 921600 | Jetson UART | Fallback link |
| USB Serial (CH343) | USB-C | 921600 | Jetson primary | `/dev/esp32-bridge` |
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
### 7. ReSpeaker 2-Mic HAT (on Orin 40-pin header)
## ReSpeaker 2-Mic HAT (Orin 40-pin)
| Orin Pin | Signal | Function |
|----------|--------|----------|
@ -214,117 +176,20 @@ VESC Left CAN ID = 56 (0x38), VESC Right CAN ID = 68 (0x44).
| Pin 35 (GPIO 19) | I2S LRCLK | Audio left/right clock |
| Pin 38 (GPIO 20) | I2S DIN | Audio data in (from mics) |
| Pin 40 (GPIO 21) | I2S DOUT | Audio data out (to speaker) |
| Pin 3 (GPIO 2) | I2C SDA | WM8960 codec control (i2c-7) |
| Pin 5 (GPIO 3) | I2C SCL | WM8960 codec control (i2c-7) |
| Pin 32 (GPIO 12) | GPIO | Button input |
| Pin 11 (GPIO 17) | GPIO | RGB LED (APA102 data) |
| Pin 3 (GPIO 2) | I2C SDA | WM8960 codec (i2c-7) |
| Pin 5 (GPIO 3) | I2C SCL | WM8960 codec (i2c-7) |
| Pin 2, 4 | 5V | Power |
| Pin 6, 9 | GND | Ground |
- Codec: Wolfson WM8960 (I2C addr 0x1A)
- Mics: 2x MEMS (left + right) --- basic stereo / sound localization
- Speaker: 3W class-D amp output (JST connector)
- Headset: 3.5mm TRRS jack
- Requires: WM8960 device tree overlay for Jetson (community port)
- Use: Voice commands (faster-whisper), wake word (openWakeWord), audio feedback, status announcements
### 8. SIM7600A 4G/LTE HAT (via USB)
| Connection | Detail |
|-----------|--------|
| Interface | USB (micro-B on HAT -> USB-A/C on Orin) |
| Device nodes | `/dev/ttyUSB0` (AT), `/dev/ttyUSB1` (PPP/data), `/dev/ttyUSB2` (GPS NMEA) |
| Power | 5V from USB or separate 5V supply (peak 2A during TX) |
| SIM | Nano-SIM slot on HAT |
| Antenna | 4G LTE + GPS/GNSS (external SMA antennas --- mount high on chassis) |
- Data: PPP or QMI for internet connectivity
- GPS/GNSS: Built-in receiver, NMEA sentences on ttyUSB2 --- outdoor positioning
- AT commands: `AT+CGPS=1` (enable GPS), `AT+CGPSINFO` (get fix)
- Connected via USB (not 40-pin) --- avoids UART conflict with BALANCE fallback, flexible antenna placement
- Use: Remote telemetry, 4G connectivity outdoors, GPS positioning, remote SSH/control
### 9. Leap Motion Controller (USB)
| Connection | Detail |
|-----------|--------|
| Interface | USB 3.0 (micro-B on controller -> USB-A on Orin) |
| Power | ~0.5W |
| Range | ~80cm, 150 deg FOV |
| SDK | Ultraleap Gemini V5+ (Linux ARM64 support) |
| ROS2 | `leap_motion_ros2` wrapper available |
- 2x IR cameras + 3x IR LEDs --- tracks all 10 fingers in 3D, sub-mm precision
- Mount: Forward-facing on sensor tower or upward on Orin plate
- Use: Gesture control (palm=stop, point=go, fist=arm), hand-following mode, demos
- Combined with ReSpeaker: Voice + gesture control with zero hardware in hand
### 10. Power Budget (USB)
| Device | Interface | Power Draw |
|--------|-----------|------------|
<<<<<<< HEAD
| CANable2 USB-CAN | USB-A | ~0.5W |
| ESP32-S3 BALANCE | USB-C | ~0.8W (WiFi off) |
| ESP32-S3 IO | USB-C | ~0.5W |
=======
| ESP32-S3 FC (CDC) | USB-C | ~0.5W (data only, FC on 5V bus) |
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
| RealSense D435i | USB-A | ~1.5W (3.5W peak) |
| RPLIDAR A1M8 | USB-A | ~2.6W (motor on) |
| SIM7600A | USB | ~1W idle, 3W TX peak |
| Leap Motion | USB-A | ~0.5W |
| ReSpeaker HAT | 40-pin | ~0.5W |
| **Total USB** | | **~7.9W typical, ~11W peak** |
Orin Nano Super delivers up to 25W --- USB peripherals are well within budget.
Codec: Wolfson WM8960 (0x1A). Use: voice commands, wake word, audio feedback.
---
## Data Flow
## SIM7600A 4G/LTE HAT (Orin USB)
```
┌──────────────┐
│ RC TX │ (in your hand)
│ (2.4GHz) │
└──────┬───────┘
│ radio
┌──────▼───────┐
│ RC RX │ CRSF 420kbaud (future)
└──────┬───────┘
│ UART
┌────────────▼────────────┐
<<<<<<< HEAD
│ ESP32-S3 BALANCE │
│ (Waveshare LCD 1.28) │
=======
│ ESP32-S3 BALANCE │
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
│ │
│ QMI8658 -> Balance PID │
│ RC -> Mode Manager │
│ Safety Monitor │
│ │
└──┬──────────┬───────────┘
<<<<<<< HEAD
CAN 500kbps─┘ └───── CAN bus / UART fallback
=======
USART2 ─────┘ └───── USB Serial (CH343) / USART6
26400 baud 921600 baud
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
│ │
┌────┴────────────┐ ▼
│ CAN bus (500k) │ ┌───────────────────┐
├─ VESC Left 56 │ │ Orin Nano Super │
└─ VESC Right 68 │ │ │
│ │ │ SLAM / Nav2 / AI │
▼ ▼ │ Person following │
LEFT RIGHT │ Voice commands │
MOTOR MOTOR │ 4G telemetry │
└──┬──────────┬───────┘
│ │
┌──────────▼─┐ ┌────▼──────────┐
│ ReSpeaker │ │ SIM7600A │
│ 2-Mic HAT │ │ 4G/LTE + GPS │
└────────────┘ └───────────────┘
```
| Connection | Detail |
|-----------|--------|
| Interface | USB (micro-B on HAT → USB-A on Orin) |
| Device nodes | `/dev/ttyUSB0` (AT), `/dev/ttyUSB1` (PPP/data), `/dev/ttyUSB2` (GPS NMEA) |
| Power | 5V from USB (peak 2A during TX) |
| SIM | Nano-SIM slot |

24
jetson/README.md
View File

@ -6,19 +6,15 @@ Self-balancing robot: Jetson Orin Nano Super dev environment for ROS2 Humble + S
| Component | Version / Part |
|-----------|---------------|
| Platform | Jetson Orin Nano Super 4GB |
| JetPack | 4.6 (L4T R32.6.1, CUDA 10.2) |
| Platform | Jetson Orin Nano Super 8GB |
| JetPack | 6.x (L4T R36.x, CUDA 12.x) |
| ROS2 | Humble Hawksbill |
| DDS | CycloneDDS |
| SLAM | slam_toolbox |
| Nav | Nav2 |
| Depth camera | Intel RealSense D435i |
| LiDAR | RPLIDAR A1M8 |
<<<<<<< HEAD
| MCU bridge | ESP32 (USB CDC @ 921600) |
=======
| MCU bridge | ESP32-S3 (USB Serial (CH343) @ 921600) |
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
| MCU bridge | ESP32-S3 BALANCE (CAN bus @ 500 kbps via CANable 2.0) |
## Quick Start
@ -46,15 +42,11 @@ bash scripts/build-and-run.sh shell
```
jetson/
├── Dockerfile # L4T base + ROS2 Humble + SLAM packages
<<<<<<< HEAD
├── docker-compose.yml # Multi-service stack (ROS2, RPLIDAR, D435i, ESP32 BALANCE)
=======
├── docker-compose.yml # Multi-service stack (ROS2, RPLIDAR, D435i, ESP32-S3)
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
├── docker-compose.yml # Multi-service stack (ROS2, RPLIDAR, D435i, CAN bridge)
├── README.md # This file
├── docs/
│ ├── pinout.md # GPIO/I2C/UART pinout reference
│ └── power-budget.md # Power budget analysis (10W envelope)
│ └── power-budget.md # Power budget analysis (25W envelope)
└── scripts/
├── entrypoint.sh # Docker container entrypoint
├── setup-jetson.sh # Host setup (udev, Docker, nvpmodel)
@ -66,8 +58,8 @@ jetson/
| Scenario | Total |
|---------|-------|
| Idle | 2.9W |
| Nominal (SLAM active) | ~10.2W |
| Peak | 15.4W |
| Nominal (SLAM active) | ~19.9W |
| Peak | ~28.2W |
Target: 10W (MAXN nvpmodel). Use RPLIDAR standby + 640p D435i for compliance.
Target: 25W (MAXN nvpmodel). 5W headroom at nominal load.
See [`docs/power-budget.md`](docs/power-budget.md) for full analysis.

12
jetson/config/RECOVERY_BEHAVIORS.md
View File

@ -10,7 +10,7 @@ Recovery behaviors are triggered when Nav2 encounters navigation failures (path
### Backup Recovery (Issue #479)
- **Distance**: 0.3 meters reverse
- **Speed**: 0.1 m/s (very conservative for FC + Hoverboard ESC)
- **Speed**: 0.1 m/s (very conservative for ESP32-S3 BALANCE + VESC)
- **Max velocity**: 0.15 m/s (absolute limit)
- **Time limit**: 5 seconds maximum
@ -34,20 +34,16 @@ Recovery behaviors are triggered when Nav2 encounters navigation failures (path
The emergency stop system (Issue #459, `saltybot_emergency` package) runs independently of Nav2 and takes absolute priority.
<<<<<<< HEAD
Recovery behaviors cannot interfere with E-stop because the emergency system operates at the motor driver level on the ESP32 BALANCE firmware.
=======
Recovery behaviors cannot interfere with E-stop because the emergency system operates at the motor driver level on the ESP32-S3 firmware.
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
Recovery behaviors cannot interfere with E-stop because the emergency system operates at the motor driver level on the ESP32-S3 BALANCE firmware.
## Behavior Tree Sequence
Recovery runs in a round-robin fashion with up to 6 retry cycles.
## Constraints for FC + Hoverboard ESC
## Constraints for ESP32-S3 BALANCE + VESC
This configuration is specifically tuned for:
- **Drivetrain**: Flux Capacitor (FC) balancing controller + Hoverboard brushless ESC
- **Drivetrain**: ESP32-S3 BALANCE + VESC (CAN bus)
- **Max linear velocity**: 1.0 m/s
- **Max angular velocity**: 1.5 rad/s
- **Recovery velocity constraints**: 50% of normal for stability

109
jetson/docs/pinout.md
View File

@ -1,9 +1,5 @@
# Jetson Orin Nano Super — GPIO / I2C / UART / CSI Pinout Reference
<<<<<<< HEAD
## Self-Balancing Robot: ESP32 Bridge + RealSense D435i + RPLIDAR A1M8 + 4× IMX219
=======
## Self-Balancing Robot: ESP32-S3 Bridge + RealSense D435i + RPLIDAR A1M8 + 4× IMX219
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
## Self-Balancing Robot: ESP32-S3 BALANCE (CAN bus) + RealSense D435i + RPLIDAR A1M8 + 4× IMX219
Last updated: 2026-02-28
JetPack version: 6.x (L4T R36.x / Ubuntu 22.04)
@ -47,75 +43,36 @@ i2cdetect -l
---
<<<<<<< HEAD
## 1. ESP32 Bridge (USB CDC — Primary)
## 1. ESP32-S3 BALANCE Bridge (CAN bus — Primary)
The ESP32 BALANCE acts as a real-time motor + IMU controller. Communication is via **USB CDC serial**.
=======
## 1. ESP32-S3 Bridge (USB Serial (CH343) — Primary)
The ESP32-S3 BALANCE acts as a real-time motor + IMU controller. Communication is via **CAN bus** through a CANable 2.0 USB-CAN adapter.
The ESP32-S3 acts as a real-time motor + IMU controller. Communication is via **USB Serial (CH343) serial**.
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
### USB Serial (CH343) Connection
### CAN Bus Connection
| Connection | Detail |
|-----------|--------|
<<<<<<< HEAD
| Interface | USB on ESP32 BALANCE board → USB-A on Jetson |
| Device node | `/dev/ttyACM0` → symlink `/dev/esp32-bridge` (via udev) |
| Baud rate | 921600 (configured in ESP32 BALANCE firmware) |
=======
| Interface | USB Micro-B on ESP32-S3 dev board → USB-A on Jetson |
| Device node | `/dev/ttyACM0` → symlink `/dev/esp32-bridge` (via udev) |
| Baud rate | 921600 (configured in ESP32-S3 firmware) |
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
| Protocol | JSON telemetry RX + ASCII command TX (see bridge docs) |
| Power | Powered via robot 5V bus (data-only via USB) |
### Hardware UART (Fallback — 40-pin header)
<<<<<<< HEAD
| Jetson Pin | Signal | ESP32 Pin | Notes |
=======
| Jetson Pin | Signal | ESP32-S3 Pin | Notes |
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
|-----------|--------|-----------|-------|
| Pin 8 (TXD0) | TX → | PA10 (UART1 RX) | Cross-connect TX→RX |
| Pin 10 (RXD0) | RX ← | PA9 (UART1 TX) | Cross-connect RX→TX |
| Pin 6 (GND) | GND | GND | Common ground **required** |
**Jetson device node:** `/dev/ttyTHS0`
**Baud rate:** 921600, 8N1
<<<<<<< HEAD
**Voltage level:** 3.3V — both Jetson Orin and ESP32 are 3.3V GPIO
=======
**Voltage level:** 3.3V — both Jetson Orin and ESP32-S3 are 3.3V GPIO
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
| Interface | CANable 2.0 USB-CAN adapter → USB-A on Jetson |
| Device node | `/dev/can0` (via CANable 2.0, SocketCAN) |
| Bitrate | 500 kbps |
| Protocol | Binary CAN frames (see balance_protocol.py) |
| Power | ESP32-S3 BALANCE powered from robot 5V DC-DC |
### Bring Up CAN Interface
```bash
# Verify UART
ls /dev/ttyTHS0
sudo usermod -aG dialout $USER
# Quick test
picocom -b 921600 /dev/ttyTHS0
# Bring up can0 at 500 kbps
sudo ip link set can0 up type can bitrate 500000
ip link show can0
# Quick test — dump CAN frames
candump can0
```
<<<<<<< HEAD
**ROS2 topics (ESP32 bridge node):**
| ROS2 Topic | Direction | Content |
|-----------|-----------|---------
| `/saltybot/imu` | ESP32 BALANCE→Jetson | IMU data (accel, gyro) at 50Hz |
| `/saltybot/balance_state` | ESP32 BALANCE→Jetson | Motor cmd, pitch, state |
| `/cmd_vel` | Jetson→ESP32 BALANCE | Velocity commands → `C<spd>,<str>\n` |
| `/saltybot/estop` | Jetson→ESP32 BALANCE | Emergency stop |
=======
**ROS2 topics (ESP32-S3 bridge node):**
**ROS2 topics (CAN bridge node):**
| ROS2 Topic | Direction | Content |
|-----------|-----------|---------
| `/saltybot/imu` | ESP32-S3→Jetson | IMU data (accel, gyro) at 50Hz |
| `/saltybot/balance_state` | ESP32-S3→Jetson | Motor cmd, pitch, state |
| `/cmd_vel` | Jetson→ESP32-S3 | Velocity commands → `C<spd>,<str>\n` |
| `/saltybot/estop` | Jetson→ESP32-S3 | Emergency stop |
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
| `/cmd_vel` | Jetson→CAN 0x300 | Velocity commands via CAN |
| `/saltybot/estop` | Jetson→CAN 0x302 | Emergency stop |
---
@ -300,11 +257,7 @@ sudo mkdir -p /mnt/nvme
|------|------|----------|
| USB-A (top, blue) | USB 3.1 Gen 1 | RealSense D435i |
| USB-A (bottom) | USB 2.0 | RPLIDAR (via USB-UART adapter) |
<<<<<<< HEAD
| USB-C | USB 3.1 Gen 1 (+ DP) | ESP32 CDC or host flash |
=======
| USB-C | USB 3.1 Gen 1 (+ DP) | ESP32-S3 CDC or host flash |
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
| USB-C | USB 3.1 Gen 1 (+ DP) | CANable 2.0 or host flash |
| Micro-USB | Debug/flash | JetPack flash only |
---
@ -315,17 +268,10 @@ sudo mkdir -p /mnt/nvme
|-------------|----------|---------|----------|
| 3 | SDA1 | 3.3V | I2C data (i2c-7) |
| 5 | SCL1 | 3.3V | I2C clock (i2c-7) |
<<<<<<< HEAD
| 8 | TXD0 | 3.3V | UART TX → ESP32 BALANCE (fallback) |
| 10 | RXD0 | 3.3V | UART RX ← ESP32 BALANCE (fallback) |
| 8 | TXD0 | 3.3V | UART TX → ESP32-S3 IO (inter-board, fallback) |
| 10 | RXD0 | 3.3V | UART RX ← ESP32-S3 IO (inter-board, fallback) |
| USB-A ×2 | — | 5V | D435i, RPLIDAR |
| USB-C | — | 5V | ESP32 CDC |
=======
| 8 | TXD0 | 3.3V | UART TX → ESP32-S3 (fallback) |
| 10 | RXD0 | 3.3V | UART RX ← ESP32-S3 (fallback) |
| USB-A ×2 | — | 5V | D435i, RPLIDAR |
| USB-C | — | 5V | ESP32-S3 CDC |
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
| USB-C | — | 5V | CANable 2.0 (CAN bus) |
| CSI-A (J5) | MIPI CSI-2 | — | Cameras front + left |
| CSI-B (J8) | MIPI CSI-2 | — | Cameras rear + right |
| M.2 Key M | PCIe Gen3 ×4 | — | NVMe SSD |
@ -343,13 +289,10 @@ Apply stable device names:
KERNEL=="ttyUSB*", ATTRS{idVendor}=="10c4", ATTRS{idProduct}=="ea60", \
SYMLINK+="rplidar", MODE="0666"
<<<<<<< HEAD
# ESP32 USB CDC (STMicroelectronics)
=======
# ESP32-S3 USB Serial (CH343) (STMicroelectronics)
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
# CANable 2.0 USB-CAN adapter
# (bring up with: sudo ip link set can0 up type can bitrate 500000)
KERNEL=="ttyACM*", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="5740", \
SYMLINK+="esp32-bridge", MODE="0666"
SYMLINK+="balance", MODE="0666"
# Intel RealSense D435i
SUBSYSTEM=="usb", ATTRS{idVendor}=="8086", ATTRS{idProduct}=="0b3a", \

16
jetson/docs/power-budget.md
View File

@ -56,11 +56,7 @@ sudo jtop
|-----------|----------|------------|----------|-----------|-------|
| RealSense D435i | 0.3 | 1.5 | 3.5 | USB 3.1 | Peak during boot/init |
| RPLIDAR A1M8 | 0.4 | 2.6 | 3.0 | USB (UART adapter) | Motor spinning |
<<<<<<< HEAD
| ESP32 bridge | 0.0 | 0.0 | 0.0 | USB CDC | Self-powered from robot 5V |
=======
| ESP32-S3 bridge | 0.0 | 0.0 | 0.0 | USB Serial (CH343) | Self-powered from robot 5V |
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
| ESP32-S3 BALANCE | 0.5 | 0.5 | 0.5 | CAN bus (SN65HVD230) | Powered from 5V DC-DC |
| 4× IMX219 cameras | 0.2 | 2.0 | 2.4 | MIPI CSI-2 | ~0.5W per camera active |
| **Peripheral Subtotal** | **0.9** | **6.1** | **8.9** | | |
@ -76,7 +72,7 @@ sudo jtop
## Budget Analysis vs Previous Platform
| Metric | Jetson Orin Nano Super | Jetson Orin Nano Super |
| Metric | Jetson Nano | Jetson Orin Nano Super |
|--------|------------|------------------------|
| TDP | 10W | 25W |
| CPU | 4× Cortex-A57 @ 1.43GHz | 6× A78AE @ 1.5GHz |
@ -155,13 +151,9 @@ LiPo 4S (16.8V max)
├─► DC-DC Buck → 5V 6A ──► Jetson Orin barrel jack (30W)
│ (e.g., XL4016E1)
│
<<<<<<< HEAD
├─► DC-DC Buck → 5V 3A ──► ESP32 + logic 5V rail
=======
├─► DC-DC Buck → 5V 3A ──► ESP32-S3 + logic 5V rail
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
├─► DC-DC Buck → 5V 3A ──► ESP32-S3 BALANCE + ESP32-S3 IO + logic 5V rail
│
└─► Hoverboard ESC ──► Hub motors (48V loop)
└─► VESC left (ID 68) + VESC right (ID 56) ──► Hub motors
```
Using a 4S LiPo (vs 3S previously) gives better efficiency for the 5V buck converter

12
jetson/ros2_ws/src/saltybot_bridge/launch/uart_bridge.launch.py
View File

@ -2,11 +2,7 @@
uart_bridge.launch.py — FC↔Orin UART bridge (Issue #362)
Launches serial_bridge_node configured for Jetson Orin UART port.
<<<<<<< HEAD
Bridges Flight Controller (ESP32) telemetry from /dev/ttyTHS1 into ROS2.
=======
Bridges Flight Controller (ESP32-S3) telemetry from /dev/ttyTHS1 into ROS2.
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
Bridges ESP32-S3 BALANCE telemetry from inter-board UART into ROS2.
Published topics (same as USB CDC bridge):
/saltybot/imu sensor_msgs/Imu — pitch/roll/yaw as angular velocity
@ -24,11 +20,7 @@ Usage:
Prerequisites:
- Flight Controller connected to /dev/ttyTHS1 @ 921600 baud
<<<<<<< HEAD
- ESP32 BALANCE firmware transmitting JSON telemetry frames (50 Hz)
=======
- ESP32-S3 firmware transmitting JSON telemetry frames (50 Hz)
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
- STM32 firmware transmitting JSON telemetry frames (50 Hz)
- ROS2 environment sourced (source install/setup.bash)
Note:

64
jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/cmd_vel_bridge_node.py
View File

@ -1,9 +1,5 @@
"""
<<<<<<< HEAD
cmd_vel_bridge_node — Nav2 /cmd_vel → ESP32 BALANCE drive command bridge.
=======
cmd_vel_bridge_node — Nav2 /cmd_vel → ESP32-S3 drive command bridge.
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
cmd_vel_bridge_node — Nav2 /cmd_vel → STM32 drive command bridge.
Extends the basic saltybot_cmd_node with four additions required for safe
autonomous operation on a self-balancing robot:
@ -16,11 +12,7 @@ autonomous operation on a self-balancing robot:
3. Deadman switch — if /cmd_vel is silent for cmd_vel_timeout seconds,
zero targets immediately (Nav2 node crash / planner
stall → robot coasts to stop rather than running away).
<<<<<<< HEAD
4. Mode gate — only issue non-zero drive commands when ESP32 BALANCE reports
=======
4. Mode gate — only issue non-zero drive commands when ESP32-S3 reports
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
4. Mode gate — only issue non-zero drive commands when STM32 reports
md=2 (AUTONOMOUS). In any other mode (RC_MANUAL,
RC_ASSISTED) Jetson cannot override the RC pilot.
On mode re-entry current ramp state resets to 0 so
@ -28,15 +20,9 @@ autonomous operation on a self-balancing robot:
Serial protocol (C<speed>,<steer>\\n / H\\n — same as saltybot_cmd_node):
C<spd>,<str>\\n — drive command. speed/steer: -1000..+1000 integers.
<<<<<<< HEAD
H\\n — heartbeat. ESP32 BALANCE reverts steer to 0 after 500ms silence.
H\\n — heartbeat. STM32 reverts steer to 0 after 500ms silence.
Telemetry (50 Hz from ESP32 BALANCE):
=======
H\\n — heartbeat. ESP32-S3 reverts steer to 0 after 500ms silence.
Telemetry (50 Hz from ESP32-S3):
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
Telemetry (50 Hz from STM32):
Same RX/publish pipeline as saltybot_cmd_node.
The "md" field (0=MANUAL,1=ASSISTED,2=AUTO) is parsed for the mode gate.
@ -148,7 +134,7 @@ class CmdVelBridgeNode(Node):
self._current_speed = 0 # ramped output actually sent
self._current_steer = 0
self._last_cmd_vel = 0.0 # wall clock (seconds) of last /cmd_vel msg
self._esp32_mode = 0 # parsed "md" field: 0=MANUAL,1=ASSISTED,2=AUTO
self._stm32_mode = 0 # parsed "md" field: 0=MANUAL,1=ASSISTED,2=AUTO
self._last_state = -1
self._frame_count = 0
self._error_count = 0
@ -164,11 +150,7 @@ class CmdVelBridgeNode(Node):
self._open_serial()
# ── Timers ────────────────────────────────────────────────────────────
<<<<<<< HEAD
# Telemetry read at 100 Hz (ESP32 BALANCE sends at 50 Hz)
=======
# Telemetry read at 100 Hz (ESP32-S3 sends at 50 Hz)
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
# Telemetry read at 100 Hz (STM32 sends at 50 Hz)
self._read_timer = self.create_timer(0.01, self._read_cb)
# Control loop at 50 Hz: ramp + deadman + mode gate + send
self._control_timer = self.create_timer(1.0 / _CONTROL_HZ, self._control_cb)
@ -243,7 +225,7 @@ class CmdVelBridgeNode(Node):
# Mode gate: in non-AUTONOMOUS mode, zero and reset ramp state so
# re-entry always accelerates smoothly from 0.
if self._esp32_mode != MODE_AUTONOMOUS:
if self._stm32_mode != MODE_AUTONOMOUS:
self._current_speed = 0
self._current_steer = 0
speed, steer = 0, 0
@ -256,11 +238,7 @@ class CmdVelBridgeNode(Node):
speed = self._current_speed
steer = self._current_steer
<<<<<<< HEAD
# Send to ESP32 BALANCE
=======
# Send to ESP32-S3
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
# Send to STM32
frame = f"C{speed},{steer}\n".encode("ascii")
if not self._write(frame):
self.get_logger().warn(
@ -278,11 +256,7 @@ class CmdVelBridgeNode(Node):
# ── Heartbeat TX ──────────────────────────────────────────────────────────
def _heartbeat_cb(self):
<<<<<<< HEAD
"""H\\n keeps ESP32 BALANCE jetson_cmd heartbeat alive regardless of mode."""
=======
"""H\\n keeps ESP32-S3 jetson_cmd heartbeat alive regardless of mode."""
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
"""H\\n keeps STM32 jetson_cmd heartbeat alive regardless of mode."""
self._write(b"H\n")
# ── Telemetry RX ──────────────────────────────────────────────────────────
@ -345,7 +319,7 @@ class CmdVelBridgeNode(Node):
state = int(data["s"])
mode = int(data.get("md", 0)) # 0=MANUAL if not present
self._esp32_mode = mode
self._stm32_mode = mode
self._frame_count += 1
self._publish_imu(pitch_deg, roll_deg, yaw_deg, now)
@ -404,11 +378,7 @@ class CmdVelBridgeNode(Node):
diag.header.stamp = stamp
status = DiagnosticStatus()
status.name = "saltybot/balance_controller"
<<<<<<< HEAD
status.hardware_id = "esp32"
=======
status.hardware_id = "esp32s322"
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
status.hardware_id = "esp32s3_balance"
status.message = f"{state_label} [{mode_label}]"
status.level = (
DiagnosticStatus.OK if state == 1 else
@ -436,19 +406,11 @@ class CmdVelBridgeNode(Node):
status = DiagnosticStatus()
status.level = DiagnosticStatus.ERROR
status.name = "saltybot/balance_controller"
<<<<<<< HEAD
status.hardware_id = "esp32"
status.hardware_id = "esp32s3_balance"
status.message = f"IMU fault errno={errno}"
diag.status.append(status)
self._diag_pub.publish(diag)
self.get_logger().error(f"ESP32 BALANCE IMU fault: errno={errno}")
=======
status.hardware_id = "esp32s322"
status.message = f"IMU fault errno={errno}"
diag.status.append(status)
self._diag_pub.publish(diag)
self.get_logger().error(f"ESP32-S3 IMU fault: errno={errno}")
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
self.get_logger().error(f"STM32 IMU fault: errno={errno}")
# ── Lifecycle ─────────────────────────────────────────────────────────────

383
jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/esp32_cmd_node.py
View File

@ -1,66 +1,45 @@
<<<<<<< HEAD:jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/stm32_cmd_node.py
"""stm32_cmd_node.py — Orin ↔ ESP32-S3 IO auxiliary bridge node.
=======
"""esp32_cmd_node.py — Full bidirectional binary-framed ESP32-S3↔Jetson bridge.
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only):jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/esp32_cmd_node.py
"""esp32_cmd_node.py — Full bidirectional binary-framed ESP32-S3 BALANCE↔Jetson bridge.
Connects to the ESP32-S3 IO board via USB-CDC (/dev/esp32-io) using the
inter-board binary protocol (docs/SAUL-TEE-SYSTEM-REFERENCE.md §5).
Issue #119: replaces the ASCII-protocol saltybot_cmd_node with a robust binary
framing protocol (STX/TYPE/LEN/PAYLOAD/CRC16/ETX) at 460800 baud (inter-board UART).
<<<<<<< HEAD:jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/stm32_cmd_node.py
This node is NOT the primary drive path (that is CAN via can_bridge_node).
It handles auxiliary I/O: RC monitoring, sensor data, LED/output control.
=======
TX commands (Jetson → ESP32-S3):
TX commands (Jetson → ESP32-S3 BALANCE):
SPEED_STEER — 50 Hz from /cmd_vel subscription
HEARTBEAT — 200 ms timer (ESP32-S3 watchdog fires at 500 ms)
HEARTBEAT — 200 ms timer (ESP32-S3 BALANCE watchdog fires at 500 ms)
ARM — via /saltybot/arm service
SET_MODE — via /saltybot/set_mode service
PID_UPDATE — via /saltybot/pid_update topic
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only):jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/esp32_cmd_node.py
Frame format: [0xAA][LEN][TYPE][PAYLOAD][CRC8] @ 460800 baud
Watchdog: if /cmd_vel is silent for 500 ms, send SPEED_STEER(0,0) and log warning.
<<<<<<< HEAD:jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/stm32_cmd_node.py
RX from ESP32 IO:
RC_CHANNELS (0x01) → /saltybot/rc_channels (std_msgs/String JSON)
SENSORS (0x02) → /saltybot/sensors (std_msgs/String JSON)
=======
RX telemetry (ESP32-S3 → Jetson):
RX telemetry (ESP32-S3 BALANCE → Jetson):
IMU → /saltybot/imu (sensor_msgs/Imu)
BATTERY → /saltybot/telemetry/battery (std_msgs/String JSON)
MOTOR_RPM → /saltybot/telemetry/motor_rpm (std_msgs/String JSON)
ARM_STATE → /saltybot/arm_state (std_msgs/String JSON)
ERROR → /saltybot/error (std_msgs/String JSON)
All frames → /diagnostics (diagnostic_msgs/DiagnosticArray)
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only):jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/esp32_cmd_node.py
TX to ESP32 IO:
LED_CMD (0x10) ← /saltybot/leds (std_msgs/String JSON)
OUTPUT_CMD (0x11) ← /saltybot/outputs (std_msgs/String JSON)
HEARTBEAT (0x20) — sent every heartbeat_period (keep IO watchdog alive)
Auto-reconnect: USB disconnect is detected when serial.read() raises; node
continuously retries at reconnect_delay interval.
This node owns /dev/can0 exclusively — do NOT run alongside
serial_bridge_node or saltybot_cmd_node on the same port.
<<<<<<< HEAD:jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/stm32_cmd_node.py
Parameters (config/stm32_cmd_params.yaml):
serial_port /dev/esp32-io
baud_rate 460800
reconnect_delay 2.0
heartbeat_period 0.2 (ESP32 IO watchdog fires at ~500 ms)
=======
Parameters (config/esp32_cmd_params.yaml):
serial_port /dev/ttyACM0
baud_rate 921600
serial_port /dev/can0
baud_rate 460800
reconnect_delay 2.0 (seconds)
heartbeat_period 0.2 (seconds)
watchdog_timeout 0.5 (seconds — no /cmd_vel → send zero-speed)
speed_scale 1000.0 (linear.x m/s → ESC units)
steer_scale -500.0 (angular.z rad/s → ESC units, neg to flip convention)
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only):jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/esp32_cmd_node.py
"""
from __future__ import annotations
import json
import math
import threading
import time
@ -71,82 +50,119 @@ from rclpy.qos import HistoryPolicy, QoSProfile, ReliabilityPolicy
import serial
from diagnostic_msgs.msg import DiagnosticArray, DiagnosticStatus, KeyValue
from geometry_msgs.msg import Twist
from sensor_msgs.msg import Imu
from std_msgs.msg import String
from std_srvs.srv import SetBool, Trigger
<<<<<<< HEAD:jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/stm32_cmd_node.py
from .stm32_protocol import (
BAUD_RATE,
=======
from .esp32_protocol import (
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only):jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/esp32_cmd_node.py
FrameParser,
RcChannels,
SensorData,
encode_heartbeat,
encode_led_cmd,
encode_output_cmd,
ImuFrame, BatteryFrame, MotorRpmFrame, ArmStateFrame, ErrorFrame,
encode_heartbeat, encode_speed_steer, encode_arm, encode_set_mode,
encode_pid_update,
)
# ── Constants ─────────────────────────────────────────────────────────────────
class Stm32CmdNode(Node):
<<<<<<< HEAD:jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/stm32_cmd_node.py
"""Orin ↔ ESP32-S3 IO auxiliary bridge node."""
=======
"""Binary-framed Jetson↔ESP32-S3 bridge node."""
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only):jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/esp32_cmd_node.py
IMU_FRAME_ID = "imu_link"
_ARM_LABEL = {0: "DISARMED", 1: "ARMED", 2: "TILT_FAULT"}
def _clamp(v: float, lo: float, hi: float) -> float:
return max(lo, min(hi, v))
# ── Node ──────────────────────────────────────────────────────────────────────
class Esp32CmdNode(Node):
"""Binary-framed Jetson↔ESP32-S3 BALANCE bridge node."""
def __init__(self) -> None:
super().__init__("esp32_cmd_node")
# ── Parameters ────────────────────────────────────────────────────
self.declare_parameter("serial_port", "/dev/esp32-io")
self.declare_parameter("baud_rate", BAUD_RATE)
# ── Parameters ────────────────────────────────────────────────────────
self.declare_parameter("serial_port", "/dev/can0")
self.declare_parameter("baud_rate", 460800)
self.declare_parameter("reconnect_delay", 2.0)
self.declare_parameter("heartbeat_period", 0.2)
self.declare_parameter("watchdog_timeout", 0.5)
self.declare_parameter("speed_scale", 1000.0)
self.declare_parameter("steer_scale", -500.0)
self._port_name = self.get_parameter("serial_port").value
self._baud = self.get_parameter("baud_rate").value
port = self.get_parameter("serial_port").value
baud = self.get_parameter("baud_rate").value
self._reconnect_delay = self.get_parameter("reconnect_delay").value
self._hb_period = self.get_parameter("heartbeat_period").value
self._wd_timeout = self.get_parameter("watchdog_timeout").value
self._speed_scale = self.get_parameter("speed_scale").value
self._steer_scale = self.get_parameter("steer_scale").value
# ── QoS ───────────────────────────────────────────────────────────
# ── QoS ───────────────────────────────────────────────────────────────
sensor_qos = QoSProfile(
reliability=ReliabilityPolicy.BEST_EFFORT,
history=HistoryPolicy.KEEP_LAST, depth=10,
)
rel_qos = QoSProfile(
reliability=ReliabilityPolicy.RELIABLE,
history=HistoryPolicy.KEEP_LAST, depth=10,
)
# ── Publishers ────────────────────────────────────────────────────
self._rc_pub = self.create_publisher(String, "/saltybot/rc_channels", rel_qos)
self._sens_pub = self.create_publisher(String, "/saltybot/sensors", rel_qos)
self._diag_pub = self.create_publisher(DiagnosticArray, "/diagnostics", rel_qos)
# ── Publishers ────────────────────────────────────────────────────────
self._imu_pub = self.create_publisher(Imu, "/saltybot/imu", sensor_qos)
self._arm_pub = self.create_publisher(String, "/saltybot/arm_state", rel_qos)
self._error_pub = self.create_publisher(String, "/saltybot/error", rel_qos)
self._battery_pub = self.create_publisher(String, "/saltybot/telemetry/battery", rel_qos)
self._rpm_pub = self.create_publisher(String, "/saltybot/telemetry/motor_rpm", rel_qos)
self._diag_pub = self.create_publisher(DiagnosticArray, "/diagnostics", rel_qos)
# ── Subscriptions ─────────────────────────────────────────────────
self.create_subscription(String, "/saltybot/leds", self._on_leds, rel_qos)
self.create_subscription(String, "/saltybot/outputs", self._on_outputs, rel_qos)
# ── Serial state ──────────────────────────────────────────────────
self._ser: serial.Serial | None = None
self._ser_lock = threading.Lock()
self._parser = FrameParser()
self._rx_count = 0
# ── Open serial and start timers ──────────────────────────────────
self._open_serial()
self._read_timer = self.create_timer(0.005, self._read_cb)
self._hb_timer = self.create_timer(self._hb_period, self._heartbeat_cb)
self._diag_timer = self.create_timer(1.0, self._publish_diagnostics)
self.get_logger().info(
<<<<<<< HEAD:jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/stm32_cmd_node.py
f"stm32_cmd_node started — {self._port_name} @ {self._baud} baud"
=======
f"esp32_cmd_node started — {port} @ {baud} baud | "
f"HB {int(self._hb_period * 1000)}ms | WD {int(self._wd_timeout * 1000)}ms"
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only):jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/esp32_cmd_node.py
# ── Subscribers ───────────────────────────────────────────────────────
self._cmd_vel_sub = self.create_subscription(
Twist, "/cmd_vel", self._on_cmd_vel, rel_qos,
)
self._pid_sub = self.create_subscription(
String, "/saltybot/pid_update", self._on_pid_update, rel_qos,
)
# ── Serial management ─────────────────────────────────────────────────
# ── Services ──────────────────────────────────────────────────────────
self._arm_srv = self.create_service(SetBool, "/saltybot/arm", self._svc_arm)
self._mode_srv = self.create_service(SetBool, "/saltybot/set_mode", self._svc_set_mode)
# ── Serial state ──────────────────────────────────────────────────────
self._port_name = port
self._baud = baud
self._ser: serial.Serial | None = None
self._ser_lock = threading.Lock()
self._parser = FrameParser()
# ── TX state ──────────────────────────────────────────────────────────
self._last_speed = 0
self._last_steer = 0
self._last_cmd_t = time.monotonic()
self._watchdog_sent = False # tracks whether we already sent zero
# ── Diagnostics state ──────────────────────────────────────────────────
self._last_arm_state = -1
self._last_battery_mv = 0
self._rx_frame_count = 0
# ── Open serial and start timers ──────────────────────────────────────
self._open_serial()
# Read at 200 Hz (serial RX thread is better, but timer keeps ROS2 integration clean)
self._read_timer = self.create_timer(0.005, self._read_cb)
# Heartbeat TX
self._hb_timer = self.create_timer(self._hb_period, self._heartbeat_cb)
# Watchdog check (fires at 2× watchdog_timeout for quick detection)
self._wd_timer = self.create_timer(self._wd_timeout / 2, self._watchdog_cb)
# Periodic diagnostics
self._diag_timer = self.create_timer(1.0, self._publish_diagnostics)
self.get_logger().info(
f"esp32_cmd_node started — {port} @ {baud} baud | "
f"HB {int(self._hb_period * 1000)}ms | WD {int(self._wd_timeout * 1000)}ms"
)
# ── Serial management ─────────────────────────────────────────────────────
def _open_serial(self) -> bool:
with self._ser_lock:
@ -154,7 +170,7 @@ class Stm32CmdNode(Node):
self._ser = serial.Serial(
port=self._port_name,
baudrate=self._baud,
timeout=0.005,
timeout=0.005, # non-blocking reads
write_timeout=0.1,
)
self._ser.reset_input_buffer()
@ -169,7 +185,17 @@ class Stm32CmdNode(Node):
self._ser = None
return False
def _close_serial(self) -> None:
with self._ser_lock:
if self._ser and self._ser.is_open:
try:
self._ser.close()
except Exception:
pass
self._ser = None
def _write(self, data: bytes) -> bool:
"""Thread-safe serial write. Returns False if port is not open."""
with self._ser_lock:
if self._ser is None or not self._ser.is_open:
return False
@ -181,15 +207,16 @@ class Stm32CmdNode(Node):
self._ser = None
return False
# ── RX ────────────────────────────────────────────────────────────────
# ── RX — read callback ────────────────────────────────────────────────────
def _read_cb(self) -> None:
"""Read bytes from serial and feed them to the frame parser."""
raw: bytes | None = None
reconnect = False
reconnect_needed = False
with self._ser_lock:
if self._ser is None or not self._ser.is_open:
reconnect = True
reconnect_needed = True
else:
try:
n = self._ser.in_waiting
@ -198,9 +225,9 @@ class Stm32CmdNode(Node):
except serial.SerialException as exc:
self.get_logger().error(f"Serial read error: {exc}")
self._ser = None
reconnect = True
reconnect_needed = True
if reconnect:
if reconnect_needed:
self.get_logger().warn(
"Serial disconnected — will retry",
throttle_duration_sec=self._reconnect_delay,
@ -213,41 +240,24 @@ class Stm32CmdNode(Node):
return
for byte in raw:
msg = self._parser.feed(byte)
if msg is not None:
self._rx_count += 1
self._dispatch(msg)
frame = self._parser.feed(byte)
if frame is not None:
self._rx_frame_count += 1
self._dispatch_frame(frame)
def _dispatch(self, msg) -> None:
def _dispatch_frame(self, frame) -> None:
"""Route a decoded frame to the appropriate publisher."""
now = self.get_clock().now().to_msg()
ts = f"{now.sec}.{now.nanosec:09d}"
if isinstance(msg, RcChannels):
out = String()
out.data = json.dumps({
"channels": msg.channels,
"source": msg.source,
"ts": ts,
})
self._rc_pub.publish(out)
if isinstance(frame, ImuFrame):
self._publish_imu(frame, now)
elif isinstance(msg, SensorData):
out = String()
out.data = json.dumps({
"pressure_pa": msg.pressure_pa,
"temperature_c": msg.temperature_c,
"tof_mm": msg.tof_mm,
"ts": ts,
})
self._sens_pub.publish(out)
elif isinstance(frame, BatteryFrame):
self._publish_battery(frame, now)
elif isinstance(msg, tuple):
type_code, _ = msg
self.get_logger().debug(f"Unknown inter-board type 0x{type_code:02X}")
elif isinstance(frame, MotorRpmFrame):
self._publish_motor_rpm(frame, now)
<<<<<<< HEAD:jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/stm32_cmd_node.py
# ── TX ────────────────────────────────────────────────────────────────
=======
elif isinstance(frame, ArmStateFrame):
self._publish_arm_state(frame, now)
@ -358,85 +368,108 @@ class Stm32CmdNode(Node):
"SPEED_STEER dropped — serial not open",
throttle_duration_sec=2.0,
)
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only):jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/esp32_cmd_node.py
def _heartbeat_cb(self) -> None:
"""Send HEARTBEAT every heartbeat_period (default 200ms)."""
self._write(encode_heartbeat())
def _on_leds(self, msg: String) -> None:
"""Parse JSON {"pattern":N,"r":R,"g":G,"b":B} and send LED_CMD."""
try:
d = json.loads(msg.data)
frame = encode_led_cmd(
int(d.get("pattern", 0)),
int(d.get("r", 0)),
int(d.get("g", 0)),
int(d.get("b", 0)),
)
except (ValueError, KeyError, json.JSONDecodeError) as exc:
self.get_logger().error(f"Bad /saltybot/leds JSON: {exc}")
return
self._write(frame)
def _watchdog_cb(self) -> None:
"""Send zero-speed if /cmd_vel silent for watchdog_timeout seconds."""
if time.monotonic() - self._last_cmd_t >= self._wd_timeout:
if not self._watchdog_sent:
self.get_logger().warn(
f"No /cmd_vel for {self._wd_timeout:.1f}s — sending zero-speed"
)
self._watchdog_sent = True
self._last_speed = 0
self._last_steer = 0
self._write(encode_speed_steer(0, 0))
def _on_outputs(self, msg: String) -> None:
"""Parse JSON {"horn":bool,"buzzer":bool,"headlight":0-255,"fan":0-255}."""
def _on_pid_update(self, msg: String) -> None:
"""Parse JSON /saltybot/pid_update and send PID_UPDATE frame."""
try:
d = json.loads(msg.data)
frame = encode_output_cmd(
bool(d.get("horn", False)),
bool(d.get("buzzer", False)),
int(d.get("headlight", 0)),
int(d.get("fan", 0)),
)
data = json.loads(msg.data)
kp = float(data["kp"])
ki = float(data["ki"])
kd = float(data["kd"])
except (ValueError, KeyError, json.JSONDecodeError) as exc:
self.get_logger().error(f"Bad /saltybot/outputs JSON: {exc}")
self.get_logger().error(f"Bad PID update JSON: {exc}")
return
self._write(frame)
frame = encode_pid_update(kp, ki, kd)
if self._write(frame):
self.get_logger().info(f"PID update: kp={kp}, ki={ki}, kd={kd}")
else:
self.get_logger().warn("PID_UPDATE dropped — serial not open")
# ── Diagnostics ───────────────────────────────────────────────────────
# ── Services ──────────────────────────────────────────────────────────────
def _svc_arm(self, request: SetBool.Request, response: SetBool.Response):
"""SetBool(True) = arm, SetBool(False) = disarm."""
arm = request.data
frame = encode_arm(arm)
ok = self._write(frame)
response.success = ok
response.message = ("ARMED" if arm else "DISARMED") if ok else "serial not open"
self.get_logger().info(
f"ARM service: {'arm' if arm else 'disarm'} — {'sent' if ok else 'FAILED'}"
)
return response
def _svc_set_mode(self, request: SetBool.Request, response: SetBool.Response):
"""SetBool: data maps to mode byte (True=1, False=0)."""
mode = 1 if request.data else 0
frame = encode_set_mode(mode)
ok = self._write(frame)
response.success = ok
response.message = f"mode={mode}" if ok else "serial not open"
return response
# ── Diagnostics ───────────────────────────────────────────────────────────
def _publish_diagnostics(self) -> None:
diag = DiagnosticArray()
diag.header.stamp = self.get_clock().now().to_msg()
status = DiagnosticStatus()
<<<<<<< HEAD:jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/stm32_cmd_node.py
status.name = "saltybot/esp32_io_bridge"
status.hardware_id = "esp32-s3-io"
=======
status.name = "saltybot/esp32_cmd_node"
status.hardware_id = "esp32s322"
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only):jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/esp32_cmd_node.py
status = DiagnosticStatus()
status.name = "saltybot/esp32_cmd_node"
status.hardware_id = "esp32s3_balance"
port_ok = self._ser is not None and self._ser.is_open
status.level = DiagnosticStatus.OK if port_ok else DiagnosticStatus.ERROR
status.message = "Serial OK" if port_ok else f"Disconnected: {self._port_name}"
status.values = [
KeyValue(key="serial_port", value=self._port_name),
KeyValue(key="baud_rate", value=str(self._baud)),
KeyValue(key="port_open", value=str(port_ok)),
KeyValue(key="rx_frames", value=str(self._rx_count)),
KeyValue(key="rx_errors", value=str(self._parser.frames_error)),
if port_ok:
status.level = DiagnosticStatus.OK
status.message = "Serial OK"
else:
status.level = DiagnosticStatus.ERROR
status.message = f"Serial disconnected: {self._port_name}"
wd_age = time.monotonic() - self._last_cmd_t
status.values = [
KeyValue(key="serial_port", value=self._port_name),
KeyValue(key="port_open", value=str(port_ok)),
KeyValue(key="rx_frames", value=str(self._rx_frame_count)),
KeyValue(key="rx_errors", value=str(self._parser.frames_error)),
KeyValue(key="last_speed", value=str(self._last_speed)),
KeyValue(key="last_steer", value=str(self._last_steer)),
KeyValue(key="cmd_vel_age_s", value=f"{wd_age:.2f}"),
KeyValue(key="battery_mv", value=str(self._last_battery_mv)),
KeyValue(key="arm_state", value=_ARM_LABEL.get(self._last_arm_state, "?")),
]
diag.status.append(status)
self._diag_pub.publish(diag)
# ── Lifecycle ─────────────────────────────────────────────────────────
# ── Lifecycle ─────────────────────────────────────────────────────────────
def destroy_node(self) -> None:
self._write(encode_heartbeat(state=0))
with self._ser_lock:
if self._ser and self._ser.is_open:
try:
self._ser.close()
except Exception:
pass
self._ser = None
# Send zero-speed + disarm on shutdown
self._write(encode_speed_steer(0, 0))
self._write(encode_arm(False))
self._close_serial()
super().destroy_node()
def main(args=None) -> None:
rclpy.init(args=args)
node = Stm32CmdNode()
node = Esp32CmdNode()
try:
rclpy.spin(node)
except KeyboardInterrupt:

16
jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/esp32_protocol.py
View File

@ -1,7 +1,7 @@
"""esp32_protocol.py — Binary frame codec for Jetson↔ESP32-S3 communication.
"""esp32_protocol.py — Binary frame codec for Jetson↔ESP32-S3 BALANCE communication.
Issue #119: defines the binary serial protocol between the Jetson Orin Nano Super and the
ESP32-S3 ESP32-S3 BALANCE over USB CDC @ 921600 baud.
ESP32-S3 BALANCE board over inter-board UART @ 460800 baud.
Frame layout (all multi-byte fields are big-endian):
┌──────┬──────┬──────┬──────────────────┬───────────┬──────┐
@ -12,14 +12,14 @@ Frame layout (all multi-byte fields are big-endian):
CRC16 covers: TYPE + LEN + PAYLOAD (not STX, ETX, or CRC bytes themselves).
CRC algorithm: CCITT-16, polynomial=0x1021, init=0xFFFF, no final XOR.
Command types (Jetson → ESP32-S3):
Command types (Jetson → ESP32-S3 BALANCE):
0x01 HEARTBEAT — no payload (len=0)
0x02 SPEED_STEER — int16 speed + int16 steer (len=4) range: -1000..+1000
0x03 ARM — uint8 (0=disarm, 1=arm) (len=1)
0x04 SET_MODE — uint8 mode (len=1)
0x05 PID_UPDATE — float32 kp + ki + kd (len=12)
Telemetry types (ESP32-S3 → Jetson):
Telemetry types (ESP32-S3 BALANCE → Jetson):
0x10 IMU — int16×6: pitch,roll,yaw (×100 deg), ax,ay,az (×100 m/s²) (len=12)
0x11 BATTERY — uint16 voltage_mv + int16 current_ma + uint8 soc_pct (len=5)
0x12 MOTOR_RPM — int16 left_rpm + int16 right_rpm (len=4)
@ -27,11 +27,11 @@ Telemetry types (ESP32-S3 → Jetson):
0x14 ERROR — uint8 error_code + uint8 subcode (len=2)
Usage:
# Encoding (Jetson → ESP32-S3)
# Encoding (Jetson → ESP32-S3 BALANCE)
frame = encode_speed_steer(300, -150)
ser.write(frame)
# Decoding (ESP32-S3 → Jetson), one byte at a time
# Decoding (ESP32-S3 BALANCE → Jetson), one byte at a time
parser = FrameParser()
for byte in incoming_bytes:
result = parser.feed(byte)
@ -87,7 +87,7 @@ class ImuFrame:
class BatteryFrame:
voltage_mv: int # millivolts (e.g. 11100 = 11.1 V)
current_ma: int # milliamps (negative = charging)
soc_pct: int # state of charge 0–100 (from ESP32-S3 fuel gauge or lookup)
soc_pct: int # state of charge 0–100 (from ESP32-S3 BALANCE fuel gauge or lookup)
@dataclass
@ -183,7 +183,7 @@ class ParseError(Exception):
class FrameParser:
"""Byte-by-byte streaming parser for ESP32-S3 telemetry frames.
"""Byte-by-byte streaming parser for ESP32-S3 BALANCE telemetry frames.
Feed individual bytes via feed(); returns a decoded TelemetryFrame (or raw
bytes tuple) when a complete valid frame is received.

6
jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/saltybot_can_node.py
View File

@ -322,11 +322,7 @@ class SaltybotCanNode(Node):
diag.header.stamp = stamp
st = DiagnosticStatus()
st.name = "saltybot/balance_controller"
<<<<<<< HEAD
st.hardware_id = "esp32"
=======
st.hardware_id = "esp32s322"
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
st.hardware_id = "esp32s3_balance"
st.message = state_label
st.level = (DiagnosticStatus.OK if state == 1 else
DiagnosticStatus.WARN if state == 0 else

60
jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/saltybot_cmd_node.py
View File

@ -1,38 +1,20 @@
"""
<<<<<<< HEAD
saltybot_cmd_node — full bidirectional ESP32 BALANCE↔Jetson bridge
=======
saltybot_cmd_node — full bidirectional ESP32-S3↔Jetson bridge
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
saltybot_cmd_node — full bidirectional STM32↔Jetson bridge
Combines telemetry RX (from serial_bridge_node) with drive command TX.
Owns /dev/ttyACM0 exclusively — do NOT run alongside serial_bridge_node.
<<<<<<< HEAD
RX path (50Hz from ESP32 BALANCE):
RX path (50Hz from STM32):
JSON telemetry → /saltybot/imu, /saltybot/balance_state, /diagnostics
TX path:
/cmd_vel (geometry_msgs/Twist) → C<speed>,<steer>\\n → ESP32 BALANCE
Heartbeat timer (200ms) → H\\n → ESP32 BALANCE
/cmd_vel (geometry_msgs/Twist) → C<speed>,<steer>\\n → STM32
Heartbeat timer (200ms) → H\\n → STM32
Protocol:
H\\n — heartbeat. ESP32 BALANCE reverts steer to 0 if gap > 500ms.
H\\n — heartbeat. STM32 reverts steer to 0 if gap > 500ms.
C<spd>,<str>\\n — drive command. speed/steer: -1000..+1000 integers.
C command also refreshes ESP32 BALANCE heartbeat timer.
=======
RX path (50Hz from ESP32-S3):
JSON telemetry → /saltybot/imu, /saltybot/balance_state, /diagnostics
TX path:
/cmd_vel (geometry_msgs/Twist) → C<speed>,<steer>\\n → ESP32-S3
Heartbeat timer (200ms) → H\\n → ESP32-S3
Protocol:
H\\n — heartbeat. ESP32-S3 reverts steer to 0 if gap > 500ms.
C<spd>,<str>\\n — drive command. speed/steer: -1000..+1000 integers.
C command also refreshes ESP32-S3 heartbeat timer.
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
C command also refreshes STM32 heartbeat timer.
Twist mapping (configurable via ROS2 params):
speed = clamp(linear.x * speed_scale, -1000, 1000)
@ -118,11 +100,7 @@ class SaltybotCmdNode(Node):
self._open_serial()
# ── Timers ────────────────────────────────────────────────────────────
<<<<<<< HEAD
# Telemetry read at 100Hz (ESP32 BALANCE sends at 50Hz)
=======
# Telemetry read at 100Hz (ESP32-S3 sends at 50Hz)
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
# Telemetry read at 100Hz (STM32 sends at 50Hz)
self._read_timer = self.create_timer(0.01, self._read_cb)
# Heartbeat TX at configured period (default 200ms)
self._hb_timer = self.create_timer(self._hb_period, self._heartbeat_cb)
@ -288,11 +266,7 @@ class SaltybotCmdNode(Node):
diag.header.stamp = stamp
status = DiagnosticStatus()
status.name = "saltybot/balance_controller"
<<<<<<< HEAD
status.hardware_id = "esp32"
=======
status.hardware_id = "esp32s322"
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
status.hardware_id = "esp32s3_balance"
status.message = state_label
if state == 1:
status.level = DiagnosticStatus.OK
@ -320,19 +294,11 @@ class SaltybotCmdNode(Node):
status = DiagnosticStatus()
status.level = DiagnosticStatus.ERROR
status.name = "saltybot/balance_controller"
<<<<<<< HEAD
status.hardware_id = "esp32"
status.hardware_id = "esp32s3_balance"
status.message = f"IMU fault errno={errno}"
diag.status.append(status)
self._diag_pub.publish(diag)
self.get_logger().error(f"ESP32 BALANCE IMU fault: errno={errno}")
=======
status.hardware_id = "esp32s322"
status.message = f"IMU fault errno={errno}"
diag.status.append(status)
self._diag_pub.publish(diag)
self.get_logger().error(f"ESP32-S3 IMU fault: errno={errno}")
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
self.get_logger().error(f"STM32 IMU fault: errno={errno}")
# ── TX — command send ─────────────────────────────────────────────────────
@ -350,11 +316,7 @@ class SaltybotCmdNode(Node):
)
def _heartbeat_cb(self):
<<<<<<< HEAD
"""Send H\\n heartbeat. ESP32 BALANCE reverts steer to 0 if gap > 500ms."""
=======
"""Send H\\n heartbeat. ESP32-S3 reverts steer to 0 if gap > 500ms."""
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
"""Send H\\n heartbeat. STM32 reverts steer to 0 if gap > 500ms."""
self._write(b"H\n")
# ── Lifecycle ─────────────────────────────────────────────────────────────

50
jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/serial_bridge_node.py
View File

@ -1,10 +1,6 @@
"""
saltybot_bridge — serial_bridge_node
<<<<<<< HEAD
ESP32 USB CDC → ROS2 topic publisher
=======
ESP32-S3 USB CDC → ROS2 topic publisher
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
ESP32-S3 BALANCE → ROS2 topic publisher (inter-board UART)
Telemetry frame (50 Hz, newline-delimited JSON):
{"p":<pitch×10>,"r":<roll×10>,"e":<err×10>,"ig":<integral×10>,
@ -33,11 +29,7 @@ from sensor_msgs.msg import Imu
from std_msgs.msg import String
from diagnostic_msgs.msg import DiagnosticArray, DiagnosticStatus, KeyValue
<<<<<<< HEAD
# Balance state labels matching ESP32 BALANCE balance_state_t enum
=======
# Balance state labels matching ESP32-S3 balance_state_t enum
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
# Balance state labels matching STM32 balance_state_t enum
_STATE_LABEL = {0: "DISARMED", 1: "ARMED", 2: "TILT_FAULT"}
# Sensor frame_id published in Imu header
@ -46,7 +38,7 @@ IMU_FRAME_ID = "imu_link"
class SerialBridgeNode(Node):
def __init__(self):
super().__init__("esp32_serial_bridge")
super().__init__("stm32_serial_bridge")
# ── Parameters ────────────────────────────────────────────────────────
self.declare_parameter("serial_port", "/dev/ttyACM0")
@ -91,11 +83,7 @@ class SerialBridgeNode(Node):
# ── Open serial and start read timer ──────────────────────────────────
self._open_serial()
<<<<<<< HEAD
# Poll at 100 Hz — ESP32 BALANCE sends at 50 Hz, so we never miss a frame
=======
# Poll at 100 Hz — ESP32-S3 sends at 50 Hz, so we never miss a frame
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
# Poll at 100 Hz — STM32 sends at 50 Hz, so we never miss a frame
self._timer = self.create_timer(0.01, self._read_cb)
self.get_logger().info(
@ -129,11 +117,7 @@ class SerialBridgeNode(Node):
def write_serial(self, data: bytes) -> bool:
"""
<<<<<<< HEAD
Send raw bytes to ESP32 BALANCE over the open serial port.
=======
Send raw bytes to ESP32-S3 over the open serial port.
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
Send raw bytes to STM32 over the open serial port.
Returns False if port is not open (caller should handle gracefully).
Note: for bidirectional use prefer saltybot_cmd_node which owns TX natively.
"""
@ -222,11 +206,7 @@ class SerialBridgeNode(Node):
"""
Publish sensor_msgs/Imu.
<<<<<<< HEAD
The ESP32 BALANCE IMU gives Euler angles (pitch/roll from accelerometer+gyro
=======
The ESP32-S3 IMU gives Euler angles (pitch/roll from accelerometer+gyro
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
The STM32 IMU gives Euler angles (pitch/roll from accelerometer+gyro
fusion, yaw from gyro integration). We publish them as angular_velocity
for immediate use by slam_toolbox / robot_localization.
@ -284,11 +264,7 @@ class SerialBridgeNode(Node):
diag.header.stamp = stamp
status = DiagnosticStatus()
status.name = "saltybot/balance_controller"
<<<<<<< HEAD
status.hardware_id = "esp32"
=======
status.hardware_id = "esp32s322"
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
status.hardware_id = "esp32s3_balance"
status.message = state_label
if state == 1: # ARMED
@ -317,19 +293,11 @@ class SerialBridgeNode(Node):
status = DiagnosticStatus()
status.level = DiagnosticStatus.ERROR
status.name = "saltybot/balance_controller"
<<<<<<< HEAD
status.hardware_id = "esp32"
status.hardware_id = "esp32s3_balance"
status.message = f"IMU fault errno={errno}"
diag.status.append(status)
self._diag_pub.publish(diag)
self.get_logger().error(f"ESP32 BALANCE reported IMU fault: errno={errno}")
=======
status.hardware_id = "esp32s322"
status.message = f"IMU fault errno={errno}"
diag.status.append(status)
self._diag_pub.publish(diag)
self.get_logger().error(f"ESP32-S3 reported IMU fault: errno={errno}")
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
self.get_logger().error(f"STM32 reported IMU fault: errno={errno}")
def destroy_node(self):
self._close_serial()

16
jetson/ros2_ws/src/saltybot_bringup/test/README_INTEGRATION_TESTS.md
View File

@ -61,11 +61,7 @@ kill %1
### Core System Components
- Robot Description (URDF/TF tree)
<<<<<<< HEAD
- ESP32 Serial Bridge
=======
- ESP32-S3 Serial Bridge
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
- ESP32-S3 CAN Bridge
- cmd_vel Bridge
- Rosbridge WebSocket
@ -129,15 +125,11 @@ free -h
### cmd_vel bridge not responding
```bash
<<<<<<< HEAD
# Verify ESP32 bridge is running first
=======
# Verify ESP32-S3 bridge is running first
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
# Verify CAN bridge is running first
ros2 node list | grep bridge
# Check serial port
ls -l /dev/esp32-bridge
# Check CAN interface
ip link show can0
```
## Performance Baseline

34
jetson/ros2_ws/src/saltybot_can_bridge/saltybot_can_bridge/balance_protocol.py
View File

@ -6,13 +6,13 @@ and VESC telemetry.
CAN message layout
------------------
Command frames (Orin → ESP32-S3 BALANCE / VESC):
MAMBA_CMD_VELOCITY 0x100 8 bytes left_speed (f32, m/s) | right_speed (f32, m/s)
MAMBA_CMD_MODE 0x101 1 byte mode (0=idle, 1=drive, 2=estop)
MAMBA_CMD_ESTOP 0x102 1 byte 0x01 = stop
BALANCE_CMD_VELOCITY 0x100 8 bytes left_speed (f32, m/s) | right_speed (f32, m/s)
BALANCE_CMD_MODE 0x101 1 byte mode (0=idle, 1=drive, 2=estop)
BALANCE_CMD_ESTOP 0x102 1 byte 0x01 = stop
Telemetry frames (ESP32-S3 BALANCE → Orin):
MAMBA_TELEM_IMU 0x200 24 bytes accel_x, accel_y, accel_z, gyro_x, gyro_y, gyro_z (f32 each)
MAMBA_TELEM_BATTERY 0x201 8 bytes voltage (f32, V) | current (f32, A)
BALANCE_TELEM_IMU 0x200 24 bytes accel_x, accel_y, accel_z, gyro_x, gyro_y, gyro_z (f32 each)
BALANCE_TELEM_BATTERY 0x201 8 bytes voltage (f32, V) | current (f32, A)
VESC telemetry frame (VESC → Orin):
VESC_TELEM_STATE 0x300 16 bytes erpm (f32) | duty (f32) | voltage (f32) | current (f32)
@ -30,12 +30,12 @@ from typing import Tuple
# CAN message IDs
# ---------------------------------------------------------------------------
MAMBA_CMD_VELOCITY: int = 0x100
MAMBA_CMD_MODE: int = 0x101
MAMBA_CMD_ESTOP: int = 0x102
BALANCE_CMD_VELOCITY: int = 0x100
BALANCE_CMD_MODE: int = 0x101
BALANCE_CMD_ESTOP: int = 0x102
MAMBA_TELEM_IMU: int = 0x200
MAMBA_TELEM_BATTERY: int = 0x201
BALANCE_TELEM_IMU: int = 0x200
BALANCE_TELEM_BATTERY: int = 0x201
VESC_TELEM_STATE: int = 0x300
ORIN_CAN_ID_PID_SET: int = 0x305
@ -56,7 +56,7 @@ MODE_ESTOP: int = 2
@dataclass
class ImuTelemetry:
"""Decoded IMU telemetry from ESP32-S3 BALANCE (MAMBA_TELEM_IMU)."""
"""Decoded IMU telemetry from ESP32-S3 BALANCE (BALANCE_TELEM_IMU)."""
accel_x: float = 0.0 # m/s²
accel_y: float = 0.0
@ -68,7 +68,7 @@ class ImuTelemetry:
@dataclass
class BatteryTelemetry:
"""Decoded battery telemetry from ESP32-S3 BALANCE (MAMBA_TELEM_BATTERY)."""
"""Decoded battery telemetry from ESP32-S3 BALANCE (BALANCE_TELEM_BATTERY)."""
voltage: float = 0.0 # V
current: float = 0.0 # A
@ -106,7 +106,7 @@ _FMT_VESC = ">ffff" # 4 × float32
def encode_velocity_cmd(left_mps: float, right_mps: float) -> bytes:
"""
Encode a MAMBA_CMD_VELOCITY payload.
Encode a BALANCE_CMD_VELOCITY payload.
Parameters
----------
@ -122,7 +122,7 @@ def encode_velocity_cmd(left_mps: float, right_mps: float) -> bytes:
def encode_mode_cmd(mode: int) -> bytes:
"""
Encode a MAMBA_CMD_MODE payload.
Encode a BALANCE_CMD_MODE payload.
Parameters
----------
@ -139,7 +139,7 @@ def encode_mode_cmd(mode: int) -> bytes:
def encode_estop_cmd(stop: bool = True) -> bytes:
"""
Encode a MAMBA_CMD_ESTOP payload.
Encode a BALANCE_CMD_ESTOP payload.
Parameters
----------
@ -165,7 +165,7 @@ def encode_pid_set_cmd(kp: float, ki: float, kd: float) -> bytes:
def decode_imu_telem(data: bytes) -> ImuTelemetry:
"""
Decode a MAMBA_TELEM_IMU payload.
Decode a BALANCE_TELEM_IMU payload.
Parameters
----------
@ -188,7 +188,7 @@ def decode_imu_telem(data: bytes) -> ImuTelemetry:
def decode_battery_telem(data: bytes) -> BatteryTelemetry:
"""
Decode a MAMBA_TELEM_BATTERY payload.
Decode a BALANCE_TELEM_BATTERY payload.
Parameters
----------

289
jetson/ros2_ws/src/saltybot_can_bridge/saltybot_can_bridge/can_bridge_node.py
View File

@ -1,9 +1,10 @@
#!/usr/bin/env python3
"""
can_bridge_node.py — ROS2 node bridging the SaltyBot Orin to the ESP32-S3 BALANCE motor
can_bridge_node.py — ROS2 node bridging the SaltyBot Orin to the ESP32-S3 BALANCE
controller and VESC motor controllers over CAN bus.
Spec: docs/SAUL-TEE-SYSTEM-REFERENCE.md §6 (2026-04-04)
The node opens the SocketCAN interface (slcan0 by default), spawns a background
reader thread to process incoming telemetry, and exposes the following interface:
Subscriptions
-------------
@ -18,15 +19,9 @@ Publications
/can/vesc/right/state std_msgs/Float32MultiArray Right VESC state
/can/connection_status std_msgs/String "connected" | "disconnected"
Parameters
----------
can_interface str CAN socket name (default: slcan0)
speed_scale float /cmd_vel linear.x (m/s) → motor units (default: 1000.0)
steer_scale float /cmd_vel angular.z (rad/s) → motor units (default: -500.0)
command_timeout_s float watchdog zero-vel threshold (default: 0.5)
Issue: https://gitea.vayrette.com/seb/saltylab-firmware/issues/674
"""
import json
import threading
import time
from typing import Optional
@ -35,32 +30,36 @@ import can
import rclpy
from geometry_msgs.msg import Twist
from rclpy.node import Node
from sensor_msgs.msg import BatteryState
from rcl_interfaces.msg import SetParametersResult
from sensor_msgs.msg import BatteryState, Imu
from std_msgs.msg import Bool, Float32MultiArray, String
from saltybot_can_bridge.balance_protocol import (
MAMBA_CMD_ESTOP,
MAMBA_CMD_MODE,
MAMBA_CMD_VELOCITY,
MAMBA_TELEM_BATTERY,
MAMBA_TELEM_IMU,
BALANCE_CMD_ESTOP,
BALANCE_CMD_MODE,
BALANCE_CMD_VELOCITY,
BALANCE_TELEM_BATTERY,
BALANCE_TELEM_IMU,
VESC_TELEM_STATE,
ORIN_CAN_ID_FC_PID_ACK,
ORIN_CAN_ID_PID_SET,
MODE_DRIVE,
MODE_ESTOP,
MODE_IDLE,
encode_drive_cmd,
encode_arm_cmd,
encode_estop_cmd,
decode_attitude,
decode_battery,
decode_vesc_status1,
encode_mode_cmd,
encode_velocity_cmd,
encode_pid_set_cmd,
decode_battery_telem,
decode_imu_telem,
decode_pid_ack,
decode_vesc_state,
)
# Reconnect attempt interval when CAN bus is lost
_RECONNECT_INTERVAL_S: float = 5.0
# Watchdog tick rate (Hz); sends zero DRIVE when /cmd_vel is silent
# Watchdog timer tick rate (Hz)
_WATCHDOG_HZ: float = 10.0
@ -71,41 +70,50 @@ class CanBridgeNode(Node):
super().__init__("can_bridge_node")
# ── Parameters ────────────────────────────────────────────────────
self.declare_parameter("can_interface", "slcan0")
self.declare_parameter("left_vesc_can_id", VESC_LEFT_ID)
self.declare_parameter("right_vesc_can_id", VESC_RIGHT_ID)
self.declare_parameter("speed_scale", 1000.0)
self.declare_parameter("steer_scale", -500.0)
self.declare_parameter("can_interface", "can0")
self.declare_parameter("left_vesc_can_id", 68)
self.declare_parameter("right_vesc_can_id", 56)
self.declare_parameter("balance_can_id", 1)
self.declare_parameter("command_timeout_s", 0.5)
self.declare_parameter("pid/kp", 0.0)
self.declare_parameter("pid/ki", 0.0)
self.declare_parameter("pid/kd", 0.0)
self._iface = self.get_parameter("can_interface").value
self._left_vesc_id = self.get_parameter("left_vesc_can_id").value
self._right_vesc_id = self.get_parameter("right_vesc_can_id").value
self._speed_scale = self.get_parameter("speed_scale").value
self._steer_scale = self.get_parameter("steer_scale").value
self._cmd_timeout = self.get_parameter("command_timeout_s").value
self._iface: str = self.get_parameter("can_interface").value
self._left_vesc_id: int = self.get_parameter("left_vesc_can_id").value
self._right_vesc_id: int = self.get_parameter("right_vesc_can_id").value
self._balance_id: int = self.get_parameter("balance_can_id").value
self._cmd_timeout: float = self.get_parameter("command_timeout_s").value
self._pid_kp: float = self.get_parameter("pid/kp").value
self._pid_ki: float = self.get_parameter("pid/ki").value
self._pid_kd: float = self.get_parameter("pid/kd").value
# ── State ─────────────────────────────────────────────────────────
self._bus: Optional[can.BusABC] = None
self._connected: bool = False
self._last_cmd_time: float = time.monotonic()
self._lock = threading.Lock()
self._lock = threading.Lock() # protects _bus / _connected
# ── Publishers ────────────────────────────────────────────────────
self._pub_attitude = self.create_publisher(String, "/saltybot/attitude", 10)
self._pub_balance = self.create_publisher(String, "/saltybot/balance_state", 10)
self._pub_battery = self.create_publisher(BatteryState, "/can/battery", 10)
self._pub_vesc_left = self.create_publisher(Float32MultiArray,"/can/vesc/left/state", 10)
self._pub_vesc_right= self.create_publisher(Float32MultiArray,"/can/vesc/right/state", 10)
self._pub_status = self.create_publisher(String, "/can/connection_status", 10)
self._pub_imu = self.create_publisher(Imu, "/can/imu", 10)
self._pub_battery = self.create_publisher(BatteryState, "/can/battery", 10)
self._pub_vesc_left = self.create_publisher(
Float32MultiArray, "/can/vesc/left/state", 10
)
self._pub_vesc_right = self.create_publisher(
Float32MultiArray, "/can/vesc/right/state", 10
)
self._pub_status = self.create_publisher(
String, "/can/connection_status", 10
)
# ── Subscriptions ─────────────────────────────────────────────────
self.create_subscription(Twist, "/cmd_vel", self._cmd_vel_cb, 10)
self.create_subscription(Bool, "/estop", self._estop_cb, 10)
self.create_subscription(Bool, "/saltybot/arm", self._arm_cb, 10)
self.create_subscription(Twist, "/cmd_vel", self._cmd_vel_cb, 10)
self.create_subscription(Bool, "/estop", self._estop_cb, 10)
self.add_on_set_parameters_callback(self._on_set_parameters)
# ── Timers ────────────────────────────────────────────────────────
self.create_timer(1.0 / _WATCHDOG_HZ, self._watchdog_cb)
self.create_timer(1.0 / _WATCHDOG_HZ, self._watchdog_cb)
self.create_timer(_RECONNECT_INTERVAL_S, self._reconnect_cb)
# ── Open CAN ──────────────────────────────────────────────────────
@ -120,17 +128,46 @@ class CanBridgeNode(Node):
self.get_logger().info(
f"can_bridge_node ready — iface={self._iface} "
f"left_vesc={self._left_vesc_id} right_vesc={self._right_vesc_id} "
f"speed_scale={self._speed_scale} steer_scale={self._steer_scale}"
f"balance={self._balance_id}"
)
# -- PID parameter callback (Issue #693) --
def _on_set_parameters(self, params) -> SetParametersResult:
"""Send new PID gains over CAN when pid/* params change."""
for p in params:
if p.name == "pid/kp":
self._pid_kp = float(p.value)
elif p.name == "pid/ki":
self._pid_ki = float(p.value)
elif p.name == "pid/kd":
self._pid_kd = float(p.value)
else:
continue
try:
payload = encode_pid_set_cmd(self._pid_kp, self._pid_ki, self._pid_kd)
self._send_can(ORIN_CAN_ID_PID_SET, payload, "pid_set")
self.get_logger().info(
f"PID gains sent: Kp={self._pid_kp:.2f} "
f"Ki={self._pid_ki:.2f} Kd={self._pid_kd:.2f}"
)
except ValueError as exc:
return SetParametersResult(successful=False, reason=str(exc))
return SetParametersResult(successful=True)
# ── Connection management ──────────────────────────────────────────────
def _try_connect(self) -> None:
"""Attempt to open the CAN interface; silently skip if already connected."""
with self._lock:
if self._connected:
return
try:
self._bus = can.interface.Bus(channel=self._iface, bustype="socketcan")
bus = can.interface.Bus(
channel=self._iface,
bustype="socketcan",
)
self._bus = bus
self._connected = True
self.get_logger().info(f"CAN bus connected: {self._iface}")
self._publish_status("connected")
@ -143,10 +180,12 @@ class CanBridgeNode(Node):
self._publish_status("disconnected")
def _reconnect_cb(self) -> None:
"""Periodic timer: try to reconnect when disconnected."""
if not self._connected:
self._try_connect()
def _handle_can_error(self, exc: Exception, context: str) -> None:
"""Mark bus as disconnected on any CAN error."""
self.get_logger().warning(f"CAN error in {context}: {exc}")
with self._lock:
if self._bus is not None:
@ -161,8 +200,9 @@ class CanBridgeNode(Node):
# ── ROS callbacks ─────────────────────────────────────────────────────
def _cmd_vel_cb(self, msg: Twist) -> None:
"""Convert /cmd_vel Twist to ORIN_CMD_DRIVE over CAN."""
"""Convert /cmd_vel Twist to VESC speed commands over CAN."""
self._last_cmd_time = time.monotonic()
if not self._connected:
return
@ -179,40 +219,54 @@ class CanBridgeNode(Node):
right_mps = linear + angular
payload = encode_velocity_cmd(left_mps, right_mps)
self._send_can(MAMBA_CMD_VELOCITY, payload, "cmd_vel")
self._send_can(BALANCE_CMD_VELOCITY, payload, "cmd_vel")
# Keep ESP32-S3 BALANCE in DRIVE mode while receiving commands
self._send_can(MAMBA_CMD_MODE, encode_mode_cmd(MODE_DRIVE), "cmd_vel mode")
self._send_can(BALANCE_CMD_MODE, encode_mode_cmd(MODE_DRIVE), "cmd_vel mode")
def _estop_cb(self, msg: Bool) -> None:
"""Forward /estop to ESP32-S3 BALANCE over CAN."""
if not self._connected:
return
payload = encode_estop_cmd(msg.data)
self._send_can(BALANCE_CMD_ESTOP, payload, "estop")
if msg.data:
self._send_can(
MAMBA_CMD_MODE, encode_mode_cmd(MODE_ESTOP), "estop mode"
BALANCE_CMD_MODE, encode_mode_cmd(MODE_ESTOP), "estop mode"
)
self.get_logger().warning("E-stop asserted — sent ESTOP to ESP32-S3 BALANCE")
# ── Watchdog ──────────────────────────────────────────────────────────
def _watchdog_cb(self) -> None:
"""If /cmd_vel is silent for command_timeout_s, send zero DRIVE (acts as keepalive)."""
"""If no /cmd_vel arrives within the timeout, send zero velocity."""
if not self._connected:
return
if time.monotonic() - self._last_cmd_time > self._cmd_timeout:
self._send_can(ORIN_CMD_DRIVE, encode_drive_cmd(0, 0, MODE_IDLE), "watchdog")
elapsed = time.monotonic() - self._last_cmd_time
if elapsed > self._cmd_timeout:
self._send_can(
BALANCE_CMD_VELOCITY,
encode_velocity_cmd(0.0, 0.0),
"watchdog zero-vel",
)
self._send_can(
BALANCE_CMD_MODE, encode_mode_cmd(MODE_IDLE), "watchdog idle"
)
# ── CAN send helper ───────────────────────────────────────────────────
def _send_can(self, arb_id: int, data: bytes, context: str,
extended: bool = False) -> None:
def _send_can(self, arb_id: int, data: bytes, context: str) -> None:
"""Send a standard CAN frame; handle errors gracefully."""
with self._lock:
if not self._connected or self._bus is None:
return
bus = self._bus
msg = can.Message(arbitration_id=arb_id, data=data,
is_extended_id=extended)
msg = can.Message(
arbitration_id=arb_id,
data=data,
is_extended_id=False,
)
try:
bus.send(msg, timeout=0.05)
except can.CanError as exc:
@ -221,41 +275,55 @@ class CanBridgeNode(Node):
# ── Background CAN reader ─────────────────────────────────────────────
def _reader_loop(self) -> None:
"""
Blocking CAN read loop executed in a daemon thread.
Dispatches incoming frames to the appropriate handler.
"""
while rclpy.ok():
with self._lock:
connected, bus = self._connected, self._bus
connected = self._connected
bus = self._bus
if not connected or bus is None:
time.sleep(0.1)
continue
try:
frame = bus.recv(timeout=0.5)
except can.CanError as exc:
self._handle_can_error(exc, "reader_loop recv")
continue
if frame is None:
# Timeout — no frame within 0.5 s, loop again
continue
self._dispatch_frame(frame)
def _dispatch_frame(self, frame: can.Message) -> None:
"""Route an incoming CAN frame to the correct publisher."""
arb_id = frame.arbitration_id
data = bytes(frame.data)
vesc_l = (VESC_STATUS_1 << 8) | self._left_vesc_id
vesc_r = (VESC_STATUS_1 << 8) | self._right_vesc_id
data = bytes(frame.data)
try:
if arb_id == ESP32_TELEM_ATTITUDE:
self._handle_attitude(data)
elif arb_id == ESP32_TELEM_BATTERY:
self._handle_battery(data)
elif arb_id == vesc_l:
t = decode_vesc_status1(self._left_vesc_id, data)
m = Float32MultiArray()
m.data = [t.erpm, t.duty, 0.0, t.current]
self._pub_vesc_left.publish(m)
elif arb_id == vesc_r:
t = decode_vesc_status1(self._right_vesc_id, data)
m = Float32MultiArray()
m.data = [t.erpm, t.duty, 0.0, t.current]
self._pub_vesc_right.publish(m)
if arb_id == BALANCE_TELEM_IMU:
self._handle_imu(data, frame.timestamp)
elif arb_id == BALANCE_TELEM_BATTERY:
self._handle_battery(data, frame.timestamp)
elif arb_id == VESC_TELEM_STATE + self._left_vesc_id:
self._handle_vesc_state(data, frame.timestamp, side="left")
elif arb_id == VESC_TELEM_STATE + self._right_vesc_id:
self._handle_vesc_state(data, frame.timestamp, side="right")
elif arb_id == ORIN_CAN_ID_FC_PID_ACK:
gains = decode_pid_ack(data)
self.get_logger().debug(
f"FC PID ACK: Kp={gains.kp:.2f} Ki={gains.ki:.2f} Kd={gains.kd:.2f}"
)
except Exception as exc:
self.get_logger().warning(
f"Error parsing CAN frame 0x{arb_id:03X}: {exc}"
@ -263,36 +331,52 @@ class CanBridgeNode(Node):
# ── Frame handlers ────────────────────────────────────────────────────
_STATE_LABEL = {0: "IDLE", 1: "RUNNING", 2: "FAULT"}
def _handle_imu(self, data: bytes, timestamp: float) -> None:
telem = decode_imu_telem(data)
def _handle_attitude(self, data: bytes) -> None:
"""ATTITUDE (0x400): pitch, speed, yaw_rate, state, flags → /saltybot/attitude."""
t = decode_attitude(data)
now = self.get_clock().now().to_msg()
payload = {
"pitch_deg": round(t.pitch_deg, 2),
"speed_mps": round(t.speed, 3),
"yaw_rate": round(t.yaw_rate, 3),
"state": t.state,
"state_label": self._STATE_LABEL.get(t.state, f"UNKNOWN({t.state})"),
"flags": t.flags,
"ts": f"{now.sec}.{now.nanosec:09d}",
}
msg = String()
msg.data = json.dumps(payload)
self._pub_attitude.publish(msg)
self._pub_balance.publish(msg) # keep /saltybot/balance_state alive
msg = Imu()
msg.header.stamp = self.get_clock().now().to_msg()
msg.header.frame_id = "imu_link"
msg.linear_acceleration.x = telem.accel_x
msg.linear_acceleration.y = telem.accel_y
msg.linear_acceleration.z = telem.accel_z
msg.angular_velocity.x = telem.gyro_x
msg.angular_velocity.y = telem.gyro_y
msg.angular_velocity.z = telem.gyro_z
# Covariance unknown; mark as -1 per REP-145
msg.orientation_covariance[0] = -1.0
self._pub_imu.publish(msg)
def _handle_battery(self, data: bytes, timestamp: float) -> None:
telem = decode_battery_telem(data)
def _handle_battery(self, data: bytes) -> None:
"""BATTERY (0x401): vbat_mv, fault_code, rssi → /can/battery."""
t = decode_battery(data)
msg = BatteryState()
msg.header.stamp = self.get_clock().now().to_msg()
msg.voltage = t.vbat_mv / 1000.0
msg.voltage = telem.voltage
msg.current = telem.current
msg.present = True
msg.power_supply_status = BatteryState.POWER_SUPPLY_STATUS_DISCHARGING
self._pub_battery.publish(msg)
def _handle_vesc_state(
self, data: bytes, timestamp: float, side: str
) -> None:
telem = decode_vesc_state(data)
msg = Float32MultiArray()
# Layout: [erpm, duty, voltage, current]
msg.data = [telem.erpm, telem.duty, telem.voltage, telem.current]
if side == "left":
self._pub_vesc_left.publish(msg)
else:
self._pub_vesc_right.publish(msg)
# ── Status helper ─────────────────────────────────────────────────────
def _publish_status(self, status: str) -> None:
@ -303,10 +387,17 @@ class CanBridgeNode(Node):
# ── Shutdown ──────────────────────────────────────────────────────────
def destroy_node(self) -> None:
"""Send zero velocity and shut down the CAN bus cleanly."""
if self._connected and self._bus is not None:
try:
self._send_can(ORIN_CMD_DRIVE, encode_drive_cmd(0, 0, MODE_IDLE), "shutdown")
self._send_can(ORIN_CMD_ARM, encode_arm_cmd(False), "shutdown")
self._send_can(
BALANCE_CMD_VELOCITY,
encode_velocity_cmd(0.0, 0.0),
"shutdown",
)
self._send_can(
BALANCE_CMD_MODE, encode_mode_cmd(MODE_IDLE), "shutdown"
)
except Exception:
pass
try:
@ -316,6 +407,8 @@ class CanBridgeNode(Node):
super().destroy_node()
# ---------------------------------------------------------------------------
def main(args=None) -> None:
rclpy.init(args=args)
node = CanBridgeNode()

4
jetson/ros2_ws/src/saltybot_can_bridge/setup.py
View File

@ -15,11 +15,7 @@ setup(
zip_safe=True,
maintainer="sl-controls",
maintainer_email="sl-controls@saltylab.local",
<<<<<<< HEAD
description="CAN bus bridge for ESP32 IO motor controller and VESC telemetry",
=======
description="CAN bus bridge for ESP32-S3 BALANCE controller and VESC telemetry",
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
license="MIT",
tests_require=["pytest"],
entry_points={

20
jetson/ros2_ws/src/saltybot_can_bridge/test/test_can_bridge.py
View File

@ -12,11 +12,11 @@ import struct
import unittest
from saltybot_can_bridge.balance_protocol import (
MAMBA_CMD_ESTOP,
MAMBA_CMD_MODE,
MAMBA_CMD_VELOCITY,
MAMBA_TELEM_BATTERY,
MAMBA_TELEM_IMU,
BALANCE_CMD_ESTOP,
BALANCE_CMD_MODE,
BALANCE_CMD_VELOCITY,
BALANCE_TELEM_BATTERY,
BALANCE_TELEM_IMU,
VESC_TELEM_STATE,
MODE_DRIVE,
MODE_ESTOP,
@ -37,13 +37,13 @@ class TestMessageIDs(unittest.TestCase):
"""Verify the CAN message ID constants are correct."""
def test_command_ids(self):
self.assertEqual(MAMBA_CMD_VELOCITY, 0x100)
self.assertEqual(MAMBA_CMD_MODE, 0x101)
self.assertEqual(MAMBA_CMD_ESTOP, 0x102)
self.assertEqual(BALANCE_CMD_VELOCITY, 0x100)
self.assertEqual(BALANCE_CMD_MODE, 0x101)
self.assertEqual(BALANCE_CMD_ESTOP, 0x102)
def test_telemetry_ids(self):
self.assertEqual(MAMBA_TELEM_IMU, 0x200)
self.assertEqual(MAMBA_TELEM_BATTERY, 0x201)
self.assertEqual(BALANCE_TELEM_IMU, 0x200)
self.assertEqual(BALANCE_TELEM_BATTERY, 0x201)
self.assertEqual(VESC_TELEM_STATE, 0x300)

41
jetson/ros2_ws/src/saltybot_can_e2e_test/saltybot_can_e2e_test/protocol_defs.py
View File

@ -4,31 +4,28 @@ protocol_defs.py — CAN message ID constants and frame builders/parsers for the
Orin↔ESP32-S3 BALANCE↔VESC integration test suite.
All IDs and payload formats are derived from:
include/orin_can.h — Orin↔FC (ESP32-S3 BALANCE) protocol
include/orin_can.h — Orin↔ESP32-S3 BALANCE protocol
include/vesc_can.h — VESC CAN protocol
saltybot_can_bridge/balance_protocol.py — existing bridge constants
CAN IDs used in tests
---------------------
Orin → FC (ESP32-S3 BALANCE) commands (standard 11-bit, matching orin_can.h):
Orin → ESP32-S3 BALANCE commands (standard 11-bit, matching orin_can.h):
ORIN_CMD_HEARTBEAT 0x300
ORIN_CMD_DRIVE 0x301 int16 speed (−1000..+1000), int16 steer (−1000..+1000)
ORIN_CMD_MODE 0x302 uint8 mode byte
ORIN_CMD_ESTOP 0x303 uint8 action (1=ESTOP, 0=CLEAR)
FC (ESP32-S3 BALANCE) → Orin telemetry (standard 11-bit, matching orin_can.h):
ESP32-S3 BALANCE → Orin telemetry (standard 11-bit, matching orin_can.h):
FC_STATUS 0x400 8 bytes (see orin_can_fc_status_t)
FC_VESC 0x401 8 bytes (see orin_can_fc_vesc_t)
FC_IMU 0x402 8 bytes
FC_BARO 0x403 8 bytes
Mamba ↔ VESC internal commands (matching balance_protocol.py):
=======
ESP32-S3 BALANCE ↔ VESC internal commands (matching balance_protocol.py):
>>>>>>> 9aed963 (fix: scrub remaining Mamba references in can_bridge and e2e test protocol files)
MAMBA_CMD_VELOCITY 0x100 8 bytes left_mps (f32) | right_mps (f32) big-endian
MAMBA_CMD_MODE 0x101 1 byte mode (0=idle,1=drive,2=estop)
MAMBA_CMD_ESTOP 0x102 1 byte 0x01=stop
BALANCE_CMD_VELOCITY 0x100 8 bytes left_mps (f32) | right_mps (f32) big-endian
BALANCE_CMD_MODE 0x101 1 byte mode (0=idle,1=drive,2=estop)
BALANCE_CMD_ESTOP 0x102 1 byte 0x01=stop
VESC STATUS (extended 29-bit, matching vesc_can.h):
arb_id = (VESC_PKT_STATUS << 8) | vesc_node_id = (9 << 8) | node_id
@ -39,7 +36,7 @@ import struct
from typing import Tuple
# ---------------------------------------------------------------------------
# Orin → FC (ESP32-S3 BALANCE) command IDs (from orin_can.h)
# Orin → ESP32-S3 BALANCE command IDs (from orin_can.h)
# ---------------------------------------------------------------------------
ORIN_CMD_HEARTBEAT: int = 0x300
@ -48,7 +45,7 @@ ORIN_CMD_MODE: int = 0x302
ORIN_CMD_ESTOP: int = 0x303
# ---------------------------------------------------------------------------
# FC (ESP32-S3 BALANCE) → Orin telemetry IDs (from orin_can.h)
# ESP32-S3 BALANCE → Orin telemetry IDs (from orin_can.h)
# ---------------------------------------------------------------------------
FC_STATUS: int = 0x400
@ -57,18 +54,15 @@ FC_IMU: int = 0x402
FC_BARO: int = 0x403
# ---------------------------------------------------------------------------
# Mamba → VESC internal command IDs (from balance_protocol.py)
=======
# ESP32-S3 BALANCE → VESC internal command IDs (from balance_protocol.py)
>>>>>>> 9aed963 (fix: scrub remaining Mamba references in can_bridge and e2e test protocol files)
# ---------------------------------------------------------------------------
MAMBA_CMD_VELOCITY: int = 0x100
MAMBA_CMD_MODE: int = 0x101
MAMBA_CMD_ESTOP: int = 0x102
BALANCE_CMD_VELOCITY: int = 0x100
BALANCE_CMD_MODE: int = 0x101
BALANCE_CMD_ESTOP: int = 0x102
MAMBA_TELEM_IMU: int = 0x200
MAMBA_TELEM_BATTERY: int = 0x201
BALANCE_TELEM_IMU: int = 0x200
BALANCE_TELEM_BATTERY: int = 0x201
VESC_TELEM_STATE: int = 0x300
# ---------------------------------------------------------------------------
@ -142,15 +136,12 @@ def build_estop_cmd(action: int = 1) -> bytes:
# ---------------------------------------------------------------------------
# Frame builders — Mamba velocity commands (balance_protocol.py encoding)
=======
# Frame builders — ESP32-S3 BALANCE velocity commands (balance_protocol.py encoding)
>>>>>>> 9aed963 (fix: scrub remaining Mamba references in can_bridge and e2e test protocol files)
# ---------------------------------------------------------------------------
def build_velocity_cmd(left_mps: float, right_mps: float) -> bytes:
"""
Build a MAMBA_CMD_VELOCITY payload (8 bytes, 2 × float32 big-endian).
Build a BALANCE_CMD_VELOCITY payload (8 bytes, 2 × float32 big-endian).
Matches encode_velocity_cmd() in balance_protocol.py.
"""
@ -312,12 +303,12 @@ def parse_vesc_status(data: bytes):
def parse_velocity_cmd(data: bytes) -> Tuple[float, float]:
"""
Parse a MAMBA_CMD_VELOCITY payload (8 bytes, 2 × float32 big-endian).
Parse a BALANCE_CMD_VELOCITY payload (8 bytes, 2 × float32 big-endian).
Returns
-------
(left_mps, right_mps)
"""
if len(data) < 8:
raise ValueError(f"MAMBA_CMD_VELOCITY needs 8 bytes, got {len(data)}")
raise ValueError(f"BALANCE_CMD_VELOCITY needs 8 bytes, got {len(data)}")
return struct.unpack(">ff", data[:8])

28
jetson/ros2_ws/src/saltybot_can_e2e_test/test/test_drive_command.py
View File

@ -14,8 +14,8 @@ import struct
import pytest
from saltybot_can_e2e_test.protocol_defs import (
MAMBA_CMD_VELOCITY,
MAMBA_CMD_MODE,
BALANCE_CMD_VELOCITY,
BALANCE_CMD_MODE,
FC_VESC,
MODE_DRIVE,
MODE_IDLE,
@ -50,8 +50,8 @@ def _send_drive(bus, left_mps: float, right_mps: float) -> None:
self.data = bytearray(data)
self.is_extended_id = False
bus.send(_Msg(MAMBA_CMD_VELOCITY, payload))
bus.send(_Msg(MAMBA_CMD_MODE, encode_mode_cmd(MODE_DRIVE)))
bus.send(_Msg(BALANCE_CMD_VELOCITY, payload))
bus.send(_Msg(BALANCE_CMD_MODE, encode_mode_cmd(MODE_DRIVE)))
# ---------------------------------------------------------------------------
@ -62,11 +62,11 @@ class TestDriveForward:
def test_drive_forward_velocity_frame_sent(self, mock_can_bus):
"""
Inject DRIVE cmd (1.0 m/s, 1.0 m/s) → verify ESP32-S3 BALANCE receives
a MAMBA_CMD_VELOCITY frame with correct payload.
a BALANCE_CMD_VELOCITY frame with correct payload.
"""
_send_drive(mock_can_bus, 1.0, 1.0)
vel_frames = mock_can_bus.get_sent_frames_by_id(MAMBA_CMD_VELOCITY)
vel_frames = mock_can_bus.get_sent_frames_by_id(BALANCE_CMD_VELOCITY)
assert len(vel_frames) == 1, "Expected exactly one velocity command frame"
left, right = parse_velocity_cmd(bytes(vel_frames[0].data))
@ -77,7 +77,7 @@ class TestDriveForward:
"""After a drive command, a MODE=drive frame must accompany it."""
_send_drive(mock_can_bus, 1.0, 1.0)
mode_frames = mock_can_bus.get_sent_frames_by_id(MAMBA_CMD_MODE)
mode_frames = mock_can_bus.get_sent_frames_by_id(BALANCE_CMD_MODE)
assert len(mode_frames) >= 1, "Expected at least one MODE frame"
assert bytes(mode_frames[0].data) == bytes([MODE_DRIVE])
@ -109,7 +109,7 @@ class TestDriveTurn:
"""
_send_drive(mock_can_bus, 0.5, -0.5)
vel_frames = mock_can_bus.get_sent_frames_by_id(MAMBA_CMD_VELOCITY)
vel_frames = mock_can_bus.get_sent_frames_by_id(BALANCE_CMD_VELOCITY)
assert len(vel_frames) == 1
left, right = parse_velocity_cmd(bytes(vel_frames[0].data))
@ -142,7 +142,7 @@ class TestDriveZero:
_send_drive(mock_can_bus, 0.0, 0.0)
vel_frames = mock_can_bus.get_sent_frames_by_id(MAMBA_CMD_VELOCITY)
vel_frames = mock_can_bus.get_sent_frames_by_id(BALANCE_CMD_VELOCITY)
assert len(vel_frames) == 1
left, right = parse_velocity_cmd(bytes(vel_frames[0].data))
assert abs(left) < 1e-5, "Left motor not stopped"
@ -156,7 +156,7 @@ class TestDriveCmdTimeout:
zero velocity is sent. We test the encoding directly (without timers).
"""
# The watchdog in CanBridgeNode calls encode_velocity_cmd(0.0, 0.0) and
# sends it on MAMBA_CMD_VELOCITY. Replicate that here.
# sends it on BALANCE_CMD_VELOCITY. Replicate that here.
zero_payload = encode_velocity_cmd(0.0, 0.0)
class _Msg:
@ -165,16 +165,16 @@ class TestDriveCmdTimeout:
self.data = bytearray(data)
self.is_extended_id = False
mock_can_bus.send(_Msg(MAMBA_CMD_VELOCITY, zero_payload))
mock_can_bus.send(_Msg(MAMBA_CMD_MODE, encode_mode_cmd(MODE_IDLE)))
mock_can_bus.send(_Msg(BALANCE_CMD_VELOCITY, zero_payload))
mock_can_bus.send(_Msg(BALANCE_CMD_MODE, encode_mode_cmd(MODE_IDLE)))
vel_frames = mock_can_bus.get_sent_frames_by_id(MAMBA_CMD_VELOCITY)
vel_frames = mock_can_bus.get_sent_frames_by_id(BALANCE_CMD_VELOCITY)
assert len(vel_frames) == 1
left, right = parse_velocity_cmd(bytes(vel_frames[0].data))
assert abs(left) < 1e-5
assert abs(right) < 1e-5
mode_frames = mock_can_bus.get_sent_frames_by_id(MAMBA_CMD_MODE)
mode_frames = mock_can_bus.get_sent_frames_by_id(BALANCE_CMD_MODE)
assert len(mode_frames) == 1
assert bytes(mode_frames[0].data) == bytes([MODE_IDLE])

40
jetson/ros2_ws/src/saltybot_can_e2e_test/test/test_estop.py
View File

@ -17,9 +17,9 @@ import pytest
from saltybot_can_e2e_test.can_mock import MockCANBus
from saltybot_can_e2e_test.protocol_defs import (
MAMBA_CMD_VELOCITY,
MAMBA_CMD_MODE,
MAMBA_CMD_ESTOP,
BALANCE_CMD_VELOCITY,
BALANCE_CMD_MODE,
BALANCE_CMD_ESTOP,
ORIN_CMD_ESTOP,
FC_STATUS,
MODE_IDLE,
@ -68,16 +68,16 @@ class EstopStateMachine:
"""Send ESTOP and transition to estop mode."""
self._estop_active = True
self._mode = MODE_ESTOP
self._bus.send(_Msg(MAMBA_CMD_VELOCITY, encode_velocity_cmd(0.0, 0.0)))
self._bus.send(_Msg(MAMBA_CMD_MODE, encode_mode_cmd(MODE_ESTOP)))
self._bus.send(_Msg(MAMBA_CMD_ESTOP, encode_estop_cmd(True)))
self._bus.send(_Msg(BALANCE_CMD_VELOCITY, encode_velocity_cmd(0.0, 0.0)))
self._bus.send(_Msg(BALANCE_CMD_MODE, encode_mode_cmd(MODE_ESTOP)))
self._bus.send(_Msg(BALANCE_CMD_ESTOP, encode_estop_cmd(True)))
def clear_estop(self) -> None:
"""Clear ESTOP and return to IDLE mode."""
self._estop_active = False
self._mode = MODE_IDLE
self._bus.send(_Msg(MAMBA_CMD_ESTOP, encode_estop_cmd(False)))
self._bus.send(_Msg(MAMBA_CMD_MODE, encode_mode_cmd(MODE_IDLE)))
self._bus.send(_Msg(BALANCE_CMD_ESTOP, encode_estop_cmd(False)))
self._bus.send(_Msg(BALANCE_CMD_MODE, encode_mode_cmd(MODE_IDLE)))
def send_drive(self, left_mps: float, right_mps: float) -> None:
"""Send velocity command only if ESTOP is not active."""
@ -85,8 +85,8 @@ class EstopStateMachine:
# Bridge silently drops commands while estopped
return
self._mode = MODE_DRIVE
self._bus.send(_Msg(MAMBA_CMD_VELOCITY, encode_velocity_cmd(left_mps, right_mps)))
self._bus.send(_Msg(MAMBA_CMD_MODE, encode_mode_cmd(MODE_DRIVE)))
self._bus.send(_Msg(BALANCE_CMD_VELOCITY, encode_velocity_cmd(left_mps, right_mps)))
self._bus.send(_Msg(BALANCE_CMD_MODE, encode_mode_cmd(MODE_DRIVE)))
@property
def estop_active(self) -> bool:
@ -105,7 +105,7 @@ class TestEstopHaltsMotors:
sm = EstopStateMachine(mock_can_bus)
sm.assert_estop()
vel_frames = mock_can_bus.get_sent_frames_by_id(MAMBA_CMD_VELOCITY)
vel_frames = mock_can_bus.get_sent_frames_by_id(BALANCE_CMD_VELOCITY)
assert len(vel_frames) >= 1, "No velocity frame after ESTOP"
l, r = parse_velocity_cmd(bytes(vel_frames[-1].data))
assert abs(l) < 1e-5, f"Left motor {l} not zero after ESTOP"
@ -116,17 +116,17 @@ class TestEstopHaltsMotors:
sm = EstopStateMachine(mock_can_bus)
sm.assert_estop()
mode_frames = mock_can_bus.get_sent_frames_by_id(MAMBA_CMD_MODE)
mode_frames = mock_can_bus.get_sent_frames_by_id(BALANCE_CMD_MODE)
assert any(
bytes(f.data) == bytes([MODE_ESTOP]) for f in mode_frames
), "MODE=ESTOP not found in sent frames"
def test_estop_flag_byte_is_0x01(self, mock_can_bus):
"""MAMBA_CMD_ESTOP payload must be 0x01 when asserting e-stop."""
"""BALANCE_CMD_ESTOP payload must be 0x01 when asserting e-stop."""
sm = EstopStateMachine(mock_can_bus)
sm.assert_estop()
estop_frames = mock_can_bus.get_sent_frames_by_id(MAMBA_CMD_ESTOP)
estop_frames = mock_can_bus.get_sent_frames_by_id(BALANCE_CMD_ESTOP)
assert len(estop_frames) >= 1
assert bytes(estop_frames[-1].data) == b"\x01", \
f"ESTOP payload {estop_frames[-1].data!r} != 0x01"
@ -143,7 +143,7 @@ class TestEstopPersists:
sm.send_drive(1.0, 1.0) # should be suppressed
vel_frames = mock_can_bus.get_sent_frames_by_id(MAMBA_CMD_VELOCITY)
vel_frames = mock_can_bus.get_sent_frames_by_id(BALANCE_CMD_VELOCITY)
assert len(vel_frames) == 0, \
"Velocity command was forwarded while ESTOP is active"
@ -158,7 +158,7 @@ class TestEstopPersists:
sm.send_drive(0.5, 0.5)
# No mode frames should have been emitted (drive was suppressed)
mode_frames = mock_can_bus.get_sent_frames_by_id(MAMBA_CMD_MODE)
mode_frames = mock_can_bus.get_sent_frames_by_id(BALANCE_CMD_MODE)
assert all(
bytes(f.data) != bytes([MODE_DRIVE]) for f in mode_frames
), "MODE=DRIVE was set despite active ESTOP"
@ -174,19 +174,19 @@ class TestEstopClear:
sm.send_drive(0.8, 0.8)
vel_frames = mock_can_bus.get_sent_frames_by_id(MAMBA_CMD_VELOCITY)
vel_frames = mock_can_bus.get_sent_frames_by_id(BALANCE_CMD_VELOCITY)
assert len(vel_frames) == 1, "Velocity command not sent after ESTOP clear"
l, r = parse_velocity_cmd(bytes(vel_frames[0].data))
assert abs(l - 0.8) < 1e-4
assert abs(r - 0.8) < 1e-4
def test_estop_clear_flag_byte_is_0x00(self, mock_can_bus):
"""MAMBA_CMD_ESTOP payload must be 0x00 when clearing e-stop."""
"""BALANCE_CMD_ESTOP payload must be 0x00 when clearing e-stop."""
sm = EstopStateMachine(mock_can_bus)
sm.assert_estop()
sm.clear_estop()
estop_frames = mock_can_bus.get_sent_frames_by_id(MAMBA_CMD_ESTOP)
estop_frames = mock_can_bus.get_sent_frames_by_id(BALANCE_CMD_ESTOP)
assert len(estop_frames) >= 2
# Last ESTOP frame should be the clear
assert bytes(estop_frames[-1].data) == b"\x00", \
@ -198,7 +198,7 @@ class TestEstopClear:
sm.assert_estop()
sm.clear_estop()
mode_frames = mock_can_bus.get_sent_frames_by_id(MAMBA_CMD_MODE)
mode_frames = mock_can_bus.get_sent_frames_by_id(BALANCE_CMD_MODE)
last_mode = bytes(mode_frames[-1].data)
assert last_mode == bytes([MODE_IDLE]), \
f"Mode after ESTOP clear is {last_mode!r}, expected MODE_IDLE"

32
jetson/ros2_ws/src/saltybot_can_e2e_test/test/test_heartbeat_timeout.py
View File

@ -21,9 +21,9 @@ from saltybot_can_e2e_test.protocol_defs import (
ORIN_CMD_HEARTBEAT,
ORIN_CMD_ESTOP,
ORIN_CMD_MODE,
MAMBA_CMD_VELOCITY,
MAMBA_CMD_MODE,
MAMBA_CMD_ESTOP,
BALANCE_CMD_VELOCITY,
BALANCE_CMD_MODE,
BALANCE_CMD_ESTOP,
MODE_IDLE,
MODE_DRIVE,
MODE_ESTOP,
@ -100,9 +100,9 @@ def _simulate_estop_on_timeout(bus: MockCANBus) -> None:
self.data = bytearray(data)
self.is_extended_id = False
bus.send(_Msg(MAMBA_CMD_VELOCITY, encode_velocity_cmd(0.0, 0.0)))
bus.send(_Msg(MAMBA_CMD_MODE, encode_mode_cmd(MODE_ESTOP)))
bus.send(_Msg(MAMBA_CMD_ESTOP, encode_estop_cmd(True)))
bus.send(_Msg(BALANCE_CMD_VELOCITY, encode_velocity_cmd(0.0, 0.0)))
bus.send(_Msg(BALANCE_CMD_MODE, encode_mode_cmd(MODE_ESTOP)))
bus.send(_Msg(BALANCE_CMD_ESTOP, encode_estop_cmd(True)))
# ---------------------------------------------------------------------------
@ -121,25 +121,25 @@ class TestHeartbeatLoss:
# Simulate bridge detecting timeout and escalating
_simulate_estop_on_timeout(mock_can_bus)
vel_frames = mock_can_bus.get_sent_frames_by_id(MAMBA_CMD_VELOCITY)
vel_frames = mock_can_bus.get_sent_frames_by_id(BALANCE_CMD_VELOCITY)
assert len(vel_frames) >= 1, "Zero velocity not sent after timeout"
l, r = parse_velocity_cmd(bytes(vel_frames[-1].data))
assert abs(l) < 1e-5, "Left not zero on timeout"
assert abs(r) < 1e-5, "Right not zero on timeout"
mode_frames = mock_can_bus.get_sent_frames_by_id(MAMBA_CMD_MODE)
mode_frames = mock_can_bus.get_sent_frames_by_id(BALANCE_CMD_MODE)
assert any(
bytes(f.data) == bytes([MODE_ESTOP]) for f in mode_frames
), "ESTOP mode not asserted on heartbeat timeout"
estop_frames = mock_can_bus.get_sent_frames_by_id(MAMBA_CMD_ESTOP)
estop_frames = mock_can_bus.get_sent_frames_by_id(BALANCE_CMD_ESTOP)
assert len(estop_frames) >= 1, "ESTOP command not sent"
assert bytes(estop_frames[0].data) == b"\x01"
def test_heartbeat_loss_zero_velocity(self, mock_can_bus):
"""Zero velocity frame must appear among sent frames after timeout."""
_simulate_estop_on_timeout(mock_can_bus)
vel_frames = mock_can_bus.get_sent_frames_by_id(MAMBA_CMD_VELOCITY)
vel_frames = mock_can_bus.get_sent_frames_by_id(BALANCE_CMD_VELOCITY)
assert len(vel_frames) >= 1
for f in vel_frames:
l, r = parse_velocity_cmd(bytes(f.data))
@ -165,20 +165,20 @@ class TestHeartbeatRecovery:
mock_can_bus.reset()
# Phase 2: recovery — clear estop, restore drive mode
mock_can_bus.send(_Msg(MAMBA_CMD_ESTOP, encode_estop_cmd(False)))
mock_can_bus.send(_Msg(MAMBA_CMD_MODE, encode_mode_cmd(MODE_DRIVE)))
mock_can_bus.send(_Msg(MAMBA_CMD_VELOCITY, encode_velocity_cmd(0.5, 0.5)))
mock_can_bus.send(_Msg(BALANCE_CMD_ESTOP, encode_estop_cmd(False)))
mock_can_bus.send(_Msg(BALANCE_CMD_MODE, encode_mode_cmd(MODE_DRIVE)))
mock_can_bus.send(_Msg(BALANCE_CMD_VELOCITY, encode_velocity_cmd(0.5, 0.5)))
estop_frames = mock_can_bus.get_sent_frames_by_id(MAMBA_CMD_ESTOP)
estop_frames = mock_can_bus.get_sent_frames_by_id(BALANCE_CMD_ESTOP)
assert any(bytes(f.data) == b"\x00" for f in estop_frames), \
"ESTOP clear not sent on recovery"
mode_frames = mock_can_bus.get_sent_frames_by_id(MAMBA_CMD_MODE)
mode_frames = mock_can_bus.get_sent_frames_by_id(BALANCE_CMD_MODE)
assert any(
bytes(f.data) == bytes([MODE_DRIVE]) for f in mode_frames
), "DRIVE mode not restored after recovery"
vel_frames = mock_can_bus.get_sent_frames_by_id(MAMBA_CMD_VELOCITY)
vel_frames = mock_can_bus.get_sent_frames_by_id(BALANCE_CMD_VELOCITY)
assert len(vel_frames) >= 1
l, r = parse_velocity_cmd(bytes(vel_frames[-1].data))
assert abs(l - 0.5) < 1e-4

26
jetson/ros2_ws/src/saltybot_can_e2e_test/test/test_mode_switching.py
View File

@ -17,9 +17,9 @@ import pytest
from saltybot_can_e2e_test.can_mock import MockCANBus
from saltybot_can_e2e_test.protocol_defs import (
MAMBA_CMD_VELOCITY,
MAMBA_CMD_MODE,
MAMBA_CMD_ESTOP,
BALANCE_CMD_VELOCITY,
BALANCE_CMD_MODE,
BALANCE_CMD_ESTOP,
MODE_IDLE,
MODE_DRIVE,
MODE_ESTOP,
@ -64,12 +64,12 @@ class ModeStateMachine:
prev_mode = self._mode
self._mode = mode
self._bus.send(_Msg(MAMBA_CMD_MODE, encode_mode_cmd(mode)))
self._bus.send(_Msg(BALANCE_CMD_MODE, encode_mode_cmd(mode)))
# Side-effects of entering ESTOP from DRIVE
if mode == MODE_ESTOP and prev_mode == MODE_DRIVE:
self._bus.send(_Msg(MAMBA_CMD_VELOCITY, encode_velocity_cmd(0.0, 0.0)))
self._bus.send(_Msg(MAMBA_CMD_ESTOP, encode_estop_cmd(True)))
self._bus.send(_Msg(BALANCE_CMD_VELOCITY, encode_velocity_cmd(0.0, 0.0)))
self._bus.send(_Msg(BALANCE_CMD_ESTOP, encode_estop_cmd(True)))
return True
@ -79,7 +79,7 @@ class ModeStateMachine:
"""
if self._mode != MODE_DRIVE:
return False
self._bus.send(_Msg(MAMBA_CMD_VELOCITY, encode_velocity_cmd(left_mps, right_mps)))
self._bus.send(_Msg(BALANCE_CMD_VELOCITY, encode_velocity_cmd(left_mps, right_mps)))
return True
@property
@ -97,7 +97,7 @@ class TestIdleToDrive:
sm = ModeStateMachine(mock_can_bus)
sm.set_mode(MODE_DRIVE)
mode_frames = mock_can_bus.get_sent_frames_by_id(MAMBA_CMD_MODE)
mode_frames = mock_can_bus.get_sent_frames_by_id(BALANCE_CMD_MODE)
assert len(mode_frames) == 1
assert bytes(mode_frames[0].data) == bytes([MODE_DRIVE])
@ -108,7 +108,7 @@ class TestIdleToDrive:
forwarded = sm.send_drive(1.0, 1.0)
assert forwarded is False, "Drive cmd should be blocked in IDLE mode"
vel_frames = mock_can_bus.get_sent_frames_by_id(MAMBA_CMD_VELOCITY)
vel_frames = mock_can_bus.get_sent_frames_by_id(BALANCE_CMD_VELOCITY)
assert len(vel_frames) == 0
def test_drive_mode_allows_commands(self, mock_can_bus):
@ -120,7 +120,7 @@ class TestIdleToDrive:
forwarded = sm.send_drive(0.5, 0.5)
assert forwarded is True
vel_frames = mock_can_bus.get_sent_frames_by_id(MAMBA_CMD_VELOCITY)
vel_frames = mock_can_bus.get_sent_frames_by_id(BALANCE_CMD_VELOCITY)
assert len(vel_frames) == 1
l, r = parse_velocity_cmd(bytes(vel_frames[0].data))
assert abs(l - 0.5) < 1e-4
@ -137,7 +137,7 @@ class TestDriveToEstop:
sm.set_mode(MODE_ESTOP)
vel_frames = mock_can_bus.get_sent_frames_by_id(MAMBA_CMD_VELOCITY)
vel_frames = mock_can_bus.get_sent_frames_by_id(BALANCE_CMD_VELOCITY)
assert len(vel_frames) >= 1, "No velocity frame on DRIVE→ESTOP transition"
l, r = parse_velocity_cmd(bytes(vel_frames[-1].data))
assert abs(l) < 1e-5, f"Left motor {l} not zero after ESTOP"
@ -149,7 +149,7 @@ class TestDriveToEstop:
sm.set_mode(MODE_DRIVE)
sm.set_mode(MODE_ESTOP)
mode_frames = mock_can_bus.get_sent_frames_by_id(MAMBA_CMD_MODE)
mode_frames = mock_can_bus.get_sent_frames_by_id(BALANCE_CMD_MODE)
assert any(bytes(f.data) == bytes([MODE_ESTOP]) for f in mode_frames)
def test_estop_blocks_subsequent_drive(self, mock_can_bus):
@ -162,7 +162,7 @@ class TestDriveToEstop:
forwarded = sm.send_drive(1.0, 1.0)
assert forwarded is False
vel_frames = mock_can_bus.get_sent_frames_by_id(MAMBA_CMD_VELOCITY)
vel_frames = mock_can_bus.get_sent_frames_by_id(BALANCE_CMD_VELOCITY)
assert len(vel_frames) == 0

4
jetson/ros2_ws/src/saltybot_diagnostics/README.md
View File

@ -5,11 +5,7 @@ Comprehensive hardware diagnostics and health monitoring for SaltyBot.
## Features
### Startup Checks
<<<<<<< HEAD
- RPLIDAR, RealSense, VESC, Jabra mic, ESP32 BALANCE, servos
=======
- RPLIDAR, RealSense, VESC, Jabra mic, ESP32-S3, servos
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
- WiFi, GPS, disk space, RAM
- Boot result TTS + face animation
- JSON logging

6
legacy/stm32/USB_CDC_BUG.md
View File

@ -1,3 +1,9 @@
# USB CDC Bug — ARCHIVED (legacy STM32 era)
> **ARCHIVED** — This document records a firmware bug from the legacy STM32F722/Mamba F722S era. The hardware has been replaced by ESP32-S3 BALANCE + IO boards.
---
# USB CDC TX Bug — Investigation & Resolution
**Issue #524** | Investigated 2026-03-06 | **RESOLVED** (PR #10)

1
legacy/stm32/include/baro.h
View File

@ -1,3 +1,4 @@
/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */
#ifndef BARO_H
#define BARO_H

1
legacy/stm32/include/battery.h
View File

@ -1,3 +1,4 @@
/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */
#ifndef BATTERY_H
#define BATTERY_H

1
legacy/stm32/include/buzzer.h
View File

@ -1,3 +1,4 @@
/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */
#ifndef BUZZER_H
#define BUZZER_H

1
legacy/stm32/include/config.h
View File

@ -1,3 +1,4 @@
/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */
#ifndef CONFIG_H
#define CONFIG_H

1
legacy/stm32/include/fan.h
View File

@ -1,3 +1,4 @@
/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */
#ifndef FAN_H
#define FAN_H

1
legacy/stm32/include/orin_can.h
View File

@ -1,3 +1,4 @@
/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */
#ifndef ORIN_CAN_H
#define ORIN_CAN_H

1
legacy/stm32/include/ota.h
View File

@ -1,3 +1,4 @@
/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */
#ifndef OTA_H
#define OTA_H

1
legacy/stm32/include/pid_flash.h
View File

@ -1,3 +1,4 @@
/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */
#ifndef PID_FLASH_H
#define PID_FLASH_H

1
legacy/stm32/include/steering_pid.h
View File

@ -1,3 +1,4 @@
/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */
#ifndef STEERING_PID_H
#define STEERING_PID_H

1
legacy/stm32/include/ultrasonic.h
View File

@ -1,3 +1,4 @@
/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */
#ifndef ULTRASONIC_H
#define ULTRASONIC_H

1
legacy/stm32/include/vesc_can.h
View File

@ -1,3 +1,4 @@
/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */
#ifndef VESC_CAN_H
#define VESC_CAN_H

114
legacy/stm32/scripts/flash_firmware.py
View File

@ -1,30 +1,28 @@
#!/usr/bin/env python3
"""SaltyLab Firmware OTA Flash Script — Issue #124
Flashes firmware via USB DFU using dfu-util.
Flashes ESP32-S3 firmware via PlatformIO (pio run -t upload).
Supports CRC32 integrity verification and host-side backup/rollback.
Usage:
python flash_firmware.py firmware.bin [options]
python flash_firmware.py --rollback
python flash_firmware.py firmware.bin --trigger-dfu /dev/ttyUSB0
python flash_firmware.py --board balance # flash esp32/balance/ via PlatformIO
python flash_firmware.py --board io # flash esp32/io/ via PlatformIO
Options:
--vid HEX USB vendor ID (default: 0x0483 — STMicroelectronics)
--pid HEX USB product ID (default: 0xDF11 — DFU mode)
--alt N DFU alt setting (default: 0 — internal flash)
--board NAME Board to flash: 'balance' (ESP32-S3 BALANCE) or 'io' (ESP32-S3 IO)
--rollback Flash the previous firmware backup
--trigger-dfu PORT Send DFU_ENTER over JLink UART before flashing
--dry-run Print dfu-util command but do not execute
--dry-run Print pio command but do not execute
Requirements:
pip install pyserial (only if using --trigger-dfu)
dfu-util >= 0.9 installed and in PATH
pip install platformio (PlatformIO CLI)
pio >= 6.x installed and in PATH
Dual-bank note:
ESP32 has single-bank 512 KB flash; hardware A/B rollback is not
supported. Rollback is implemented here by saving a backup of the
previous binary (.firmware_backup.bin) before each flash.
ESP32-S3 note:
ESP32-S3 BALANCE board uses CH343G USB bridge — flashing via USB UART.
ESP32-S3 IO board uses built-in JTAG/USB-CDC.
Both flashed with: pio run -t upload in the respective esp32/ subdirectory.
"""
import argparse
@ -36,13 +34,18 @@ import subprocess
import sys
import time
# ---- ESP32 flash constants ----
FLASH_BASE = 0x08000000
FLASH_SIZE = 0x80000 # 512 KB
# ---- ESP32-S3 flash constants ----
# ESP32-S3 flash is managed by PlatformIO/esptool; these values are kept
# for reference only (CRC utility functions below are still valid for
# cross-checking firmware images).
FLASH_BASE = 0x00000000
FLASH_SIZE = 0x800000 # 8 MB
# ---- DFU device defaults (ESP32/STM32 system bootloader) ----
DFU_VID = 0x0483 # STMicroelectronics
DFU_PID = 0xDF11 # DFU mode
# ---- PlatformIO board directories ----
BOARD_DIRS = {
"balance": "esp32/balance",
"io": "esp32/io",
}
BACKUP_PATH = os.path.join(os.path.dirname(os.path.abspath(__file__)),
'.firmware_backup.bin')
@ -60,20 +63,12 @@ def crc32_file(path: str) -> int:
return binascii.crc32(data) & 0xFFFFFFFF
def stm32_crc32(data: bytes) -> int:
def esp32_crc32(data: bytes) -> int:
"""
Compute CRC-32/MPEG-2 matching ESP32 hardware CRC unit.
Compute CRC-32/MPEG-2 for firmware image integrity verification.
ESP32/STM32 algorithm:
Polynomial : 0x04C11DB7
Initial : 0xFFFFFFFF
Width : 32 bits
Reflection : none (MSB-first)
Feed size : 32-bit words from flash (little-endian CPU read)
When the ESP32 BALANCE reads a flash word it gets a little-endian uint32;
the hardware CRC unit processes bits[31:24] first, then [23:16],
[15:8], [7:0]. This Python implementation replicates that behaviour.
Note: ESP32-S3 uses esptool for flashing; this CRC is for host-side
integrity checking only (not the ESP32 hardware CRC unit).
data should be padded to a 4-byte boundary with 0xFF before calling.
"""
@ -135,24 +130,19 @@ def trigger_dfu_via_jlink(port: str, baud: int = 921600) -> None:
# ---- Flash ----
def flash(bin_path: str, vid: int, pid: int, alt: int = 0,
def flash(bin_path: str, board: str = "balance",
dry_run: bool = False) -> int:
"""
Flash firmware using dfu-util. Returns the process exit code.
Flash firmware using PlatformIO (pio run -t upload).
Returns the process exit code.
Uses --dfuse-address with :leave to reset into application after flash.
board: 'balance' → esp32/balance/, 'io' → esp32/io/
"""
addr = f'0x{FLASH_BASE:08X}'
cmd = [
'dfu-util',
'--device', f'{vid:04x}:{pid:04x}',
'--alt', str(alt),
'--dfuse-address', f'{addr}:leave',
'--download', bin_path,
]
board_dir = BOARD_DIRS.get(board, BOARD_DIRS["balance"])
cmd = ['pio', 'run', '-t', 'upload', '--project-dir', board_dir]
print('Running:', ' '.join(cmd))
if dry_run:
print('[dry-run] skipping dfu-util execution')
print('[dry-run] skipping pio upload execution')
return 0
return subprocess.call(cmd)
@ -161,31 +151,19 @@ def flash(bin_path: str, vid: int, pid: int, alt: int = 0,
def main() -> int:
parser = argparse.ArgumentParser(
description='SaltyLab firmware OTA flash via USB DFU (Issue #124)'
description='SaltyLab ESP32-S3 firmware flash via PlatformIO (Issue #124)'
)
parser.add_argument('firmware', nargs='?',
help='Firmware .bin file to flash')
parser.add_argument('--vid', type=lambda x: int(x, 0), default=DFU_VID,
help=f'USB vendor ID (default: 0x{DFU_VID:04X})')
parser.add_argument('--pid', type=lambda x: int(x, 0), default=DFU_PID,
help=f'USB product ID (default: 0x{DFU_PID:04X})')
parser.add_argument('--alt', type=int, default=0,
help='DFU alt setting (default: 0 — internal flash)')
help='Firmware .bin file (for CRC check only; PlatformIO handles actual flash)')
parser.add_argument('--board', default='balance',
choices=['balance', 'io'],
help='Board to flash: balance (ESP32-S3 BALANCE) or io (ESP32-S3 IO)')
parser.add_argument('--rollback', action='store_true',
help='Flash the previous firmware backup')
parser.add_argument('--trigger-dfu', metavar='PORT',
help='Trigger DFU via JLink UART before flashing '
'(e.g. /dev/ttyUSB0 or COM3)')
parser.add_argument('--dry-run', action='store_true',
help='Print dfu-util command without executing it')
help='Print pio command without executing it')
args = parser.parse_args()
# Optionally trigger DFU mode over JLink serial
if args.trigger_dfu:
trigger_dfu_via_jlink(args.trigger_dfu)
print('Waiting 3 s for USB DFU enumeration…')
time.sleep(3)
# Determine target binary
if args.rollback:
if not os.path.exists(BACKUP_PATH):
@ -214,23 +192,23 @@ def main() -> int:
f'({FLASH_SIZE} bytes)', file=sys.stderr)
return 1
# ESP32/STM32 hardware CRC (for cross-checking with firmware telemetry)
# CRC for cross-checking firmware integrity
with open(target, 'rb') as fh:
bin_data = fh.read()
crc_hw = stm32_crc32(bin_data.ljust(FLASH_SIZE, b'\xff'))
print(f'CRC-32 : 0x{crc_hw:08X} (MPEG-2 / ESP32/STM32 HW, padded to {FLASH_SIZE // 1024} KB)')
crc_hw = esp32_crc32(bin_data.ljust(FLASH_SIZE, b'\xff'))
print(f'CRC-32 : 0x{crc_hw:08X} (MPEG-2, padded to {FLASH_SIZE // 1024} KB)')
# Save backup before flashing (skip when rolling back)
if not args.rollback:
shutil.copy2(target, BACKUP_PATH)
print(f'Backup : {BACKUP_PATH}')
# Flash
rc = flash(target, args.vid, args.pid, args.alt, args.dry_run)
# Flash via PlatformIO
rc = flash(target, args.board, args.dry_run)
if rc == 0:
print('Flash complete — device should reset into application.')
print('Flash complete — ESP32-S3 should reset into application.')
else:
print(f'ERROR: dfu-util exited with code {rc}', file=sys.stderr)
print(f'ERROR: pio run -t upload exited with code {rc}', file=sys.stderr)
return rc

1
legacy/stm32/src/audio.c
View File

@ -1,3 +1,4 @@
/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */
#include "audio.h"
#include "config.h"
#include "stm32f7xx_hal.h"

1
legacy/stm32/src/baro.c
View File

@ -1,3 +1,4 @@
/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */
/*
* baro.c — BME280/BMP280 barometric pressure & ambient temperature module
* (Issue #672).

1
legacy/stm32/src/battery.c
View File

@ -1,3 +1,4 @@
/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */
/*
* battery.c — Vbat ADC reading for CRSF telemetry uplink (Issue #103)
*

1
legacy/stm32/src/icm42688.c
View File

@ -1,3 +1,4 @@
/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */
/* MPU6000 + ICM-42688-P dual driver — auto-detects based on WHO_AM_I */
#include "stm32f7xx_hal.h"
#include "config.h"

1
legacy/stm32/src/imu_cal_flash.c
View File

@ -1,3 +1,4 @@
/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */
/* imu_cal_flash.c — IMU mount angle calibration flash storage (Issue #680)
*
* Stores pitch/roll mount offsets in STM32F722 flash sector 7 at 0x0807FF00.

1
legacy/stm32/src/led.c
View File

@ -1,3 +1,4 @@
/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */
#include "led.h"
#include "config.h"
#include "stm32f7xx_hal.h"

1
legacy/stm32/src/mpu6000.c
View File

@ -1,3 +1,4 @@
/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */
/*
* mpu6000.c — IMU Sensor Fusion for MPU6000
*

1
legacy/stm32/src/power_mgmt.c
View File

@ -1,3 +1,4 @@
/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */
#include "power_mgmt.h"
#include "config.h"
#include "stm32f7xx_hal.h"

5
legacy/stm32/test/test_vesc_can.c
View File

@ -1,3 +1,4 @@
/* ARCHIVED: Legacy STM32F722/Mamba F722S era tests. NOT used with current hardware. */
/*
* test_vesc_can.c — Unit tests for VESC CAN protocol driver (Issue #674).
*
@ -12,8 +13,8 @@
/* ---- Block HAL and board-specific headers ---- */
/* Must appear before any board include is transitively pulled */
#define STM32F7XX_HAL_H /* skip stm32f7xx_hal.h */
#define STM32F722xx /* satisfy any chip guard */
#define STM32F7XX_HAL_H /* LEGACY: skip stm32f7xx_hal.h */
#define STM32F722xx /* LEGACY: satisfy any chip guard */
#define JLINK_H /* skip jlink.h (pid_flash / HAL deps) */
#define CAN_DRIVER_H /* skip can_driver.h body (we stub functions below) */

12
projects/saltybot/SLAM-SETUP-PLAN.md
View File

@ -16,11 +16,7 @@
| Depth Cam | Intel RealSense D435i — 848×480 @ 90fps, BMI055 IMU |
| LIDAR | RPLIDAR A1M8 — 360° 2D, 12m range, ~5.5 Hz |
| Wide Cams | 4× IMX219 160° CSI — front/right/rear/left 90° intervals *(arriving)* |
<<<<<<< HEAD
| FC | ESP32 — UART bridge `/dev/ttyACM0` @ 921600 |
=======
| FC | ESP32-S3 — UART bridge `/dev/ttyACM0` @ 921600 |
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
| BALANCE | ESP32-S3 BALANCE — CAN bus (CANable 2.0, can0, 500 kbps) |
---
@ -80,11 +76,7 @@ Jetson Orin Nano Super (Ubuntu 22.04 / JetPack 6 / CUDA 12.x)
▼
Nav2 stack (Phase 2b)
20Hz costmap
<<<<<<< HEAD
/cmd_vel → ESP32 BALANCE
=======
/cmd_vel → ESP32-S3
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
/cmd_vel → CAN 0x300
4× IMX219 CSI (Phase 2c — pending hardware)
front/right/rear/left 160°

7
test/test_power_mgmt.py
View File

@ -1,4 +1,5 @@
"""
ARCHIVED: Legacy STM32F722/Mamba F722S era tests. NOT used with current hardware.
test_power_mgmt.py — unit tests for Issue #178 power management module.
Models the PM state machine, LED brightness, peripheral gating, current
@ -471,7 +472,7 @@ class TestJlinkProtocol:
# Tests: Wake latency and IWDG budget
# ---------------------------------------------------------------------------
class TestWakeLatencyBudget:
# ESP32-S3 STOP-mode wakeup: HSI ready ~2 ms + PLL lock ~2 ms ≈ 4 ms
# LEGACY: STM32F722 STOP-mode (archived) wakeup: HSI ready ~2 ms + PLL lock ~2 ms ≈ 4 ms
ESTIMATED_WAKE_MS = 10 # conservative upper bound
def test_wake_latency_within_50ms(self):
@ -493,7 +494,7 @@ class TestWakeLatencyBudget:
assert PM_FADE_MS < PM_IDLE_TIMEOUT_MS
def test_stop_mode_wake_much_less_than_50ms(self):
# PLL startup on ESP32-S3: HSI on (0 ms, already running) +
# LEGACY: STM32F722 STOP-mode (archived) — PLL startup on STM32F7: HSI on (0 ms, already running) +
# PLL lock ~2 ms + SysTick re-init ~0.1 ms ≈ 3 ms
pll_lock_ms = 3
overhead_ms = 1
@ -539,7 +540,7 @@ class TestHardwareConstants:
assert 216 / 2 == 108
def test_flash_latency_7_required_at_216mhz(self):
"""ESP32-S3 at 2.7-3.3 V: 7 wait states for 210-216 MHz."""
"""STM32F7 at 2.7-3.3 V: 7 wait states for 210-216 MHz."""
FLASH_LATENCY = 7
assert FLASH_LATENCY == 7

4
ui/diagnostics_panel.html
View File

@ -5,7 +5,7 @@
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0">
<title>Saltybot — System Diagnostics</title>
<link rel="stylesheet" href="diagnostics_panel.css">
<script src="https://cdn.jsdelivr.net/npm/roslib@1.4.0/build/roslib.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/roslib@1.3.0/build/roslib.min.js"></script>
</head>
<body>
@ -112,7 +112,7 @@
<div class="temp-bar-track"><div class="temp-bar-fill" id="gpu-temp-bar" style="width:0%"></div></div>
</div>
<div class="temp-box" id="board-temp-box">
<div class="temp-label">Board / ESP32-S3</div>
<div class="temp-label">ESP32-S3</div>
<div class="temp-value" id="board-temp-val">—</div>
<div class="temp-bar-track"><div class="temp-bar-fill" id="board-temp-bar" style="width:0%"></div></div>
</div>