diff --git a/AUTONOMOUS_ARMING.md b/AUTONOMOUS_ARMING.md index 00904cf..76e3071 100644 --- a/AUTONOMOUS_ARMING.md +++ b/AUTONOMOUS_ARMING.md @@ -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, — 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]`) diff --git a/CLAUDE.md b/CLAUDE.md index 16d6c44..2b5e886 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 `-dev` and PR back TO `-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` diff --git a/TEAM.md b/TEAM.md index a6c1fa8..972e1b3 100644 --- a/TEAM.md +++ b/TEAM.md @@ -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) diff --git a/cad/dimensions.scad b/cad/dimensions.scad index ff612d7..e608813 100644 --- a/cad/dimensions.scad +++ b/cad/dimensions.scad @@ -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; diff --git a/chassis/ASSEMBLY.md b/chassis/ASSEMBLY.md index 9f6acf5..cdd502f 100644 --- a/chassis/ASSEMBLY.md +++ b/chassis/ASSEMBLY.md @@ -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 | diff --git a/chassis/BOM.md b/chassis/BOM.md index 2c76314..ae01088 100644 --- a/chassis/BOM.md +++ b/chassis/BOM.md @@ -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 | | diff --git a/chassis/chassis_frame.scad b/chassis/chassis_frame.scad index a925394..1e1c17b 100644 --- a/chassis/chassis_frame.scad +++ b/chassis/chassis_frame.scad @@ -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 diff --git a/chassis/ip54_BOM.md b/chassis/ip54_BOM.md index c3a68fa..87d855e 100644 --- a/chassis/ip54_BOM.md +++ b/chassis/ip54_BOM.md @@ -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 | — | diff --git a/chassis/prototype_baseplate.scad b/chassis/prototype_baseplate.scad index 1d6d079..2f47998 100644 --- a/chassis/prototype_baseplate.scad +++ b/chassis/prototype_baseplate.scad @@ -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]) diff --git a/chassis/rover_electronics_bay.scad b/chassis/rover_electronics_bay.scad index 1fbefdb..d18f23b 100644 --- a/chassis/rover_electronics_bay.scad +++ b/chassis/rover_electronics_bay.scad @@ -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. diff --git a/chassis/saltyrover_chassis_r2.scad b/chassis/saltyrover_chassis_r2.scad index 2c49720..ca201d7 100644 --- a/chassis/saltyrover_chassis_r2.scad +++ b/chassis/saltyrover_chassis_r2.scad @@ -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 diff --git a/docs/AGENTS.md b/docs/AGENTS.md index a99697a..33e4838 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -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 diff --git a/docs/FACE_LCD_ANIMATION.md b/docs/FACE_LCD_ANIMATION.md index 68956f6..81e905a 100644 --- a/docs/FACE_LCD_ANIMATION.md +++ b/docs/FACE_LCD_ANIMATION.md @@ -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 diff --git a/docs/SALTYLAB.md b/docs/SALTYLAB.md index b8c3a42..7a880f5 100644 --- a/docs/SALTYLAB.md +++ b/docs/SALTYLAB.md @@ -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 diff --git a/docs/board-viz.html b/docs/board-viz.html index 64b52c7..f1d0677 100644 --- a/docs/board-viz.html +++ b/docs/board-viz.html @@ -2,7 +2,7 @@ -GEPRC GEP-F722-45A AIO — Board Layout (Legacy / Archived) +ESP32-S3 BALANCE — Waveshare Touch LCD 1.28 Pinout -<<<<<<< HEAD -

🤖 GEPRC GEP-F722-45A AIO — SaltyLab Pinout (Legacy / Archived)

-

ESP32RET6 + ICM-42688-P | Betaflight target: GEPR-GEPRC_F722_AIO

-======= -

🤖 GEPRC GEP-F722-45A AIO — SaltyLab Pinout

-

ESP32-S3RET6 + ICM-42688-P | Betaflight target: GEPR-GEPRC_F722_AIO

->>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only) +

🤖 ESP32-S3 BALANCE — Waveshare Touch LCD 1.28

+

ESP32-S3 240 MHz | QMI8658 IMU | GC9A01 1.28″ LCD | CH343G USB-UART | SN65HVD230 CAN

- -
-
-
-
+ +
+
GC9A01
1.28″ round
240×240
SPI
+
+
ESP32-S3
240 MHz / 8MB
- -<<<<<<< HEAD -
ESP32
(legacy:
F722RET6)
-======= -
ESP32-S3
F722RET6
216MHz
->>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only) - - -
ICM
42688
-
↻
- - -
-
LED PC4
- - -
-
BOOT 🟡
- - + +
USB-A CH343G (UART0 debug/flash)
-
USB-C (DFU)
- -
-
T
- T1
PA9 -
-
-
R
- R1
PA10 -
-
-
T
- T3
PB10 -
-
-
R
- R3
PB11 + +
+
+
+ GPIO6 + IMU SDA (I2C-0) +
+
+
+ GPIO7 + IMU SCL (I2C-0) +
+
+
+ GPIO3 + QMI8658 INT +
+
+
+ GPIO43 + UART0 TX (CH343G) +
+
+
+ GPIO44 + UART0 RX (CH343G) +
+
+
+ UART1 TX + Inter-board → IO (TBD) +
+
+
+ UART1 RX + Inter-board ← IO (TBD) +
- -
- T2
PA2 -
T
+ +
+
+
+ CAN TX + → SN65HVD230 D (TBD) +
+
+
+ CAN RX + ← SN65HVD230 R (TBD) +
+
+
+ LCD SPI + GC9A01 (onboard) +
+
+
+ 5V + USB / ext 5V in +
+
+
+ 3.3V + LDO out +
+
+
+ GND + Common ground +
-
- R2
PA3 -
R
-
- - -
-
T
- T4
PC10 -
-
-
R
- R4
PC11 -
-
- T5
PC12 -
T
-
-
- R5
PD2 -
R
-
- - -
-
M1-M4 (unused)
PC6-PC9
-
- - -
-
X →
board right
-
-
Y ↓ (board forward = tilt axis)
-

🔌 UART Assignments

+

📌 Pin Assignments

-
- USART1 T1/R1 → Jetson Orin Nano Super +
+ IMU (QMI8658) — I2C-0 SDA=GPIO6, SCL=GPIO7, INT=GPIO3
- USART2 T2 → Hoverboard ESC (TX only) + CAN (SN65HVD230) — TX/RX TBD; confirm in esp32/balance/src/config.h +
+
+
+ UART0 GPIO43/44 — CH343G USB bridge (debug + flash) +
+
+
+ UART1 TBD — Inter-board @ 460800 baud → ESP32-S3 IO
- I2C2 T3/R3 → Baro/Mag (reserved) + LCD SPI — GC9A01 1.28″ round 240×240 (onboard, fixed pins)
- UART4 T4/R4 → ELRS RX (CRSF) -
-
-
- UART5 T5/R5 → Debug/spare + Power — 5V USB input; 3.3V LDO for logic + sensors
-

📡 SPI Bus

+

🔌 CAN Bus Topology

- SPI1: PA5/PA6/PA7 → IMU (CS: PA15) + Orin → CANable 2.0 → CANH/CANL (500 kbps)
- SPI2: PB13-15 → OSD MAX7456 + BALANCE: SN65HVD230 on CAN bus
- SPI3: PB3-5 → Flash W25Q128 + VESC Left: ID 0x44 (68) | VESC Right: ID 0x38 (56) +
+
+ 120 Ω termination at each bus end
-

⚡ Other

+

📡 Inter-Board Protocol

- 🔵 LED: PC4 | 📢 Beeper: PC15 + UART @ 460800 baud, 8N1
- 🔋 VBAT: PC2 | ⚡ Current: PC1 + Frame: [0xAA][LEN][TYPE][PAYLOAD][CRC8]
- 💡 LED Strip: PA1 (WS2812) -
-
- 📍 EXTI (IMU data-ready): PA8 + Types: see esp32/shared/protocol.h
-
-
-
-

🧭 IMU Orientation (CW90° from chip to board)

-
-
Board Forward (tilt for balance) = Chip's +Y axis
-
Board Right = Chip's -X axis
-
Board Pitch Rate = -Gyro X (raw)
-
Board Accel Forward = Accel Y (raw)
+
+

⚡ Safety

+
Motors NEVER spin on power-on — ARM required
+
RC kill switch checked every loop
+
CAN watchdog: 500 ms → RC-only mode
+
ESTOP: CAN 0x303 + 0xE5 → all motors off
+

- ⚠️ Pad positions are approximate — 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 TBD — confirm in esp32/balance/src/config.h before wiring. + All inter-board UART GPIO also TBD. LCD and IMU pins are fixed by Waveshare hardware.

diff --git a/docs/wiring-diagram.md b/docs/wiring-diagram.md index c1076dc..8cf94d3 100644 --- a/docs/wiring-diagram.md +++ b/docs/wiring-diagram.md @@ -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 | diff --git a/jetson/README.md b/jetson/README.md index 81fcc8b..aefc7c5 100644 --- a/jetson/README.md +++ b/jetson/README.md @@ -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. diff --git a/jetson/config/RECOVERY_BEHAVIORS.md b/jetson/config/RECOVERY_BEHAVIORS.md index 26de782..6fd5d1a 100644 --- a/jetson/config/RECOVERY_BEHAVIORS.md +++ b/jetson/config/RECOVERY_BEHAVIORS.md @@ -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 diff --git a/jetson/docs/pinout.md b/jetson/docs/pinout.md index 85b1fb6..9cb007e 100644 --- a/jetson/docs/pinout.md +++ b/jetson/docs/pinout.md @@ -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,\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,\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", \ diff --git a/jetson/docs/power-budget.md b/jetson/docs/power-budget.md index 838ea80..62b4eb7 100644 --- a/jetson/docs/power-budget.md +++ b/jetson/docs/power-budget.md @@ -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 diff --git a/jetson/ros2_ws/src/saltybot_bridge/launch/uart_bridge.launch.py b/jetson/ros2_ws/src/saltybot_bridge/launch/uart_bridge.launch.py index 56fa470..8b49263 100644 --- a/jetson/ros2_ws/src/saltybot_bridge/launch/uart_bridge.launch.py +++ b/jetson/ros2_ws/src/saltybot_bridge/launch/uart_bridge.launch.py @@ -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: diff --git a/jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/cmd_vel_bridge_node.py b/jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/cmd_vel_bridge_node.py index 992da51..9076e5f 100644 --- a/jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/cmd_vel_bridge_node.py +++ b/jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/cmd_vel_bridge_node.py @@ -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,\\n / H\\n — same as saltybot_cmd_node): C,\\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 ───────────────────────────────────────────────────────────── diff --git a/jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/esp32_cmd_node.py b/jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/esp32_cmd_node.py index 87e9971..ce1c714 100644 --- a/jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/esp32_cmd_node.py +++ b/jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/esp32_cmd_node.py @@ -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: diff --git a/jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/esp32_protocol.py b/jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/esp32_protocol.py index 19ce93c..71245ef 100644 --- a/jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/esp32_protocol.py +++ b/jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/esp32_protocol.py @@ -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. diff --git a/jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/saltybot_can_node.py b/jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/saltybot_can_node.py index 4aa73bb..7a06c4a 100644 --- a/jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/saltybot_can_node.py +++ b/jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/saltybot_can_node.py @@ -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 diff --git a/jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/saltybot_cmd_node.py b/jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/saltybot_cmd_node.py index b2acaf1..1acc6e1 100644 --- a/jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/saltybot_cmd_node.py +++ b/jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/saltybot_cmd_node.py @@ -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,\\n → ESP32 BALANCE - Heartbeat timer (200ms) → H\\n → ESP32 BALANCE + /cmd_vel (geometry_msgs/Twist) → C,\\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,\\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,\\n → ESP32-S3 - Heartbeat timer (200ms) → H\\n → ESP32-S3 - -Protocol: - H\\n — heartbeat. ESP32-S3 reverts steer to 0 if gap > 500ms. - C,\\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 ───────────────────────────────────────────────────────────── diff --git a/jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/serial_bridge_node.py b/jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/serial_bridge_node.py index c405c52..a9210d7 100644 --- a/jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/serial_bridge_node.py +++ b/jetson/ros2_ws/src/saltybot_bridge/saltybot_bridge/serial_bridge_node.py @@ -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":,"r":,"e":,"ig":, @@ -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() diff --git a/jetson/ros2_ws/src/saltybot_bringup/test/README_INTEGRATION_TESTS.md b/jetson/ros2_ws/src/saltybot_bringup/test/README_INTEGRATION_TESTS.md index 8ac3a1e..01c574c 100644 --- a/jetson/ros2_ws/src/saltybot_bringup/test/README_INTEGRATION_TESTS.md +++ b/jetson/ros2_ws/src/saltybot_bringup/test/README_INTEGRATION_TESTS.md @@ -61,12 +61,8 @@ 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) -- cmd_vel Bridge +- ESP32-S3 CAN Bridge +- cmd_vel Bridge - Rosbridge WebSocket ### Sensors @@ -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 diff --git a/jetson/ros2_ws/src/saltybot_can_bridge/saltybot_can_bridge/balance_protocol.py b/jetson/ros2_ws/src/saltybot_can_bridge/saltybot_can_bridge/balance_protocol.py index ae9326e..fe6fcb9 100644 --- a/jetson/ros2_ws/src/saltybot_can_bridge/saltybot_can_bridge/balance_protocol.py +++ b/jetson/ros2_ws/src/saltybot_can_bridge/saltybot_can_bridge/balance_protocol.py @@ -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 ---------- diff --git a/jetson/ros2_ws/src/saltybot_can_bridge/saltybot_can_bridge/can_bridge_node.py b/jetson/ros2_ws/src/saltybot_can_bridge/saltybot_can_bridge/can_bridge_node.py index db6a1a5..d93d0f3 100644 --- a/jetson/ros2_ws/src/saltybot_can_bridge/saltybot_can_bridge/can_bridge_node.py +++ b/jetson/ros2_ws/src/saltybot_can_bridge/saltybot_can_bridge/can_bridge_node.py @@ -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() diff --git a/jetson/ros2_ws/src/saltybot_can_bridge/setup.py b/jetson/ros2_ws/src/saltybot_can_bridge/setup.py index 9ac12dc..e940f26 100644 --- a/jetson/ros2_ws/src/saltybot_can_bridge/setup.py +++ b/jetson/ros2_ws/src/saltybot_can_bridge/setup.py @@ -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={ diff --git a/jetson/ros2_ws/src/saltybot_can_bridge/test/test_can_bridge.py b/jetson/ros2_ws/src/saltybot_can_bridge/test/test_can_bridge.py index 6bddca2..15ef454 100644 --- a/jetson/ros2_ws/src/saltybot_can_bridge/test/test_can_bridge.py +++ b/jetson/ros2_ws/src/saltybot_can_bridge/test/test_can_bridge.py @@ -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) diff --git a/jetson/ros2_ws/src/saltybot_can_e2e_test/saltybot_can_e2e_test/protocol_defs.py b/jetson/ros2_ws/src/saltybot_can_e2e_test/saltybot_can_e2e_test/protocol_defs.py index cf1dc6a..8400088 100644 --- a/jetson/ros2_ws/src/saltybot_can_e2e_test/saltybot_can_e2e_test/protocol_defs.py +++ b/jetson/ros2_ws/src/saltybot_can_e2e_test/saltybot_can_e2e_test/protocol_defs.py @@ -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]) diff --git a/jetson/ros2_ws/src/saltybot_can_e2e_test/test/test_drive_command.py b/jetson/ros2_ws/src/saltybot_can_e2e_test/test/test_drive_command.py index 3e63e3d..e991015 100644 --- a/jetson/ros2_ws/src/saltybot_can_e2e_test/test/test_drive_command.py +++ b/jetson/ros2_ws/src/saltybot_can_e2e_test/test/test_drive_command.py @@ -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]) diff --git a/jetson/ros2_ws/src/saltybot_can_e2e_test/test/test_estop.py b/jetson/ros2_ws/src/saltybot_can_e2e_test/test/test_estop.py index 746840f..895674e 100644 --- a/jetson/ros2_ws/src/saltybot_can_e2e_test/test/test_estop.py +++ b/jetson/ros2_ws/src/saltybot_can_e2e_test/test/test_estop.py @@ -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" diff --git a/jetson/ros2_ws/src/saltybot_can_e2e_test/test/test_heartbeat_timeout.py b/jetson/ros2_ws/src/saltybot_can_e2e_test/test/test_heartbeat_timeout.py index 726921d..f622675 100644 --- a/jetson/ros2_ws/src/saltybot_can_e2e_test/test/test_heartbeat_timeout.py +++ b/jetson/ros2_ws/src/saltybot_can_e2e_test/test/test_heartbeat_timeout.py @@ -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 diff --git a/jetson/ros2_ws/src/saltybot_can_e2e_test/test/test_mode_switching.py b/jetson/ros2_ws/src/saltybot_can_e2e_test/test/test_mode_switching.py index 9e8da58..1f8e8b5 100644 --- a/jetson/ros2_ws/src/saltybot_can_e2e_test/test/test_mode_switching.py +++ b/jetson/ros2_ws/src/saltybot_can_e2e_test/test/test_mode_switching.py @@ -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 diff --git a/jetson/ros2_ws/src/saltybot_diagnostics/README.md b/jetson/ros2_ws/src/saltybot_diagnostics/README.md index ea989a8..61579cc 100644 --- a/jetson/ros2_ws/src/saltybot_diagnostics/README.md +++ b/jetson/ros2_ws/src/saltybot_diagnostics/README.md @@ -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 diff --git a/legacy/stm32/USB_CDC_BUG.md b/legacy/stm32/USB_CDC_BUG.md index 90f05cc..e848e8c 100644 --- a/legacy/stm32/USB_CDC_BUG.md +++ b/legacy/stm32/USB_CDC_BUG.md @@ -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) diff --git a/legacy/stm32/include/baro.h b/legacy/stm32/include/baro.h index be8c01f..4f83bcb 100644 --- a/legacy/stm32/include/baro.h +++ b/legacy/stm32/include/baro.h @@ -1,3 +1,4 @@ +/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */ #ifndef BARO_H #define BARO_H diff --git a/legacy/stm32/include/battery.h b/legacy/stm32/include/battery.h index a5c969b..e9da257 100644 --- a/legacy/stm32/include/battery.h +++ b/legacy/stm32/include/battery.h @@ -1,3 +1,4 @@ +/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */ #ifndef BATTERY_H #define BATTERY_H diff --git a/legacy/stm32/include/buzzer.h b/legacy/stm32/include/buzzer.h index 82ce46b..d9cebfd 100644 --- a/legacy/stm32/include/buzzer.h +++ b/legacy/stm32/include/buzzer.h @@ -1,3 +1,4 @@ +/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */ #ifndef BUZZER_H #define BUZZER_H diff --git a/legacy/stm32/include/config.h b/legacy/stm32/include/config.h index e63cb36..afa58cc 100644 --- a/legacy/stm32/include/config.h +++ b/legacy/stm32/include/config.h @@ -1,3 +1,4 @@ +/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */ #ifndef CONFIG_H #define CONFIG_H diff --git a/legacy/stm32/include/fan.h b/legacy/stm32/include/fan.h index ef3e2fb..aebbe6e 100644 --- a/legacy/stm32/include/fan.h +++ b/legacy/stm32/include/fan.h @@ -1,3 +1,4 @@ +/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */ #ifndef FAN_H #define FAN_H diff --git a/legacy/stm32/include/orin_can.h b/legacy/stm32/include/orin_can.h index aea84b0..b38c03a 100644 --- a/legacy/stm32/include/orin_can.h +++ b/legacy/stm32/include/orin_can.h @@ -1,3 +1,4 @@ +/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */ #ifndef ORIN_CAN_H #define ORIN_CAN_H diff --git a/legacy/stm32/include/ota.h b/legacy/stm32/include/ota.h index 2b3d9a5..e021db4 100644 --- a/legacy/stm32/include/ota.h +++ b/legacy/stm32/include/ota.h @@ -1,3 +1,4 @@ +/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */ #ifndef OTA_H #define OTA_H diff --git a/legacy/stm32/include/pid_flash.h b/legacy/stm32/include/pid_flash.h index db29718..ba79fd4 100644 --- a/legacy/stm32/include/pid_flash.h +++ b/legacy/stm32/include/pid_flash.h @@ -1,3 +1,4 @@ +/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */ #ifndef PID_FLASH_H #define PID_FLASH_H diff --git a/legacy/stm32/include/steering_pid.h b/legacy/stm32/include/steering_pid.h index 66ef413..c5e885b 100644 --- a/legacy/stm32/include/steering_pid.h +++ b/legacy/stm32/include/steering_pid.h @@ -1,3 +1,4 @@ +/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */ #ifndef STEERING_PID_H #define STEERING_PID_H diff --git a/legacy/stm32/include/ultrasonic.h b/legacy/stm32/include/ultrasonic.h index 2e1c349..a0b323d 100644 --- a/legacy/stm32/include/ultrasonic.h +++ b/legacy/stm32/include/ultrasonic.h @@ -1,3 +1,4 @@ +/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */ #ifndef ULTRASONIC_H #define ULTRASONIC_H diff --git a/legacy/stm32/include/vesc_can.h b/legacy/stm32/include/vesc_can.h index 21f67d1..17ae042 100644 --- a/legacy/stm32/include/vesc_can.h +++ b/legacy/stm32/include/vesc_can.h @@ -1,3 +1,4 @@ +/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */ #ifndef VESC_CAN_H #define VESC_CAN_H diff --git a/legacy/stm32/scripts/flash_firmware.py b/legacy/stm32/scripts/flash_firmware.py index 26f0938..15e0963 100644 --- a/legacy/stm32/scripts/flash_firmware.py +++ b/legacy/stm32/scripts/flash_firmware.py @@ -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 diff --git a/legacy/stm32/src/audio.c b/legacy/stm32/src/audio.c index 053e889..f168a96 100644 --- a/legacy/stm32/src/audio.c +++ b/legacy/stm32/src/audio.c @@ -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" diff --git a/legacy/stm32/src/baro.c b/legacy/stm32/src/baro.c index 3a401a6..145ede2 100644 --- a/legacy/stm32/src/baro.c +++ b/legacy/stm32/src/baro.c @@ -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). diff --git a/legacy/stm32/src/battery.c b/legacy/stm32/src/battery.c index 680a5d1..fdc8157 100644 --- a/legacy/stm32/src/battery.c +++ b/legacy/stm32/src/battery.c @@ -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) * diff --git a/legacy/stm32/src/icm42688.c b/legacy/stm32/src/icm42688.c index 9e83861..bc5d40d 100644 --- a/legacy/stm32/src/icm42688.c +++ b/legacy/stm32/src/icm42688.c @@ -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" diff --git a/legacy/stm32/src/imu_cal_flash.c b/legacy/stm32/src/imu_cal_flash.c index 6bd9b3c..986614c 100644 --- a/legacy/stm32/src/imu_cal_flash.c +++ b/legacy/stm32/src/imu_cal_flash.c @@ -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. diff --git a/legacy/stm32/src/led.c b/legacy/stm32/src/led.c index 6252484..4e94a03 100644 --- a/legacy/stm32/src/led.c +++ b/legacy/stm32/src/led.c @@ -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" diff --git a/legacy/stm32/src/mpu6000.c b/legacy/stm32/src/mpu6000.c index e89bf6c..30fd010 100644 --- a/legacy/stm32/src/mpu6000.c +++ b/legacy/stm32/src/mpu6000.c @@ -1,3 +1,4 @@ +/* ARCHIVED: Legacy STM32F722/Mamba F722S era code. NOT used in current hardware. */ /* * mpu6000.c — IMU Sensor Fusion for MPU6000 * diff --git a/legacy/stm32/src/power_mgmt.c b/legacy/stm32/src/power_mgmt.c index ccb76a1..5ded1b8 100644 --- a/legacy/stm32/src/power_mgmt.c +++ b/legacy/stm32/src/power_mgmt.c @@ -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" diff --git a/legacy/stm32/test/test_vesc_can.c b/legacy/stm32/test/test_vesc_can.c index 8557a17..3b1c95c 100644 --- a/legacy/stm32/test/test_vesc_can.c +++ b/legacy/stm32/test/test_vesc_can.c @@ -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) */ diff --git a/projects/saltybot/SLAM-SETUP-PLAN.md b/projects/saltybot/SLAM-SETUP-PLAN.md index b9c99c3..f164d4a 100644 --- a/projects/saltybot/SLAM-SETUP-PLAN.md +++ b/projects/saltybot/SLAM-SETUP-PLAN.md @@ -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° diff --git a/test/test_power_mgmt.py b/test/test_power_mgmt.py index 09a357d..aa9a2d9 100644 --- a/test/test_power_mgmt.py +++ b/test/test_power_mgmt.py @@ -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 diff --git a/ui/diagnostics_panel.html b/ui/diagnostics_panel.html index 43efcf1..51e433d 100644 --- a/ui/diagnostics_panel.html +++ b/ui/diagnostics_panel.html @@ -5,7 +5,7 @@ Saltybot — System Diagnostics - + @@ -112,7 +112,7 @@
-
Board / ESP32-S3
+
ESP32-S3
—