Bump version to 0.4.0 and update documentation
This commit is contained in:
+111
-345
@@ -1,398 +1,164 @@
|
||||
# Project State
|
||||
|
||||
Last Updated: June 2026
|
||||
Last updated: 2026-06-04
|
||||
|
||||
## Project Name
|
||||
## Version
|
||||
|
||||
Overland Controller
|
||||
Current firmware version:
|
||||
|
||||
## Current Status
|
||||
0.4.0
|
||||
|
||||
Phase 1 is functional.
|
||||
## Current Architecture
|
||||
|
||||
The ESP32 controller can:
|
||||
The project is now an ESP32-based overland controller with a lightweight embedded WebUI.
|
||||
|
||||
- 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
|
||||
Core controller:
|
||||
|
||||
The Pico dashboard hardware has not yet been brought online.
|
||||
ESP32 relay board
|
||||
|
||||
---
|
||||
Current dashboard plan:
|
||||
|
||||
## Hardware Owned
|
||||
Raspberry Pi Pico 2 W physical dashboard over UART
|
||||
|
||||
### ESP32 Controller
|
||||
Optional future expansion:
|
||||
|
||||
Owned and operational.
|
||||
Pi Zero 2 W for advanced logging, charts, and integrations
|
||||
|
||||
Current hardware:
|
||||
## ESP32 Responsibilities
|
||||
|
||||
- ESP32 relay board
|
||||
- 2 relay outputs
|
||||
The ESP32 is the source of truth for:
|
||||
|
||||
### Dashboard
|
||||
- Relay control
|
||||
- JBD/Xiaoxiang BLE BMS telemetry
|
||||
- DS18B20 temperature sensors
|
||||
- Persistent configuration
|
||||
- HTTP API
|
||||
- Embedded WebUI
|
||||
- WiFi AP recovery network
|
||||
- WiFi STA client mode
|
||||
- UART protocol for future Pico dashboard
|
||||
|
||||
Owned but not yet integrated.
|
||||
## Current Working Features
|
||||
|
||||
Current hardware:
|
||||
- BMS live data from Greta/JBD BMS
|
||||
- Relay control
|
||||
- Embedded phone-friendly WebUI
|
||||
- AP mode at `192.168.4.1`
|
||||
- STA mode on saved WiFi networks
|
||||
- Multiple saved WiFi networks with priority
|
||||
- WiFi reconnect/failover behavior
|
||||
- DS18B20 scan/assign/config workflow
|
||||
- One DS18B20 probe verified working
|
||||
- Generic relay IDs
|
||||
- Generic temperature IDs
|
||||
- Config-driven relay names
|
||||
- Config-driven temperature names
|
||||
- WebUI setup workflow
|
||||
- HTTP API
|
||||
- UART JSON protocol
|
||||
- USB serial maintenance commands
|
||||
|
||||
- Raspberry Pi Pico 2 W
|
||||
## WebUI Tabs
|
||||
|
||||
Potential display:
|
||||
### Overview
|
||||
|
||||
- 3.5" touchscreen expansion board
|
||||
Shows:
|
||||
|
||||
### 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
|
||||
- Battery SOC
|
||||
- Voltage
|
||||
- Current
|
||||
- Estimated runtime
|
||||
- Temperature sensors
|
||||
- Relay controls
|
||||
- Network status
|
||||
- Alarm summary
|
||||
|
||||
### Battery
|
||||
|
||||
Shows:
|
||||
|
||||
- BMS online/offline
|
||||
- Source
|
||||
- Remaining Ah
|
||||
- Capacity
|
||||
- Temperature
|
||||
- Capacity Ah
|
||||
- Battery temperature
|
||||
- Cycle count
|
||||
- Cell voltages
|
||||
- Cell count
|
||||
- Cell delta
|
||||
- Individual cell voltages
|
||||
- BMS enable/disable controls
|
||||
|
||||
Configuration is stored in persistent settings.
|
||||
### Config
|
||||
|
||||
---
|
||||
Supports:
|
||||
|
||||
## 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
|
||||
- Device name editing
|
||||
- BMS name/address/address type editing
|
||||
- BMS reconnect
|
||||
- Temperature probe scan
|
||||
- Temperature probe assignment
|
||||
- Relay renaming
|
||||
- Temperature sensor enabled count
|
||||
- Temperature sensor renaming
|
||||
- WiFi network configuration
|
||||
- Restart
|
||||
- Factory reset
|
||||
|
||||
Documentation:
|
||||
## Hardware Direction
|
||||
|
||||
See:
|
||||
Current rear enclosure target:
|
||||
|
||||
docs/api.md
|
||||
- ESP32 relay board
|
||||
- Compact fuse block
|
||||
- Ground bus
|
||||
- CAT6 keystone
|
||||
- DS18B20 terminal/distribution board
|
||||
- Built-in relay outputs for Starlink Mini and fridge
|
||||
|
||||
---
|
||||
Relay strategy:
|
||||
|
||||
## UART Status
|
||||
Battery positive -> fuse -> relay COM -> relay NO -> load positive
|
||||
Load negative -> ground bus
|
||||
|
||||
Partially complete.
|
||||
The built-in relays are currently planned for:
|
||||
|
||||
Current UART capabilities:
|
||||
- Starlink Mini
|
||||
- 12V fridge
|
||||
|
||||
- Status requests
|
||||
- Dashboard communications
|
||||
- Basic command support
|
||||
External automotive relays remain a future option for higher-current loads.
|
||||
|
||||
Missing goal:
|
||||
## Temperature Sensor Direction
|
||||
|
||||
UART should eventually expose every operation available through HTTP and serial.
|
||||
DS18B20 bus:
|
||||
|
||||
Target:
|
||||
ESP32 GPIO4 = data
|
||||
ESP32 3.3V = VCC
|
||||
ESP32 GND = ground
|
||||
|
||||
UART becomes the primary dashboard integration interface.
|
||||
Required:
|
||||
|
||||
---
|
||||
One 4.7k pull-up resistor between data and 3.3V
|
||||
|
||||
## Simulator Status
|
||||
Final install should use a terminal/distribution board.
|
||||
|
||||
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
|
||||
## Network Direction
|
||||
|
||||
Current:
|
||||
|
||||
ESP32 AP mode
|
||||
http://192.168.4.1
|
||||
- AP always available
|
||||
- STA attempts saved networks by priority
|
||||
- AP remains available even when STA is connected
|
||||
|
||||
Planned:
|
||||
Examples:
|
||||
|
||||
ESP32 AP + STA mode
|
||||
Priority 1: Starlink
|
||||
Priority 2: Home WiFi
|
||||
|
||||
Expected future behavior:
|
||||
## Next Recommended Work
|
||||
|
||||
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
|
||||
1. Verify WebUI setup workflow after fresh flash.
|
||||
2. Clean up DS18B20 physical distribution hardware.
|
||||
3. Test 2-4 temperature probes after distribution board is installed.
|
||||
4. Start Pico dashboard MVP over UART.
|
||||
5. Add config backup/restore.
|
||||
6. Improve BMS out-of-range behavior without changing NimBLE connect timeout.
|
||||
|
||||
Reference in New Issue
Block a user