381 lines
5.3 KiB
Markdown
381 lines
5.3 KiB
Markdown
# 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
|