399 lines
5.7 KiB
Markdown
399 lines
5.7 KiB
Markdown
# Project State
|
|
|
|
Last Updated: June 2026
|
|
|
|
## Project Name
|
|
|
|
Overland Controller
|
|
|
|
## Current Status
|
|
|
|
Phase 1 is functional.
|
|
|
|
The ESP32 controller can:
|
|
|
|
- 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 Owned
|
|
|
|
### ESP32 Controller
|
|
|
|
Owned and operational.
|
|
|
|
Current hardware:
|
|
|
|
- ESP32 relay board
|
|
- 2 relay outputs
|
|
|
|
### 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.
|
|
|
|
---
|
|
|
|
## BMS Status
|
|
|
|
Working.
|
|
|
|
Current battery:
|
|
|
|
- JBD / Xiaoxiang BLE BMS
|
|
|
|
Current telemetry:
|
|
|
|
- SOC
|
|
- Voltage
|
|
- Current
|
|
- Remaining Ah
|
|
- Capacity
|
|
- Temperature
|
|
- Cycle count
|
|
- Cell voltages
|
|
- Cell delta
|
|
|
|
Configuration is stored in persistent settings.
|
|
|
|
---
|
|
|
|
## Relay Status
|
|
|
|
Working.
|
|
|
|
Current relay outputs:
|
|
|
|
relay_1
|
|
relay_2
|
|
|
|
Current installation-specific names:
|
|
|
|
Starlink
|
|
Fridge
|
|
|
|
These names are configuration only.
|
|
|
|
No relay names are intended to be hardcoded.
|
|
|
|
---
|
|
|
|
## Temperature Sensor Status
|
|
|
|
Partially complete.
|
|
|
|
Framework exists.
|
|
|
|
Current status:
|
|
|
|
- Configuration exists
|
|
- Status reporting exists
|
|
- Naming exists
|
|
|
|
Not yet completed:
|
|
|
|
- Physical DS18B20 integration
|
|
- Sensor discovery workflow
|
|
- Sensor assignment workflow
|
|
|
|
Planned support:
|
|
|
|
Up to 8 DS18B20 sensors.
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
---
|
|
|
|
## Current Direction Update
|
|
|
|
The project direction is now:
|
|
|
|
ESP32:
|
|
|
|
Controller
|
|
Source of truth
|
|
BMS telemetry
|
|
Temperature sensors
|
|
Relay control
|
|
Configuration storage
|
|
HTTP API
|
|
Lightweight embedded web dashboard
|
|
WiFi AP recovery network
|
|
|
|
Pico 2 W:
|
|
|
|
Instant-on physical dashboard
|
|
UART client
|
|
Touchscreen UI
|
|
Local control surface
|
|
|
|
Optional future Pi Zero 2 W:
|
|
|
|
Advanced web app
|
|
Historical logging
|
|
Graphs
|
|
MQTT/Home Assistant bridge
|
|
Advanced integrations
|
|
|
|
The base system should remain ESP32 + Pico.
|
|
|
|
A Pi Zero may be added later as an optional expansion module, not a required component.
|
|
|
|
---
|
|
|
|
## Networking Direction
|
|
|
|
Current:
|
|
|
|
ESP32 AP mode
|
|
http://192.168.4.1
|
|
|
|
Planned:
|
|
|
|
ESP32 AP + STA mode
|
|
|
|
Expected future behavior:
|
|
|
|
AP always remains enabled
|
|
ESP32 attempts to join configured WiFi networks
|
|
Multiple saved networks are tried in priority order
|
|
|
|
Example network priority:
|
|
|
|
1. Starlink
|
|
2. Home WiFi
|
|
3. Shop WiFi
|
|
|
|
This allows:
|
|
|
|
- Direct connection when camping without Starlink
|
|
- Phone access over Starlink at camp
|
|
- Phone/laptop access over home WiFi in the driveway
|
|
- Recovery access even when STA setup fails
|
|
|
|
---
|
|
|
|
## Recent Design Decisions
|
|
|
|
The onboard ESP32 relays may be acceptable for low-current loads such as:
|
|
|
|
Starlink Mini
|
|
12V fridge
|
|
small accessories
|
|
|
|
Reason:
|
|
|
|
- Starlink Mini current draw is modest
|
|
- Typical 12V fridge current is modest
|
|
- Smaller enclosure is a priority
|
|
|
|
External automotive relays remain recommended for higher-current loads or future expansion.
|
|
|
|
The current enclosure concept includes:
|
|
|
|
- ESP32 relay board
|
|
- Small fuse block
|
|
- Ground bus
|
|
- CAT6 keystone
|
|
- CAT5/CAT6 run to dash
|
|
- 12V feed to dash
|
|
- Buck converter in dash enclosure
|
|
|
|
The dash power plan is:
|
|
|
|
Rear fused 12V
|
|
-> CAT5/CAT6 blue pair
|
|
-> dash buck converter
|
|
-> Pico VSYS
|