diff --git a/docs/project-state.md b/docs/project-state.md index 3ed7444..9177e8a 100644 --- a/docs/project-state.md +++ b/docs/project-state.md @@ -1,341 +1,297 @@ -# Xterra Overland Power & Monitoring Dashboard +# Project State -## Current Goal +Last Updated: June 2026 -Build a custom monitoring and control system for a Nissan Xterra using: +## Project Overview -- Raspberry Pi Pico 2 W dashboard module -- ESP32 cargo-area controller -- 3.5 inch 320x480 SPI capacitive touchscreen -- DS18B20 temperature sensors -- UART over CAT5 communication -- WiFi HTTP backup interface +Overland Controller is a distributed vehicle monitoring and control system. --------------------------------------------------- +Current architecture: -## Current Hardware +- 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 -Ordered / Planned +Primary goal: -- Raspberry Pi Pico 2 W -- ESP32 2-channel relay board -- 3.5 inch 320x480 touchscreen -- ST7796S display controller -- FT6336U capacitive touch controller -- 4x DS18B20 waterproof sensors -- Active 5V buzzer -- CAT5 cable -- Bosch automotive relays -- 12V to 5V buck converter +Provide monitoring and control of overland vehicle systems from a dashboard interface. --------------------------------------------------- +--- -## Architecture +## Hardware Status -Dashboard Module (Pico) +### Purchased -Responsibilities: +ESP32 2-channel relay board -- Touchscreen UI -- Audible alarms -- Dashboard display -- User interaction -- Sends commands to ESP32 -- Receives status updates +Status: +Operational -Cargo Controller (ESP32) - -Responsibilities: +Functions: - Relay control -- Sensor collection -- Configuration storage -- Future battery monitoring -- HTTP backup API -- UART communications +- WiFi access point +- BLE BMS communication +- HTTP API +- UART interface --------------------------------------------------- +--- -## Communications +Raspberry Pi Pico 2 W -Primary: +Status: +Purchased -UART over CAT5 +Planned functions: -Backup: +- Dashboard UI +- Touchscreen interface +- UART communication with ESP32 -WiFi HTTP API +--- -Fallback: +### Planned Hardware -RS485 over CAT5 if UART proves unreliable +3.5" touchscreen for Pico -Message format: +DS18B20 temperature sensors -Newline-delimited JSON +Automotive relays -Example Request: +Future OBD-II interface -{"type":"status_request"} +Future GPS interface -Example Response: +Future inverter monitoring -{"type":"status_response"} +--- --------------------------------------------------- +## ESP32 Status -## CAT5 Pinout +### Working -Pair 1 +Relay control -Blue +5V -Blue/White +5V +Configuration persistence -Pair 2 +Factory reset -Orange Ground -Orange/White Ground +BLE BMS connection -Pair 3 +JBD/Xiaoxiang battery monitoring -Green Pico TX -> ESP32 RX -Green/White Pico RX <- ESP32 TX +Status API -Pair 4 +Config API -Brown Ignition Sense -Brown/White Spare +UART status responses --------------------------------------------------- +BMS discovery mode -## Power Plan +BLE device selection -House Battery +Generic relay configuration -- Powers ESP32 directly through fused 12V -- Powers 12V to 5V buck converter -- Buck converter powers Pico through CAT5 +Generic temperature configuration -Important: +Generic BMS configuration -- ESP32 relay board never carries fridge load current -- ESP32 relay board never carries Starlink load current -- ESP32 relay outputs only trigger Bosch relays -- High current circuits are separately fused +Device naming --------------------------------------------------- +--- -## Temperature Sensors +### In Progress -Current Sensors +UART command parity with HTTP -- Fridge Zone 1 -- Fridge Zone 2 -- Rear Seat Area -- Outside Air +Generic configuration endpoints -No battery bay temperature sensor planned. +Documentation cleanup -Reason: +--- -Battery temperature will eventually come from the JBD/Xiaoxiang BMS. +### Not Started --------------------------------------------------- +DS18B20 integration -## Battery Monitoring +Vehicle ignition sensing -Future Integration +OBD-II integration -JBD / Xiaoxiang BLE Battery +GPS integration -Planned Data: +Data logging -- State of Charge +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: + +- SOC - Voltage - Current -- Remaining Ah -- Runtime Estimate -- Battery Temperature -- Cell Voltages -- Cell Imbalance +- Remaining capacity +- Temperature +- Cycle count +- Cell voltages +- Cell delta --------------------------------------------------- +--- -## Relay Outputs +### Planned -Current +DS18B20 sensors -- Starlink -- Fridge +Vehicle ignition -Future +OBD-II -- Inverter -- Camp Lights +GPS -Known GPIO Assignments +Starlink diagnostics -GPIO16 = Relay Output 1 -GPIO17 = Relay Output 2 +Inverter monitoring -Relay ON = HIGH -Relay OFF = LOW +--- --------------------------------------------------- +## Communication Architecture -## Dashboard Screens +### Primary -Implemented in Simulator +UART -- Dashboard -- Battery -- Temps -- Power -- System -- Config +Pico <-> ESP32 -Dashboard Screen +Purpose: -- Battery Percentage -- Runtime Remaining -- Fridge Zone 1 Temperature -- Fridge Zone 2 Temperature -- Rear Seat Temperature -- Outside Air Temperature -- Relay Status +- Dashboard status +- Relay control +- Configuration --------------------------------------------------- +--- -## Alarm System +### Secondary -Implemented in Simulator +HTTP API -- Warning alarms -- Critical alarms -- Full screen alarm overlay -- Acknowledge required -- Sensor fault alarms -- Configurable thresholds +Purpose: -Alarm Targets +- Setup +- Debugging +- Testing +- Future web UI -- Rear Seat Warning -- Rear Seat Critical -- Fridge Zone 1 Warm -- Fridge Zone 2 Warm -- Battery Low +--- -Future +### Service Interface -- Dashboard buzzer +USB Serial --------------------------------------------------- +Purpose: -## Simulator Status +- Recovery +- Debugging +- Development -Location +--- -simulator/ +## Current Firmware Version -Implemented +Firmware: -- Flask backend -- Browser dashboard -- Pico simulator -- ESP32 simulator -- Protocol layer -- Transport layer -- Config persistence -- Sensor fault simulation -- Ignition simulation -- Communication failure simulation -- Latency simulation -- Packet loss simulation + overland-controller -Run Command +Version: -python3 simulator/app.py + 0.3.0 --------------------------------------------------- +--- -## Firmware Status +## Major Architectural Decisions -ESP32 Firmware +Configuration is stored on ESP32. -Location +Names are configuration, not firmware. -firmware/esp32/overland-controller/ +UART is the primary dashboard interface. -Implemented +HTTP mirrors UART functionality where practical. -- Relay framework -- Sensor framework -- DS18B20 support -- HTTP status endpoint -- WiFi AP mode -- GPIO16 relay -- GPIO17 relay +Relay IDs remain generic: -Next ESP32 Tasks + relay_1 + relay_2 -- Verify relay hardware -- Verify DS18B20 hardware -- Implement UART communications +Temperature IDs remain generic: --------------------------------------------------- + temp_1 through temp_8 -## Pico Status +Installation-specific naming is handled entirely through configuration. -Not started. +--- -Next Tasks +## Next Recommended Milestones -Create: +1. Finish UART protocol implementation -firmware/pico/display_test/ -firmware/pico/touch_test/ -firmware/pico/dashboard/ +2. Add DS18B20 support -Goals +3. Build Pico simulator integration -1. Verify ST7796S display -2. Verify FT6336U touch controller -3. Select graphics library -4. Build dashboard UI -5. Implement UART communications +4. Bring up Pico touchscreen --------------------------------------------------- +5. Implement dashboard UI -## Important Decisions +6. Add vehicle ignition monitoring -- Touchscreen-only interface -- Active buzzer mounted in dashboard enclosure -- UART over CAT5 is primary wired communication -- WiFi is backup communication -- RS485 is back-burnered as fallback -- No persistent logging currently planned -- Focus on live monitoring, alarms, and control -- Repository is the source of truth -- Verify current file contents before generating patches +7. Add OBD-II support --------------------------------------------------- +8. Add logging and history -## Repository +9. Add Home Assistant integration -Repository is the source of truth. - -Do not assume previous patches were applied successfully. - -Verify file contents before modifying existing files. - --------------------------------------------------- - -## New Chat Handoff - -When continuing this project in a new chat: - -Continue my Xterra Overland Power & Monitoring Dashboard project from docs/project-state.md. - -The repository is the source of truth. - -Ask me for current file contents before generating patches that modify existing files. +10. Prepare first vehicle installation