# 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