nick/overland-controller
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update architecture for UART-first control model

Browse Source
This commit is contained in:
nick
2026-06-04 04:17:58 -06:00
parent a68fd557b9
commit a1fafff8cb
1 changed files with 172 additions and 317 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ARCHITECTURE.md
+172 -317
View File
@@ -1,380 +1,235 @@
# ARCHITECTURE.md
# Architecture
# System Architecture
Overland Controller is a distributed monitoring and control platform for vehicles, trailers, campers, and mobile power systems.
Overland Controller is built as a distributed monitoring and control platform for overland vehicles, campers, trailers, and mobile power systems.
The system separates electrical control from user interface logic.
The architecture intentionally separates user interface functions from monitoring and control functions.
## Main Components
This improves reliability, modularity, and future expandability.
---
# High-Level Overview
text User │ ▼ +----------------+ | Dashboard UI | | Pico 2 W | +----------------+ │ │ UART / WiFi ▼ +----------------+ | ESP32 Controller| +----------------+ │ │ │ │ │ │ ▼ ▼ ▼ BMS Sensors Relays
### ESP32 Controller
The ESP32 is the system authority.
The dashboard acts as a user interface only.
Responsibilities:
---
- Read battery/BMS data
- Read temperature sensors
- Control relay outputs
- Store configuration
- Serve the HTTP API
- Communicate with the Pico dashboard over UART
- Maintain system status
- Handle alarms
# Core Design Principles
### Pico Dashboard
## Local First
The system must function completely offline.
Requirements:
- No cloud dependency
- No internet requirement
- No third-party service requirement
- No account requirement
---
## Controller First
The ESP32 is responsible for:
- Data collection
- Device control
- Configuration storage
- State management
The dashboard should never be required for normal operation.
---
## Generic Hardware Naming
The firmware should never assume installation-specific names.
Avoid:
text Fridge Starlink Greta Outside Rear Seat
Instead use:
text relay_1 relay_2 temp_1 temp_2 temp_3 temp_4
User-specific naming belongs in configuration.
---
## API Driven
All data should be exposed through structured APIs.
Benefits:
- Dashboard independence
- Future Home Assistant integration
- Future MQTT support
- Easier testing
- Easier automation
---
# ESP32 Controller
The ESP32 is the primary controller.
The Pico is the primary user interface.
Responsibilities:
## Battery Monitoring
- Request status from ESP32
- Display battery data
- Display temperature data
- Display relay states
- Send relay commands
- Send configuration commands
- Provide setup workflows
- Operate without internet
Source:
The Pico should not own critical control state. The ESP32 remains the source of truth.
text JBD / Xiaoxiang BLE BMS
## Communication Paths
Provides:
### UART
- State of charge
- Voltage
- Current
- Capacity
- Temperature
- Cell data
Primary dashboard/control path.
---
Used for:
## Temperature Monitoring
- Status requests
- Relay control
- Configuration updates
- BMS setup
- BLE scan requests
- BMS selection
Source:
UART should eventually support every core management action needed by the Pico.
text DS18B20 Sensors
### HTTP
Provides:
Secondary setup/debug path.
- Temperature readings
- Sensor health
- Online/offline status
Used for:
---
- Browser testing
- Phone/laptop setup
- Future web UI
- API debugging
## Relay Control
HTTP should mirror the same data model as UART where practical.
Provides:
### USB Serial
- Output control
- State reporting
- Future automation logic
Service/debug path.
---
Used for:
## Configuration Storage
- Development
- Recovery
- Troubleshooting
- Emergency configuration
Stores:
## Data Model
The same generic data model should be used across:
- HTTP API
- UART protocol
- Pico dashboard
- Simulator
- Future MQTT/Home Assistant integrations
## Generic IDs
Firmware uses generic IDs.
Relays:
relay_1
relay_2
Temperature sensors:
temp_1
temp_2
temp_3
temp_4
temp_5
temp_6
temp_7
temp_8
Installation-specific names belong only in saved configuration.
Examples of configuration names:
Fridge
Starlink
Cabin
Outside
House Battery
These names should not be hardcoded into firmware behavior.
## Configuration Ownership
Configuration is stored on the ESP32.
Stored configuration includes:
- Device name
- Relay configuration
- Temperature sensor configuration
- BMS configuration
- Relay names
- Relay enable states
- Temperature sensor names
- Temperature sensor addresses
- Temperature sensor enable states
- BMS name
- BMS BLE address
- BMS address type
Configuration survives reboot.
The Pico may edit configuration through UART, but the ESP32 stores and owns it.
---
## Status Flow
## Local Web Server
Pico sends:
Provides:
status_request
- Status endpoint
- Configuration endpoint
- Relay control endpoint
ESP32 responds with the same shape as HTTP /status:
Current transport:
battery
temps
relays
vehicle
network
alarms
system
config
text HTTP JSON
## Relay Control Flow
---
Pico sends a generic relay command:
# Dashboard
relay_1 on
relay_1 off
relay_2 on
relay_2 off
Current target:
ESP32 updates the relay output and reports the new state.
text Raspberry Pi Pico 2 W
## BMS Setup Flow
Responsibilities:
BMS setup can be started from the Pico.
- Display information
- User interaction
- Relay control
- Configuration management
Expected flow:
The dashboard should not contain critical business logic.
enter_bms_setup
scan_ble
scan_ble
select_bms
save_config
---
The ESP32 handles BLE scanning and BMS selection.
# Data Flow
The Pico only displays options and sends the selected index or address.
## Battery Data
## HTTP / UART Parity
text BMS │ ▼ ESP32 │ ▼ Status API │ ▼ Dashboard
Long-term goal:
---
- HTTP /status equals UART status_request
- HTTP /config equals UART config_request
- HTTP /config/device equals UART config_device
- HTTP /config/relay equals UART config_relay
- HTTP /config/temp equals UART config_temp
- HTTP /config/bms equals UART config_bms
- HTTP relay control equals UART set_relay
- HTTP factory reset equals UART factory_reset
## Temperature Data
## Current Priority
text DS18B20 │ ▼ ESP32 │ ▼ Status API │ ▼ Dashboard
The next implementation priority is UART parity.
---
The Pico should be able to do the important setup and control operations without relying on WiFi.
## Relay Control
Minimum UART v1 scope:
text User │ ▼ Dashboard │ ▼ ESP32 API │ ▼ Relay Output
- 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
Future automation may bypass the dashboard entirely.
## Future Integrations
---
# Communications
## Current
### BMS → ESP32
text BLE
### Dashboard → ESP32
text UART
### Browser → ESP32
text HTTP
---
## Future
Potential future transports:
text WiFi MQTT WebSockets CAN Bus
---
# Configuration Model
Configuration exists in three layers.
## Firmware Defaults
Built into firmware.
Example:
text relay_1 relay_2 temp_1 temp_2
Used when no configuration exists.
---
## Stored Configuration
Saved in non-volatile storage.
Contains:
- User names
- Addresses
- Enable states
Persists through reboot.
---
## Runtime State
Current operational values.
Examples:
text Battery voltage Relay state Temperature readings Alarm status
Generated dynamically.
Never stored permanently.
---
# Status Model
The status API contains six major sections.
## Battery
Battery telemetry.
---
## Temperatures
Temperature sensor readings.
---
## Relays
Relay states.
---
## Vehicle
Vehicle telemetry.
Currently minimal.
Future expansion point.
---
## Alarms
System alarm state.
Examples:
text Low battery High temperature BMS disconnected Cell imbalance
---
## System
Controller information.
Examples:
text Firmware version Build date Build time Uptime
---
# Future Expansion
## Vehicle Integration
Potential sources:
text OBD-II ELM327 CAN Bus
Potential data:
- RPM
- Fuel level
- Coolant temperature
- Vehicle speed
- Trouble codes
---
## GPS
Potential features:
- Location
- Trip logging
- Route history
---
## MQTT
Potential integrations:
Possible future integrations:
- MQTT
- Home Assistant
- Node-RED
- Grafana
- InfluxDB
- OBD-II
- CAN bus
- GPS
- Data logging
- OTA updates
---
## Data Logging
Potential storage:
text SD Card Internal Flash Network Storage
Potential data:
- Battery history
- Temperature history
- Relay history
- Vehicle telemetry
---
# Long-Term Vision
The long-term goal is a modular platform capable of monitoring and controlling nearly every subsystem in an overland vehicle while remaining:
- Offline capable
- Self-hosted
- Hardware independent
- Expandable
- Easy to troubleshoot
- Easy to maintain
- Free from cloud dependencies
All future integrations should consume the same generic status/config model.