overland-controller/docs/CHATGPT_HANDOFF.md

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:

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:

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:

python3 run_tests.py

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

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.