diff --git a/docs/architecture.md b/docs/architecture.md index 870d9bd..96878ed 100644 --- a/docs/architecture.md +++ b/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 -* ESP32 cargo-area controller -* RS-485 wired communications -* WiFi backup communications -* Touchscreen dashboard interface +The system provides: -The system is designed to operate completely offline and continue functioning even when WiFi is disabled. - ---- - -## System Goals - -* 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 - ---- +- House battery monitoring +- Fridge monitoring +- Temperature monitoring +- Power control +- Alarm management +- Future vehicle telemetry ## Dashboard Module ### Hardware -* Raspberry Pi Pico 2 W -* 3.5" touchscreen -* Powered by 5V from cargo-area buck converter +- Raspberry Pi Pico 2 W +- 3.5" SPI Capacitive Touchscreen +- RS-485 communications +- WiFi backup communications ### Responsibilities -* Display information -* Accept touch input -* Send commands to controller -* Display alarms and warnings -* Provide user configuration interface +- Touchscreen user interface +- Local web dashboard +- Alarm display +- Configuration management +- Relay control interface +- Data visualization -### Communications - -Primary: - -* RS-485 over CAT5 - -Secondary: - -* WiFi HTTP API - ---- - -## Controller Module +## Cargo Module ### Hardware -* ESP32 relay board -* House battery connection -* Bosch-style automotive relays +- ESP32 Relay Controller +- RS-485 Interface +- House Battery Interface +- DS18B20 Temperature Sensor Bus +- Bosch Relay Drivers ### Responsibilities -* Read sensors -* Interface with BMS -* Control relays -* Serve API data -* Handle logging - ---- - -## 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. - ---- +- Sensor collection +- Relay control +- Alarm processing +- Communications server +- Configuration storage ## Communications -### Primary +Primary: +- RS-485 -RS-485 over CAT5 +Backup: +- WiFi HTTP API -Advantages: - -* Reliable -* Noise resistant -* Independent of WiFi -* 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: +- MQTT +- Home Assistant +- Grafana +- InfluxDB ## Future Expansion -### Vehicle Data - -* OBD-II -* CAN bus -* Fuel level -* RPM -* Coolant temperature -* Vehicle speed - -### Navigation - -* GPS -* Trip logging - -### Connectivity - -* MQTT -* Home Assistant -* InfluxDB -* Grafana - -### Additional Sensors - -* Additional DS18B20 sensors -* Voltage sensors -* Current sensors -* Environmental monitoring +- JBD/Xiaoxiang BLE Battery Monitoring +- OBD-II +- CAN Bus +- GPS +- Trip Logging +- Fuel Level +- Coolant Temperature +- RPM +- Starlink Diagnostics diff --git a/docs/communications.md b/docs/communications.md new file mode 100644 index 0000000..d19b8ab --- /dev/null +++ b/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 diff --git a/docs/dashboard-ui.md b/docs/dashboard-ui.md new file mode 100644 index 0000000..8be8187 --- /dev/null +++ b/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 diff --git a/docs/decisions.md b/docs/decisions.md new file mode 100644 index 0000000..e211ece --- /dev/null +++ b/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 diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000..b057170 --- /dev/null +++ b/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 diff --git a/docs/sensors.md b/docs/sensors.md new file mode 100644 index 0000000..7cbfbd1 --- /dev/null +++ b/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. diff --git a/docs/wiring.md b/docs/wiring.md index e69de29..cea93bb 100644 --- a/docs/wiring.md +++ b/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 diff --git a/hardware/bom.md b/hardware/bom.md index e69de29..ca54ea2 100644 --- a/hardware/bom.md +++ b/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 diff --git a/hardware/cat5-pinout.md b/hardware/cat5-pinout.md new file mode 100644 index 0000000..ea0c83e --- /dev/null +++ b/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 diff --git a/hardware/esp32-pinout.md b/hardware/esp32-pinout.md new file mode 100644 index 0000000..2fdc033 --- /dev/null +++ b/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. diff --git a/hardware/pico-pinout.md b/hardware/pico-pinout.md new file mode 100644 index 0000000..754b31d --- /dev/null +++ b/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.