From 4e7e6b870332b418a433ce88eba88d6f78a394ff Mon Sep 17 00:00:00 2001 From: nick Date: Thu, 4 Jun 2026 04:21:35 -0600 Subject: [PATCH] Update project state documentation --- docs/project-state.md | 477 +++++++++++++++++++++--------------------- 1 file changed, 237 insertions(+), 240 deletions(-) diff --git a/docs/project-state.md b/docs/project-state.md index 9177e8a..a121232 100644 --- a/docs/project-state.md +++ b/docs/project-state.md @@ -2,296 +2,293 @@ Last Updated: June 2026 -## Project Overview +## Project Name -Overland Controller is a distributed vehicle monitoring and control system. +Overland Controller -Current architecture: +## Current Status -- ESP32 controller in cargo area -- Raspberry Pi Pico 2 W dashboard -- UART communication between devices -- Local WiFi for setup and debugging -- HTTP API for configuration and diagnostics -- JSON protocol shared between UART and HTTP +Phase 1 is functional. -Primary goal: +The ESP32 controller can: -Provide monitoring and control of overland vehicle systems from a dashboard interface. +- Host a local WiFi access point +- Serve a web interface +- Expose an HTTP API +- Read JBD/Xiaoxiang BLE BMS data +- Persist configuration +- Factory reset configuration +- Control relay outputs +- Report relay status +- Report BMS status +- Report temperature sensor status +- Communicate over UART +- Support BLE setup mode for BMS discovery + +The Pico dashboard hardware has not yet been brought online. --- -## Hardware Status +## Hardware Owned -### Purchased +### ESP32 Controller -ESP32 2-channel relay board +Owned and operational. -Status: -Operational +Current hardware: -Functions: +- ESP32 relay board +- 2 relay outputs -- Relay control -- WiFi access point -- BLE BMS communication -- HTTP API -- UART interface +### Dashboard + +Owned but not yet integrated. + +Current hardware: + +- Raspberry Pi Pico 2 W + +Potential display: + +- 3.5" touchscreen expansion board + +### Vehicle + +Current target vehicle: + +- Nissan Xterra + +The firmware itself should remain vehicle-agnostic. --- -Raspberry Pi Pico 2 W +## BMS Status -Status: -Purchased +Working. -Planned functions: +Current battery: -- Dashboard UI -- Touchscreen interface -- UART communication with ESP32 +- JBD / Xiaoxiang BLE BMS ---- - -### Planned Hardware - -3.5" touchscreen for Pico - -DS18B20 temperature sensors - -Automotive relays - -Future OBD-II interface - -Future GPS interface - -Future inverter monitoring - ---- - -## ESP32 Status - -### Working - -Relay control - -Configuration persistence - -Factory reset - -BLE BMS connection - -JBD/Xiaoxiang battery monitoring - -Status API - -Config API - -UART status responses - -BMS discovery mode - -BLE device selection - -Generic relay configuration - -Generic temperature configuration - -Generic BMS configuration - -Device naming - ---- - -### In Progress - -UART command parity with HTTP - -Generic configuration endpoints - -Documentation cleanup - ---- - -### Not Started - -DS18B20 integration - -Vehicle ignition sensing - -OBD-II integration - -GPS integration - -Data logging - -Historical graphs - -Home Assistant integration - -MQTT support - -OTA firmware updates - ---- - -## Pico Dashboard Status - -### Complete - -Desktop simulator architecture - -Protocol design - -Dashboard architecture planning - ---- - -### Not Started - -Display driver integration - -Touch input - -Status display - -Relay control UI - -Configuration UI - -BLE setup UI - ---- - -## Data Sources - -### Active - -JBD / Xiaoxiang BMS - -Data currently available: +Current telemetry: - SOC - Voltage - Current -- Remaining capacity +- Remaining Ah +- Capacity - Temperature - Cycle count - Cell voltages - Cell delta ---- - -### Planned - -DS18B20 sensors - -Vehicle ignition - -OBD-II - -GPS - -Starlink diagnostics - -Inverter monitoring +Configuration is stored in persistent settings. --- -## Communication Architecture +## Relay Status -### Primary +Working. -UART - -Pico <-> ESP32 - -Purpose: - -- Dashboard status -- Relay control -- Configuration - ---- - -### Secondary - -HTTP API - -Purpose: - -- Setup -- Debugging -- Testing -- Future web UI - ---- - -### Service Interface - -USB Serial - -Purpose: - -- Recovery -- Debugging -- Development - ---- - -## Current Firmware Version - -Firmware: - - overland-controller - -Version: - - 0.3.0 - ---- - -## Major Architectural Decisions - -Configuration is stored on ESP32. - -Names are configuration, not firmware. - -UART is the primary dashboard interface. - -HTTP mirrors UART functionality where practical. - -Relay IDs remain generic: +Current relay outputs: relay_1 relay_2 -Temperature IDs remain generic: +Current installation-specific names: - temp_1 through temp_8 + Starlink + Fridge -Installation-specific naming is handled entirely through configuration. +These names are configuration only. + +No relay names are intended to be hardcoded. --- -## Next Recommended Milestones +## Temperature Sensor Status -1. Finish UART protocol implementation +Partially complete. -2. Add DS18B20 support +Framework exists. -3. Build Pico simulator integration +Current status: -4. Bring up Pico touchscreen +- Configuration exists +- Status reporting exists +- Naming exists -5. Implement dashboard UI +Not yet completed: -6. Add vehicle ignition monitoring +- Physical DS18B20 integration +- Sensor discovery workflow +- Sensor assignment workflow -7. Add OBD-II support +Planned support: -8. Add logging and history +Up to 8 DS18B20 sensors. -9. Add Home Assistant integration +--- -10. Prepare first vehicle installation +## Configuration Status + +Persistent configuration works. + +Stored settings include: + +- Device name +- Relay names +- Relay enabled state +- Temperature sensor names +- Temperature sensor enabled state +- BMS name +- BMS address +- BMS address type + +Factory reset is functional. + +--- + +## HTTP API Status + +Working. + +Implemented: + +- Status endpoint +- Config endpoint +- Relay control +- Configuration updates +- Save configuration +- Factory reset + +Documentation: + +See: + + docs/api.md + +--- + +## UART Status + +Partially complete. + +Current UART capabilities: + +- Status requests +- Dashboard communications +- Basic command support + +Missing goal: + +UART should eventually expose every operation available through HTTP and serial. + +Target: + +UART becomes the primary dashboard integration interface. + +--- + +## Simulator Status + +Working. + +Simulator provides: + +- Fake ESP32 controller +- Fake Pico dashboard +- Test data generation +- Protocol validation + +Useful for development before hardware is connected. + +--- + +## Documentation Status + +Primary documents: + + README.md + HARDWARE.md + + docs/project-state.md + docs/architecture.md + docs/api.md + docs/protocol.md + docs/roadmap.md + docs/decisions.md + docs/SERIAL_COMMANDS.md + +Older planning/design documents may be archived later. + +--- + +## Highest Priority Next Tasks + +### Priority 1 + +UART parity. + +Goal: + +Anything possible through serial or HTTP should also be possible through UART. + +Required additions: + +- config_request +- config_device +- config_relay +- config_temp +- config_bms +- save_config +- factory_reset +- enter_bms_setup +- scan_ble +- select_bms +- exit_bms_setup + +### Priority 2 + +DS18B20 support. + +Needed: + +- Scan sensors +- Assign sensors +- Save assignments + +### Priority 3 + +Pico hardware bring-up. + +Needed: + +- UART communication +- Display status screen +- Relay control screen + +--- + +## Long-Term Vision + +A vehicle-agnostic overland monitoring and control platform. + +Core principles: + +- Local-first +- No cloud required +- Generic hardware model +- Generic API model +- Generic UART model +- Dashboard optional +- Vehicle independent + +Target use cases: + +- Overland vehicles +- Campers +- Trailers +- RV electrical systems +- Mobile command systems +- Off-grid battery monitoring