Add project state document

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.