170 lines
6.4 KiB
Markdown
170 lines
6.4 KiB
Markdown
# 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
|