Add project documentation

docs/architecture.md

@@ -1,235 +1,76 @@
-# Xterra Overland Power & Monitoring Dashboard Architecture
+# Xterra Overland Power & Monitoring Dashboard
 
-## Overview
+## Purpose
 
-The Xterra Overland Power & Monitoring Dashboard is a distributed monitoring and control system consisting of:
+A custom monitoring and control system for a Nissan Xterra using a Raspberry Pi Pico 2 W dashboard interface and an ESP32 cargo-area controller.
 
-* Raspberry Pi Pico 2 W dashboard module
+The system provides:
-* ESP32 cargo-area controller
-* RS-485 wired communications
-* WiFi backup communications
-* Touchscreen dashboard interface
 
-The system is designed to operate completely offline and continue functioning even when WiFi is disabled.
+- House battery monitoring
-
+- Fridge monitoring
----
+- Temperature monitoring
-
+- Power control
-## System Goals
+- Alarm management
-
+- Future vehicle telemetry
-* Monitor house battery status
-* Monitor fridge temperatures
-* Monitor rear seat temperature
-* Monitor outside ambient temperature
-* Control Starlink power
-* Control fridge power
-* Provide a dashboard display while driving
-* Expand later to vehicle telemetry and trip logging
-
----
 
 ## Dashboard Module
 
 ### Hardware
 
-* Raspberry Pi Pico 2 W
+- Raspberry Pi Pico 2 W
-* 3.5" touchscreen
+- 3.5" SPI Capacitive Touchscreen
-* Powered by 5V from cargo-area buck converter
+- RS-485 communications
+- WiFi backup communications
 
 ### Responsibilities
 
-* Display information
+- Touchscreen user interface
-* Accept touch input
+- Local web dashboard
-* Send commands to controller
+- Alarm display
-* Display alarms and warnings
+- Configuration management
-* Provide user configuration interface
+- Relay control interface
+- Data visualization
 
-### Communications
+## Cargo Module
-
-Primary:
-
-* RS-485 over CAT5
-
-Secondary:
-
-* WiFi HTTP API
-
----
-
-## Controller Module
 
 ### Hardware
 
-* ESP32 relay board
+- ESP32 Relay Controller
-* House battery connection
+- RS-485 Interface
-* Bosch-style automotive relays
+- House Battery Interface
+- DS18B20 Temperature Sensor Bus
+- Bosch Relay Drivers
 
 ### Responsibilities
 
-* Read sensors
+- Sensor collection
-* Interface with BMS
+- Relay control
-* Control relays
+- Alarm processing
-* Serve API data
+- Communications server
-* Handle logging
+- Configuration storage
-
----
-
-## Temperature Sensors
-
-### Planned Sensors
-
-1. Fridge Zone 1
-2. Fridge Zone 2
-3. Rear Seat Temperature
-4. Outside Ambient Temperature
-5. Battery Compartment Temperature (future)
-
-### Interface
-
-* DS18B20
-* Shared 1-Wire bus
-* Connected to ESP32
-
----
-
-## Battery Monitoring
-
-### Planned BMS
-
-* Xiaoxiang / JBD Bluetooth BMS
-
-### Data Collected
-
-* State of Charge
-* Voltage
-* Current
-* Remaining Capacity
-* Runtime Estimate
-* Battery Temperature
-* Cell Voltages
-* Cell Imbalance
-
----
-
-## Relay Control
-
-### Current Loads
-
-* Starlink
-* Fridge
-
-### Future Loads
-
-* Inverter
-* Camp Lights
-
-### Design
-
-ESP32 relay outputs SHALL NOT carry load current.
-
-ESP32 relays will only energize Bosch-style 30A/40A automotive relays.
-
-All loads must be fused appropriately.
-
----
 
 ## Communications
 
-### Primary
+Primary:
+- RS-485
 
-RS-485 over CAT5
+Backup:
+- WiFi HTTP API
 
-Advantages:
+Future:
-
+- MQTT
-* Reliable
+- Home Assistant
-* Noise resistant
+- Grafana
-* Independent of WiFi
+- InfluxDB
-* Works while driving
-
-### Backup
-
-WiFi HTTP API
-
-Used for:
-
-* Phone access
-* Web dashboard
-* Configuration
-* Future Home Assistant integration
-
----
-
-## WiFi Rules
-
-### Starlink OFF
-
-* Dashboard operational
-* Sensors operational
-* Relay control operational
-* WiFi disabled
-* Web dashboard disabled
-
-### Starlink ON
-
-* WiFi enabled
-* Web dashboard enabled
-* Remote access enabled
-
-### Override
-
-User may temporarily enable WiFi for troubleshooting.
-
-Default timeout:
-10 minutes.
-
----
-
-## Dashboard Behavior
-
-### Ignition ON
-
-* Screen active
-* Full brightness
-
-### Ignition OFF
-
-* Screen black
-* Pico remains powered
-* Touch input remains active
-
-Touching screen:
-
-* Wake display
-* Display dashboard
-* Auto-sleep after timeout
-
----
 
 ## Future Expansion
 
