diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index ec75746..3ba2e9f 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -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. diff --git a/docs/CHATGPT_HANDOFF.md b/docs/CHATGPT_HANDOFF.md index 659582f..ea88228 100644 --- a/docs/CHATGPT_HANDOFF.md +++ b/docs/CHATGPT_HANDOFF.md @@ -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. diff --git a/docs/HARDWARE.md b/docs/HARDWARE.md index 175ba15..29f3ea7 100644 --- a/docs/HARDWARE.md +++ b/docs/HARDWARE.md @@ -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 diff --git a/docs/README.md b/docs/README.md index 7aae532..61994aa 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 diff --git a/docs/controller-roles.md b/docs/controller-roles.md new file mode 100644 index 0000000..46586ae --- /dev/null +++ b/docs/controller-roles.md @@ -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 diff --git a/docs/dashboard-esp32s3.md b/docs/dashboard-esp32s3.md index de2fafb..ff424e0 100644 --- a/docs/dashboard-esp32s3.md +++ b/docs/dashboard-esp32s3.md @@ -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. diff --git a/docs/project-state.md b/docs/project-state.md index d8ee596..373bbc0 100644 --- a/docs/project-state.md +++ b/docs/project-state.md @@ -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. diff --git a/docs/roadmap.md b/docs/roadmap.md index 926c13e..0203005 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -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