Align docs with ESP32-S3 dashboard architecture

HARDWARE.md

@@ -1,30 +1,10 @@
 
 ---
 
-# Relay Wiring
+# Hardware Notes
 
-Current architecture uses the onboard relay contacts
+The current hardware source of truth is `docs/HARDWARE.md`.
-as the load switching device.
 
-Positive-side switching:
+The Cargo ESP32 relay board outputs are control/trigger outputs only. Do not route fridge, Starlink, inverter, lights, or other major load current through the ESP32 relay board.
-
-    Battery +
-        |
-      Fuse
-        |
-      Relay COM
-        |
-      Relay NO
-        |
-      Load +
-
-Load negative returns directly to the ground bus.
-
-Relay 1:
-
-    Starlink Mini
-
-Relay 2:
-
-    Fridge
 
+Use properly fused automotive relays or contactors for major loads.

README.md

@@ -34,15 +34,15 @@ Current controller:
 
 - ESP32 2-relay board
 
-Planned dashboard:
+Primary dashboard target:
 
-- Raspberry Pi Pico 2 W
+- Waveshare ESP32-S3-Touch-LCD-5
-- Touchscreen display
+- WiFi client to the Cargo ESP32 access point
-- UART connection to ESP32
+- HTTP API integration
 
 Optional future expansion:
 
-- Pi Zero 2 W for advanced logging/charts/web app
+- Pi Zero for long-term logging, charts, and local integrations
 
 ## WebUI
 
@@ -68,22 +68,26 @@ The Config tab is the preferred initial setup workflow.
 
 The ESP32 is the source of truth.
 
-The Pico dashboard will be an instant-on physical display and control surface.
+The Waveshare ESP32-S3 dashboard is a client-only local display and control surface.
 
 The WebUI is used for setup, configuration, and phone access from camp.
 
+A future Pi Zero may be added for long-term logging or richer local integrations, but it must not become required for core control.
+
 ## Documentation
 
 Important docs:
 
 - `docs/project-state.md`
-- `docs/api.md`
+- `docs/API.md`
+- `docs/ARCHITECTURE.md`
+- `docs/HARDWARE.md`
 - `docs/UART_PROTOCOL.md`
 - `docs/SERIAL_COMMANDS.md`
 - `docs/PARITY_MATRIX.md`
 - `docs/wiring.md`
 - `docs/TEMP_SETUP.md`
-- `docs/roadmap.md`
+- `docs/ROADMAP.md`
 - `docs/CHANGELOG.md`
 
 ## Safety
@@ -99,4 +103,4 @@ Use:
 - Strain relief
 - Testing before connecting expensive loads
 
-Do not connect vehicle 12V directly to ESP32 or Pico GPIO pins.
+Do not connect vehicle 12V directly to ESP32 GPIO pins or dashboard GPIO pins.

docs/API.md

@@ -264,7 +264,7 @@ Design limits:
 - No large assets
 - No heavy JavaScript framework
 
-The embedded dashboard is intended as a convenient phone view, not a replacement for the physical Pico dashboard.
+The embedded dashboard is intended as a convenient phone view and setup interface. It does not replace the planned Waveshare ESP32-S3 physical dashboard.
 
 ---
 
@@ -637,11 +637,15 @@ Request:
     {
       "id": "relay_1",
       "state": true
-    }\n\n### Weather temperature sensor flag
+    }
+
+### Weather temperature sensor flag
 
 Temperature sensor config entries now include `weather: true`.
 
-When a configured temp sensor has `weather: true`, the WebUI may show it as the outside/weather temperature badge. The `/status` temp objects also include this flag so HTTP, UART, USB serial, and future Pico clients can identify the selected outside-air sensor without guessing from the sensor name.\n\n\n### Clear temperature assignments
+When a configured temp sensor has `weather: true`, the WebUI may show it as the outside/weather temperature badge. The `/status` temp objects also include this flag so HTTP, UART, USB serial, and dashboard clients can identify the selected outside-air sensor without guessing from the sensor name.
+
+### Clear temperature assignments
 
 `POST /temps/clear`
 
@@ -651,4 +655,4 @@ Request body options:
 - `{ "slot": 1 }` clears one logical temp slot by number.
 - Empty POST body clears all temp assignments.
 
-Clearing removes the stored DS18B20 address, disables the slot, clears the weather flag, resets cached temperature state, and persists config.\n
+Clearing removes the stored DS18B20 address, disables the slot, clears the weather flag, resets cached temperature state, and persists config.

docs/ARCHITECTURE.md

@@ -93,11 +93,9 @@ HTTP is the primary integration contract for:
 
 Preferred direction:
 
-    GET  /api/status
+    GET  /status
-    GET  /api/config
+    GET  /config
-    POST /api/relays/relay_1/on
+    POST /relay/set
-    POST /api/relays/relay_1/off
-    POST /api/relays/relay_1/toggle
 
 Future versioning may move to /api/v1.
 

docs/CHANGELOG.md

