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