From 8d8da8460377e7a1856039ce9258c0283777b14d Mon Sep 17 00:00:00 2001 From: root Date: Wed, 3 Jun 2026 01:51:06 -0600 Subject: [PATCH] Add project state document --- docs/project-state.md | 341 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 341 insertions(+) create mode 100644 docs/project-state.md diff --git a/docs/project-state.md b/docs/project-state.md new file mode 100644 index 0000000..71d0a6b --- /dev/null +++ b/docs/project-state.md @@ -0,0 +1,341 @@ +# Xterra Overland Power & Monitoring Dashboard + +## Current Goal + +Build a custom monitoring and control system for a Nissan Xterra using: + +- 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 + +-------------------------------------------------- + +## Current Hardware + +Ordered / Planned + +- 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 + +-------------------------------------------------- + +## Architecture + +Dashboard Module (Pico) + +Responsibilities: + +- Touchscreen UI +- Audible alarms +- Dashboard display +- User interaction +- Sends commands to ESP32 +- Receives status updates + +Cargo Controller (ESP32) + +Responsibilities: + +- Relay control +- Sensor collection +- Configuration storage +- Future battery monitoring +- HTTP backup API +- UART communications + +-------------------------------------------------- + +## Communications + +Primary: + +UART over CAT5 + +Backup: + +WiFi HTTP API + +Fallback: + +RS485 over CAT5 if UART proves unreliable + +Message format: + +Newline-delimited JSON + +Example Request: + +{"type":"status_request"} + +Example Response: + +{"type":"status_response"} + +-------------------------------------------------- + +## CAT5 Pinout + +Pair 1 + +Blue +5V +Blue/White +5V + +Pair 2 + +Orange Ground +Orange/White Ground + +Pair 3 + +Green Pico TX -> ESP32 RX +Green/White Pico RX <- ESP32 TX + +Pair 4 + +Brown Ignition Sense +Brown/White Spare + +-------------------------------------------------- + +## Power Plan + +House Battery + +- Powers ESP32 directly through fused 12V +- Powers 12V to 5V buck converter +- Buck converter powers Pico through CAT5 + +Important: + +- 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 + +-------------------------------------------------- + +## Temperature Sensors + +Current Sensors + +- Fridge Zone 1 +- Fridge Zone 2 +- Rear Seat Area +- Outside Air + +No battery bay temperature sensor planned. + +Reason: + +Battery temperature will eventually come from the JBD/Xiaoxiang BMS. + +-------------------------------------------------- + +## Battery Monitoring + +Future Integration + +JBD / Xiaoxiang BLE Battery + +Planned Data: + +- State of Charge +- Voltage +- Current +- Remaining Ah +- Runtime Estimate +- Battery Temperature +- Cell Voltages +- Cell Imbalance + +-------------------------------------------------- + +## Relay Outputs + +Current + +- Starlink +- Fridge + +Future + +- Inverter +- Camp Lights + +Known GPIO Assignments + +GPIO16 = Relay Output 1 +GPIO17 = Relay Output 2 + +Relay ON = HIGH +Relay OFF = LOW + +-------------------------------------------------- + +## Dashboard Screens + +Implemented in Simulator + +- Dashboard +- Battery +- Temps +- Power +- System +- Config + +Dashboard Screen + +- Battery Percentage +- Runtime Remaining +- Fridge Zone 1 Temperature +- Fridge Zone 2 Temperature +- Rear Seat Temperature +- Outside Air Temperature +- Relay Status + +-------------------------------------------------- + +## Alarm System + +Implemented in Simulator + +- Warning alarms +- Critical alarms +- Full screen alarm overlay +- Acknowledge required +- Sensor fault alarms +- Configurable thresholds + +Alarm Targets + +- Rear Seat Warning +- Rear Seat Critical +- Fridge Zone 1 Warm +- Fridge Zone 2 Warm +- Battery Low + +Future + +- Dashboard buzzer + +-------------------------------------------------- + +## Simulator Status + +Location + +simulator/ + +Implemented + +- 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 + +Run Command + +python3 simulator/app.py + +-------------------------------------------------- + +## Firmware Status + +ESP32 Firmware + +Location + +firmware/esp32/xterra-controller/ + +Implemented + +- Relay framework +- Sensor framework +- DS18B20 support +- HTTP status endpoint +- WiFi AP mode +- GPIO16 relay +- GPIO17 relay + +Next ESP32 Tasks + +- Verify relay hardware +- Verify DS18B20 hardware +- Implement UART communications + +-------------------------------------------------- + +## Pico Status + +Not started. + +Next Tasks + +Create: + +firmware/pico/display_test/ +firmware/pico/touch_test/ +firmware/pico/dashboard/ + +Goals + +1. Verify ST7796S display +2. Verify FT6336U touch controller +3. Select graphics library +4. Build dashboard UI +5. Implement UART communications + +-------------------------------------------------- + +## Important Decisions + +- 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 + +-------------------------------------------------- + +## Repository + +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.