@@ -27,8 +27,8 @@
 
 - ESP32 remains the controller/source of truth.
 - WebUI is now the preferred initial configuration workflow.
-- Pico dashboard remains planned as the instant-on physical dashboard.
+- Waveshare ESP32-S3 is the primary physical dashboard target.
-- Built-in ESP32 relays are the current planned relay switching method for Starlink Mini and fridge.
+- ESP32 relay board outputs are treated as control/trigger outputs for external fused automotive relays/contactors on major loads.
 - BMS source now reports configured JBD BMS even when disconnected.
 
 ### Fixed

docs/CONFIGURATION.md

@@ -9,7 +9,7 @@ Configuration survives reboot.
 - Keep firmware generic
 - Store installation-specific names in config
 - Support multiple vehicle/camper layouts
-- Allow setup from serial, HTTP, and eventually Pico UART
+- Allow setup from HTTP/WebUI and service interfaces
 - Avoid hardcoded device names, relay names, sensor names, or BMS names
 
 ## Stored Configuration

docs/HANDOFF.md

@@ -1,5 +1,17 @@
 # Overland Controller Handoff
 
+This handoff is stale and may include legacy Pico/UART dashboard assumptions.
+
+Current source of truth:
+
+- `docs/ARCHITECTURE.md`
+- `docs/HARDWARE.md`
+- `docs/ROADMAP.md`
+- `docs/API.md`
+- `docs/dashboard-esp32s3.md`
+
+The current dashboard target is the Waveshare ESP32-S3-Touch-LCD-5 over WiFi/HTTP. No Pico dashboard is planned.
+
 ## Current Version
 
 Firmware: 0.4.0
@@ -153,4 +165,6 @@ Important:
 
 - ESP32 cargo controller remains source of truth.
 - Dashboard is a client only.
-- Existing UART protocol remains supported but is no longer the primary dashboard transport.\n\nSee docs/dashboard-esp32s3.md for the current Waveshare ESP32-S3 dashboard plan.\n
+- Existing UART protocol remains supported but is no longer the primary dashboard transport.
+
+See `docs/dashboard-esp32s3.md` for the current Waveshare ESP32-S3 dashboard plan.

docs/PARITY_MATRIX.md

@@ -105,4 +105,6 @@ Future additions must be implemented on:
     UART JSON
     HTTP API
 
-before parity is considered maintained.\n\n- Temperature sensor config/status parity now includes the `weather` boolean flag for outside-air display selection.\n
+before parity is considered maintained.
+
+- Temperature sensor config/status parity now includes the `weather` boolean flag for outside-air display selection.

docs/README.md

@@ -19,8 +19,9 @@ This folder contains project documentation for Overland Controller.
 
 ## Technical References
 
-- `protocol.md` - Dashboard/controller protocol
+- `dashboard-esp32s3.md` - Current Waveshare ESP32-S3 dashboard plan
-- `wiring.md` - Wiring notes and plans
+- `protocol.md` - Legacy UART protocol reference
+- `wiring.md` - Older wiring notes; verify against `HARDWARE.md` before use
 
 ## Archive
 

docs/UART_PROTOCOL.md

@@ -1,8 +1,10 @@
 # UART Protocol
 
-The Pico dashboard communicates with the ESP32 controller over UART.
+This document describes the optional UART JSON protocol supported by the ESP32 controller.
 
-UART is the primary dashboard/control link. HTTP should mirror the same concepts, but the Pico should be able to operate the controller without WiFi.
+UART is not the primary dashboard/control link. The current dashboard target is the Waveshare ESP32-S3 display over WiFi/HTTP.
+
+Keep this protocol for diagnostics, simulator work, service tools, or alternate clients. Do not treat it as evidence that a Pico dashboard is planned.
 
 ## Serial Settings
 
@@ -41,7 +43,7 @@ Temperature sensors:
 
 ## Status Request
 
-Pico sends:
+Client sends:
 
     {"type":"status_request"}
 
@@ -49,7 +51,7 @@ ESP32 responds with the same shape as HTTP /status.
 
 ## Relay Control
 
-Pico sends:
+Client sends:
 
     {"type":"set_relay","relay":"relay_1","enabled":true}
 
@@ -59,7 +61,7 @@ ESP32 responds:
 
 ## Config Request
 
-Pico sends:
+Client sends:
 
     {"type":"config_request"}
 
@@ -69,37 +71,37 @@ ESP32 responds:
 
 ## Device Name Update
 
-Pico sends:
+Client sends:
 
     {"type":"config_device","device_name":"Overland Controller"}
 
 ## Relay Config Update
 
-Pico sends:
+Client sends:
 
     {"type":"config_relay","id":"relay_1","name":"Aux Power","enabled":true}
 
 ## Temperature Sensor Config Update
 
-Pico sends:
+Client sends:
 
     {"type":"config_temp","id":"temp_1","name":"Cabin","address":"","enabled":true}
 
 ## BMS Config Update
 
