Bump version to 0.4.0 and update documentation
This commit is contained in:
@@ -1,260 +1,102 @@
|
|||||||
Overland Controller
|
# Overland Controller
|
||||||
|
|
||||||
A modular ESP32 and Raspberry Pi Pico based monitoring and control system for overland vehicles, campers, trailers, van builds, and mobile power systems.
|
Overland Controller is a local-first vehicle power and monitoring system designed for overland, camping, and off-grid vehicle use.
|
||||||
|
|
||||||
The project uses a distributed architecture consisting of:
|
Current target vehicle:
|
||||||
|
|
||||||
* An ESP32 controller mounted near the battery and electrical system
|
Nissan Xterra
|
||||||
* A Raspberry Pi Pico 2 W dashboard mounted in the vehicle cabin
|
|
||||||
* Local WiFi communication
|
|
||||||
* Offline-first operation
|
|
||||||
* Expandable sensor and relay support
|
|
||||||
* Open JSON APIs for future integrations
|
|
||||||
|
|
||||||
⸻
|
The firmware itself is intended to stay vehicle-agnostic.
|
||||||
|
|
||||||
Project Goals
|
## Current Version
|
||||||
|
|
||||||
The goal of Overland Controller is to provide a self-hosted alternative to commercial vehicle monitoring systems.
|
0.4.0
|
||||||
|
|
||||||
The platform is designed to monitor and control:
|
## What It Does
|
||||||
|
|
||||||
* House battery systems
|
The ESP32 controller currently provides:
|
||||||
* Temperature sensors
|
|
||||||
* Auxiliary relays
|
|
||||||
* Vehicle telemetry
|
|
||||||
* Overland accessories
|
|
||||||
* Future automation systems
|
|
||||||
|
|
||||||
The system should be:
|
- Local WebUI
|
||||||
|
- HTTP API
|
||||||
|
- UART JSON protocol
|
||||||
|
- USB serial maintenance commands
|
||||||
|
- Relay control
|
||||||
|
- JBD/Xiaoxiang BLE BMS telemetry
|
||||||
|
- DS18B20 temperature sensor support
|
||||||
|
- Persistent configuration
|
||||||
|
- WiFi AP mode
|
||||||
|
- WiFi STA mode
|
||||||
|
- Multiple saved WiFi networks with priority
|
||||||
|
|
||||||
* Local-first
|
## Current Hardware
|
||||||
* Cloud independent
|
|
||||||
* Vehicle independent
|
|
||||||
* Easy to troubleshoot
|
|
||||||
* Easy to expand
|
|
||||||
|
|
||||||
⸻
|
Current controller:
|
||||||
|
|
||||||
Current Architecture
|
- ESP32 2-relay board
|
||||||
|
|
||||||
ESP32 Controller
|
Planned dashboard:
|
||||||
|
|
||||||
The ESP32 acts as the primary control and monitoring node.
|
- Raspberry Pi Pico 2 W
|
||||||
|
- Touchscreen display
|
||||||
|
- UART connection to ESP32
|
||||||
|
|
||||||
Current responsibilities:
|
Optional future expansion:
|
||||||
|
|
||||||
* JBD/Xiaoxiang BMS monitoring
|
- Pi Zero 2 W for advanced logging/charts/web app
|
||||||
* DS18B20 temperature monitoring
|
|
||||||
* Relay control
|
|
||||||
* Configuration management
|
|
||||||
* Local web API
|
|
||||||
* WiFi Access Point
|
|
||||||
* Dashboard communications
|
|
||||||
* System status reporting
|
|
||||||
|
|
||||||
⸻
|
## WebUI
|
||||||
|
|
||||||
Raspberry Pi Pico Dashboard
|
The embedded WebUI is served directly from the ESP32.
|
||||||
|
|
||||||
The Pico dashboard acts as the user interface.
|
Access through AP mode:
|
||||||
|
|
||||||
Planned responsibilities:
|
http://192.168.4.1
|
||||||
|
|
||||||
* Touchscreen dashboard
|
Access through STA mode:
|
||||||
* Relay control
|
|
||||||
* Battery monitoring display
|
|
||||||
* Temperature monitoring display
|
|
||||||
* Vehicle status display
|
|
||||||
* Configuration interface
|
|
||||||
* Alarm notifications
|
|
||||||
|
|
||||||
⸻
|
http://<controller-ip>
|
||||||
|
|
||||||
Current Features
|
The WebUI includes:
|
||||||
|
|
||||||
Battery Monitoring
|
- Overview tab
|
||||||
|
- Battery tab
|
||||||
|
- Config tab
|
||||||
|
|
||||||
Supported:
|
The Config tab is the preferred initial setup workflow.
|
||||||
|
|
||||||
* JBD / Xiaoxiang Bluetooth BMS
|
## Core Concepts
|
||||||
|
|
||||||
Available telemetry:
|
The ESP32 is the source of truth.
|
||||||
|
|
||||||
* State of charge
|
The Pico dashboard will be an instant-on physical display and control surface.
|
||||||
* Voltage
|
|
||||||
* Current
|
|
||||||
* Remaining capacity
|
|
||||||
* Total capacity
|
|
||||||
* Runtime estimates
|
|
||||||
* Temperature
|
|
||||||
* Cycle count
|
|
||||||
* Cell voltages
|
|
||||||
* Cell imbalance
|
|
||||||
* Cell count
|
|
||||||
|
|
||||||
⸻
|
The WebUI is used for setup, configuration, and phone access from camp.
|
||||||
|
|
||||||
Temperature Monitoring
|
## Documentation
|
||||||
|
|
||||||
Supported:
|
Important docs:
|
||||||
|
|
||||||
* DS18B20 OneWire temperature sensors
|
- `docs/project-state.md`
|
||||||
|
- `docs/api.md`
|
||||||
|
- `docs/UART_PROTOCOL.md`
|
||||||
|
- `docs/SERIAL_COMMANDS.md`
|
||||||
|
- `docs/PARITY_MATRIX.md`
|
||||||
|
- `docs/wiring.md`
|
||||||
|
- `docs/TEMP_SETUP.md`
|
||||||
|
- `docs/roadmap.md`
|
||||||
|
- `docs/CHANGELOG.md`
|
||||||
|
|
||||||
Features:
|
## Safety
|
||||||
|
|
||||||
* Up to 8 sensors
|
This project controls vehicle electrical loads.
|
||||||
* User-configurable names
|
|
||||||
* Online/offline detection
|
|
||||||
* Sensor health reporting
|
|
||||||
* JSON API reporting
|
|
||||||
|
|
||||||
⸻
|
Use:
|
||||||
|
|
||||||
Relay Control
|
- Proper fusing
|
||||||
|
- Proper wire gauge
|
||||||
|
- Proper terminals/ferrules
|
||||||
|
- Common ground
|
||||||
|
- Strain relief
|
||||||
|
- Testing before connecting expensive loads
|
||||||
|
|
||||||
Features:
|
Do not connect vehicle 12V directly to ESP32 or Pico GPIO pins.
|
||||||
|
|
||||||
* Multiple relay outputs
|
|
||||||
* User-configurable names
|
|
||||||
* API control
|
|
||||||
* Serial console control
|
|
||||||
* Dashboard control (planned)
|
|
||||||
|
|
||||||
Recommended usage:
|
|
||||||
|
|
||||||
* Fridge power relays
|
|
||||||
* Starlink power relays
|
|
||||||
* Lighting relays
|
|
||||||
* Inverter enable relays
|
|
||||||
* Accessory relays
|
|
||||||
|
|
||||||
The ESP32 relay outputs are intended to drive automotive relays rather than directly power large loads.
|
|
||||||
|
|
||||||
⸻
|
|
||||||
|
|
||||||
Configuration System
|
|
||||||
|
|
||||||
Configuration is stored locally and survives reboot.
|
|
||||||
|
|
||||||
Configurable items include:
|
|
||||||
|
|
||||||
Device
|
|
||||||
|
|
||||||
* Device name
|
|
||||||
|
|
||||||
Relays
|
|
||||||
|
|
||||||
* Relay name
|
|
||||||
* GPIO assignment
|
|
||||||
* Enabled state
|
|
||||||
|
|
||||||
Temperature Sensors
|
|
||||||
|
|
||||||
* Sensor name
|
|
||||||
* Sensor address
|
|
||||||
* Enabled state
|
|
||||||
|
|
||||||
BMS
|
|
||||||
|
|
||||||
* BMS name
|
|
||||||
* Bluetooth address
|
|
||||||
* Address type
|
|
||||||
|
|
||||||
⸻
|
|
||||||
|
|
||||||
Communication Interfaces
|
|
||||||
|
|
||||||
Serial Console
|
|
||||||
|
|
||||||
Used for:
|
|
||||||
|
|
||||||
* Initial setup
|
|
||||||
* Troubleshooting
|
|
||||||
* Configuration changes
|
|
||||||
* BLE discovery
|
|
||||||
* Diagnostic logging
|
|
||||||
|
|
||||||
See SERIAL_COMMANDS.md for details.
|
|
||||||
|
|
||||||
⸻
|
|
||||||
|
|
||||||
HTTP API
|
|
||||||
|
|
||||||
Provides:
|
|
||||||
|
|
||||||
* Status reporting
|
|
||||||
* Configuration management
|
|
||||||
* Relay control
|
|
||||||
* Dashboard integration
|
|
||||||
|
|
||||||
See API.md for details.
|
|
||||||
|
|
||||||
⸻
|
|
||||||
|
|
||||||
Current Development Status
|
|
||||||
|
|
||||||
Completed
|
|
||||||
|
|
||||||
* Configuration storage
|
|
||||||
* Relay control
|
|
||||||
* JSON status API
|
|
||||||
* BLE BMS integration
|
|
||||||
* BMS setup workflow
|
|
||||||
* DS18B20 framework
|
|
||||||
* Access Point mode
|
|
||||||
* Web server
|
|
||||||
* Dashboard communications framework
|
|
||||||
* Generic naming architecture
|
|
||||||
|
|
||||||
In Progress
|
|
||||||
|
|
||||||
* Dashboard software
|
|
||||||
* Temperature sensor assignment workflow
|
|
||||||
* Expanded configuration API
|
|
||||||
* Documentation cleanup
|
|
||||||
|
|
||||||
Planned
|
|
||||||
|
|
||||||
* Pico touchscreen dashboard
|
|
||||||
* OBD-II integration
|
|
||||||
* GPS integration
|
|
||||||
* MQTT support
|
|
||||||
* Home Assistant integration
|
|
||||||
* Historical data logging
|
|
||||||
* Graphing
|
|
||||||
* Alerting system
|
|
||||||
* OTA updates
|
|
||||||
* Multi-controller support
|
|
||||||
|
|
||||||
⸻
|
|
||||||
|
|
||||||
Design Philosophy
|
|
||||||
|
|
||||||
The project follows several core principles:
|
|
||||||
|
|
||||||
1. Local-first operation
|
|
||||||
2. No cloud dependency
|
|
||||||
3. Generic hardware naming
|
|
||||||
4. Open interfaces
|
|
||||||
5. Modular architecture
|
|
||||||
6. Expandable hardware support
|
|
||||||
7. Easy field troubleshooting
|
|
||||||
8. Vehicle-independent deployment
|
|
||||||
|
|
||||||
⸻
|
|
||||||
|
|
||||||
Documentation
|
|
||||||
|
|
||||||
* README.md — Project overview
|
|
||||||
* API.md — HTTP API documentation
|
|
||||||
* SERIAL_COMMANDS.md — Serial console commands
|
|
||||||
* HARDWARE.md — Hardware overview
|
|
||||||
* ARCHITECTURE.md — System architecture
|
|
||||||
* CHANGELOG.md — Project history
|
|
||||||
|
|
||||||
⸻
|
|
||||||
|
|
||||||
License
|
|
||||||
|
|
||||||
Private project currently under active development.
|
|
||||||
|
|||||||
+43
@@ -593,3 +593,46 @@ Alternative request:
|
|||||||
{
|
{
|
||||||
"slot": 1
|
"slot": 1
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Version 0.4.0 Notes
|
||||||
|
|
||||||
|
The WebUI Config tab now exposes the preferred setup workflow.
|
||||||
|
|
||||||
|
Important endpoints used by the WebUI:
|
||||||
|
|
||||||
|
GET /status
|
||||||
|
GET /config
|
||||||
|
|
||||||
|
POST /config/device
|
||||||
|
POST /config/relay
|
||||||
|
POST /config/temp
|
||||||
|
POST /config/bms
|
||||||
|
POST /config/save
|
||||||
|
POST /config/factory-reset
|
||||||
|
|
||||||
|
POST /relay/set
|
||||||
|
|
||||||
|
POST /temps/scan
|
||||||
|
POST /temps/assign
|
||||||
|
POST /temps/clear
|
||||||
|
|
||||||
|
POST /config/wifi
|
||||||
|
POST /wifi/connect
|
||||||
|
POST /wifi/clear
|
||||||
|
|
||||||
|
POST /bms/reconnect
|
||||||
|
POST /system/restart
|
||||||
|
|
||||||
|
The preferred relay command endpoint remains:
|
||||||
|
|
||||||
|
POST /relay/set
|
||||||
|
|
||||||
|
Request:
|
||||||
|
|
||||||
|
{
|
||||||
|
"id": "relay_1",
|
||||||
|
"state": true
|
||||||
|
}
|
||||||
|
|||||||
+42
-206
@@ -1,208 +1,44 @@
|
|||||||
# CHANGELOG.md
|
|
||||||
|
|
||||||
# Changelog
|
# Changelog
|
||||||
|
|
||||||
All notable changes to Overland Controller will be documented in this file.
|
## 0.4.0 - 2026-06-04
|
||||||
|
|
||||||
The format loosely follows Keep a Changelog principles.
|
### Added
|
||||||
|
|
||||||
---
|
- Embedded tabbed WebUI.
|
||||||
|
- Overview, Battery, and Config tabs.
|
||||||
# [0.3.0] - 2026-06-04
|
- Estimated runtime display.
|
||||||
|
- Battery detail page with BMS status, cell voltages, cell delta, capacity, remaining Ah, cycles, and battery temperature.
|
||||||
## Major Changes
|
- WebUI setup workflow.
|
||||||
|
- Device name configuration from WebUI.
|
||||||
### Project Renaming
|
- Relay name configuration from WebUI.
|
||||||
|
- Temperature sensor name and enabled-count configuration from WebUI.
|
||||||
- Renamed project from Xterra Controller to Overland Controller
|
- Temperature probe scan and assignment workflow from WebUI.
|
||||||
- Updated firmware naming
|
- BMS enable/disable controls from WebUI.
|
||||||
- Updated repository naming
|
- BMS reconnect action from WebUI/API.
|
||||||
- Updated documentation naming
|
- System restart action from WebUI/API.
|
||||||
- Began removal of vehicle-specific assumptions
|
- WiFi AP + STA mode.
|
||||||
|
- Multiple saved STA WiFi networks.
|
||||||
### Generic Configuration Architecture
|
- WiFi priority and runtime reconnect behavior.
|
||||||
|
- HTTP/UART/USB serial command parity documentation.
|
||||||
Removed hardcoded installation-specific values from firmware.
|
- DS18B20 configurable temperature probe support.
|
||||||
|
- Preferred relay command endpoint: `POST /relay/set`.
|
||||||
Firmware now uses generic identifiers:
|
|
||||||
|
### Changed
|
||||||
Relays:
|
|
||||||
|
- ESP32 remains the controller/source of truth.
|
||||||
text id="4xvc8l" relay_1 relay_2
|
- WebUI is now the preferred initial configuration workflow.
|
||||||
|
- Pico dashboard remains planned as the instant-on physical dashboard.
|
||||||
Temperature sensors:
|
- Built-in ESP32 relays are the current planned relay switching method for Starlink Mini and fridge.
|
||||||
|
- BMS source now reports configured JBD BMS even when disconnected.
|
||||||
text id="xq2e8v" temp_1 temp_2 temp_3 temp_4 temp_5 temp_6 temp_7 temp_8
|
|
||||||
|
### Fixed
|
||||||
Installation-specific names now belong in saved configuration.
|
|
||||||
|
- Restored default NimBLE connection behavior after custom timeout caused BMS connection failures.
|
||||||
### JSON Status API Improvements
|
- Trimmed WiFi credentials from setup inputs.
|
||||||
|
- Improved WebUI organization by moving setup/configuration controls to the Config tab.
|
||||||
Reworked status response format.
|
|
||||||
|
### Known Notes
|
||||||
Changed from:
|
|
||||||
|
- BMS connection can still temporarily block the ESP32 while attempting BLE connection if the BMS is out of range.
|
||||||
json id="k8l5yx" { "temps": { "outside": 72.0 } }
|
- WebUI BMS disable/enable controls are intended to make bench testing easier.
|
||||||
|
- DS18B20 multi-probe final install should use a proper terminal/distribution board rather than temporary Wago wiring.
|
||||||
To:
|
|
||||||
|
|
||||||
json id="k3g0ey" { "temps": [ { "id": "temp_1", "name": "Outside", "temperature_f": 72.0 } ] }
|
|
||||||
|
|
||||||
Benefits:
|
|
||||||
|
|
||||||
- Dynamic sensor support
|
|
||||||
- Generic architecture
|
|
||||||
- Easier dashboard integration
|
|
||||||
- Better future scalability
|
|
||||||
|
|
||||||
### Relay Status Improvements
|
|
||||||
|
|
||||||
Relay reporting converted to structured arrays.
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
json id="wh1f5k" { "id": "relay_1", "name": "Aux Power", "state": false }
|
|
||||||
|
|
||||||
### BMS Integration
|
|
||||||
|
|
||||||
Implemented:
|
|
||||||
|
|
||||||
- JBD BLE communication
|
|
||||||
- Xiaoxiang compatibility
|
|
||||||
- Cell voltage reporting
|
|
||||||
- SOC reporting
|
|
||||||
- Current reporting
|
|
||||||
- Capacity reporting
|
|
||||||
- Temperature reporting
|
|
||||||
- Cycle count reporting
|
|
||||||
|
|
||||||
### BLE Setup Workflow
|
|
||||||
|
|
||||||
Added:
|
|
||||||
|
|
||||||
- Setup mode
|
|
||||||
- BLE device scanning
|
|
||||||
- BMS selection
|
|
||||||
- Persistent BMS storage
|
|
||||||
|
|
||||||
Known limitation:
|
|
||||||
|
|
||||||
- Some BMS devices advertise infrequently and may require multiple scans before appearing.
|
|
||||||
|
|
||||||
### Documentation
|
|
||||||
|
|
||||||
Added:
|
|
||||||
|
|
||||||
- README.md
|
|
||||||
- API.md
|
|
||||||
- SERIAL_COMMANDS.md
|
|
||||||
- HARDWARE.md
|
|
||||||
- ARCHITECTURE.md
|
|
||||||
- CHANGELOG.md
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# [0.2.x]
|
|
||||||
|
|
||||||
## Initial Controller Development
|
|
||||||
|
|
||||||
Implemented:
|
|
||||||
|
|
||||||
- ESP32 firmware framework
|
|
||||||
- Relay control
|
|
||||||
- Configuration storage
|
|
||||||
- Access Point mode
|
|
||||||
- Web server
|
|
||||||
- UART communications
|
|
||||||
- JSON status reporting
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# [0.1.x]
|
|
||||||
|
|
||||||
## Project Foundation
|
|
||||||
|
|
||||||
Initial proof-of-concept work.
|
|
||||||
|
|
||||||
Implemented:
|
|
||||||
|
|
||||||
- Repository structure
|
|
||||||
- ESP32 firmware skeleton
|
|
||||||
- Basic relay testing
|
|
||||||
- Initial dashboard communications concept
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# Upcoming
|
|
||||||
|
|
||||||
## Planned for 0.4.x
|
|
||||||
|
|
||||||
### Dashboard Development
|
|
||||||
|
|
||||||
- Pico 2 W integration
|
|
||||||
- Dashboard communications
|
|
||||||
- Touchscreen support
|
|
||||||
- Relay control interface
|
|
||||||
|
|
||||||
### Temperature System
|
|
||||||
|
|
||||||
- Sensor assignment workflow
|
|
||||||
- Sensor discovery workflow
|
|
||||||
- Improved diagnostics
|
|
||||||
|
|
||||||
### Configuration System
|
|
||||||
|
|
||||||
- Expanded configuration API
|
|
||||||
- Additional runtime configuration
|
|
||||||
- Improved validation
|
|
||||||
|
|
||||||
### Documentation
|
|
||||||
|
|
||||||
- Installation guide
|
|
||||||
- Wiring guide
|
|
||||||
- Development guide
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Planned for 0.5.x
|
|
||||||
|
|
||||||
### Vehicle Integration
|
|
||||||
|
|
||||||
Potential support for:
|
|
||||||
|
|
||||||
- OBD-II
|
|
||||||
- ELM327
|
|
||||||
- CAN Bus
|
|
||||||
|
|
||||||
### Data Logging
|
|
||||||
|
|
||||||
Potential support for:
|
|
||||||
|
|
||||||
- Historical battery data
|
|
||||||
- Historical temperature data
|
|
||||||
- Event logging
|
|
||||||
|
|
||||||
### Integrations
|
|
||||||
|
|
||||||
Potential support for:
|
|
||||||
|
|
||||||
- MQTT
|
|
||||||
- Home Assistant
|
|
||||||
- Grafana
|
|
||||||
- InfluxDB
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Long-Term Roadmap
|
|
||||||
|
|
||||||
Potential future capabilities:
|
|
||||||
|
|
||||||
- GPS support
|
|
||||||
- Route logging
|
|
||||||
- Multi-controller support
|
|
||||||
- OTA updates
|
|
||||||
- Alerting system
|
|
||||||
- Mobile-friendly dashboard
|
|
||||||
- Remote monitoring
|
|
||||||
|
|
||||||
The roadmap is intentionally flexible and may change as the project evolves.
|
|
||||||
|
|||||||
+111
-345
@@ -1,398 +1,164 @@
|
|||||||
# Project State
|
# 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
|
Core controller:
|
||||||
- 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.
|
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
|
The ESP32 is the source of truth for:
|
||||||
- 2 relay outputs
|
|
||||||
|
|
||||||
### 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
|
- Battery SOC
|
||||||
|
|
||||||
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
|
- Voltage
|
||||||
- Current
|
- Current
|
||||||
|
- Estimated runtime
|
||||||
|
- Temperature sensors
|
||||||
|
- Relay controls
|
||||||
|
- Network status
|
||||||
|
- Alarm summary
|
||||||
|
|
||||||
|
### Battery
|
||||||
|
|
||||||
|
Shows:
|
||||||
|
|
||||||
|
- BMS online/offline
|
||||||
|
- Source
|
||||||
- Remaining Ah
|
- Remaining Ah
|
||||||
- Capacity
|
- Capacity Ah
|
||||||
- Temperature
|
- Battery temperature
|
||||||
- Cycle count
|
- Cycle count
|
||||||
- Cell voltages
|
- Cell count
|
||||||
- Cell delta
|
- Cell delta
|
||||||
|
- Individual cell voltages
|
||||||
|
- BMS enable/disable controls
|
||||||
|
|
||||||
Configuration is stored in persistent settings.
|
### Config
|
||||||
|
|
||||||
---
|
Supports:
|
||||||
|
|
||||||
## Relay Status
|
- Device name editing
|
||||||
|
- BMS name/address/address type editing
|
||||||
Working.
|
- BMS reconnect
|
||||||
|
- Temperature probe scan
|
||||||
Current relay outputs:
|
- Temperature probe assignment
|
||||||
|
- Relay renaming
|
||||||
relay_1
|
- Temperature sensor enabled count
|
||||||
relay_2
|
- Temperature sensor renaming
|
||||||
|
- WiFi network configuration
|
||||||
Current installation-specific names:
|
- Restart
|
||||||
|
|
||||||
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
|
- 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
|
External automotive relays remain a future option for higher-current loads.
|
||||||
- Dashboard communications
|
|
||||||
- Basic command support
|
|
||||||
|
|
||||||
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.
|
## Network Direction
|
||||||
|
|
||||||
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:
|
Current:
|
||||||
|
|
||||||
ESP32 AP mode
|
- AP always available
|
||||||
http://192.168.4.1
|
- 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
|
1. Verify WebUI setup workflow after fresh flash.
|
||||||
ESP32 attempts to join configured WiFi networks
|
2. Clean up DS18B20 physical distribution hardware.
|
||||||
Multiple saved networks are tried in priority order
|
3. Test 2-4 temperature probes after distribution board is installed.
|
||||||
|
4. Start Pico dashboard MVP over UART.
|
||||||
Example network priority:
|
5. Add config backup/restore.
|
||||||
|
6. Improve BMS out-of-range behavior without changing NimBLE connect timeout.
|
||||||
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
|
|
||||||
|
|||||||
@@ -404,3 +404,36 @@ Goals:
|
|||||||
- Make support easier for future users
|
- Make support easier for future users
|
||||||
|
|
||||||
This is important if the project becomes shareable or sellable.
|
This is important if the project becomes shareable or sellable.
|
||||||
|
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Post-0.4.0 Roadmap
|
||||||
|
|
||||||
|
### Near Term
|
||||||
|
|
||||||
|
- Verify complete WebUI setup workflow.
|
||||||
|
- Add config backup/export/import.
|
||||||
|
- Improve BMS out-of-range behavior without reducing NimBLE connection reliability.
|
||||||
|
- Build permanent DS18B20 distribution board.
|
||||||
|
- Test multiple temperature probes.
|
||||||
|
- Update enclosure wiring layout.
|
||||||
|
|
||||||
|
### Pico Dashboard MVP
|
||||||
|
|
||||||
|
- UART status request.
|
||||||
|
- Battery summary screen.
|
||||||
|
- Temperature screen.
|
||||||
|
- Relay control screen.
|
||||||
|
- Alarm indicators.
|
||||||
|
- Screen sleep based on ignition signal later.
|
||||||
|
|
||||||
|
### Future
|
||||||
|
|
||||||
|
- mDNS hostname.
|
||||||
|
- OTA update workflow.
|
||||||
|
- Optional Pi Zero logging module.
|
||||||
|
- Historical graphs.
|
||||||
|
- MQTT/Home Assistant bridge.
|
||||||
|
- Ignition sense.
|
||||||
|
- House battery voltage sense.
|
||||||
|
|||||||
@@ -547,3 +547,48 @@ Suggested fuse allocation:
|
|||||||
Spare optional
|
Spare optional
|
||||||
|
|
||||||
External automotive relays remain a good upgrade path for higher-current loads.
|
External automotive relays remain a good upgrade path for higher-current loads.
|
||||||
|
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Current Relay Switching Decision
|
||||||
|
|
||||||
|
For the current Starlink Mini and fridge use case, the built-in ESP32 relay board relays are the planned switching method.
|
||||||
|
|
||||||
|
Use positive-side switching:
|
||||||
|
|
||||||
|
Battery +
|
||||||
|
|
|
||||||
|
Fuse
|
||||||
|
|
|
||||||
|
Relay COM
|
||||||
|
|
|
||||||
|
Relay NO
|
||||||
|
|
|
||||||
|
Load +
|
||||||
|
|
||||||
|
Load -
|
||||||
|
|
|
||||||
|
Ground bus
|
||||||
|
|
||||||
|
External automotive relays are reserved for future higher-current loads.
|
||||||
|
|
||||||
|
## DS18B20 Final Install Direction
|
||||||
|
|
||||||
|
Temporary Wago wiring proved one probe, but final install should use a proper terminal/distribution board.
|
||||||
|
|
||||||
|
Recommended:
|
||||||
|
|
||||||
|
3.3V bus
|
||||||
|
DATA bus
|
||||||
|
GND bus
|
||||||
|
|
||||||
|
With:
|
||||||
|
|
||||||
|
4.7k resistor between DATA and 3.3V
|
||||||
|
|
||||||
|
Only three wires need to return to the ESP32:
|
||||||
|
|
||||||
|
3.3V
|
||||||
|
GPIO4
|
||||||
|
GND
|
||||||
|
|||||||
@@ -1,4 +1,4 @@
|
|||||||
#pragma once
|
#pragma once
|
||||||
|
|
||||||
#define FIRMWARE_VERSION "0.3.0"
|
#define FIRMWARE_VERSION "0.4.0"
|
||||||
#define FIRMWARE_NAME "overland-controller"
|
#define FIRMWARE_NAME "overland-controller"
|
||||||
|
|||||||
Reference in New Issue
Block a user