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
|
Overland Controller is a distributed vehicle monitoring and control system.
|
||||||
- ESP32 cargo-area controller
|
|
||||||
- 3.5 inch 320x480 SPI capacitive touchscreen
|
|
||||||
- DS18B20 temperature sensors
|
|
||||||
- UART over CAT5 communication
|
|
||||||
- WiFi HTTP backup interface
|
|
||||||
|
|
||||||
--------------------------------------------------
|
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
|
Provide monitoring and control of overland vehicle systems from a dashboard interface.
|
||||||
- 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
|
## Hardware Status
|
||||||
|
|
||||||
Dashboard Module (Pico)
|
### Purchased
|
||||||
|
|
||||||
Responsibilities:
|
ESP32 2-channel relay board
|
||||||
|
|
||||||
- Touchscreen UI
|
Status:
|
||||||
- Audible alarms
|
Operational
|
||||||
- Dashboard display
|
|
||||||
- User interaction
|
|
||||||
- Sends commands to ESP32
|
|
||||||
- Receives status updates
|
|
||||||
|
|
||||||
Cargo Controller (ESP32)
|
Functions:
|
||||||
|
|
||||||
Responsibilities:
|
|
||||||
|
|
||||||
- Relay control
|
- Relay control
|
||||||
- Sensor collection
|
- WiFi access point
|
||||||
- Configuration storage
|
- BLE BMS communication
|
||||||
- Future battery monitoring
|
- HTTP API
|
||||||
- HTTP backup API
|
- UART interface
|
||||||
- UART communications
|
|
||||||
|
|
||||||
--------------------------------------------------
|
---
|
||||||
|
|
||||||
## 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
|
Configuration persistence
|
||||||
Blue/White +5V
|
|
||||||
|
|
||||||
Pair 2
|
Factory reset
|
||||||
|
|
||||||
Orange Ground
|
BLE BMS connection
|
||||||
Orange/White Ground
|
|
||||||
|
|
||||||
Pair 3
|
JBD/Xiaoxiang battery monitoring
|
||||||
|
|
||||||
Green Pico TX -> ESP32 RX
|
Status API
|
||||||
Green/White Pico RX <- ESP32 TX
|
|
||||||
|
|
||||||
Pair 4
|
Config API
|
||||||
|
|
||||||
Brown Ignition Sense
|
UART status responses
|
||||||
Brown/White Spare
|
|
||||||
|
|
||||||
--------------------------------------------------
|
BMS discovery mode
|
||||||
|
|
||||||
## Power Plan
|
BLE device selection
|
||||||
|
|
||||||
House Battery
|
Generic relay configuration
|
||||||
|
|
||||||
- Powers ESP32 directly through fused 12V
|
Generic temperature configuration
|
||||||
- Powers 12V to 5V buck converter
|
|
||||||
- Buck converter powers Pico through CAT5
|
|
||||||
|
|
||||||
Important:
|
Generic BMS configuration
|
||||||
|
|
||||||
- ESP32 relay board never carries fridge load current
|
Device naming
|
||||||
- ESP32 relay board never carries Starlink load current
|
|
||||||
- ESP32 relay outputs only trigger Bosch relays
|
|
||||||
- High current circuits are separately fused
|
|
||||||
|
|
||||||
--------------------------------------------------
|
---
|
||||||
|
|
||||||
## Temperature Sensors
|
### In Progress
|
||||||
|
|
||||||
Current Sensors
|
UART command parity with HTTP
|
||||||
|
|
||||||
- Fridge Zone 1
|
Generic configuration endpoints
|
||||||
- Fridge Zone 2
|
|
||||||
- Rear Seat Area
|
|
||||||
- Outside Air
|
|
||||||
|
|
||||||
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
|
- Voltage
|
||||||
- Current
|
- Current
|
||||||
- Remaining Ah
|
- Remaining capacity
|
||||||
- Runtime Estimate
|
- Temperature
|
||||||
- Battery Temperature
|
- Cycle count
|
||||||
- Cell Voltages
|
- Cell voltages
|
||||||
- Cell Imbalance
|
- Cell delta
|
||||||
|
|
||||||
--------------------------------------------------
|
---
|
||||||
|
|
||||||
## Relay Outputs
|
### Planned
|
||||||
|
|
||||||
Current
|
DS18B20 sensors
|
||||||
|
|
||||||
- Starlink
|
Vehicle ignition
|
||||||
- Fridge
|
|
||||||
|
|
||||||
Future
|
OBD-II
|
||||||
|
|
||||||
- Inverter
|
GPS
|
||||||
- Camp Lights
|
|
||||||
|
|
||||||
Known GPIO Assignments
|
Starlink diagnostics
|
||||||
|
|
||||||
GPIO16 = Relay Output 1
|
Inverter monitoring
|
||||||
GPIO17 = Relay Output 2
|
|
||||||
|
|
||||||
Relay ON = HIGH
|
---
|
||||||
Relay OFF = LOW
|
|
||||||
|
|
||||||
--------------------------------------------------
|
## Communication Architecture
|
||||||
|
|
||||||
## Dashboard Screens
|
### Primary
|
||||||
|
|
||||||
Implemented in Simulator
|
UART
|
||||||
|
|
||||||
- Dashboard
|
Pico <-> ESP32
|
||||||
- Battery
|
|
||||||
- Temps
|
|
||||||
- Power
|
|
||||||
- System
|
|
||||||
- Config
|
|
||||||
|
|
||||||
Dashboard Screen
|
Purpose:
|
||||||
|
|
||||||
- Battery Percentage
|
- Dashboard status
|
||||||
- Runtime Remaining
|
- Relay control
|
||||||
- Fridge Zone 1 Temperature
|
- Configuration
|
||||||
- Fridge Zone 2 Temperature
|
|
||||||
- Rear Seat Temperature
|
|
||||||
- Outside Air Temperature
|
|
||||||
- Relay Status
|
|
||||||
|
|
||||||
--------------------------------------------------
|
---
|
||||||
|
|
||||||
## Alarm System
|
### Secondary
|
||||||
|
|
||||||
Implemented in Simulator
|
HTTP API
|
||||||
|
|
||||||
- Warning alarms
|
Purpose:
|
||||||
- Critical alarms
|
|
||||||
- Full screen alarm overlay
|
|
||||||
- Acknowledge required
|
|
||||||
- Sensor fault alarms
|
|
||||||
- Configurable thresholds
|
|
||||||
|
|
||||||
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
|
overland-controller
|
||||||
- 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
|
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
|
Relay IDs remain generic:
|
||||||
- Sensor framework
|
|
||||||
- DS18B20 support
|
|
||||||
- HTTP status endpoint
|
|
||||||
- WiFi AP mode
|
|
||||||
- GPIO16 relay
|
|
||||||
- GPIO17 relay
|
|
||||||
|
|
||||||
Next ESP32 Tasks
|
relay_1
|
||||||
|
relay_2
|
||||||
|
|
||||||
- Verify relay hardware
|
Temperature IDs remain generic:
|
||||||
- Verify DS18B20 hardware
|
|
||||||
- Implement UART communications
|
|
||||||
|
|
||||||
--------------------------------------------------
|
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/
|
2. Add DS18B20 support
|
||||||
firmware/pico/touch_test/
|
|
||||||
firmware/pico/dashboard/
|
|
||||||
|
|
||||||
Goals
|
3. Build Pico simulator integration
|
||||||
|
|
||||||
1. Verify ST7796S display
|
4. Bring up Pico touchscreen
|
||||||
2. Verify FT6336U touch controller
|
|
||||||
3. Select graphics library
|
|
||||||
4. Build dashboard UI
|
|
||||||
5. Implement UART communications
|
|
||||||
|
|
||||||
--------------------------------------------------
|
5. Implement dashboard UI
|
||||||
|
|
||||||
## Important Decisions
|
6. Add vehicle ignition monitoring
|
||||||
|
|
||||||
- Touchscreen-only interface
|
7. Add OBD-II support
|
||||||
- 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
|
|
||||||
|
|
||||||
--------------------------------------------------
|
8. Add logging and history
|
||||||
|
|
||||||
## Repository
|
9. Add Home Assistant integration
|
||||||
|
|
||||||
Repository is the source of truth.
|
10. Prepare first vehicle installation
|
||||||
|
|
||||||
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.
|
|
||||||
|
|||||||
Reference in New Issue
Block a user