-Pico sends:
+Client sends:
 
     {"type":"config_bms","enabled":true,"name":"House Battery","address":"aa:bb:cc:dd:ee:ff","address_type":"public"}
 
 ## Save Config
 
-Pico sends:
+Client sends:
 
     {"type":"save_config"}
 
 ## Factory Reset
 
-Pico sends:
+Client sends:
 
     {"type":"factory_reset"}
 
@@ -156,14 +158,14 @@ The UART protocol should eventually support the same management capabilities as
 
 ## Notes
 
-- UART is the preferred dashboard/control path.
+- HTTP is the preferred dashboard/control path.
-- HTTP is useful for setup, debugging, and future web UI.
+- UART is useful for diagnostics and alternate clients.
 - USB serial remains the emergency service/debug interface.
-- The Pico should not depend on WiFi for normal control.
+- No Pico dashboard is currently planned.
 
 ## WiFi Config Request
 
-Pico sends:
+Client sends:
 
     {"type":"wifi_request"}
 
@@ -173,19 +175,19 @@ ESP32 responds:
 
 ## WiFi Config Update
 
-Pico sends:
+Client sends:
 
     {"type":"config_wifi","ssid":"Starlink","password":"password_here"}
 
 ## WiFi Connect
 
-Pico sends:
+Client sends:
 
     {"type":"wifi_connect"}
 
 ## WiFi Clear
 
-Pico sends:
+Client sends:
 
     {"type":"wifi_clear"}
 
@@ -239,7 +241,7 @@ Lower priority numbers are tried first.
 
 ## Scan Temperature Sensors
 
-Pico sends:
+Client sends:
 
     {"type":"scan_temps"}
 
@@ -249,7 +251,7 @@ ESP32 responds:
 
 ## Assign Temperature Sensor
 
-Pico sends:
+Client sends:
 
     {"type":"assign_temp","id":"temp_1","index":1}
 
@@ -259,14 +261,16 @@ Alternative:
 
 ## Clear Temperature Sensor
 
-Pico sends:
+Client sends:
 
     {"type":"clear_temp","id":"temp_1"}
 
 Alternative:
 
-    {"type":"clear_temp","slot":1}\n\n### Temperature weather flag
+    {"type":"clear_temp","slot":1}
+
+### Temperature weather flag
 
 `status_response.config.temperature_sensors[]` and `status_response.temps[]` include `weather: false`.
 
-`config_temp` may include `weather: true` to mark one configured sensor as the outside/weather sensor. Pico clients should treat this as optional and default missing values to `false`.\n
+`config_temp` may include `weather: true` to mark one configured sensor as the outside/weather sensor. Clients should treat this as optional and default missing values to `false`.

docs/dashboard-esp32s3.md

@@ -29,21 +29,18 @@ Primary transport:
 - HTTP JSON API
 
 Not required for normal dashboard operation:
-- Pico UART
 - MicroPython display drivers
 - CAT5e UART data pair
 
-UART JSON remains useful for future diagnostics, alternate displays, or debug clients.
+UART JSON remains useful for diagnostics, alternate displays, or debug clients, but it is not part of the planned dashboard path.
 
 ## Power
 
 Dashboard power path:
 
-Cargo area 12V
+ACC switched 12V
-→ CAT5e power pair(s)
+-> fuse
-→ Dash enclosure
+-> Waveshare VIN
-→ Buck converter
-→ 5V dashboard input
 
 All grounds remain common.
 
@@ -149,8 +146,6 @@ Later:
 - WebUI Config tab remains the preferred setup workflow.
 - Cargo ESP32 should continue to work without the dashboard powered on.
 
-## Deferred Pico Path
+## Out of Scope
 
-The Pico 2 W dashboard plan is deferred.
+No Pico dashboard is planned. Existing Pico/UART material is legacy unless explicitly revived for diagnostics or alternate hardware.
-
-Keep existing UART protocol docs because UART remains useful, but new dashboard work should target the ESP32-S3 display first.

docs/decisions.md

@@ -20,38 +20,45 @@ Reason:
 
 The ESP32 is installed near the electrical system and should continue operating even if the dashboard is disconnected.
 
-## Decision: Pico Is a Dashboard, Not the Controller
+## Decision: Waveshare ESP32-S3 Is the Dashboard Client
 
-The Pico dashboard is responsible for user interaction.
+The Waveshare ESP32-S3 touchscreen dashboard is responsible for local user interaction.
 
-It should not own critical control state.
+It connects to the Cargo ESP32 access point and consumes the HTTP API. It should not own critical control state.
 
 Reason:
 
 The dashboard may reboot, disconnect, or be removed without disabling the controller.
 
-## Decision: UART Is the Primary Dashboard Link
+## Decision: HTTP Is the Primary Dashboard Link
 
-UART is the preferred Pico-to-ESP32 communication path.
+HTTP over the Cargo ESP32 local WiFi network is the preferred dashboard-to-controller communication path.
 
 Reason:
 
