Align docs with ESP32-S3 dashboard architecture
This commit is contained in:
+8
-4
@@ -264,7 +264,7 @@ Design limits:
|
||||
- No large assets
|
||||
- No heavy JavaScript framework
|
||||
|
||||
The embedded dashboard is intended as a convenient phone view, not a replacement for the physical Pico dashboard.
|
||||
The embedded dashboard is intended as a convenient phone view and setup interface. It does not replace the planned Waveshare ESP32-S3 physical dashboard.
|
||||
|
||||
---
|
||||
|
||||
@@ -637,11 +637,15 @@ Request:
|
||||
{
|
||||
"id": "relay_1",
|
||||
"state": true
|
||||
}\n\n### Weather temperature sensor flag
|
||||
}
|
||||
|
||||
### Weather temperature sensor flag
|
||||
|
||||
Temperature sensor config entries now include `weather: true`.
|
||||
|
||||
When a configured temp sensor has `weather: true`, the WebUI may show it as the outside/weather temperature badge. The `/status` temp objects also include this flag so HTTP, UART, USB serial, and future Pico clients can identify the selected outside-air sensor without guessing from the sensor name.\n\n\n### Clear temperature assignments
|
||||
When a configured temp sensor has `weather: true`, the WebUI may show it as the outside/weather temperature badge. The `/status` temp objects also include this flag so HTTP, UART, USB serial, and dashboard clients can identify the selected outside-air sensor without guessing from the sensor name.
|
||||
|
||||
### Clear temperature assignments
|
||||
|
||||
`POST /temps/clear`
|
||||
|
||||
@@ -651,4 +655,4 @@ Request body options:
|
||||
- `{ "slot": 1 }` clears one logical temp slot by number.
|
||||
- Empty POST body clears all temp assignments.
|
||||
|
||||
Clearing removes the stored DS18B20 address, disables the slot, clears the weather flag, resets cached temperature state, and persists config.\n
|
||||
Clearing removes the stored DS18B20 address, disables the slot, clears the weather flag, resets cached temperature state, and persists config.
|
||||
|
||||
@@ -93,11 +93,9 @@ HTTP is the primary integration contract for:
|
||||
|
||||
Preferred direction:
|
||||
|
||||
GET /api/status
|
||||
GET /api/config
|
||||
POST /api/relays/relay_1/on
|
||||
POST /api/relays/relay_1/off
|
||||
POST /api/relays/relay_1/toggle
|
||||
GET /status
|
||||
GET /config
|
||||
POST /relay/set
|
||||
|
||||
Future versioning may move to /api/v1.
|
||||
|
||||
|
||||
+2
-2
@@ -27,8 +27,8 @@
|
||||
|
||||
- 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.
|
||||
- Waveshare ESP32-S3 is the primary physical dashboard target.
|
||||
- ESP32 relay board outputs are treated as control/trigger outputs for external fused automotive relays/contactors on major loads.
|
||||
- BMS source now reports configured JBD BMS even when disconnected.
|
||||
|
||||
### Fixed
|
||||
|
||||
@@ -9,7 +9,7 @@ Configuration survives reboot.
|
||||
- Keep firmware generic
|
||||
- Store installation-specific names in config
|
||||
- Support multiple vehicle/camper layouts
|
||||
- Allow setup from serial, HTTP, and eventually Pico UART
|
||||
- Allow setup from HTTP/WebUI and service interfaces
|
||||
- Avoid hardcoded device names, relay names, sensor names, or BMS names
|
||||
|
||||
## Stored Configuration
|
||||
|
||||
+15
-1
@@ -1,5 +1,17 @@
|
||||
# Overland Controller Handoff
|
||||
|
||||
This handoff is stale and may include legacy Pico/UART dashboard assumptions.
|
||||
|
||||
Current source of truth:
|
||||
|
||||
- `docs/ARCHITECTURE.md`
|
||||
- `docs/HARDWARE.md`
|
||||
- `docs/ROADMAP.md`
|
||||
- `docs/API.md`
|
||||
- `docs/dashboard-esp32s3.md`
|
||||
|
||||
The current dashboard target is the Waveshare ESP32-S3-Touch-LCD-5 over WiFi/HTTP. No Pico dashboard is planned.
|
||||
|
||||
## Current Version
|
||||
|
||||
Firmware: 0.4.0
|
||||
@@ -153,4 +165,6 @@ Important:
|
||||
|
||||
- ESP32 cargo controller remains source of truth.
|
||||
- Dashboard is a client only.
|
||||
- Existing UART protocol remains supported but is no longer the primary dashboard transport.\n\nSee docs/dashboard-esp32s3.md for the current Waveshare ESP32-S3 dashboard plan.\n
|
||||
- Existing UART protocol remains supported but is no longer the primary dashboard transport.
|
||||
|
||||
See `docs/dashboard-esp32s3.md` for the current Waveshare ESP32-S3 dashboard plan.
|
||||
|
||||
@@ -105,4 +105,6 @@ Future additions must be implemented on:
|
||||
UART JSON
|
||||
HTTP API
|
||||
|
||||
before parity is considered maintained.\n\n- Temperature sensor config/status parity now includes the `weather` boolean flag for outside-air display selection.\n
|
||||
before parity is considered maintained.
|
||||
|
||||
- Temperature sensor config/status parity now includes the `weather` boolean flag for outside-air display selection.
|
||||
|
||||
+3
-2
@@ -19,8 +19,9 @@ This folder contains project documentation for Overland Controller.
|
||||
|
||||
## Technical References
|
||||
|
||||
- `protocol.md` - Dashboard/controller protocol
|
||||
- `wiring.md` - Wiring notes and plans
|
||||
- `dashboard-esp32s3.md` - Current Waveshare ESP32-S3 dashboard plan
|
||||
- `protocol.md` - Legacy UART protocol reference
|
||||
- `wiring.md` - Older wiring notes; verify against `HARDWARE.md` before use
|
||||
|
||||
## Archive
|
||||
|
||||
|
||||
+27
-23
@@ -1,8 +1,10 @@
|
||||
# UART Protocol
|
||||
|
||||
The Pico dashboard communicates with the ESP32 controller over UART.
|
||||
This document describes the optional UART JSON protocol supported by the ESP32 controller.
|
||||
|
||||
UART is the primary dashboard/control link. HTTP should mirror the same concepts, but the Pico should be able to operate the controller without WiFi.
|
||||
UART is not the primary dashboard/control link. The current dashboard target is the Waveshare ESP32-S3 display over WiFi/HTTP.
|
||||
|
||||
Keep this protocol for diagnostics, simulator work, service tools, or alternate clients. Do not treat it as evidence that a Pico dashboard is planned.
|
||||
|
||||
## Serial Settings
|
||||
|
||||
@@ -41,7 +43,7 @@ Temperature sensors:
|
||||
|
||||
## Status Request
|
||||
|
||||
Pico sends:
|
||||
Client sends:
|
||||
|
||||
{"type":"status_request"}
|
||||
|
||||
@@ -49,7 +51,7 @@ ESP32 responds with the same shape as HTTP /status.
|
||||
|
||||
## Relay Control
|
||||
|
||||
Pico sends:
|
||||
Client sends:
|
||||
|
||||
{"type":"set_relay","relay":"relay_1","enabled":true}
|
||||
|
||||
@@ -59,7 +61,7 @@ ESP32 responds:
|
||||
|
||||
## Config Request
|
||||
|
||||
Pico sends:
|
||||
Client sends:
|
||||
|
||||
{"type":"config_request"}
|
||||
|
||||
@@ -69,37 +71,37 @@ ESP32 responds:
|
||||
|
||||
## Device Name Update
|
||||
|
||||
Pico sends:
|
||||
Client sends:
|
||||
|
||||
{"type":"config_device","device_name":"Overland Controller"}
|
||||
|
||||
## Relay Config Update
|
||||
|
||||
Pico sends:
|
||||
Client sends:
|
||||
|
||||
{"type":"config_relay","id":"relay_1","name":"Aux Power","enabled":true}
|
||||
|
||||
## Temperature Sensor Config Update
|
||||
|
||||
Pico sends:
|
||||
Client sends:
|
||||
|
||||
{"type":"config_temp","id":"temp_1","name":"Cabin","address":"","enabled":true}
|
||||
|
||||
## BMS Config Update
|
||||
|
||||
Pico sends:
|
||||
Client sends:
|
||||
|
||||
{"type":"config_bms","enabled":true,"name":"House Battery","address":"aa:bb:cc:dd:ee:ff","address_type":"public"}
|
||||
|
||||
## Save Config
|
||||
|
||||
Pico sends:
|
||||
Client sends:
|
||||
|
||||
{"type":"save_config"}
|
||||
|
||||
## Factory Reset
|
||||
|
||||
Pico sends:
|
||||
Client sends:
|
||||
|
||||
{"type":"factory_reset"}
|
||||
|
||||
@@ -156,14 +158,14 @@ The UART protocol should eventually support the same management capabilities as
|
||||
|
||||
## Notes
|
||||
|
||||
- UART is the preferred dashboard/control path.
|
||||
- HTTP is useful for setup, debugging, and future web UI.
|
||||
- HTTP is the preferred dashboard/control path.
|
||||
- UART is useful for diagnostics and alternate clients.
|
||||
- USB serial remains the emergency service/debug interface.
|
||||
- The Pico should not depend on WiFi for normal control.
|
||||
- No Pico dashboard is currently planned.
|
||||
|
||||
## WiFi Config Request
|
||||
|
||||
Pico sends:
|
||||
Client sends:
|
||||
|
||||
{"type":"wifi_request"}
|
||||
|
||||
@@ -173,19 +175,19 @@ ESP32 responds:
|
||||
|
||||
## WiFi Config Update
|
||||
|
||||
Pico sends:
|
||||
Client sends:
|
||||
|
||||
{"type":"config_wifi","ssid":"Starlink","password":"password_here"}
|
||||
|
||||
## WiFi Connect
|
||||
|
||||
Pico sends:
|
||||
Client sends:
|
||||
|
||||
{"type":"wifi_connect"}
|
||||
|
||||
## WiFi Clear
|
||||
|
||||
Pico sends:
|
||||
Client sends:
|
||||
|
||||
{"type":"wifi_clear"}
|
||||
|
||||
@@ -239,7 +241,7 @@ Lower priority numbers are tried first.
|
||||
|
||||
## Scan Temperature Sensors
|
||||
|
||||
Pico sends:
|
||||
Client sends:
|
||||
|
||||
{"type":"scan_temps"}
|
||||
|
||||
@@ -249,7 +251,7 @@ ESP32 responds:
|
||||
|
||||
## Assign Temperature Sensor
|
||||
|
||||
Pico sends:
|
||||
Client sends:
|
||||
|
||||
{"type":"assign_temp","id":"temp_1","index":1}
|
||||
|
||||
@@ -259,14 +261,16 @@ Alternative:
|
||||
|
||||
## Clear Temperature Sensor
|
||||
|
||||
Pico sends:
|
||||
Client sends:
|
||||
|
||||
{"type":"clear_temp","id":"temp_1"}
|
||||
|
||||
Alternative:
|
||||
|
||||
{"type":"clear_temp","slot":1}\n\n### Temperature weather flag
|
||||
{"type":"clear_temp","slot":1}
|
||||
|
||||
### Temperature weather flag
|
||||
|
||||
`status_response.config.temperature_sensors[]` and `status_response.temps[]` include `weather: false`.
|
||||
|
||||
`config_temp` may include `weather: true` to mark one configured sensor as the outside/weather sensor. Pico clients should treat this as optional and default missing values to `false`.\n
|
||||
`config_temp` may include `weather: true` to mark one configured sensor as the outside/weather sensor. Clients should treat this as optional and default missing values to `false`.
|
||||
|
||||
@@ -29,21 +29,18 @@ Primary transport:
|
||||
- HTTP JSON API
|
||||
|
||||
Not required for normal dashboard operation:
|
||||
- Pico UART
|
||||
- MicroPython display drivers
|
||||
- CAT5e UART data pair
|
||||
|
||||
UART JSON remains useful for future diagnostics, alternate displays, or debug clients.
|
||||
UART JSON remains useful for diagnostics, alternate displays, or debug clients, but it is not part of the planned dashboard path.
|
||||
|
||||
## Power
|
||||
|
||||
Dashboard power path:
|
||||
|
||||
Cargo area 12V
|
||||
→ CAT5e power pair(s)
|
||||
→ Dash enclosure
|
||||
→ Buck converter
|
||||
→ 5V dashboard input
|
||||
ACC switched 12V
|
||||
-> fuse
|
||||
-> Waveshare VIN
|
||||
|
||||
All grounds remain common.
|
||||
|
||||
@@ -149,8 +146,6 @@ Later:
|
||||
- WebUI Config tab remains the preferred setup workflow.
|
||||
- Cargo ESP32 should continue to work without the dashboard powered on.
|
||||
|
||||
## Deferred Pico Path
|
||||
## Out of Scope
|
||||
|
||||
The Pico 2 W dashboard plan is deferred.
|
||||
|
||||
Keep existing UART protocol docs because UART remains useful, but new dashboard work should target the ESP32-S3 display first.
|
||||
No Pico dashboard is planned. Existing Pico/UART material is legacy unless explicitly revived for diagnostics or alternate hardware.
|
||||
|
||||
+29
-12
@@ -20,38 +20,45 @@ Reason:
|
||||
|
||||
The ESP32 is installed near the electrical system and should continue operating even if the dashboard is disconnected.
|
||||
|
||||
## Decision: Pico Is a Dashboard, Not the Controller
|
||||
## Decision: Waveshare ESP32-S3 Is the Dashboard Client
|
||||
|
||||
The Pico dashboard is responsible for user interaction.
|
||||
The Waveshare ESP32-S3 touchscreen dashboard is responsible for local user interaction.
|
||||
|
||||
It should not own critical control state.
|
||||
It connects to the Cargo ESP32 access point and consumes the HTTP API. It should not own critical control state.
|
||||
|
||||
Reason:
|
||||
|
||||
The dashboard may reboot, disconnect, or be removed without disabling the controller.
|
||||
|
||||
## Decision: UART Is the Primary Dashboard Link
|
||||
## Decision: HTTP Is the Primary Dashboard Link
|
||||
|
||||
UART is the preferred Pico-to-ESP32 communication path.
|
||||
HTTP over the Cargo ESP32 local WiFi network is the preferred dashboard-to-controller communication path.
|
||||
|
||||
Reason:
|
||||
|
||||
- Simple wiring
|
||||
- Deterministic
|
||||
- No WiFi dependency
|
||||
- Works offline
|
||||
- Easier to debug electrically
|
||||
- Matches the WebUI and future integration contract
|
||||
- Avoids a dedicated dashboard data cable
|
||||
- Supports the Waveshare ESP32-S3 dashboard target
|
||||
- Keeps the dashboard a simple client
|
||||
|
||||
HTTP remains useful for setup, debugging, and future web UI.
|
||||
The Cargo ESP32 AP remains available for local operation without internet.
|
||||
|
||||
## Decision: UART Is Optional Diagnostics
|
||||
|
||||
UART JSON may remain useful for service diagnostics, simulator work, or alternate clients.
|
||||
|
||||
Reason:
|
||||
|
||||
USB serial and UART are useful recovery/debug paths, but the dashboard architecture should not depend on a Pico or UART cable.
|
||||
|
||||
## Decision: HTTP and UART Should Share a Data Model
|
||||
|
||||
The same status/config model should be used across:
|
||||
|
||||
- UART
|
||||
- HTTP
|
||||
- Simulator
|
||||
- Future MQTT/Home Assistant integrations
|
||||
- Optional UART diagnostics
|
||||
|
||||
Reason:
|
||||
|
||||
@@ -177,3 +184,13 @@ Cloud dashboards and remote access are not current priorities.
|
||||
Reason:
|
||||
|
||||
The core controller/dashboard system should be reliable locally before remote features are considered.
|
||||
|
||||
## Decision: Future Pi Zero Is Optional
|
||||
|
||||
A Pi Zero may be added later for long-term logging, charts, dashboards, or local integrations.
|
||||
|
||||
It must not own relay control, BMS state, alarm authority, or persistent controller configuration.
|
||||
|
||||
Reason:
|
||||
|
||||
The Cargo ESP32 must continue operating as the controller and source of truth without any higher-level computer powered on.
|
||||
|
||||
@@ -2,6 +2,10 @@
|
||||
|
||||
Last Updated: 2026-06-03
|
||||
|
||||
This document is stale and records earlier hardware ordering/status notes. Current hardware direction is documented in `docs/HARDWARE.md` and `docs/dashboard-esp32s3.md`.
|
||||
|
||||
The current dashboard target is the Waveshare ESP32-S3-Touch-LCD-5 over WiFi/HTTP. No Pico dashboard is planned.
|
||||
|
||||
--------------------------------------------------
|
||||
|
||||
## Dashboard Hardware
|
||||
|
||||
+18
-15
@@ -1,6 +1,6 @@
|
||||
# Project State
|
||||
|
||||
Last updated: 2026-06-04
|
||||
Last updated: 2026-06-07
|
||||
|
||||
## Version
|
||||
|
||||
@@ -18,11 +18,11 @@ Core controller:
|
||||
|
||||
Current dashboard plan:
|
||||
|
||||
Raspberry Pi Pico 2 W physical dashboard over UART
|
||||
Waveshare ESP32-S3-Touch-LCD-5 over WiFi/HTTP
|
||||
|
||||
Optional future expansion:
|
||||
|
||||
Pi Zero 2 W for advanced logging, charts, and integrations
|
||||
Pi Zero for long-term logging, charts, and local integrations
|
||||
|
||||
## ESP32 Responsibilities
|
||||
|
||||
@@ -36,7 +36,7 @@ The ESP32 is the source of truth for:
|
||||
- Embedded WebUI
|
||||
- WiFi AP recovery network
|
||||
- WiFi STA client mode
|
||||
- UART protocol for future Pico dashboard
|
||||
- Optional UART JSON protocol for diagnostics or alternate clients
|
||||
|
||||
## Current Working Features
|
||||
|
||||
@@ -117,15 +117,11 @@ Current rear enclosure target:
|
||||
|
||||
Relay strategy:
|
||||
|
||||
Battery positive -> fuse -> relay COM -> relay NO -> load positive
|
||||
Load negative -> ground bus
|
||||
ESP32 relay board output
|
||||
-> external fused automotive relay or contactor trigger
|
||||
-> fused load circuit
|
||||
|
||||
The built-in relays are currently planned for:
|
||||
|
||||
- Starlink Mini
|
||||
- 12V fridge
|
||||
|
||||
External automotive relays remain a future option for higher-current loads.
|
||||
The ESP32 relay board outputs are control/trigger outputs only. Fridge, Starlink, inverter, and other major loads must use properly fused automotive relay or contactor circuits.
|
||||
|
||||
## Temperature Sensor Direction
|
||||
|
||||
@@ -159,11 +155,16 @@ Examples:
|
||||
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.
|
||||
4. Start Waveshare ESP32-S3 dashboard MVP over WiFi/HTTP.
|
||||
5. Add config backup/restore.
|
||||
6. Improve BMS out-of-range behavior without changing NimBLE connect timeout.
|
||||
7. Define future Pi Zero logging/integration role without moving control authority off the Cargo ESP32.
|
||||
|
||||
- Fixed WebUI temperature probe scan by registering `/temps/scan`, `/temps/assign`, and `/temps/clear` firmware routes.\n\n- Added per-temperature-sensor `weather` flag and WebUI outside temperature badge with emoji thresholds: below 50°F ice, 50-74°F happy, 75-84°F sun, and 85°F+ fire.\n\n- Improved WebUI temperature sensor config checkbox layout with compact On/Weather controls.\n\n- Temperature probe assignment now enforces one logical slot per physical DS18B20 address; assigning a probe to a new slot clears the old slot mapping.\n\n- Added per-slot WebUI Clear buttons for temperature probe assignments using the existing `/temps/clear` API.\n\n- Fixed weather temp checkbox persistence by saving the `weather` flag from WebUI temp config and auto-saving checkbox changes.\n\n- Fixed temperature assignment clearing so Clear removes the stored DS18B20 address, disables the slot, clears weather flag, and resets cached temp state.\n\n- Hardened `/temps/clear` so clearing a temp slot removes the persisted DS18B20 address, disables the slot, clears weather flag, resets cached temp state, and supports clearing all slots with an empty POST body.\n\n- Removed legacy physical-scan-order fallback for unassigned DS18B20 slots; enabled slots now require an explicit assigned address before reporting a value.\n\n- Filtered DS18B20 scan results so already-assigned probe addresses are hidden until cleared from their configured temp slot.\n\n- Moved WebUI Temperature Assignment card directly above Temperature Sensor Config for better setup flow.\n\n- Added read-only assigned DS18B20 address display under each WebUI temperature config slot.\n\n- Fixed DS18B20 scan filtering so assigned probes are hidden from assignment results without removing them from runtime polling.\n\n- Dashboard temperature list now hides disabled, unassigned, offline, or invalid temp slots while keeping all slots visible in Config.\n\n- Fixed dashboard temp filtering to avoid requiring address in runtime temp payload.\n\n- Fixed WebUI temp config so the On checkbox fully controls whether each temp slot is enabled.\n\n- Restored Overview relay control rendering after dashboard temp layout changes.\n\n- Fixed Overview relay buttons to call the existing `relay()` WebUI handler instead of missing `setRelay()`.\n\n- Restored Overview relay controls to separate ON and OFF buttons per relay.\n
|
||||
Recent notes:
|
||||
|
||||
- WebUI temperature scan, assign, clear, and weather/outside-air selection are implemented.
|
||||
- DS18B20 slots now require explicit assigned addresses before reporting values.
|
||||
- Relay controls and temperature configuration remain driven by generic IDs plus saved configuration names.
|
||||
|
||||
|
||||
## Dashboard Architecture Update
|
||||
@@ -181,4 +182,6 @@ Dashboard Client:
|
||||
→ Consumes existing HTTP API
|
||||
→ Planned LVGL-based dashboard UI
|
||||
|
||||
The Raspberry Pi Pico 2 W dashboard path is no longer the primary implementation target. UART JSON remains supported as an optional interface for future expansion, debugging, or alternate dashboard hardware.\n\n- Added dedicated ESP32-S3 dashboard planning document covering architecture, API use, LVGL screens, connection flow, and deferred Pico path.\n
|
||||
There is no planned Pico dashboard path. Existing Pico/UART files are legacy artifacts unless explicitly revived later.
|
||||
|
||||
UART JSON remains optional for diagnostics or alternate clients. New dashboard work should target the Waveshare ESP32-S3 display and the HTTP API.
|
||||
|
||||
+6
-6
@@ -1,10 +1,10 @@
|
||||
# ESP32 ↔ Pico Communication Protocol
|
||||
# Legacy UART Communication Protocol
|
||||
|
||||
## Current Decision
|
||||
|
||||
Primary communication is **UART over CAT5**.
|
||||
Primary dashboard communication is **WiFi HTTP API** between the Waveshare ESP32-S3 dashboard and the Cargo ESP32.
|
||||
|
||||
Backup communication is the **ESP32 WiFi HTTP API**.
|
||||
This legacy UART protocol is retained for historical reference, diagnostics, simulator work, or alternate clients. It is not the current dashboard architecture.
|
||||
|
||||
RS-485/MAX3485 is fallback-only and is not currently planned.
|
||||
|
||||
@@ -14,7 +14,7 @@ RS-485/MAX3485 is fallback-only and is not currently planned.
|
||||
* Baud: 115200
|
||||
* Format: 8N1
|
||||
* Framing: newline-delimited JSON
|
||||
* Direction: Pico dashboard ↔ ESP32 cargo controller
|
||||
* Direction: UART client ↔ ESP32 cargo controller
|
||||
|
||||
## Message Rules
|
||||
|
||||
@@ -28,7 +28,7 @@ Example:
|
||||
|
||||
Responses should also be one JSON object followed by a newline.
|
||||
|
||||
## Pico → ESP32 Messages
|
||||
## Client → ESP32 Messages
|
||||
|
||||
### Status Request
|
||||
|
||||
@@ -68,7 +68,7 @@ Expected response:
|
||||
}
|
||||
```
|
||||
|
||||
## ESP32 → Pico Messages
|
||||
## ESP32 → Client Messages
|
||||
|
||||
### Status Response
|
||||
|
||||
|
||||
+45
-509
@@ -1,526 +1,62 @@
|
||||
# Roadmap
|
||||
|
||||
This roadmap tracks planned Overland Controller development.
|
||||
## Phase 1: Solid Local Cargo Controller
|
||||
|
||||
The roadmap is flexible and may change as the project evolves.
|
||||
- Reliable relay control
|
||||
- Reliable DS18B20 temps
|
||||
- Reliable JBD/Xiaoxiang BMS BLE
|
||||
- WPA2 AP mode
|
||||
- Stable WebUI
|
||||
- Stable HTTP API
|
||||
- Clear status/config/control model
|
||||
|
||||
## Phase 1: ESP32 Controller Foundation
|
||||
## Phase 2: Waveshare ESP32-S3 Dashboard
|
||||
|
||||
Status: mostly complete
|
||||
|
||||
Goals:
|
||||
|
||||
- Establish ESP32 firmware structure
|
||||
- Implement relay control
|
||||
- Implement status reporting
|
||||
- Implement local configuration
|
||||
- Implement BMS telemetry
|
||||
- Implement generic relay/sensor naming
|
||||
- Establish HTTP and UART communication models
|
||||
|
||||
Completed:
|
||||
|
||||
- Relay control
|
||||
- JSON status API
|
||||
- Configuration persistence
|
||||
- Factory reset
|
||||
- BMS BLE telemetry
|
||||
- Cell voltage telemetry
|
||||
- Generic relay IDs
|
||||
- Generic temperature sensor IDs
|
||||
- HTTP API
|
||||
- Serial console commands
|
||||
- Documentation cleanup
|
||||
|
||||
Remaining:
|
||||
|
||||
- Finish UART parity
|
||||
- Improve BLE setup reliability
|
||||
- Add stronger config validation
|
||||
- Add better command help output
|
||||
|
||||
## Phase 2: UART Parity
|
||||
|
||||
Status: next priority
|
||||
|
||||
Goal:
|
||||
|
||||
The Pico dashboard should be able to configure and control the ESP32 over UART without relying on WiFi.
|
||||
|
||||
Minimum UART v1 messages:
|
||||
|
||||
- status_request
|
||||
- set_relay
|
||||
- config_request
|
||||
- config_device
|
||||
- config_relay
|
||||
- config_temp
|
||||
- config_bms
|
||||
- save_config
|
||||
- factory_reset
|
||||
- enter_bms_setup
|
||||
- scan_ble
|
||||
- select_bms
|
||||
- exit_bms_setup
|
||||
|
||||
Expected result:
|
||||
|
||||
The Pico can:
|
||||
|
||||
- Read full system status
|
||||
- Display current configuration
|
||||
- Control relays
|
||||
- Rename relays
|
||||
- Rename temperature sensors
|
||||
- Configure BMS
|
||||
- Run BMS setup workflow
|
||||
- Save configuration
|
||||
|
||||
## Phase 3: Temperature Sensors
|
||||
|
||||
Status: partially started
|
||||
|
||||
Goals:
|
||||
|
||||
- Complete DS18B20 hardware wiring
|
||||
- Add proper 4.7k pull-up resistor
|
||||
- Detect connected sensors
|
||||
- Report sensor addresses
|
||||
- Assign sensors to config slots
|
||||
- Persist sensor address assignments
|
||||
|
||||
Planned serial commands:
|
||||
|
||||
- scan temps
|
||||
- assign temp 1 <address>
|
||||
- clear temp 1
|
||||
|
||||
Planned UART messages:
|
||||
|
||||
- scan_temps
|
||||
- assign_temp
|
||||
- clear_temp
|
||||
|
||||
Expected result:
|
||||
|
||||
A user can connect multiple DS18B20 sensors, identify each one, name it, and save the configuration.
|
||||
|
||||
## Phase 4: Pico Dashboard Bring-Up
|
||||
|
||||
Status: not started on hardware
|
||||
|
||||
Goals:
|
||||
|
||||
- Bring up Pico 2 W
|
||||
- Bring up touchscreen
|
||||
- Establish UART connection to ESP32
|
||||
- Display status response
|
||||
- Display battery data
|
||||
- Display relay states
|
||||
- Display temperature data
|
||||
- LVGL project scaffold
|
||||
- WiFi client to Cargo ESP32 AP
|
||||
- Poll /status
|
||||
- Display battery, relays, temps, and alarms
|
||||
- Send relay commands
|
||||
- Handle offline/stale/failed-command states
|
||||
|
||||
Initial dashboard screens:
|
||||
UI direction:
|
||||
|
||||
- Main overview
|
||||
- Battery screen
|
||||
- Temperature screen
|
||||
- Relay control screen
|
||||
- Settings screen
|
||||
- Dark theme
|
||||
- Large readable text
|
||||
- Circular SOC gauge
|
||||
- Card-based layout
|
||||
- Smooth subtle animations
|
||||
- No stock LVGL demo look
|
||||
|
||||
## Phase 5: Pico Configuration UI
|
||||
## Phase 3: Vehicle Data
|
||||
|
||||
Status: planned
|
||||
- Connect Waveshare CAN to OBD-II CAN-H/CAN-L
|
||||
- Keep CAN termination disabled
|
||||
- Read coolant temp via PID 0105
|
||||
- Read RPM via PID 010C
|
||||
- Read vehicle speed via PID 010D
|
||||
|
||||
Goals:
|
||||
## Phase 4: Transmission Temperature
|
||||
|
||||
- Configure device name
|
||||
- Configure relay names
|
||||
- Configure temperature names
|
||||
- Configure BMS
|
||||
- Run BLE scan workflow
|
||||
- Save config
|
||||
- Factory reset
|
||||
- Install dedicated sender
|
||||
- Read through exposed ADC or ADS1115 over I2C
|
||||
- Convert resistance to temp with lookup interpolation
|
||||
- Add alert thresholds
|
||||
|
||||
Expected result:
|
||||
## Phase 5: Future Home Server
|
||||
|
||||
A new installation can be configured from the dashboard without using a laptop.
|
||||
- Cargo ESP32 outbound connection
|
||||
- Remote read-only dashboard first
|
||||
- Optional commands later
|
||||
- HTTPS reverse proxy/PWA
|
||||
- Possible MQTT/WebSocket bridge
|
||||
- Optional Grafana/Home Assistant/InflDB
|
||||
|
||||
## Phase 6: Vehicle Inputs
|
||||
## Phase 6: Optional Enhancements
|
||||
|
||||
Status: planned
|
||||
|
||||
Possible inputs:
|
||||
|
||||
- Ignition signal
|
||||
- Vehicle battery voltage
|
||||
- OBD-II
|
||||
- CAN bus
|
||||
- microSD logging
|
||||
- GPS
|
||||
|
||||
Potential data:
|
||||
|
||||
- Ignition state
|
||||
- Engine RPM
|
||||
- Coolant temperature
|
||||
- Vehicle speed
|
||||
- Fuel level
|
||||
- Diagnostic trouble codes
|
||||
- Location
|
||||
- Trip data
|
||||
|
||||
## Phase 7: Logging and History
|
||||
|
||||
Status: planned
|
||||
|
||||
Goals:
|
||||
|
||||
- Log battery history
|
||||
- Log temperature history
|
||||
- Log relay events
|
||||
- Log alarm events
|
||||
- Show historical charts
|
||||
|
||||
Possible storage:
|
||||
|
||||
- ESP32 flash
|
||||
- SD card
|
||||
- External service
|
||||
- Future InfluxDB integration
|
||||
|
||||
## Phase 8: Integrations
|
||||
|
||||
Status: planned
|
||||
|
||||
Potential integrations:
|
||||
|
||||
- MQTT
|
||||
- Home Assistant
|
||||
- Grafana
|
||||
- InfluxDB
|
||||
- Node-RED
|
||||
|
||||
Design goal:
|
||||
|
||||
Integrations should consume the same generic status/config model used by HTTP and UART.
|
||||
|
||||
## Phase 9: Enclosure and Installation
|
||||
|
||||
Status: planned
|
||||
|
||||
Goals:
|
||||
|
||||
- Design ESP32 enclosure
|
||||
- Design Pico dashboard enclosure
|
||||
- Design wiring harness
|
||||
- Document installation
|
||||
- Create BOM
|
||||
- Create printable STL files
|
||||
- Validate thermal and vibration behavior
|
||||
|
||||
## Phase 10: Public Release
|
||||
|
||||
Status: future
|
||||
|
||||
Goals:
|
||||
|
||||
- Clean documentation
|
||||
- Stable API
|
||||
- Stable UART protocol
|
||||
- Installation guide
|
||||
- Wiring guide
|
||||
- Build guide
|
||||
- Example configurations
|
||||
- Versioned releases
|
||||
|
||||
Potential release name:
|
||||
|
||||
Overland Controller v1.0
|
||||
|
||||
## Long-Term Ideas
|
||||
|
||||
Potential future features:
|
||||
|
||||
- OTA firmware updates
|
||||
- Multi-controller support
|
||||
- Expansion modules
|
||||
- Water tank monitoring
|
||||
- Inverter monitoring
|
||||
- Solar charge controller monitoring
|
||||
- Starlink diagnostics
|
||||
- Bluetooth sensor support
|
||||
- Mobile web dashboard
|
||||
- Plugin-style integrations
|
||||
|
||||
---
|
||||
|
||||
## Networking Roadmap
|
||||
|
||||
### Current
|
||||
|
||||
The ESP32 currently operates as a local access point.
|
||||
|
||||
Default local access:
|
||||
|
||||
http://192.168.4.1
|
||||
|
||||
This provides a reliable recovery/setup path even when no other WiFi network is available.
|
||||
|
||||
### Planned: AP + STA Mode
|
||||
|
||||
The ESP32 should support AP and STA mode at the same time.
|
||||
|
||||
Access Point mode:
|
||||
|
||||
Overland-Controller
|
||||
192.168.4.1
|
||||
|
||||
Station mode:
|
||||
|
||||
Connects to a configured WiFi network such as Starlink, home WiFi, or shop WiFi.
|
||||
|
||||
The AP should remain enabled even when STA mode is connected.
|
||||
|
||||
Reason:
|
||||
|
||||
- Always available recovery path
|
||||
- Easier setup
|
||||
- Less risk of locking yourself out
|
||||
- Useful when Starlink/home WiFi is unavailable
|
||||
|
||||
### Planned: Multiple Saved WiFi Networks
|
||||
|
||||
The controller should eventually support multiple saved WiFi profiles.
|
||||
|
||||
Example priority order:
|
||||
|
||||
1. Starlink
|
||||
2. Home WiFi
|
||||
3. Shop WiFi
|
||||
|
||||
Expected boot behavior:
|
||||
|
||||
Start AP
|
||||
Try Starlink
|
||||
If Starlink fails, try Home WiFi
|
||||
If Home WiFi fails, try Shop WiFi
|
||||
If all fail, remain AP-only
|
||||
|
||||
The ESP32 only connects to one STA network at a time, but it can remember and try multiple networks.
|
||||
|
||||
### Planned WiFi Configuration
|
||||
|
||||
Future configuration should include:
|
||||
|
||||
ap_enabled
|
||||
sta_enabled
|
||||
hostname
|
||||
saved networks
|
||||
priority order
|
||||
|
||||
Future setup options:
|
||||
|
||||
- Serial console
|
||||
- HTTP API
|
||||
- Pico dashboard UI
|
||||
- Embedded web dashboard
|
||||
|
||||
### Planned mDNS
|
||||
|
||||
The controller should eventually support mDNS.
|
||||
|
||||
Example:
|
||||
|
||||
http://overland-controller.local
|
||||
|
||||
This would avoid needing to look up the controller IP when connected through Starlink or home WiFi.
|
||||
|
||||
---
|
||||
|
||||
## Embedded Web Dashboard
|
||||
|
||||
### Current Direction
|
||||
|
||||
The ESP32 should serve a lightweight mobile-friendly dashboard.
|
||||
|
||||
Purpose:
|
||||
|
||||
- Check battery status from a phone
|
||||
- Check fridge/temp status from camp
|
||||
- Toggle relays if needed
|
||||
- View alarms
|
||||
- Provide fallback UI without the Pico display
|
||||
|
||||
Design limits:
|
||||
|
||||
- No React
|
||||
- No external libraries
|
||||
- No images
|
||||
- Small inline HTML/CSS/JS
|
||||
- Poll /status every few seconds
|
||||
- Use existing relay endpoints
|
||||
|
||||
This dashboard is not intended to replace the physical Pico dashboard.
|
||||
|
||||
---
|
||||
|
||||
## Optional Future Pi Zero Module
|
||||
|
||||
The base system should not require a Pi Zero.
|
||||
|
||||
Base system:
|
||||
|
||||
ESP32 controller
|
||||
Pico 2 W dashboard
|
||||
|
||||
Optional future advanced module:
|
||||
|
||||
Pi Zero 2 W
|
||||
|
||||
Possible Pi Zero functions:
|
||||
|
||||
- Rich web dashboard
|
||||
- Historical logging
|
||||
- Graphs
|
||||
- SQLite database
|
||||
- MQTT bridge
|
||||
- Home Assistant bridge
|
||||
- Advanced configuration UI
|
||||
|
||||
The core controller should remain functional without the Pi Zero.
|
||||
|
||||
---
|
||||
|
||||
## Configuration Backup and Restore
|
||||
|
||||
Planned future feature.
|
||||
|
||||
Goals:
|
||||
|
||||
- Export configuration JSON
|
||||
- Import configuration JSON
|
||||
- Backup install-specific setup
|
||||
- Restore after factory reset
|
||||
- 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.
|
||||
|
||||
---
|
||||
|
||||
## Pico Dashboard MVP Plan
|
||||
|
||||
MVP means Minimum Viable Product.
|
||||
|
||||
Goal:
|
||||
|
||||
Prove Pico 2 W can reliably read ESP32 status over UART and display live data.
|
||||
|
||||
Phase 1:
|
||||
|
||||
- MicroPython on Pico 2 W / RP2350
|
||||
- UART to ESP32 dashboard UART
|
||||
- USB debug output
|
||||
- Request status from ESP32
|
||||
- Parse status JSON
|
||||
|
||||
Phase 2:
|
||||
|
||||
- ST7796S display bring-up
|
||||
- Backlight control
|
||||
- Hello World screen
|
||||
- Static dashboard layout
|
||||
|
||||
Phase 3:
|
||||
|
||||
- Live battery card
|
||||
- Runtime / time-to-full card
|
||||
- Temperature list
|
||||
- Relay state list
|
||||
- ESP32 connection indicator
|
||||
|
||||
Phase 4:
|
||||
|
||||
- Touch support using FT6336U
|
||||
- Page navigation
|
||||
- Relay controls
|
||||
- Alarm details
|
||||
|
||||
Do not start with touch or config UI on the Pico. The WebUI is the preferred configuration workflow.
|
||||
|
||||
|
||||
|
||||
## Revised Dashboard Roadmap
|
||||
|
||||
### Phase 1
|
||||
ESP32 cargo controller backend
|
||||
- WiFi
|
||||
- WebUI
|
||||
- Relay control
|
||||
- JBD/Xiaoxiang BMS
|
||||
- DS18B20
|
||||
- Config persistence
|
||||
|
||||
### Phase 2
|
||||
Waveshare 5" ESP32-S3 Dashboard
|
||||
- Connect to cargo ESP AP
|
||||
- Read /status API
|
||||
- Basic dashboard
|
||||
- Battery SOC
|
||||
- Voltage/current
|
||||
- Temps
|
||||
- Relay status
|
||||
|
||||
### Phase 3
|
||||
LVGL Dashboard UI
|
||||
- Touch support
|
||||
- Relay controls
|
||||
- Alarm screens
|
||||
- Config/status pages
|
||||
|
||||
### Phase 4
|
||||
Extended Vehicle Telemetry
|
||||
- OBD-II
|
||||
- Coolant temp
|
||||
- GPS
|
||||
- Trip data
|
||||
- Vehicle metrics
|
||||
|
||||
### Phase 5
|
||||
Advanced Integrations
|
||||
- Home Assistant
|
||||
- MQTT
|
||||
- Grafana
|
||||
- InfluxDB\n\n- Added docs/dashboard-esp32s3.md as the primary dashboard implementation plan for the Waveshare 5 inch ESP32-S3 display.\n
|
||||
- OTA updates
|
||||
- Dashboard alert sounds
|
||||
- More vehicle PIDs
|
||||
- Historical charts
|
||||
|
||||
+13
-7
@@ -1,16 +1,22 @@
|
||||
# Wiring
|
||||
|
||||
This document describes the current planned wiring for the Overland Controller install.
|
||||
This document contains older wiring notes and may include legacy Pico/UART dashboard assumptions.
|
||||
|
||||
The current system uses:
|
||||
Current dashboard and hardware source of truth:
|
||||
|
||||
- ESP32 2-relay controller board
|
||||
- Raspberry Pi Pico 2 W dashboard
|
||||
- CAT5/CAT6 cable between rear controller and dash
|
||||
- 12V-to-5V buck converter in the dash enclosure
|
||||
- `docs/HARDWARE.md`
|
||||
- `docs/dashboard-esp32s3.md`
|
||||
|
||||
Do not use Pico-specific wiring in this file for the current dashboard build.
|
||||
|
||||
Current planned system uses:
|
||||
|
||||
- Cargo ESP32 2-relay controller board
|
||||
- Waveshare ESP32-S3-Touch-LCD-5 dashboard over WiFi/HTTP
|
||||
- ACC switched 12V fused dashboard power into Waveshare VIN
|
||||
- DS18B20 temperature sensors
|
||||
- JBD/Xiaoxiang BMS over BLE
|
||||
- External automotive relays for high-current loads
|
||||
- External fused automotive relays or contactors for major loads
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user