From a721f6b5397b64213fd7c2ca678f950392637168 Mon Sep 17 00:00:00 2001 From: nick Date: Sun, 7 Jun 2026 10:40:46 -0600 Subject: [PATCH] Add ChatGPT handoff document --- docs/CHATGPT_HANDOFF.md | 131 ++++++++++++++++++++++++++++++++++++++++ docs/README.md | 1 + 2 files changed, 132 insertions(+) create mode 100644 docs/CHATGPT_HANDOFF.md diff --git a/docs/CHATGPT_HANDOFF.md b/docs/CHATGPT_HANDOFF.md new file mode 100644 index 0000000..bc12d4a --- /dev/null +++ b/docs/CHATGPT_HANDOFF.md @@ -0,0 +1,131 @@ +# 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.4.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. diff --git a/docs/README.md b/docs/README.md index a95dbf1..7aae532 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,6 +12,7 @@ This folder contains project documentation for Overland Controller. ## Project Tracking +- `CHATGPT_HANDOFF.md` - Concise assistant handoff with current status, goals, constraints, and validation notes - `project-state.md` - Current project state - `roadmap.md` - Roadmap and future plans - `decisions.md` - Architecture and implementation decisions