Update project state documentation
This commit is contained in:
+237
-240
@@ -2,296 +2,293 @@
|
||||
|
||||
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
|
||||
- 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
|
||||
Phase 1 is functional.
|
||||
|
||||
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:
|
||||
Operational
|
||||
Current hardware:
|
||||
|
||||
Functions:
|
||||
- ESP32 relay board
|
||||
- 2 relay outputs
|
||||
|
||||
- Relay control
|
||||
- WiFi access point
|
||||
- BLE BMS communication
|
||||
- HTTP API
|
||||
- UART interface
|
||||
### Dashboard
|
||||
|
||||
Owned but not yet integrated.
|
||||
|
||||
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:
|
||||
Purchased
|
||||
Working.
|
||||
|
||||
Planned functions:
|
||||
Current battery:
|
||||
|
||||
- Dashboard UI
|
||||
- Touchscreen interface
|
||||
- UART communication with ESP32
|
||||
- JBD / Xiaoxiang BLE BMS
|
||||
|
||||
---
|
||||
|
||||
### 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:
|
||||
Current telemetry:
|
||||
|
||||
- SOC
|
||||
- Voltage
|
||||
- Current
|
||||
- Remaining capacity
|
||||
- Remaining Ah
|
||||
- Capacity
|
||||
- Temperature
|
||||
- Cycle count
|
||||
- Cell voltages
|
||||
- Cell delta
|
||||
|
||||
---
|
||||
|
||||
### Planned
|
||||
|
||||
DS18B20 sensors
|
||||
|
||||
Vehicle ignition
|
||||
|
||||
OBD-II
|
||||
|
||||
GPS
|
||||
|
||||
Starlink diagnostics
|
||||
|
||||
Inverter monitoring
|
||||
Configuration is stored in persistent settings.
|
||||
|
||||
---
|
||||
|
||||
## Communication Architecture
|
||||
## Relay Status
|
||||
|
||||
### Primary
|
||||
Working.
|
||||
|
||||
UART
|
||||
|
||||
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:
|
||||
Current relay outputs:
|
||||
|
||||
relay_1
|
||||
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