Update project state documentation
This commit is contained in:
+237
-240
@@ -2,296 +2,293 @@
|
|||||||
|
|
||||||
Last Updated: June 2026
|
Last Updated: June 2026
|
||||||
|
|
||||||
## Project Overview
|
## Project Name
|
||||||
|
|
||||||
Overland Controller is a distributed vehicle monitoring and control system.
|
Overland Controller
|
||||||
|
|
||||||
Current architecture:
|
## Current Status
|
||||||
|
|
||||||
- ESP32 controller in cargo area
|
Phase 1 is functional.
|
||||||
- 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
|
|
||||||
|
|
||||||
Primary goal:
|
The ESP32 controller can:
|
||||||
|
|
||||||
Provide monitoring and control of overland vehicle systems from a dashboard interface.
|
- Host a local WiFi access point
|
||||||
|
- Serve a web interface
|
||||||
|
- Expose an HTTP API
|
||||||
|
- Read JBD/Xiaoxiang BLE BMS data
|
||||||
|
- Persist configuration
|
||||||
|
- Factory reset configuration
|
||||||
|
- Control relay outputs
|
||||||
|
- Report relay status
|
||||||
|
- Report BMS status
|
||||||
|
- Report temperature sensor status
|
||||||
|
- Communicate over UART
|
||||||
|
- Support BLE setup mode for BMS discovery
|
||||||
|
|
||||||
|
The Pico dashboard hardware has not yet been brought online.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Hardware Status
|
## Hardware Owned
|
||||||
|
|
||||||
### Purchased
|
### ESP32 Controller
|
||||||
|
|
||||||
ESP32 2-channel relay board
|
Owned and operational.
|
||||||
|
|
||||||
Status:
|
Current hardware:
|
||||||
Operational
|
|
||||||
|
|
||||||
Functions:
|
- ESP32 relay board
|
||||||
|
- 2 relay outputs
|
||||||
|
|
||||||
- Relay control
|
### Dashboard
|
||||||
- WiFi access point
|
|
||||||
- BLE BMS communication
|
Owned but not yet integrated.
|
||||||
- HTTP API
|
|
||||||
- UART interface
|
Current hardware:
|
||||||
|
|
||||||
|
- Raspberry Pi Pico 2 W
|
||||||
|
|
||||||
|
Potential display:
|
||||||
|
|
||||||
|
- 3.5" touchscreen expansion board
|
||||||
|
|
||||||
|
### Vehicle
|
||||||
|
|
||||||
|
Current target vehicle:
|
||||||
|
|
||||||
|
- Nissan Xterra
|
||||||
|
|
||||||
|
The firmware itself should remain vehicle-agnostic.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
Raspberry Pi Pico 2 W
|
## BMS Status
|
||||||
|
|
||||||
Status:
|
Working.
|
||||||
Purchased
|
|
||||||
|
|
||||||
Planned functions:
|
Current battery:
|
||||||
|
|
||||||
- Dashboard UI
|
- JBD / Xiaoxiang BLE BMS
|
||||||
- Touchscreen interface
|
|
||||||
- UART communication with ESP32
|
|
||||||
|
|
||||||
---
|
Current telemetry:
|
||||||
|
|
||||||
### Planned Hardware
|
|
||||||
|
|
||||||
3.5" touchscreen for Pico
|
|
||||||
|
|
||||||
DS18B20 temperature sensors
|
|
||||||
|
|
||||||
Automotive relays
|
|
||||||
|
|
||||||
Future OBD-II interface
|
|
||||||
|
|
||||||
Future GPS interface
|
|
||||||
|
|
||||||
Future inverter monitoring
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ESP32 Status
|
|
||||||
|
|
||||||
### Working
|
|
||||||
|
|
||||||
Relay control
|
|
||||||
|
|
||||||
Configuration persistence
|
|
||||||
|
|
||||||
Factory reset
|
|
||||||
|
|
||||||
BLE BMS connection
|
|
||||||
|
|
||||||
JBD/Xiaoxiang battery monitoring
|
|
||||||
|
|
||||||
Status API
|
|
||||||
|
|
||||||
Config API
|
|
||||||
|
|
||||||
UART status responses
|
|
||||||
|
|
||||||
BMS discovery mode
|
|
||||||
|
|
||||||
BLE device selection
|
|
||||||
|
|
||||||
Generic relay configuration
|
|
||||||
|
|
||||||
Generic temperature configuration
|
|
||||||
|
|
||||||
Generic BMS configuration
|
|
||||||
|
|
||||||
Device naming
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### In Progress
|
|
||||||
|
|
||||||
UART command parity with HTTP
|
|
||||||
|
|
||||||
Generic configuration endpoints
|
|
||||||
|
|
||||||
Documentation cleanup
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### Not Started
|
|
||||||
|
|
||||||
DS18B20 integration
|
|
||||||
|
|
||||||
Vehicle ignition sensing
|
|
||||||
|
|
||||||
OBD-II integration
|
|
||||||
|
|
||||||
GPS integration
|
|
||||||
|
|
||||||
Data logging
|
|
||||||
|
|
||||||
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
|
- SOC
|
||||||
- Voltage
|
- Voltage
|
||||||
- Current
|
- Current
|
||||||
- Remaining capacity
|
- Remaining Ah
|
||||||
|
- Capacity
|
||||||
- Temperature
|
- Temperature
|
||||||
- Cycle count
|
- Cycle count
|
||||||
- Cell voltages
|
- Cell voltages
|
||||||
- Cell delta
|
- Cell delta
|
||||||
|
|
||||||
---
|
Configuration is stored in persistent settings.
|
||||||
|
|
||||||
### Planned
|
|
||||||
|
|
||||||
DS18B20 sensors
|
|
||||||
|
|
||||||
Vehicle ignition
|
|
||||||
|
|
||||||
OBD-II
|
|
||||||
|
|
||||||
GPS
|
|
||||||
|
|
||||||
Starlink diagnostics
|
|
||||||
|
|
||||||
Inverter monitoring
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Communication Architecture
|
## Relay Status
|
||||||
|
|
||||||
### Primary
|
Working.
|
||||||
|
|
||||||
UART
|
Current relay outputs:
|
||||||
|
|
||||||
Pico <-> ESP32
|
|
||||||
|
|
||||||
Purpose:
|
|
||||||
|
|
||||||
- Dashboard status
|
|
||||||
- Relay control
|
|
||||||
- Configuration
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### Secondary
|
|
||||||
|
|
||||||
HTTP API
|
|
||||||
|
|
||||||
Purpose:
|
|
||||||
|
|
||||||
- Setup
|
|
||||||
- Debugging
|
|
||||||
- Testing
|
|
||||||
- Future web UI
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### Service Interface
|
|
||||||
|
|
||||||
USB Serial
|
|
||||||
|
|
||||||
Purpose:
|
|
||||||
|
|
||||||
- Recovery
|
|
||||||
- Debugging
|
|
||||||
- Development
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Current Firmware Version
|
|
||||||
|
|
||||||
Firmware:
|
|
||||||
|
|
||||||
overland-controller
|
|
||||||
|
|
||||||
Version:
|
|
||||||
|
|
||||||
0.3.0
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Major Architectural Decisions
|
|
||||||
|
|
||||||
Configuration is stored on ESP32.
|
|
||||||
|
|
||||||
Names are configuration, not firmware.
|
|
||||||
|
|
||||||
UART is the primary dashboard interface.
|
|
||||||
|
|
||||||
HTTP mirrors UART functionality where practical.
|
|
||||||
|
|
||||||
Relay IDs remain generic:
|
|
||||||
|
|
||||||
relay_1
|
relay_1
|
||||||
relay_2
|
relay_2
|
||||||
|
|
||||||
Temperature IDs remain generic:
|
Current installation-specific names:
|
||||||
|
|
||||||
temp_1 through temp_8
|
Starlink
|
||||||
|
Fridge
|
||||||
|
|
||||||
Installation-specific naming is handled entirely through configuration.
|
These names are configuration only.
|
||||||
|
|
||||||
|
No relay names are intended to be hardcoded.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Next Recommended Milestones
|
## Temperature Sensor Status
|
||||||
|
|
||||||
1. Finish UART protocol implementation
|
Partially complete.
|
||||||
|
|
||||||
2. Add DS18B20 support
|
Framework exists.
|
||||||
|
|
||||||
3. Build Pico simulator integration
|
Current status:
|
||||||
|
|
||||||
4. Bring up Pico touchscreen
|
- Configuration exists
|
||||||
|
- Status reporting exists
|
||||||
|
- Naming exists
|
||||||
|
|
||||||
5. Implement dashboard UI
|
Not yet completed:
|
||||||
|
|
||||||
6. Add vehicle ignition monitoring
|
- Physical DS18B20 integration
|
||||||
|
- Sensor discovery workflow
|
||||||
|
- Sensor assignment workflow
|
||||||
|
|
||||||
7. Add OBD-II support
|
Planned support:
|
||||||
|
|
||||||
8. Add logging and history
|
Up to 8 DS18B20 sensors.
|
||||||
|
|
||||||
9. Add Home Assistant integration
|
---
|
||||||
|
|
||||||
10. Prepare first vehicle installation
|
## Configuration Status
|
||||||
|
|
||||||
|
Persistent configuration works.
|
||||||
|
|
||||||
|
Stored settings include:
|
||||||
|
|
||||||
|
- Device name
|
||||||
|
- Relay names
|
||||||
|
- Relay enabled state
|
||||||
|
- Temperature sensor names
|
||||||
|
- Temperature sensor enabled state
|
||||||
|
- BMS name
|
||||||
|
- BMS address
|
||||||
|
- BMS address type
|
||||||
|
|
||||||
|
Factory reset is functional.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## HTTP API Status
|
||||||
|
|
||||||
|
Working.
|
||||||
|
|
||||||
|
Implemented:
|
||||||
|
|
||||||
|
- Status endpoint
|
||||||
|
- Config endpoint
|
||||||
|
- Relay control
|
||||||
|
- Configuration updates
|
||||||
|
- Save configuration
|
||||||
|
- Factory reset
|
||||||
|
|
||||||
|
Documentation:
|
||||||
|
|
||||||
|
See:
|
||||||
|
|
||||||
|
docs/api.md
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## UART Status
|
||||||
|
|
||||||
|
Partially complete.
|
||||||
|
|
||||||
|
Current UART capabilities:
|
||||||
|
|
||||||
|
- Status requests
|
||||||
|
- Dashboard communications
|
||||||
|
- Basic command support
|
||||||
|
|
||||||
|
Missing goal:
|
||||||
|
|
||||||
|
UART should eventually expose every operation available through HTTP and serial.
|
||||||
|
|
||||||
|
Target:
|
||||||
|
|
||||||
|
UART becomes the primary dashboard integration interface.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Simulator Status
|
||||||
|
|
||||||
|
Working.
|
||||||
|
|
||||||
|
Simulator provides:
|
||||||
|
|
||||||
|
- Fake ESP32 controller
|
||||||
|
- Fake Pico dashboard
|
||||||
|
- Test data generation
|
||||||
|
- Protocol validation
|
||||||
|
|
||||||
|
Useful for development before hardware is connected.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Documentation Status
|
||||||
|
|
||||||
|
Primary documents:
|
||||||
|
|
||||||
|
README.md
|
||||||
|
HARDWARE.md
|
||||||
|
|
||||||
|
docs/project-state.md
|
||||||
|
docs/architecture.md
|
||||||
|
docs/api.md
|
||||||
|
docs/protocol.md
|
||||||
|
docs/roadmap.md
|
||||||
|
docs/decisions.md
|
||||||
|
docs/SERIAL_COMMANDS.md
|
||||||
|
|
||||||
|
Older planning/design documents may be archived later.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Highest Priority Next Tasks
|
||||||
|
|
||||||
|
### Priority 1
|
||||||
|
|
||||||
|
UART parity.
|
||||||
|
|
||||||
|
Goal:
|
||||||
|
|
||||||
|
Anything possible through serial or HTTP should also be possible through UART.
|
||||||
|
|
||||||
|
Required additions:
|
||||||
|
|
||||||
|
- config_request
|
||||||
|
- config_device
|
||||||
|
- config_relay
|
||||||
|
- config_temp
|
||||||
|
- config_bms
|
||||||
|
- save_config
|
||||||
|
- factory_reset
|
||||||
|
- enter_bms_setup
|
||||||
|
- scan_ble
|
||||||
|
- select_bms
|
||||||
|
- exit_bms_setup
|
||||||
|
|
||||||
|
### Priority 2
|
||||||
|
|
||||||
|
DS18B20 support.
|
||||||
|
|
||||||
|
Needed:
|
||||||
|
|
||||||
|
- Scan sensors
|
||||||
|
- Assign sensors
|
||||||
|
- Save assignments
|
||||||
|
|
||||||
|
### Priority 3
|
||||||
|
|
||||||
|
Pico hardware bring-up.
|
||||||
|
|
||||||
|
Needed:
|
||||||
|
|
||||||
|
- UART communication
|
||||||
|
- Display status screen
|
||||||
|
- Relay control screen
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Long-Term Vision
|
||||||
|
|
||||||
|
A vehicle-agnostic overland monitoring and control platform.
|
||||||
|
|
||||||
|
Core principles:
|
||||||
|
|
||||||
|
- Local-first
|
||||||
|
- No cloud required
|
||||||
|
- Generic hardware model
|
||||||
|
- Generic API model
|
||||||
|
- Generic UART model
|
||||||
|
- Dashboard optional
|
||||||
|
- Vehicle independent
|
||||||
|
|
||||||
|
Target use cases:
|
||||||
|
|
||||||
|
- Overland vehicles
|
||||||
|
- Campers
|
||||||
|
- Trailers
|
||||||
|
- RV electrical systems
|
||||||
|
- Mobile command systems
|
||||||
|
- Off-grid battery monitoring
|
||||||
|
|||||||
Reference in New Issue
Block a user