# 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

## Current Architecture Guardrails

- Inspect the repo before proposing code or documentation changes.
- Preserve the Cargo ESP vs Dashboard ESP32-S3 role split.
- Cargo ESP32 does not own CAN, OBD-II, tilt sensing, vehicle data, or dashboard rendering.
- Dashboard ESP32-S3 does not own relay authority, BMS authority, alarm authority, or persistent cargo-controller configuration.
- v1 dashboard communication is WiFi/HTTP REST only.
- ESP-NOW, MQTT, UART dashboard link, and CAN-between-controllers are not v1 architecture.
- Load-switching hardware is not finalized. Bosch relays, WUPP-style fused distribution, smart high-side switching, and custom PCB options remain implementation choices until explicitly selected.

## Legacy Pico Dashboard Archive

The old Pico dashboard implementation has been archived at `archive/legacy-pico-dashboard/`.

Do not treat it as active firmware. It may be referenced for old HTTP/state/alarm/UI ideas, but new dashboard work should target the ESP32-S3 dashboard path.

Default validation should use the repo-local virtual environment:

    source .venv/bin/activate
    python run_tests.py

## DS18B20 Implementation Note

DS18B20 temperature support is already implemented in the Cargo ESP/WebUI/API path.

Do not suggest adding DS18B20 support as if it is missing. Future work should preserve existing Cargo ESP temperature ownership and expose/display that telemetry through the API and ESP32-S3 dashboard.

## Cargo API Contract Guardrail

The Cargo ESP API contract is documented in `docs/cargo-api-contract.md`.

Before making dashboard firmware changes, inspect the current API tests and this contract. Do not move relay, BMS, DS18B20, alarm, or configuration ownership from the Cargo ESP to the dashboard.

## Pre-LilyGO Baseline Checklist

Before suggesting a release/tag prior to Cargo ESP hardware migration, check `docs/pre-lilygo-baseline-checklist.md`.

Do not suggest migrating active Cargo ESP firmware to LilyGO hardware until the user explicitly decides to buy/use that board.

## LilyGO Transition Guardrail

The user has ordered a LILYGO T-Relay-S3 6-way board, but it will not arrive for a couple weeks.

Until the user confirms hardware is available and bench tested:

- Keep the existing 2-channel relay board as the active test target.
- Do not remove 2-channel support.
- Do not assume LilyGO firmware is active.
- Prepare API/config/docs for output-count-agnostic operation.
- Treat LilyGO migration as a future hardware-profile change.