seb/saltylab-firmware
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
saltylab-firmware/docs/wiring-diagram.md
sl-uwb c958cf4474
Some checks failed
social-bot integration tests / Lint (flake8 + pep257) (pull_request) Failing after 2s
Details
social-bot integration tests / Core integration tests (mock sensors, no GPU) (pull_request) Has been skipped
Details
social-bot integration tests / Latency profiling (GPU, Orin) (pull_request) Has been cancelled
Details
chore: complete legacy hardware cleanup — zero Mamba/STM32/BlackPill refs 
Final pass after sl-firmware/cleanup-legacy-hw initial sweep:

Deleted:
- legacy/stm32/ (entire archive — all STM32 firmware, HAL stubs, tests,
  platformio.ini, USB_CDC lib — moved there by prior commit, now removed)
- test/test_ota.py (STM32 JLink/DFU OTA tests — imports from deleted
  legacy/stm32/scripts/; irrelevant to ESP32 OTA mechanism)

Updated:
- docs/wiring-diagram.md: remove "Mamba F722S / STM32 retired" banner
  and obsolete STM32 UART pin table (PA2/PB6/etc.); replace with
  ESP32-S3 GPIO table per SAUL-TEE-SYSTEM-REFERENCE.md
- docs/AGENTS.md: remove "archived STM32 HAL code" note
- TEAM.md: remove legacy/stm32/USB_CDC_BUG.md references
- serial_bridge_node.py: "stm32_serial_bridge" → "esp32_serial_bridge"

Result: grep for mamba|f722|stm32f7|stm32f4|blackpill across all
*.py *.cpp *.h *.c *.md *.yaml *.ini *.json returns zero hits
(excluding docs/SAUL-TEE-SYSTEM-REFERENCE.md superseded-hw table).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-04 09:15:04 -04:00

13 KiB
Raw Permalink Blame History

SaltyLab / SAUL-TEE Wiring Reference

Authoritative reference: docs/SAUL-TEE-SYSTEM-REFERENCE.md New stack: ESP32-S3 BALANCE + ESP32-S3 IO + VESCs on 500 kbps CAN.

System Overview

┌─────────────────────────────────────────────────────────────────────┐
│                        ORIN NANO SUPER                              │
│                     (Top Plate — 25W)                               │
│                                                                     │
│  USB-C ──── ESP32-S3 CDC (/dev/esp32-bridge, 921600 baud)            ││  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                       │
         ▼                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                     ESP32-S3 BALANCE (FC)                                 │
│                  (Middle Plate — foam mounted)                       ││                                                                     │
│  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

Wire-by-Wire Connections

1. Orin ↔ ESP32-S3 BALANCE (Primary: USB Serial via CH343)

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
  • Device: /dev/ttyACM0 → symlink /dev/esp32-bridge
  • Baud: 921600, 8N1
  • Protocol: JSON telemetry (FC→Orin), ASCII commands (Orin→FC)

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)

From To Notes
Orin USB-A ESP32-S3 IO USB-C USB cable, /dev/esp32-io
  • 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

4. ESP32-S3 BALANCE <-> VESC Motors (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
  • 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)

5. 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)

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

ESP32-S3 BALANCE — UART Summary

UART GPIO Pins Baud Assignment Notes
UART0 (CRSF primary) IO44=RX, IO43=TX 400000 TBS Crossfire RC via ESP32-S3 IO board
UART1 (inter-board) IO17=TX, IO18=RX 460800 ESP32-S3 IO ↔ BALANCE binary [0xAA][LEN][TYPE]
CAN (SN65HVD230) IO43=TX, IO44=RX 500 kbps VESCs + Orin CANable2 ISO 11898
USB Serial (CH343) USB-C 460800 Orin primary /dev/balance-esp

7. ReSpeaker 2-Mic HAT (on Orin 40-pin header)

Orin Pin Signal Function
Pin 12 (GPIO 18) I2S BCLK Audio bit clock
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 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
ESP32-S3 BALANCE (CH343) USB-C ~0.5W (data only, BALANCE on 5V bus)
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.

Data Flow

                    ┌──────────────┐
                    │  RC TX       │ (in your hand)
                    │  (2.4GHz)    │
                    └──────┬───────┘
                           │ radio
                    ┌──────▼───────┐
                    │  RC RX       │ CRSF 420kbaud (future)
                    └──────┬───────┘
                           │ UART
              ┌────────────▼────────────┐
              │      ESP32-S3 BALANCE        │              │                         │
              │  QMI8658 -> Balance PID │
              │  RC -> Mode Manager     │
              │  Safety Monitor         │
              │                         │
              └──┬──────────┬───────────┘
    USART2 ─────┘          └───── USB Serial (CH343) / USART6
    26400 baud                    921600 baud         │                              │
    ┌────┴────────────┐                 ▼
    │ 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 │
                       └────────────┘   └───────────────┘