# ChatGPT Handoff

Last updated: 2026-06-07

Use this document to bring a new ChatGPT/Codex session up to speed quickly. Keep it current when project goals, architecture, APIs, hardware assumptions, validation status, or near-term priorities change.

## How to Use This

At the start of a new assistant session, provide this file along with:

- `AGENTS.md`
- `docs/project-state.md`
- `docs/ARCHITECTURE.md`
- `docs/HARDWARE.md`
- `docs/API.md`
- `docs/ROADMAP.md`

The assistant should treat the Cargo ESP32 firmware and primary docs as the source of truth, then update this handoff before finishing any meaningful change.

## Non-Negotiable Constraints

- Cargo ESP32 remains the controller, API server, WebUI host, and source of truth.
- Waveshare ESP32-S3 dashboard is a client only.
- Do not move relay, BMS, or control authority into the dashboard.
- Do not modify JBD/Xiaoxiang BLE behavior without explicit approval.
- Do not change BLE timeout, reconnect, scan, or BMS-selection behavior without approval.
- Do not hardcode install-specific names into firmware.
- Preserve API compatibility when practical.
- Prefer HTTP API integration over custom protocols.
- ESP32 relay board outputs trigger external fused automotive relays/contactors only.
- Do not route fridge, Starlink, inverter, or other major load current through the ESP32 relay board.
- Dashboard target is Waveshare ESP32-S3-Touch-LCD-5.
- Dashboard connects to Cargo ESP32 AP over WiFi and is powered from ACC switched 12V into VIN.
- Do not power dashboard from OBD-II pin 16 in the permanent install.
- CAN termination must stay disabled when connected to vehicle CAN.

## Current Status

Current firmware version:

```text
0.5.0
```

Current architecture:

- ESP32 relay board is the cargo controller.
- Embedded WebUI is served by the Cargo ESP32.
- HTTP API base path is `/api/v1`.
- Root HTTP routes remain as compatibility aliases for existing local clients.
- Dashboard direction is Waveshare ESP32-S3 over WiFi/HTTP, not Pico/UART.
- UART JSON remains optional for diagnostics or alternate clients.

Current working feature areas:

- Relay control through WebUI, HTTP API, UART JSON, and USB serial.
- JBD/Xiaoxiang BLE BMS telemetry.
- DS18B20 temperature scan, assignment, clear, and configured naming workflow.
- WiFi AP recovery network at `192.168.4.1`.
- STA mode with saved WiFi networks and priorities.
- Config-driven generic relay and temperature IDs.
- Config backup/restore API.
- BMS setup workflow API.

## API Direction

New clients should use `/api/v1`.

Dashboard MVP should initially consume only:

```text
GET  /api/v1/status
POST /api/v1/relay/set
```

Other current HTTP API areas include:

- Health and capability discovery.
- Configuration read/update/save/factory-reset.
- Config export/import.
- WiFi config/connect/clear.
- Temperature scan/assign/clear.
- BMS setup enter/exit, scan, and select.

See `docs/API.md` for the current contract and `tests/test_http_api_contract.py` for contract coverage.

## Near-Term Goals

1. Verify WebUI setup workflow after a fresh flash.
2. Clean up DS18B20 physical distribution hardware.
3. Test 2-4 temperature probes after the distribution board is installed.
4. Start the Waveshare ESP32-S3 dashboard MVP over WiFi/HTTP.
5. Improve BMS out-of-range handling only with explicit approval for BLE behavior changes.
6. Define future Pi Zero logging/integration role without moving control authority off the Cargo ESP32.

## Recent Context

- The project recently standardized current HTTP routes under `/api/v1`.
- Health, capabilities, config backup/restore, configuration update, WiFi, temperature setup, and BMS setup endpoints are documented in `docs/API.md`.
- The embedded WebUI uses `const API_BASE="/api/v1";`.
- Pre-versioned HTTP routes remain registered as compatibility aliases.
- `docs/archive/` contains older or superseded planning material and should not override the primary docs.

## Validation Status

Available validation is driven by:

```text
python3 run_tests.py
```

The script performs Python compile checks for the dashboard code, then runs:

```text
python3 -m pytest tests/test_pico_core.py
python3 -m pytest tests/test_http_api_contract.py
```

As of this update, the compile step passes in the local environment, but full test execution is blocked because `pytest` is not installed for the active `python3`.

## Handoff Maintenance Checklist

Update this document when any of these change:

- Active project phase or near-term goals.
- Cargo ESP32 vs dashboard responsibility boundaries.
- Current firmware version.
- HTTP API route list, response shape, or compatibility policy.
- Hardware assumptions, wiring, power, relay, CAN, or dashboard target.
- Validation commands, dependencies, or current test status.
- Important decisions that a future assistant should not rediscover from scratch.


## Current communications and GPIO decision

Active dashboard communication is WiFi/HTTP using `/api/v1`.

The old Pico/dashboard UART path is retired from active hardware use. USB Serial remains available for development, debug, and manual configuration from a computer.

Current Cargo ESP32 GPIO plan:

- GPIO 16: Relay 1 trigger output
- GPIO 17: Relay 2 trigger output
- GPIO 4: DS18B20 OneWire temperature bus
- GPIO 34: Ignition sense input
- GPIO 21: SSD1306 OLED I2C SDA
- GPIO 22: SSD1306 OLED I2C SCL
- GPIO 25: OLED setup/status button