overland-controller/docs/controller-roles.md

Controller Roles

This document separates committed v1 architecture from future wishlist items.

Cargo ESP32 Controller

The Cargo ESP32 is the power-system controller and source of truth.

Responsibilities:

• WiFi AP
• Embedded WebUI
• REST/HTTP API
• Relay/output control
• Automotive load-switching control outputs
• JBD/Xiaoxiang BLE BMS telemetry
• DS18B20 temperature sensors
• Optional SSD1306 OLED service/status display
• Local configuration storage
• Alarm and fault state

Does not do:

• CAN sniffing
• OBD-II polling
• Vehicle data ownership
• Tilt/roll sensing
• Dashboard rendering
• Gauge cluster rendering

Dashboard ESP32-S3

The Dashboard ESP32-S3 is a touchscreen client and future vehicle-visualization node.

Responsibilities:

• Touchscreen UI
• LVGL dashboard rendering
• Vehicle gauges
• CAN bus access
• OBD-II polling
• Future VIN decoding
• Future fault-code display
• Future transmission temperature display
• Future tilt/roll sensor display
• Future off-road screen
• Vehicle status visualization

The dashboard must not own relay state, BMS state, alarm authority, or persistent cargo-controller configuration.

v1 Communications

Current planned v1 path:

Dashboard ESP32-S3
        <-> WiFi / HTTP REST
Cargo ESP32 AP
        <-> control outputs
Automotive load-switching layer
        <-> fused loads
Fridge / Starlink / lights / spare outputs

Not planned for v1 controller-to-dashboard communication:

• ESP-NOW
• MQTT
• CAN between controllers
• UART between dashboard and Cargo ESP

MQTT may be considered later for optional Home Assistant, Grafana, InfluxDB, or home-server integrations, but it is not the v1 dashboard link.

Power Distribution

Current v1 assumption:

Cargo ESP32 control outputs
        ↓
Automotive load-switching layer
        ↓
Properly fused loads:
- Fridge
- Starlink
- Lights
- Spare

The ESP32 relay board must not directly carry fridge, Starlink, inverter, compressor, or lighting load current.

The exact load-switching hardware is not finalized yet. Candidate implementation options include:

• Bosch-style automotive relays
• WUPP-style fused relay/distribution module
• Smart high-side switching
• Future custom PCB

Hardware Wishlist / Future

Keep these separate from committed architecture until explicitly promoted:

• BNO085/BNO086 tilt sensor
• CAN sniffing
• Fault-code support
• Standalone dashboard mode
• Additional outputs
• Custom PCB
• Smart high-side switching
• GPS
• microSD logging
• Home Assistant / MQTT / Grafana / InfluxDB