Update project state documentation
This commit is contained in:
+183
-227
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user