Align docs with ESP32-S3 dashboard architecture

This commit is contained in:
2026-06-07 09:48:13 -06:00
parent fdf3d657b6
commit dc8340a1ec
22 changed files with 211 additions and 638 deletions
+4 -24
View File
@@ -1,30 +1,10 @@
---
# Relay Wiring
# Hardware Notes
Current architecture uses the onboard relay contacts
as the load switching device.
The current hardware source of truth is `docs/HARDWARE.md`.
Positive-side switching:
Battery +
|
Fuse
|
Relay COM
|
Relay NO
|
Load +
Load negative returns directly to the ground bus.
Relay 1:
Starlink Mini
Relay 2:
Fridge
The Cargo ESP32 relay board outputs are control/trigger outputs only. Do not route fridge, Starlink, inverter, lights, or other major load current through the ESP32 relay board.
Use properly fused automotive relays or contactors for major loads.
+13 -9
View File
@@ -34,15 +34,15 @@ Current controller:
- ESP32 2-relay board
Planned dashboard:
Primary dashboard target:
- Raspberry Pi Pico 2 W
- Touchscreen display
- UART connection to ESP32
- Waveshare ESP32-S3-Touch-LCD-5
- WiFi client to the Cargo ESP32 access point
- HTTP API integration
Optional future expansion:
- Pi Zero 2 W for advanced logging/charts/web app
- Pi Zero for long-term logging, charts, and local integrations
## WebUI
@@ -68,22 +68,26 @@ The Config tab is the preferred initial setup workflow.
The ESP32 is the source of truth.
The Pico dashboard will be an instant-on physical display and control surface.
The Waveshare ESP32-S3 dashboard is a client-only local display and control surface.
The WebUI is used for setup, configuration, and phone access from camp.
A future Pi Zero may be added for long-term logging or richer local integrations, but it must not become required for core control.
## Documentation
Important docs:
- `docs/project-state.md`
- `docs/api.md`
- `docs/API.md`
- `docs/ARCHITECTURE.md`
- `docs/HARDWARE.md`
- `docs/UART_PROTOCOL.md`
- `docs/SERIAL_COMMANDS.md`
- `docs/PARITY_MATRIX.md`
- `docs/wiring.md`
- `docs/TEMP_SETUP.md`
- `docs/roadmap.md`
- `docs/ROADMAP.md`
- `docs/CHANGELOG.md`
## Safety
@@ -99,4 +103,4 @@ Use:
- Strain relief
- Testing before connecting expensive loads
Do not connect vehicle 12V directly to ESP32 or Pico GPIO pins.
Do not connect vehicle 12V directly to ESP32 GPIO pins or dashboard GPIO pins.
+8 -4
View File
@@ -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.
+3 -5
View File
@@ -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
View File
@@ -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
+1 -1
View File
@@ -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
View File
@@ -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.
+3 -1
View File
@@ -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
View File
@@ -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
View File
@@ -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`.
+6 -11
View File
@@ -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
View File
@@ -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.
+4
View File
@@ -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
View File
@@ -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
View File
@@ -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
View File
@@ -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
View File
@@ -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
---
+3 -6
View File
@@ -2,15 +2,13 @@
## Ordered
- Raspberry Pi Pico 2 W
- ESP32 2-Channel Relay Board
- 3.5" SPI Capacitive Touchscreen
## Required
- 4x DS18B20 Waterproof Sensors
- 12V→5V Buck Converter
- CAT5 Cable
- Waveshare ESP32-S3-Touch-LCD-5 dashboard
- Fused ACC switched 12V dashboard power
- Bosch Relay Sockets
- 30A/40A Bosch Relays
- Automotive Fuse Block
@@ -18,8 +16,7 @@
## Future / Optional Fallback
- 2x MAX3485 RS-485 Modules, only if UART over CAT5 proves unreliable
- Pi Zero 2 W
- Pi Zero for long-term logging and local integrations
- GPS Module
- ELM327 OBD-II Interface
- CAN Interface
+2
View File
@@ -1,5 +1,7 @@
# CAT5 Pinout
Legacy note: this file describes an older Pico/UART dashboard wiring plan. Do not use it for the current Waveshare ESP32-S3 dashboard build.
## Primary Configuration
UART over CAT5
+2
View File
@@ -1,5 +1,7 @@
# ESP32 Pinout (Planned)
Legacy note: Pico/UART references in this file are not part of the current dashboard plan. Current dashboard target is Waveshare ESP32-S3 over WiFi/HTTP.
GPIO 16 Relay 1 (Starlink)
GPIO 17 Relay 2 (Fridge)
+2
View File
@@ -1,5 +1,7 @@
# Pico Pinout (Planned)
Legacy note: no Pico dashboard is currently planned. This file is retained only as historical/reference material.
## Display
3.5 inch SPI capacitive touchscreen
+2
View File
@@ -1,5 +1,7 @@
# UART CAT5 Pinout
Legacy note: this file describes an older Pico/UART dashboard wiring plan. Do not use it for the current Waveshare ESP32-S3 dashboard build.
## Pair 1
Blue +5V