Update architecture for UART-first control model
This commit is contained in:
+172
-317
@@ -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.
|
### ESP32 Controller
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# High-Level Overview
|
|
||||||
|
|
||||||
text User │ ▼ +----------------+ | Dashboard UI | | Pico 2 W | +----------------+ │ │ UART / WiFi ▼ +----------------+ | ESP32 Controller| +----------------+ │ │ │ │ │ │ ▼ ▼ ▼ BMS Sensors Relays
|
|
||||||
|
|
||||||
The ESP32 is the system authority.
|
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 Pico is the primary user interface.
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
Responsibilities:
|
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
|
Primary dashboard/control path.
|
||||||
- Voltage
|
|
||||||
- Current
|
|
||||||
- Capacity
|
|
||||||
- Temperature
|
|
||||||
- Cell data
|
|
||||||
|
|
||||||
---
|
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
|
Used for:
|
||||||
- Sensor health
|
|
||||||
- Online/offline status
|
|
||||||
|
|
||||||
---
|
- 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
|
Service/debug path.
|
||||||
- State reporting
|
|
||||||
- Future automation logic
|
|
||||||
|
|
||||||
---
|
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
|
- Device name
|
||||||
- Relay configuration
|
- Relay names
|
||||||
- Temperature sensor configuration
|
- Relay enable states
|
||||||
- BMS configuration
|
- 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
|
ESP32 responds with the same shape as HTTP /status:
|
||||||
- Configuration endpoint
|
|
||||||
- Relay control endpoint
|
|
||||||
|
|
||||||
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
|
Expected flow:
|
||||||
- User interaction
|
|
||||||
- Relay control
|
|
||||||
- Configuration management
|
|
||||||
|
|
||||||
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
|
||||||
|
|
||||||
---
|
Possible 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:
|
|
||||||
|
|
||||||
|
- MQTT
|
||||||
- Home Assistant
|
- Home Assistant
|
||||||
- Node-RED
|
|
||||||
- Grafana
|
- Grafana
|
||||||
- InfluxDB
|
- InfluxDB
|
||||||
|
- OBD-II
|
||||||
|
- CAN bus
|
||||||
|
- GPS
|
||||||
|
- Data logging
|
||||||
|
- OTA updates
|
||||||
|
|
||||||
---
|
All future integrations should consume the same generic status/config model.
|
||||||
|
|
||||||
## 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
|
|
||||||
|
|||||||
Reference in New Issue
Block a user