diff --git a/README.md b/README.md index dcdc407..b7bcde2 100644 --- a/README.md +++ b/README.md @@ -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 -* 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 + Nissan Xterra -⸻ +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 -* Temperature sensors -* Auxiliary relays -* Vehicle telemetry -* Overland accessories -* Future automation systems +The ESP32 controller currently provides: -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 -* Cloud independent -* Vehicle independent -* Easy to troubleshoot -* Easy to expand +## Current Hardware -⸻ +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 -* DS18B20 temperature monitoring -* Relay control -* Configuration management -* Local web API -* WiFi Access Point -* Dashboard communications -* System status reporting +- Pi Zero 2 W for advanced logging/charts/web app -⸻ +## 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 -* Relay control -* Battery monitoring display -* Temperature monitoring display -* Vehicle status display -* Configuration interface -* Alarm notifications +Access through STA mode: -⸻ + http:// -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 -* Voltage -* Current -* Remaining capacity -* Total capacity -* Runtime estimates -* Temperature -* Cycle count -* Cell voltages -* Cell imbalance -* Cell count +The Pico dashboard will be an instant-on physical display and control surface. -⸻ +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 -* User-configurable names -* Online/offline detection -* Sensor health reporting -* JSON API reporting +This project controls vehicle electrical loads. -⸻ +Use: -Relay Control +- Proper fusing +- Proper wire gauge +- Proper terminals/ferrules +- Common ground +- Strain relief +- Testing before connecting expensive loads -Features: - -* 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. +Do not connect vehicle 12V directly to ESP32 or Pico GPIO pins. diff --git a/docs/API.md b/docs/API.md index e320fd8..8b3437f 100644 --- a/docs/API.md +++ b/docs/API.md @@ -593,3 +593,46 @@ Alternative request: { "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 + } diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index e23d54b..66f670f 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -1,208 +1,44 @@ -# CHANGELOG.md - # Changelog -All notable changes to Overland Controller will be documented in this file. - -The format loosely follows Keep a Changelog principles. - ---- - -# [0.3.0] - 2026-06-04 - -## Major Changes - -### Project Renaming - -- Renamed project from Xterra Controller to Overland Controller -- Updated firmware naming -- Updated repository naming -- Updated documentation naming -- Began removal of vehicle-specific assumptions - -### Generic Configuration Architecture - -Removed hardcoded installation-specific values from firmware. - -Firmware now uses generic identifiers: - -Relays: - -text id="4xvc8l" relay_1 relay_2 - -Temperature sensors: - -text id="xq2e8v" temp_1 temp_2 temp_3 temp_4 temp_5 temp_6 temp_7 temp_8 - -Installation-specific names now belong in saved configuration. - -### JSON Status API Improvements - -Reworked status response format. - -Changed from: - -json id="k8l5yx" { "temps": { "outside": 72.0 } } - -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. +## 0.4.0 - 2026-06-04 + +### Added + +- Embedded tabbed WebUI. +- Overview, Battery, and Config tabs. +- Estimated runtime display. +- Battery detail page with BMS status, cell voltages, cell delta, capacity, remaining Ah, cycles, and battery temperature. +- WebUI setup workflow. +- Device name configuration from WebUI. +- Relay name configuration from WebUI. +- Temperature sensor name and enabled-count configuration from WebUI. +- Temperature probe scan and assignment workflow from WebUI. +- BMS enable/disable controls from WebUI. +- BMS reconnect action from WebUI/API. +- System restart action from WebUI/API. +- WiFi AP + STA mode. +- Multiple saved STA WiFi networks. +- WiFi priority and runtime reconnect behavior. +- HTTP/UART/USB serial command parity documentation. +- DS18B20 configurable temperature probe support. +- Preferred relay command endpoint: `POST /relay/set`. + +### Changed + +- ESP32 remains the controller/source of truth. +- WebUI is now the preferred initial configuration workflow. +- Pico dashboard remains planned as the instant-on physical dashboard. +- 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. + +### Fixed + +- Restored default NimBLE connection behavior after custom timeout caused BMS connection failures. +- Trimmed WiFi credentials from setup inputs. +- Improved WebUI organization by moving setup/configuration controls to the Config tab. + +### Known Notes + +- BMS connection can still temporarily block the ESP32 while attempting BLE connection if the BMS is out of range. +- 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. diff --git a/docs/project-state.md b/docs/project-state.md index 8503748..1e91353 100644 --- a/docs/project-state.md +++ b/docs/project-state.md @@ -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. diff --git a/docs/roadmap.md b/docs/roadmap.md index a0fe845..3bbb5b2 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -404,3 +404,36 @@ Goals: - Make support easier for future users 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. diff --git a/docs/wiring.md b/docs/wiring.md index fa2d66b..d568613 100644 --- a/docs/wiring.md +++ b/docs/wiring.md @@ -547,3 +547,48 @@ Suggested fuse allocation: Spare optional 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 diff --git a/firmware/esp32/overland-controller/system_status.h b/firmware/esp32/overland-controller/system_status.h index 5ad04dc..7256fe4 100644 --- a/firmware/esp32/overland-controller/system_status.h +++ b/firmware/esp32/overland-controller/system_status.h @@ -1,4 +1,4 @@ #pragma once -#define FIRMWARE_VERSION "0.3.0" +#define FIRMWARE_VERSION "0.4.0" #define FIRMWARE_NAME "overland-controller"