# AGENTS.md — SAUL-TEE Agent Onboarding

You're working on **SAUL-TEE**, a 4-wheel wagon robot. Read this entire file before touching anything.

**Full system reference:** `docs/SAUL-TEE-SYSTEM-REFERENCE.md`

## Project Overview

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

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

## ⚠️ SAFETY — READ THIS OR PEOPLE GET HURT

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: 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 without RC transmitter in hand.**

**If you break any of these, you are removed from the project.**

## Repository Layout

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

src/                  — LEGACY STM32 code (ARCHIVED — do not touch)
include/              — LEGACY STM32 headers (ARCHIVED — do not touch)

chassis/              — OpenSCAD mechanical parts
├── ASSEMBLY.md       — assembly instructions
├── BOM.md            — bill of materials
└── *.scad            — parametric parts

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

### ESP32-S3 BALANCE (Waveshare Touch LCD 1.28)

| Spec | Value |
|------|-------|
| 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 |

### ESP32-S3 IO (bare board)

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

> All TBD GPIO assignments are confirmed in `esp32/io/src/config.h`.

### CAN Bus

| 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

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

## Inter-Board Protocol

**UART @ 460800 baud, 8N1.** Frame: `[0xAA][LEN][TYPE][PAYLOAD…][CRC8]`

CRC polynomial: CRC-8/MAXIM (poly 0x31, init 0x00, RefIn/RefOut true).

Authoritative message type definitions: `esp32/shared/protocol.h`

## Build & Flash

```bash
# 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)
```

## Critical Lessons Learned

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.

## LED States (WS2812B on ESP32-IO)

| State | Pattern | Color |
|-------|---------|-------|
| Disarmed | Slow breathe | White |
| Arming | Fast blink | Yellow |
| Armed | Solid | Green |
| Turning | Sweep direction | Orange |
| Braking | Flash rear | Red |
| Fault / ESTOP | Triple flash | Red |
| RC lost | Alternating flash | Red/Blue |

## Printing (Bambu Lab)

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