-- Simple wiring
+- Matches the WebUI and future integration contract
-- Deterministic
+- Avoids a dedicated dashboard data cable
-- No WiFi dependency
+- Supports the Waveshare ESP32-S3 dashboard target
-- Works offline
+- Keeps the dashboard a simple client
-- Easier to debug electrically
 
-HTTP remains useful for setup, debugging, and future web UI.
+The Cargo ESP32 AP remains available for local operation without internet.
+
+## Decision: UART Is Optional Diagnostics
+
+UART JSON may remain useful for service diagnostics, simulator work, or alternate clients.
+
+Reason:
+
+USB serial and UART are useful recovery/debug paths, but the dashboard architecture should not depend on a Pico or UART cable.
 
 ## Decision: HTTP and UART Should Share a Data Model
 
 The same status/config model should be used across:
 
-- UART
 - HTTP
 - Simulator
 - Future MQTT/Home Assistant integrations
+- Optional UART diagnostics
 
 Reason:
 
@@ -177,3 +184,13 @@ Cloud dashboards and remote access are not current priorities.
 Reason:
 
 The core controller/dashboard system should be reliable locally before remote features are considered.
+
+## Decision: Future Pi Zero Is Optional
+
+A Pi Zero may be added later for long-term logging, charts, dashboards, or local integrations.
+
+It must not own relay control, BMS state, alarm authority, or persistent controller configuration.
+
+Reason:
+
+The Cargo ESP32 must continue operating as the controller and source of truth without any higher-level computer powered on.

docs/hardware-status.md

@@ -2,6 +2,10 @@
 
 Last Updated: 2026-06-03
 
+This document is stale and records earlier hardware ordering/status notes. Current hardware direction is documented in `docs/HARDWARE.md` and `docs/dashboard-esp32s3.md`.
+
+The current dashboard target is the Waveshare ESP32-S3-Touch-LCD-5 over WiFi/HTTP. No Pico dashboard is planned.
+
 --------------------------------------------------
 
 ## Dashboard Hardware

docs/project-state.md

@@ -1,6 +1,6 @@
 # Project State
 
-Last updated: 2026-06-04
+Last updated: 2026-06-07
 
 ## Version
 
@@ -18,11 +18,11 @@ Core controller:
 
 Current dashboard plan:
 
-    Raspberry Pi Pico 2 W physical dashboard over UART
+    Waveshare ESP32-S3-Touch-LCD-5 over WiFi/HTTP
 
 Optional future expansion:
 
-    Pi Zero 2 W for advanced logging, charts, and integrations
+    Pi Zero for long-term logging, charts, and local integrations
 
 ## ESP32 Responsibilities
 
@@ -36,7 +36,7 @@ The ESP32 is the source of truth for:
 - Embedded WebUI
 - WiFi AP recovery network
 - WiFi STA client mode
-- UART protocol for future Pico dashboard
+- Optional UART JSON protocol for diagnostics or alternate clients
 
 ## Current Working Features
 
@@ -117,15 +117,11 @@ Current rear enclosure target:
 
 Relay strategy:
 
-    Battery positive -> fuse -> relay COM -> relay NO -> load positive
+    ESP32 relay board output
-    Load negative -> ground bus
+      -> external fused automotive relay or contactor trigger
+      -> fused load circuit
 
-The built-in relays are currently planned for:
+The ESP32 relay board outputs are control/trigger outputs only. Fridge, Starlink, inverter, and other major loads must use properly fused automotive relay or contactor circuits.
-
-- Starlink Mini
-- 12V fridge
-
-External automotive relays remain a future option for higher-current loads.
 
 ## Temperature Sensor Direction
 
@@ -159,11 +155,16 @@ Examples:
 1. Verify WebUI setup workflow after fresh flash.
 2. Clean up DS18B20 physical distribution hardware.
 3. Test 2-4 temperature probes after distribution board is installed.
-4. Start Pico dashboard MVP over UART.
+4. Start Waveshare ESP32-S3 dashboard MVP over WiFi/HTTP.
 5. Add config backup/restore.
 6. Improve BMS out-of-range behavior without changing NimBLE connect timeout.
+7. Define future Pi Zero logging/integration role without moving control authority off the Cargo ESP32.
 
