From a1fafff8cbebbe6e789a20f4caaa74abd7356ef3 Mon Sep 17 00:00:00 2001 From: nick Date: Thu, 4 Jun 2026 04:17:58 -0600 Subject: [PATCH] Update architecture for UART-first control model --- docs/ARCHITECTURE.md | 489 +++++++++++++++---------------------------- 1 file changed, 172 insertions(+), 317 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index c2662ca..59f7fa9 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -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.