-### Vehicle Data
+- JBD/Xiaoxiang BLE Battery Monitoring
-
+- OBD-II
-* OBD-II
+- CAN Bus
-* CAN bus
+- GPS
-* Fuel level
+- Trip Logging
-* RPM
+- Fuel Level
-* Coolant temperature
+- Coolant Temperature
-* Vehicle speed
+- RPM
-
+- Starlink Diagnostics
-### Navigation
-
-* GPS
-* Trip logging
-
-### Connectivity
-
-* MQTT
-* Home Assistant
-* InfluxDB
-* Grafana
-
-### Additional Sensors
-
-* Additional DS18B20 sensors
-* Voltage sensors
-* Current sensors
-* Environmental monitoring

docs/communications.md

@@ -0,0 +1,41 @@
+# Communications
+
+## Architecture
+
+Pico Dashboard
+↓
+RS-485
+↓
+ESP32 Controller
+
+Backup:
+WiFi
+
+## Protocol
+
+Message Types:
+
+- status_request
+- status_response
+- set_relay
+- relay_response
+- enable_wifi
+- wifi_response
+- toggle_ignition
+- ignition_response
+- toggle_sensor_fault
+- sensor_fault_response
+
+## Failure Handling
+
+If RS-485 is lost:
+- Dashboard displays warning
+- Last known values remain visible
+- Relay commands fail safely
+
+## Future Features
+
+- MQTT
+- Home Assistant
+- OTA Updates
+- Remote Diagnostics

docs/dashboard-ui.md

@@ -0,0 +1,75 @@
+# Dashboard User Interface
+
+## Dashboard Screen
+
+Displays:
+- Battery %
+- Runtime Remaining
+- Fridge Zone 1 Temperature
+- Fridge Zone 2 Temperature
+- Rear Seat Temperature
+- Outside Temperature
+- Starlink Status
+- Fridge Status
+
+## Battery Screen
+
+Displays:
+- SOC
+- Voltage
+- Current
+- Remaining Ah
+- Runtime Estimate
+- Battery Temperature
+
+Future:
+- Cell Voltages
+- Cell Imbalance
+- Charge Cycles
+
+## Temperature Screen
+
+Displays:
+- Fridge Zone 1
+- Fridge Zone 2
+- Rear Seat
+- Outside Air
+
+Future:
+- Battery Bay
+- Cabin Air
+
+## Power Screen
+
+Controls:
+- Starlink
+- Fridge
+
+Future:
+- Inverter
+- Camp Lights
+
+## System Screen
+
+Displays:
+- RS-485 Status
+- WiFi Status
+- Message Counts
+- Latency
+- Packet Loss
+
+Testing:
+- RS-485 Disconnect
+- Sensor Fault Simulation
+- Ignition Simulation
+
+## Config Screen
+
+Configuration:
+- Alarm Thresholds
+- Audible Alarm Settings
+
+Future:
+- WiFi Settings
+- Device Naming
+- Firmware Information

docs/decisions.md

@@ -0,0 +1,57 @@
+# Project Decisions
+
+## Communications
+
+Primary:
+- RS-485
+
+Backup:
+- WiFi
+
+## Dashboard
+
+- Touchscreen only
+- No physical buttons required
+- Screen sleeps when ignition is off
+- Touch wakes display
+
+## Relay Design
+
+- ESP32 relay board does NOT switch loads directly
+- Bosch-style automotive relays switch all major loads
+
+## Power Loads
+
+Current:
+- Starlink
+- Fridge
+
+Future:
+- Inverter
+- Camp Lights
+
+## Sensors
+
+Current:
+- Fridge Zone 1
+- Fridge Zone 2
+- Rear Seat Area
+- Outside Air
+
+Future:
+- Battery Bay
+- Cabin Air
+- Water Tank
+
+## Configuration
+
+Configuration is stored on controller side, not browser side.
+
+## Logging
+
+No persistent logging currently planned.
+
+Focus:
+- Live monitoring
+- Alarms
+- Control

docs/roadmap.md

@@ -0,0 +1,71 @@
+# Project Roadmap
+
+## Phase 1 — Simulator
+
+Status: Complete
+
+Features:
+- Dashboard UI
+- Alarm System
+- Sensor Simulation
+- RS-485 Simulation
+- Protocol Layer
+
+## Phase 2 — Pico Dashboard
+
+Status: Pending
+
+Features:
+- 3.5" Touchscreen
+- Native Dashboard UI
+- Sleep/Wake Functionality
+
+## Phase 3 — ESP32 Controller
+
+Status: Pending
+
+Features:
+- Relay Control
+- RS-485 Communications
+- Configuration Storage
+
+## Phase 4 — DS18B20 Sensors
+
+Status: Pending
+
+Features:
+- Fridge Monitoring
+- Rear Seat Monitoring
+- Outside Temperature
+
+## Phase 5 — JBD BLE Integration
+
+Status: Pending
+
+Features:
+- SOC
+- Voltage
+- Current
+- Remaining Ah
+- Cell Voltages
+
+## Phase 6 — Vehicle Telemetry
+
+Status: Pending
+
+Features:
+- OBD-II
+- CAN Bus
+- RPM
+- Coolant Temperature
+- Fuel Level
+
+## Phase 7 — Integrations
+
+Status: Future
+
+Features:
+- MQTT
+- Home Assistant
+- Grafana
+- InfluxDB

