nick/overland-controller
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
overland-controller/docs/CHATGPT_HANDOFF.md
T

7.7 KiB
Raw Permalink Blame History

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.

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.
Reference in New Issue View Git Blame Copy Permalink