docs: clarify controller roles and load switching boundaries

2026-06-09 00:41:52 -06:00
parent 6acfa61ddb
commit 9cb06b86ff
8 changed files with 207 additions and 0 deletions
@@ -210,3 +210,25 @@ Current Cargo ESP32 GPIO plan:
 - GPIO 21: SSD1306 OLED I2C SDA
 - GPIO 22: SSD1306 OLED I2C SCL
 - GPIO 25: OLED setup/status button
+
+## Role Boundary Summary
+
+See `docs/controller-roles.md` for the authoritative role split.
+
+Committed v1 architecture:
+
+    Dashboard ESP32-S3
+            <-> WiFi / HTTP REST
+    Cargo ESP32 AP
+            <-> control outputs
+    Automotive load-switching layer
+            <-> fused loads
+    Fridge / Starlink / lights / spare outputs
+
+The Cargo ESP32 owns power-system control.
+
+The Dashboard ESP32-S3 renders the touchscreen UI and future vehicle visualization.
+
+For v1, controller-to-dashboard communication is WiFi/HTTP only. ESP-NOW, MQTT, UART, and CAN-between-controllers are not part of the v1 dashboard link.
+
+The load-switching hardware is not finalized. Bosch relays, WUPP-style modules, smart high-side switching, or a future custom PCB remain implementation options until explicitly selected.
@@ -146,3 +146,13 @@ Current Cargo ESP32 GPIO plan:
 - GPIO 21: SSD1306 OLED I2C SDA
 - GPIO 22: SSD1306 OLED I2C SCL
 - GPIO 25: OLED setup/status button
+
+## Current Architecture Guardrails
+
+- Inspect the repo before proposing code or documentation changes.
+- Preserve the Cargo ESP vs Dashboard ESP32-S3 role split.
+- Cargo ESP32 does not own CAN, OBD-II, tilt sensing, vehicle data, or dashboard rendering.
+- Dashboard ESP32-S3 does not own relay authority, BMS authority, alarm authority, or persistent cargo-controller configuration.
+- v1 dashboard communication is WiFi/HTTP REST only.
+- ESP-NOW, MQTT, UART dashboard link, and CAN-between-controllers are not v1 architecture.
+- Load-switching hardware is not finalized. Bosch relays, WUPP-style fused distribution, smart high-side switching, and custom PCB options remain implementation choices until explicitly selected.
@@ -158,3 +158,30 @@ Current Cargo ESP32 GPIO plan:
 - GPIO 21: SSD1306 OLED I2C SDA
 - GPIO 22: SSD1306 OLED I2C SCL
 - GPIO 25: OLED setup/status button
+
+## Automotive Load-Switching Layer
+
+Current v1 load-control assumption:
+
+    Cargo ESP32
+        -> control outputs
+        -> automotive load-switching layer
+        -> fused loads
+
+Expected fused loads:
+
+- Fridge
+- Starlink
+- Lights
+- Spare output
+
+The ESP32 relay board is treated as a trigger/control layer only. Major load current must be handled by properly fused automotive wiring, relays, contactors, smart high-side switches, or another suitable fused distribution module.
+
+The exact load-switching hardware is not finalized yet.
+
+Candidate options:
+
+- Bosch-style automotive relays
+- WUPP-style fused relay/distribution module
+- Smart high-side switching
+- Future custom PCB
@@ -33,3 +33,5 @@ Archived documents are kept for history, but the primary documents above should
 ## Parity

 - `PARITY_MATRIX.md` - Command parity across USB serial, UART JSON, and HTTP API
+
+- `controller-roles.md` - Cargo ESP vs Dashboard ESP32-S3 responsibility boundaries
@@ -0,0 +1,108 @@
+# 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
@@ -171,3 +171,15 @@ Current Cargo ESP32 GPIO plan:
 - GPIO 21: SSD1306 OLED I2C SDA
 - GPIO 22: SSD1306 OLED I2C SCL
 - GPIO 25: OLED setup/status button
+
+## Not Dashboard Responsibilities
+
+The Dashboard ESP32-S3 does not own:
+
+- Relay state authority
+- BMS connection/configuration
+- Cargo ESP configuration
+- Alarm authority
+- Load-switching output ownership
+
+It may display state and request changes through the Cargo ESP HTTP API, but the Cargo ESP remains the source of truth.
@@ -202,3 +202,15 @@ Current Cargo ESP32 GPIO plan:
 - GPIO 21: SSD1306 OLED I2C SDA
 - GPIO 22: SSD1306 OLED I2C SCL
 - GPIO 25: OLED setup/status button
+
+## Current Role Boundary
+
+The authoritative role split is documented in `docs/controller-roles.md`.
+
+Summary:
+
+- Cargo ESP32: power-system controller, WebUI, REST API, output control, BMS, DS18B20, local config, optional OLED.
+- Dashboard ESP32-S3: touchscreen UI, gauges, future CAN/OBD-II, future tilt/roll/off-road visualization.
+- v1 communications: Dashboard connects to Cargo ESP AP over WiFi/HTTP REST.
+- Not v1 communications: ESP-NOW, MQTT, UART dashboard link, or CAN between controllers.
+- Load-switching hardware is still an implementation choice, not frozen architecture.
@@ -145,3 +145,17 @@ Current Cargo ESP32 GPIO plan:
 - GPIO 21: SSD1306 OLED I2C SDA
 - GPIO 22: SSD1306 OLED I2C SCL
 - GPIO 25: OLED setup/status button
+
+## Future Wishlist Parking Lot
+
+These are intentionally not committed v1 architecture until explicitly promoted:
+
+- BNO085/BNO086 tilt sensor
+- CAN sniffing beyond standard OBD-II polling
+- Fault-code support
+- Standalone dashboard mode
+- Additional cargo outputs
+- Custom PCB
+- Smart high-side switching
+- WUPP-style fused distribution module
+- MQTT/Home Assistant/Grafana/InfluxDB integrations