docs/sensors.md

@@ -0,0 +1,61 @@
+# Sensor Architecture
+
+## Current Sensors
+
+### Fridge Zone 1
+
+Purpose:
+Refrigerator or freezer monitoring.
+
+Alarm:
+User configurable.
+
+### Fridge Zone 2
+
+Purpose:
+Refrigerator or freezer monitoring.
+
+Alarm:
+User configurable.
+
+### Rear Seat Area
+
+Purpose:
+Monitor child seating area.
+
+Alarms:
+- Warning Threshold
+- Critical Threshold
+
+### Outside Air
+
+Purpose:
+Ambient outside temperature.
+
+## Future Sensors
+
+### Battery Bay
+
+Purpose:
+Battery compartment monitoring.
+
+### Cabin Air
+
+Purpose:
+Cabin temperature monitoring.
+
+### Water Tank
+
+Purpose:
+Water freeze protection.
+
+### Cooler
+
+Purpose:
+Secondary food storage monitoring.
+
+## Sensor Bus
+
+DS18B20 OneWire
+
+Single bus shared across all sensors.

docs/wiring.md

@@ -0,0 +1,63 @@
+# Wiring Overview
+
+## House Battery Power Distribution
+
+House Battery Positive
+├── 5A Fuse → ESP32 Controller
+├── 3A Fuse → 12V→5V Buck Converter
+├── 30A Fuse → Fridge Relay
+└── 30A Fuse → Starlink Relay
+
+House Battery Negative
+├── ESP32 Ground
+├── Buck Converter Ground
+├── Relay Grounds
+└── Sensor Grounds
+
+## Dashboard Power
+
+12V House Battery
+↓
+Buck Converter (5V)
+↓
+CAT5 Cable
+↓
+Pico Dashboard
+
+## Communications
+
+Pico
+↓
+RS-485
+↓
+ESP32
+
+Backup:
+WiFi
+
+## Relay Control
+
+ESP32 Relay Output
+↓
+Bosch Relay Coil
+
+Bosch Relay Contacts
+↓
+Fridge / Starlink / Future Loads
+
+No high-current loads pass through the ESP32 relay board.
+
+## Temperature Sensors
+
+Single DS18B20 Bus
+
+Sensors:
+- Fridge Zone 1
+- Fridge Zone 2
+- Rear Seat Area
+- Outside Air
+
+Future:
+- Battery Compartment
+- Cabin Air
+- Water Tank

hardware/bom.md

@@ -0,0 +1,26 @@
+# Hardware BOM
+
+## Ordered
+
+- Raspberry Pi Pico 2 W
+- ESP32 2-Channel Relay Board
+- 3.5" SPI Capacitive Touchscreen
+
+## Required
+
+- 2x MAX3485 RS-485 Modules
+- 4x DS18B20 Waterproof Sensors
+- 12V→5V Buck Converter
+- CAT5 Cable
+- Bosch Relay Sockets
+- 30A/40A Bosch Relays
+- Automotive Fuse Block
+- Assorted ATC Fuses
+
+## Future
+
+- Pi Zero 2 W
+- GPS Module
+- ELM327 OBD-II Interface
+- CAN Interface
+- Additional DS18B20 Sensors

hardware/cat5-pinout.md

@@ -0,0 +1,23 @@
+# CAT5 Pinout
+
+Pair 1
+Blue        +5V
+Blue/White  +5V
+
+Pair 2
+Orange      Ground
+Orange/White Ground
+
+Pair 3
+Green       RS-485 A
+Green/White RS-485 B
+
+Pair 4
+Brown       Ignition Sense
+Brown/White Spare
+
+Notes:
+
+- Use twisted pair for RS-485
+- Double conductors for power
+- Spare conductor reserved for future use

hardware/esp32-pinout.md

@@ -0,0 +1,18 @@
+# ESP32 Pinout (Planned)
+
+GPIO 16  Relay 1 (Starlink)
+GPIO 17  Relay 2 (Fridge)
+
+GPIO 4   DS18B20 Bus
+
+GPIO 21  RS-485 TX
+GPIO 22  RS-485 RX
+GPIO 23  RS-485 DE/RE
+
+GPIO 34  Ignition Sense
+
+Future:
+- Additional Relays
+- Additional Sensor Inputs
+
+Final assignments pending exact relay board verification.

hardware/pico-pinout.md

@@ -0,0 +1,17 @@
+# Pico Pinout (Planned)
+
+Display:
+- SPI Touchscreen
+
+Communications:
+- RS-485 Interface
+
+Inputs:
+- Touchscreen
+
+Future:
+- Physical Wake Button
+- Rotary Encoder
+- Status LED
+
+Final pin assignments pending touchscreen testing.