-- Fixed WebUI temperature probe scan by registering `/temps/scan`, `/temps/assign`, and `/temps/clear` firmware routes.\n\n- Added per-temperature-sensor `weather` flag and WebUI outside temperature badge with emoji thresholds: below 50°F ice, 50-74°F happy, 75-84°F sun, and 85°F+ fire.\n\n- Improved WebUI temperature sensor config checkbox layout with compact On/Weather controls.\n\n- Temperature probe assignment now enforces one logical slot per physical DS18B20 address; assigning a probe to a new slot clears the old slot mapping.\n\n- Added per-slot WebUI Clear buttons for temperature probe assignments using the existing `/temps/clear` API.\n\n- Fixed weather temp checkbox persistence by saving the `weather` flag from WebUI temp config and auto-saving checkbox changes.\n\n- Fixed temperature assignment clearing so Clear removes the stored DS18B20 address, disables the slot, clears weather flag, and resets cached temp state.\n\n- Hardened `/temps/clear` so clearing a temp slot removes the persisted DS18B20 address, disables the slot, clears weather flag, resets cached temp state, and supports clearing all slots with an empty POST body.\n\n- Removed legacy physical-scan-order fallback for unassigned DS18B20 slots; enabled slots now require an explicit assigned address before reporting a value.\n\n- Filtered DS18B20 scan results so already-assigned probe addresses are hidden until cleared from their configured temp slot.\n\n- Moved WebUI Temperature Assignment card directly above Temperature Sensor Config for better setup flow.\n\n- Added read-only assigned DS18B20 address display under each WebUI temperature config slot.\n\n- Fixed DS18B20 scan filtering so assigned probes are hidden from assignment results without removing them from runtime polling.\n\n- Dashboard temperature list now hides disabled, unassigned, offline, or invalid temp slots while keeping all slots visible in Config.\n\n- Fixed dashboard temp filtering to avoid requiring address in runtime temp payload.\n\n- Fixed WebUI temp config so the On checkbox fully controls whether each temp slot is enabled.\n\n- Restored Overview relay control rendering after dashboard temp layout changes.\n\n- Fixed Overview relay buttons to call the existing `relay()` WebUI handler instead of missing `setRelay()`.\n\n- Restored Overview relay controls to separate ON and OFF buttons per relay.\n
+Recent notes:
+
+- WebUI temperature scan, assign, clear, and weather/outside-air selection are implemented.
+- DS18B20 slots now require explicit assigned addresses before reporting values.
+- Relay controls and temperature configuration remain driven by generic IDs plus saved configuration names.
 
 
 ## Dashboard Architecture Update
@@ -181,4 +182,6 @@ Dashboard Client:
 → Consumes existing HTTP API
 → Planned LVGL-based dashboard UI
 
-The Raspberry Pi Pico 2 W dashboard path is no longer the primary implementation target. UART JSON remains supported as an optional interface for future expansion, debugging, or alternate dashboard hardware.\n\n- Added dedicated ESP32-S3 dashboard planning document covering architecture, API use, LVGL screens, connection flow, and deferred Pico path.\n
+There is no planned Pico dashboard path. Existing Pico/UART files are legacy artifacts unless explicitly revived later.
+
+UART JSON remains optional for diagnostics or alternate clients. New dashboard work should target the Waveshare ESP32-S3 display and the HTTP API.

docs/protocol.md

@@ -1,10 +1,10 @@
-# ESP32 ↔ Pico Communication Protocol
+# Legacy UART Communication Protocol
 
 ## Current Decision
 
-Primary communication is **UART over CAT5**.
+Primary dashboard communication is **WiFi HTTP API** between the Waveshare ESP32-S3 dashboard and the Cargo ESP32.
 
-Backup communication is the **ESP32 WiFi HTTP API**.
+This legacy UART protocol is retained for historical reference, diagnostics, simulator work, or alternate clients. It is not the current dashboard architecture.
 
 RS-485/MAX3485 is fallback-only and is not currently planned.
 
@@ -14,7 +14,7 @@ RS-485/MAX3485 is fallback-only and is not currently planned.
 * Baud: 115200
 * Format: 8N1
 * Framing: newline-delimited JSON
-* Direction: Pico dashboard ↔ ESP32 cargo controller
+* Direction: UART client ↔ ESP32 cargo controller
 
 ## Message Rules
 
@@ -28,7 +28,7 @@ Example:
 
 Responses should also be one JSON object followed by a newline.
 
-## Pico → ESP32 Messages
+## Client → ESP32 Messages
 
 ### Status Request
 
