5.7 KiB
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