# SaltyLab — Self-Balancing Indoor Bot 🔬

Two-wheeled, self-balancing robot for indoor AI/SLAM experiments.

## ⚠️ SAFETY — TOP PRIORITY

**This robot can cause serious injury.** 8" hub motors with 36V power can crush toes, break fingers, and launch the frame if control is lost. Every design decision must prioritize safety.

### Mandatory Safety Systems
1. **Hardware kill switch** — physical big red button, wired inline with battery. Cuts ALL power instantly. Must be reachable without approaching the wheels.
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** — 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.
9. **Bumpers** — TPU bumpers on all sides, mandatory before any untethered operation.
10. **Test area** — clear 3m radius, no pets/kids/cables. Shoes mandatory.
11. **RC kill channel** — ELRS receiver connected to FC UART. Dedicated switch on radio = instant disarm. Works independently of Jetson. Always have radio in hand during testing.

### Safety Rules for Development
- **Never reach near wheels while powered** — even "stopped" motors can spike
- **Never test new firmware untethered** — tether FIRST, always
- **Never increase speed and change PID in the same test** — one variable at a time
- **Log everything** — FC sends telemetry (pitch, PID output, motor commands) to Jetson for post-crash analysis
- **Two people for early tests** — one at the kill switch, one observing

## Parts

| Part | Status |
|------|--------|
| 2x 8" pneumatic hub motors (36 PSI) | ✅ Have |
| 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 |
| 1x battery pack (36V) | ✅ Have |
| 1x DC-DC 5V converter | ✅ Have |
| 1x DC-DC 12V converter | ✅ Have |
| 1x ESP32-C3 (LED controller) | ⬜ Need (~$3) |
| WS2812B LED strip (60/m) | ⬜ Need |
| BNO055 9-DOF IMU | ✅ Have (spare/backup) |
| MPU6050 | ✅ Have (spare/backup) |
| 1x Big red kill switch (NC, inline with battery) | ⬜ Need |
| 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 — failover RC on ESP32-IO UART2 |

### 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

```
                    ┌──────────────┐
                    │  RPLIDAR A1  │ ← 360° scan, top-mounted
                    └──────┬───────┘
                    ┌──────┴───────┐
                    │ RealSense    │ ← Forward-facing depth+RGB
                    │ D435i        │
                    ├──────────────┤
                    │ Jetson Orin  │ ← AI brain: ROS2, SLAM, Nav2
                    │ Nano Super   │   Sends CAN cmds 0x300–0x303
                    ├──────────────┤
                    │ 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     │
                    ├──────┬───────┤
              ┌─────┤ VESC Left    ├─────┐
              │     │ (ID 68)      │     │
              │     │ VESC Right   │     │
              │     │ (ID 56)      │     │
              │     └──────────────┘     │
           ┌──┴──┐                   ┌──┴──┐
           │ Hub │                   │ Hub │
           │motor│                   │motor│
           └─────┘                   └─────┘
```

## Self-Balancing Control — Custom Firmware on ESP32-S3 BALANCE

### Architecture
```
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
```

### Wiring

```
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
```

### LED Patterns
| State | Pattern | Color |
|-------|---------|-------|
| Disarmed | Slow breathe | White |
| Arming | Fast blink | Yellow |
| Armed idle | Solid | Green |
| Turning left | Sweep left | Orange |
| Turning right | Sweep right | Orange |
| Braking | Flash rear | Red |
| Fault | Triple flash | Red |
| RC signal lost | Alternating flash | Red/Blue |

### Wiring
```
ESP32-S3 IO RMT GPIO (TBD) ──→ WS2812B data in
5V bus                     ──→ WS2812B 5V + ESP32-S3 IO VCC
GND                        ──→ Common ground
```

### Dev Tools
- **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

### Frame: Vertical Tower
```
         SIDE VIEW                    FRONT VIEW
    
    ┌───────────┐                 ┌─────────────────┐
    │  RPLIDAR  │ ~500mm          │     RPLIDAR     │
    ├───────────┤                 ├─────────────────┤
    │ RealSense │ ~400mm          │   [RealSense]   │
    ├───────────┤                 ├─────────────────┤
    │  Jetson   │ ~300mm          │    [Jetson]     │
    ├───────────┤                 ├─────────────────┤
    │ ESP32-S3  │ ~200mm          │   [BALANCE]     │
    ├───────────┤                 ├─────────────────┤
    │  Battery  │ ~100mm          │   [Battery]     │
    │  + ESC    │  LOW!           │   [ESC+DCDC]    │
    ├─────┬─────┤                 ├──┬──────────┬───┤
    │     │     │                 │  │          │   │
   ─┘     └─────┘─               ─┘ 8"      8" └──┘─
   ═══════════════               ═══            ═══
       GROUND                     L              R
```

### Key Dimensions
- **Height:** ~500-550mm total (sensor tower top)
- **Width:** ~350mm (axle to axle, constrained by motors)
- **Depth:** ~150-200mm (thin profile for doorways)
- **Weight target:** <10kg including battery
- **Center of gravity:** AS LOW AS POSSIBLE — battery + ESC at bottom

### Critical: Center of Mass
- Battery is the heaviest component → mount at axle height or below
- Jetson + sensors are light → can go higher
- Lower CoG = easier to balance, less aggressive PID needed
- If CoG is too high → oscillations, falls easily

### Frame Material
- **Main spine:** Aluminum extrusion 2020, vertical
- **Motor mount plate:** 3D printed PETG, 6mm thick, reinforced
- **Component shelves:** 3D printed PETG, bolt to spine
- **Fender/bumper:** 3D printed TPU (flexible, absorbs falls)

### 3D Printed Parts
| Part | Size (mm) | Material | Qty |
|------|-----------|----------|-----|
| Motor mount plate | 350×150×6 | PETG 80% | 1 |
| Battery shelf | 200×100×40 | PETG 60% | 1 |
| ESC mount | 150×100×15 | PETG 40% | 1 |
| Jetson shelf | 120×100×15 | PETG 40% | 1 |
| Sensor tower top | 120×120×10 | ASA 80% | 1 |
| LIDAR standoff | Ø80×80 | ASA 40% | 1 |
| RealSense bracket | 100×50×40 | PETG 60% | 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 |
| Kill switch mount | 60×60×40 | PETG 80% | 1 |
| Tether anchor point | 50×50×20 | PETG 100% | 1 |
| LED diffuser ring | Ø120×15 | Clear PETG 30% | 1 |
| ESP32-C3 mount | 30×25×10 | PETG 40% | 1 |

## Software Stack

### Jetson Orin Nano Super
- **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 (~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
2. **RC** — manual control via ELRS radio (primary testing mode)
3. **Follow** — tracks person with RealSense, follows at set distance
4. **Explore** — autonomous SLAM mapping, builds house map
5. **Patrol** — follows waypoints on saved map
6. **Dock** — returns to charging station (future)

**Mode priority:** RC override always wins. If radio sends stick input, it overrides Jetson commands. Kill switch overrides everything.

## Build Order

### Phase 1: Balance (Week 1)
**Safety first — no motor spins without kill switch + tether in place.**
- [ ] 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 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
  - 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 Orin Nano Super + power (DC-DC 5V via USB-C PD)
- [ ] Set up JetPack + ROS2
- [ ] 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
- [ ] SLAM mapping of a room
- [ ] Person detection + tracking (SSD-MobileNet-v2 via TensorRT)
- [ ] Follow mode: maintain 1.5m distance from person

### Phase 4: Polish (Week 4)
- [ ] Print proper enclosures, bumpers, diffuser ring
- [ ] 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/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