@@ -68,7 +68,7 @@ Expected response:
 }
 ```
 
-## ESP32 → Pico Messages
+## ESP32 → Client Messages
 
 ### Status Response
 

docs/roadmap.md

@@ -1,526 +1,62 @@
 # Roadmap
 
-This roadmap tracks planned Overland Controller development.
+## Phase 1: Solid Local Cargo Controller
 
-The roadmap is flexible and may change as the project evolves.
+- Reliable relay control
+- Reliable DS18B20 temps
+- Reliable JBD/Xiaoxiang BMS BLE
+- WPA2 AP mode
+- Stable WebUI
+- Stable HTTP API
+- Clear status/config/control model
 
-## Phase 1: ESP32 Controller Foundation
+## Phase 2: Waveshare ESP32-S3 Dashboard
 
-Status: mostly complete
+- LVGL project scaffold
-
+- WiFi client to Cargo ESP32 AP
-Goals:
+- Poll /status
-
+- Display battery, relays, temps, and alarms
-- Establish ESP32 firmware structure
-- Implement relay control
-- Implement status reporting
-- Implement local configuration
-- Implement BMS telemetry
-- Implement generic relay/sensor naming
-- Establish HTTP and UART communication models
-
-Completed:
-
-- Relay control
-- JSON status API
-- Configuration persistence
-- Factory reset
-- BMS BLE telemetry
-- Cell voltage telemetry
-- Generic relay IDs
-- Generic temperature sensor IDs
-- HTTP API
-- Serial console commands
-- Documentation cleanup
-
-Remaining:
-
-- Finish UART parity
-- Improve BLE setup reliability
-- Add stronger config validation
-- Add better command help output
-
-## Phase 2: UART Parity
-
-Status: next priority
-
-Goal:
-
-The Pico dashboard should be able to configure and control the ESP32 over UART without relying on WiFi.
-
-Minimum UART v1 messages:
-
-- status_request
-- set_relay
-- config_request
-- config_device
-- config_relay
-- config_temp
-- config_bms
-- save_config
-- factory_reset
-- enter_bms_setup
-- scan_ble
-- select_bms
-- exit_bms_setup
-
-Expected result:
-
-The Pico can:
-
-- Read full system status
-- Display current configuration
-- Control relays
-- Rename relays
-- Rename temperature sensors
-- Configure BMS
-- Run BMS setup workflow
-- Save configuration
-
-## Phase 3: Temperature Sensors
-
-Status: partially started
-
-Goals:
-
-- Complete DS18B20 hardware wiring
-- Add proper 4.7k pull-up resistor
-- Detect connected sensors
-- Report sensor addresses
-- Assign sensors to config slots
-- Persist sensor address assignments
-
-Planned serial commands:
-
-- scan temps
-- assign temp 1 <address>
-- clear temp 1
-
-Planned UART messages:
-
-- scan_temps
-- assign_temp
-- clear_temp
-
-Expected result:
-
-A user can connect multiple DS18B20 sensors, identify each one, name it, and save the configuration.
-
-## Phase 4: Pico Dashboard Bring-Up
-
-Status: not started on hardware
-
-Goals:
-
-- Bring up Pico 2 W
-- Bring up touchscreen
-- Establish UART connection to ESP32
-- Display status response
-- Display battery data
-- Display relay states
-- Display temperature data
 - Send relay commands
+- Handle offline/stale/failed-command states
 
-Initial dashboard screens:
+UI direction:
 
-- Main overview
+- Dark theme
-- Battery screen
+- Large readable text
-- Temperature screen
+- Circular SOC gauge
-- Relay control screen
+- Card-based layout
-- Settings screen
+- Smooth subtle animations
+- No stock LVGL demo look
 
-## Phase 5: Pico Configuration UI
+## Phase 3: Vehicle Data
 
-Status: planned
+- Connect Waveshare CAN to OBD-II CAN-H/CAN-L
+- Keep CAN termination disabled
+- Read coolant temp via PID 0105
+- Read RPM via PID 010C
+- Read vehicle speed via PID 010D
 
-Goals:
+## Phase 4: Transmission Temperature
 
-- Configure device name
+- Install dedicated sender
-- Configure relay names
+- Read through exposed ADC or ADS1115 over I2C
-- Configure temperature names
+- Convert resistance to temp with lookup interpolation
-- Configure BMS
+- Add alert thresholds
-- Run BLE scan workflow
-- Save config
-- Factory reset
 
-Expected result:
+## Phase 5: Future Home Server
 
-A new installation can be configured from the dashboard without using a laptop.
+- Cargo ESP32 outbound connection
+- Remote read-only dashboard first
+- Optional commands later
+- HTTPS reverse proxy/PWA
+- Possible MQTT/WebSocket bridge
+- Optional Grafana/Home Assistant/InflDB
 
-## Phase 6: Vehicle Inputs
+## Phase 6: Optional Enhancements
 
-Status: planned
+- microSD logging
-
-Possible inputs:
-
-- Ignition signal
-- Vehicle battery voltage
-- OBD-II
-- CAN bus
 - GPS
-
+- OTA updates
-Potential data:
+- Dashboard alert sounds
-
+- More vehicle PIDs
-- Ignition state
+- Historical charts
-- Engine RPM
-- Coolant temperature
-- Vehicle speed
-- Fuel level
-- Diagnostic trouble codes
-- Location
-- Trip data
-
-## Phase 7: Logging and History
-
-Status: planned
-
-Goals:
-
-- Log battery history
-- Log temperature history
-- Log relay events
-- Log alarm events
-- Show historical charts
-
-Possible storage:
-
-- ESP32 flash
-- SD card
-- External service
-- Future InfluxDB integration
-
-## Phase 8: Integrations
-
-Status: planned
-
-Potential integrations:
-
-- MQTT
-- Home Assistant
-- Grafana
-- InfluxDB
-- Node-RED
-
-Design goal:
-
-Integrations should consume the same generic status/config model used by HTTP and UART.
-
-## Phase 9: Enclosure and Installation
-
-Status: planned
-
-Goals:
-
-- Design ESP32 enclosure
-- Design Pico dashboard enclosure
-- Design wiring harness
-- Document installation
-- Create BOM
-- Create printable STL files
-- Validate thermal and vibration behavior
-
-## Phase 10: Public Release
-
-Status: future
-
-Goals:
-
-- Clean documentation
-- Stable API
-- Stable UART protocol
-- Installation guide
-- Wiring guide
-- Build guide
-- Example configurations
-- Versioned releases
-
-Potential release name:
-
-    Overland Controller v1.0
-
-## Long-Term Ideas
-
-Potential future features:
-
-- OTA firmware updates
-- Multi-controller support
-- Expansion modules
-- Water tank monitoring
-- Inverter monitoring
-- Solar charge controller monitoring
-- Starlink diagnostics
-- Bluetooth sensor support
-- Mobile web dashboard
-- Plugin-style integrations
-
----
-
-## Networking Roadmap
-
-### Current
-
-The ESP32 currently operates as a local access point.
-
-Default local access:
-
-    http://192.168.4.1
-
-This provides a reliable recovery/setup path even when no other WiFi network is available.
-
-### Planned: AP + STA Mode
-
-The ESP32 should support AP and STA mode at the same time.
-
-Access Point mode:
-
-    Overland-Controller
-    192.168.4.1
-
-Station mode:
-
-    Connects to a configured WiFi network such as Starlink, home WiFi, or shop WiFi.
-
-The AP should remain enabled even when STA mode is connected.
-
-Reason:
-
-- Always available recovery path
-- Easier setup
-- Less risk of locking yourself out
-- Useful when Starlink/home WiFi is unavailable
-
-### Planned: Multiple Saved WiFi Networks
-
-The controller should eventually support multiple saved WiFi profiles.
-
-Example priority order:
-
-    1. Starlink
-    2. Home WiFi
-    3. Shop WiFi
-
-Expected boot behavior:
-
-    Start AP
-    Try Starlink
-    If Starlink fails, try Home WiFi
-    If Home WiFi fails, try Shop WiFi
-    If all fail, remain AP-only
-
-The ESP32 only connects to one STA network at a time, but it can remember and try multiple networks.
-
-### Planned WiFi Configuration
-
-Future configuration should include:
-
-    ap_enabled
-    sta_enabled
-    hostname
-    saved networks
-    priority order
-
-Future setup options:
-
-- Serial console
-- HTTP API
-- Pico dashboard UI
-- Embedded web dashboard
-
-### Planned mDNS
-
-The controller should eventually support mDNS.
-
-Example:
-
-    http://overland-controller.local
-
-This would avoid needing to look up the controller IP when connected through Starlink or home WiFi.
-
----
-
-## Embedded Web Dashboard
-
-### Current Direction
-
-The ESP32 should serve a lightweight mobile-friendly dashboard.
-
-Purpose:
-
-- Check battery status from a phone
-- Check fridge/temp status from camp
-- Toggle relays if needed
-- View alarms
-- Provide fallback UI without the Pico display
-
-Design limits:
-
-- No React
-- No external libraries
-- No images
-- Small inline HTML/CSS/JS
-- Poll /status every few seconds
-- Use existing relay endpoints
-
-This dashboard is not intended to replace the physical Pico dashboard.
-
----
-
-## Optional Future Pi Zero Module
-
-The base system should not require a Pi Zero.
-
-Base system:
-
-    ESP32 controller
-    Pico 2 W dashboard
-
-Optional future advanced module:
-
-    Pi Zero 2 W
-
-Possible Pi Zero functions:
-
-- Rich web dashboard
-- Historical logging
-- Graphs
-- SQLite database
-- MQTT bridge
-- Home Assistant bridge
-- Advanced configuration UI
-
-The core controller should remain functional without the Pi Zero.
-
----
-
-## Configuration Backup and Restore
-
-Planned future feature.
-
-Goals:
-
-- Export configuration JSON
-- Import configuration JSON
-- Backup install-specific setup
-- Restore after factory reset
-- Make support easier for future users
-
-This is important if the project becomes shareable or sellable.
-
-
----
-
-## Post-0.4.0 Roadmap
-
-### Near Term
-
-- Verify complete WebUI setup workflow.
-- Add config backup/export/import.
-- Improve BMS out-of-range behavior without reducing NimBLE connection reliability.
-- Build permanent DS18B20 distribution board.
-- Test multiple temperature probes.
-- Update enclosure wiring layout.
-
-### Pico Dashboard MVP
-
-- UART status request.
-- Battery summary screen.
-- Temperature screen.
-- Relay control screen.
-- Alarm indicators.
-- Screen sleep based on ignition signal later.
-
-### Future
-
-- mDNS hostname.
-- OTA update workflow.
-- Optional Pi Zero logging module.
-- Historical graphs.
-- MQTT/Home Assistant bridge.
-- Ignition sense.
-- House battery voltage sense.
-
----
-
-## Pico Dashboard MVP Plan
-
-MVP means Minimum Viable Product.
-
-Goal:
-
-    Prove Pico 2 W can reliably read ESP32 status over UART and display live data.
-
-Phase 1:
-
-- MicroPython on Pico 2 W / RP2350
-- UART to ESP32 dashboard UART
-- USB debug output
-- Request status from ESP32
-- Parse status JSON
-
-Phase 2:
-
-- ST7796S display bring-up
-- Backlight control
-- Hello World screen
-- Static dashboard layout
-
-Phase 3:
-
-- Live battery card
-- Runtime / time-to-full card
-- Temperature list
-- Relay state list
-- ESP32 connection indicator
-
-Phase 4:
-
-- Touch support using FT6336U
-- Page navigation
-- Relay controls
-- Alarm details
-
-Do not start with touch or config UI on the Pico. The WebUI is the preferred configuration workflow.
-
-
-
-## Revised Dashboard Roadmap
-
-### Phase 1
-ESP32 cargo controller backend
-- WiFi
-- WebUI
-- Relay control
-- JBD/Xiaoxiang BMS
-- DS18B20
-- Config persistence
-
-### Phase 2
-Waveshare 5" ESP32-S3 Dashboard
-- Connect to cargo ESP AP
-- Read /status API
-- Basic dashboard
-- Battery SOC
-- Voltage/current
-- Temps
-- Relay status
-
-### Phase 3
-LVGL Dashboard UI
-- Touch support
-- Relay controls
-- Alarm screens
-- Config/status pages
-
-### Phase 4
-Extended Vehicle Telemetry
-- OBD-II
-- Coolant temp
-- GPS
-- Trip data
-- Vehicle metrics
-
-### Phase 5
-Advanced Integrations
-- Home Assistant
-- MQTT
-- Grafana
-- InfluxDB\n\n- Added docs/dashboard-esp32s3.md as the primary dashboard implementation plan for the Waveshare 5 inch ESP32-S3 display.\n

docs/wiring.md

@@ -1,16 +1,22 @@
 # Wiring
 
-This document describes the current planned wiring for the Overland Controller install.
+This document contains older wiring notes and may include legacy Pico/UART dashboard assumptions.
 
-The current system uses:
+Current dashboard and hardware source of truth:
 
-- ESP32 2-relay controller board
+- `docs/HARDWARE.md`
-- Raspberry Pi Pico 2 W dashboard
+- `docs/dashboard-esp32s3.md`
-- CAT5/CAT6 cable between rear controller and dash
+
-- 12V-to-5V buck converter in the dash enclosure
+Do not use Pico-specific wiring in this file for the current dashboard build.
+
+Current planned system uses:
+
+- Cargo ESP32 2-relay controller board
+- Waveshare ESP32-S3-Touch-LCD-5 dashboard over WiFi/HTTP
+- ACC switched 12V fused dashboard power into Waveshare VIN
 - DS18B20 temperature sensors
 - JBD/Xiaoxiang BMS over BLE
-- External automotive relays for high-current loads
+- External fused automotive relays or contactors for major loads
 
 ---
 

hardware/bom.md

@@ -2,15 +2,13 @@
 
 ## Ordered
 
-- Raspberry Pi Pico 2 W
 - ESP32 2-Channel Relay Board
-- 3.5" SPI Capacitive Touchscreen
 
 ## Required
 
 - 4x DS18B20 Waterproof Sensors
-- 12V→5V Buck Converter
+- Waveshare ESP32-S3-Touch-LCD-5 dashboard
-- CAT5 Cable
+- Fused ACC switched 12V dashboard power
 - Bosch Relay Sockets
 - 30A/40A Bosch Relays
 - Automotive Fuse Block
@@ -18,8 +16,7 @@
 
 ## Future / Optional Fallback
 
-- 2x MAX3485 RS-485 Modules, only if UART over CAT5 proves unreliable
+- Pi Zero for long-term logging and local integrations
-- Pi Zero 2 W
 - GPS Module
 - ELM327 OBD-II Interface
 - CAN Interface

hardware/cat5-pinout.md

@@ -1,5 +1,7 @@
 # CAT5 Pinout
 
+Legacy note: this file describes an older Pico/UART dashboard wiring plan. Do not use it for the current Waveshare ESP32-S3 dashboard build.
+
 ## Primary Configuration
 
 UART over CAT5

hardware/esp32-pinout.md

@@ -1,5 +1,7 @@
 # ESP32 Pinout (Planned)
 
+Legacy note: Pico/UART references in this file are not part of the current dashboard plan. Current dashboard target is Waveshare ESP32-S3 over WiFi/HTTP.
+
 GPIO 16  Relay 1 (Starlink)
 GPIO 17  Relay 2 (Fridge)
 

hardware/pico-pinout.md

@@ -1,5 +1,7 @@
 # Pico Pinout (Planned)
 
+Legacy note: no Pico dashboard is currently planned. This file is retained only as historical/reference material.
+
 ## Display
 
 3.5 inch SPI capacitive touchscreen

hardware/uart-cat5-pinout.md

@@ -1,5 +1,7 @@
 # UART CAT5 Pinout
 
+Legacy note: this file describes an older Pico/UART dashboard wiring plan. Do not use it for the current Waveshare ESP32-S3 dashboard build.
+
 ## Pair 1
 
 Blue       +5V