236 lines
4.0 KiB
Markdown
236 lines
4.0 KiB
Markdown
# Architecture
|
|
|
|
Overland Controller is a distributed monitoring and control platform for vehicles, trailers, campers, and mobile power systems.
|
|
|
|
The system separates electrical control from user interface logic.
|
|
|
|
## Main Components
|
|
|
|
### ESP32 Controller
|
|
|
|
The ESP32 is the system authority.
|
|
|
|
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
|
|
|
|
### Pico Dashboard
|
|
|
|
The Pico is the primary user interface.
|
|
|
|
Responsibilities:
|
|
|
|
- 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
|
|
|
|
The Pico should not own critical control state. The ESP32 remains the source of truth.
|
|
|
|
## Communication Paths
|
|
|
|
### UART
|
|
|
|
Primary dashboard/control path.
|
|
|
|
Used for:
|
|
|
|
- Status requests
|
|
- Relay control
|
|
- Configuration updates
|
|
- BMS setup
|
|
- BLE scan requests
|
|
- BMS selection
|
|
|
|
UART should eventually support every core management action needed by the Pico.
|
|
|
|
### HTTP
|
|
|
|
Secondary setup/debug path.
|
|
|
|
Used for:
|
|
|
|
- Browser testing
|
|
- Phone/laptop setup
|
|
- Future web UI
|
|
- API debugging
|
|
|
|
HTTP should mirror the same data model as UART where practical.
|
|
|
|
### USB Serial
|
|
|
|
Service/debug path.
|
|
|
|
Used for:
|
|
|
|
- Development
|
|
- Recovery
|
|
- Troubleshooting
|
|
- Emergency configuration
|
|
|
|
## 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 names
|
|
- Relay enable states
|
|
- Temperature sensor names
|
|
- Temperature sensor addresses
|
|
- Temperature sensor enable states
|
|
- BMS name
|
|
- BMS BLE address
|
|
- BMS address type
|
|
|
|
The Pico may edit configuration through UART, but the ESP32 stores and owns it.
|
|
|
|
## Status Flow
|
|
|
|
Pico sends:
|
|
|
|
status_request
|
|
|
|
ESP32 responds with the same shape as HTTP /status:
|
|
|
|
battery
|
|
temps
|
|
relays
|
|
vehicle
|
|
network
|
|
alarms
|
|
system
|
|
config
|
|
|
|
## Relay Control Flow
|
|
|
|
Pico sends a generic relay command:
|
|
|
|
relay_1 on
|
|
relay_1 off
|
|
relay_2 on
|
|
relay_2 off
|
|
|
|
ESP32 updates the relay output and reports the new state.
|
|
|
|
## BMS Setup Flow
|
|
|
|
BMS setup can be started from the Pico.
|
|
|
|
Expected flow:
|
|
|
|
enter_bms_setup
|
|
scan_ble
|
|
scan_ble
|
|
select_bms
|
|
save_config
|
|
|
|
The ESP32 handles BLE scanning and BMS selection.
|
|
|
|
The Pico only displays options and sends the selected index or address.
|
|
|
|
## HTTP / UART Parity
|
|
|
|
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
|
|
|
|
## Current Priority
|
|
|
|
The next implementation priority is UART parity.
|
|
|
|
The Pico should be able to do the important setup and control operations without relying on WiFi.
|
|
|
|
Minimum UART v1 scope:
|
|
|
|
- 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 Integrations
|
|
|
|
Possible future integrations:
|
|
|
|
- MQTT
|
|
- Home Assistant
|
|
- Grafana
|
|
- InfluxDB
|
|
- OBD-II
|
|
- CAN bus
|
|
- GPS
|
|
- Data logging
|
|
- OTA updates
|
|
|
|
All future integrations should consume the same generic status/config model.
|