5.3 KiB
ARCHITECTURE.md
System Architecture
Overland Controller is built as a distributed monitoring and control platform for overland vehicles, campers, trailers, and mobile power systems.
The architecture intentionally separates user interface functions from monitoring and control functions.
This improves reliability, modularity, and future expandability.
High-Level Overview
text User │ ▼ +----------------+ | Dashboard UI | | Pico 2 W | +----------------+ │ │ UART / WiFi ▼ +----------------+ | ESP32 Controller| +----------------+ │ │ │ │ │ │ ▼ ▼ ▼ BMS Sensors Relays
The ESP32 is the system authority.
The dashboard acts as a user interface only.
Core Design Principles
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.
Responsibilities:
Battery Monitoring
Source:
text JBD / Xiaoxiang BLE BMS
Provides:
- State of charge
- Voltage
- Current
- Capacity
- Temperature
- Cell data
Temperature Monitoring
Source:
text DS18B20 Sensors
Provides:
- Temperature readings
- Sensor health
- Online/offline status
Relay Control
Provides:
- Output control
- State reporting
- Future automation logic
Configuration Storage
Stores:
- Device name
- Relay configuration
- Temperature sensor configuration
- BMS configuration
Configuration survives reboot.
Local Web Server
Provides:
- Status endpoint
- Configuration endpoint
- Relay control endpoint
Current transport:
text HTTP JSON
Dashboard
Current target:
text Raspberry Pi Pico 2 W
Responsibilities:
- Display information
- User interaction
- Relay control
- Configuration management
The dashboard should not contain critical business logic.
Data Flow
Battery Data
text BMS │ ▼ ESP32 │ ▼ Status API │ ▼ Dashboard
Temperature Data
text DS18B20 │ ▼ ESP32 │ ▼ Status API │ ▼ Dashboard
Relay Control
text User │ ▼ Dashboard │ ▼ ESP32 API │ ▼ Relay Output
Future automation may bypass the dashboard entirely.
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:
- Home Assistant
- Node-RED
- Grafana
- InfluxDB
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