diff --git a/HARDWARE.md b/HARDWARE.md index 52784ce..7781a40 100644 --- a/HARDWARE.md +++ b/HARDWARE.md @@ -1,30 +1,10 @@ --- -# Relay Wiring +# Hardware Notes -Current architecture uses the onboard relay contacts -as the load switching device. +The current hardware source of truth is `docs/HARDWARE.md`. -Positive-side switching: - - Battery + - | - Fuse - | - Relay COM - | - Relay NO - | - Load + - -Load negative returns directly to the ground bus. - -Relay 1: - - Starlink Mini - -Relay 2: - - Fridge +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. +Use properly fused automotive relays or contactors for major loads. diff --git a/README.md b/README.md index b7bcde2..b24bae0 100644 --- a/README.md +++ b/README.md @@ -34,15 +34,15 @@ Current controller: - ESP32 2-relay board -Planned dashboard: +Primary dashboard target: -- Raspberry Pi Pico 2 W -- Touchscreen display -- UART connection to ESP32 +- Waveshare ESP32-S3-Touch-LCD-5 +- WiFi client to the Cargo ESP32 access point +- 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. diff --git a/docs/API.md b/docs/API.md index a02c840..5976c42 100644 --- a/docs/API.md +++ b/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 \ No newline at end of file +Clearing removes the stored DS18B20 address, disables the slot, clears the weather flag, resets cached temperature state, and persists config. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 2f29cf4..99bffa4 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -93,11 +93,9 @@ HTTP is the primary integration contract for: Preferred direction: - GET /api/status - GET /api/config - POST /api/relays/relay_1/on - POST /api/relays/relay_1/off - POST /api/relays/relay_1/toggle + GET /status + GET /config + POST /relay/set Future versioning may move to /api/v1. diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 66f670f..c0db0aa 100644 --- a/docs/CHANGELOG.md +++ b/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. -- Built-in ESP32 relays are the current planned relay switching method for Starlink Mini and fridge. +- Waveshare ESP32-S3 is the primary physical dashboard target. +- 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 diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 927c44e..88f3148 100644 --- a/docs/CONFIGURATION.md +++ b/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 diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index dfc0736..7400667 100644 --- a/docs/HANDOFF.md +++ b/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 \ No newline at end of file +- 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. diff --git a/docs/PARITY_MATRIX.md b/docs/PARITY_MATRIX.md index 1129314..d35c779 100644 --- a/docs/PARITY_MATRIX.md +++ b/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 \ No newline at end of file +before parity is considered maintained. + +- Temperature sensor config/status parity now includes the `weather` boolean flag for outside-air display selection. diff --git a/docs/README.md b/docs/README.md index 17a4bad..e12d332 100644 --- a/docs/README.md +++ b/docs/README.md @@ -19,8 +19,9 @@ This folder contains project documentation for Overland Controller. ## Technical References -- `protocol.md` - Dashboard/controller protocol -- `wiring.md` - Wiring notes and plans +- `dashboard-esp32s3.md` - Current Waveshare ESP32-S3 dashboard plan +- `protocol.md` - Legacy UART protocol reference +- `wiring.md` - Older wiring notes; verify against `HARDWARE.md` before use ## Archive diff --git a/docs/UART_PROTOCOL.md b/docs/UART_PROTOCOL.md index 9908f39..e3dabed 100644 --- a/docs/UART_PROTOCOL.md +++ b/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 useful for setup, debugging, and future web UI. +- HTTP is the preferred dashboard/control path. +- 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 \ No newline at end of file +`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`. diff --git a/docs/dashboard-esp32s3.md b/docs/dashboard-esp32s3.md index 6caf403..148f39d 100644 --- a/docs/dashboard-esp32s3.md +++ b/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 -→ CAT5e power pair(s) -→ Dash enclosure -→ Buck converter -→ 5V dashboard input +ACC switched 12V +-> fuse +-> Waveshare VIN 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. - -Keep existing UART protocol docs because UART remains useful, but new dashboard work should target the ESP32-S3 display first. +No Pico dashboard is planned. Existing Pico/UART material is legacy unless explicitly revived for diagnostics or alternate hardware. diff --git a/docs/decisions.md b/docs/decisions.md index b6e3fce..7e751f8 100644 --- a/docs/decisions.md +++ b/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 -- Deterministic -- No WiFi dependency -- Works offline -- Easier to debug electrically +- Matches the WebUI and future integration contract +- Avoids a dedicated dashboard data cable +- Supports the Waveshare ESP32-S3 dashboard target +- Keeps the dashboard a simple client -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. diff --git a/docs/hardware-status.md b/docs/hardware-status.md index 8f09dc4..a288f02 100644 --- a/docs/hardware-status.md +++ b/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 diff --git a/docs/project-state.md b/docs/project-state.md index faa4576..1190a72 100644 --- a/docs/project-state.md +++ b/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 - Load negative -> ground bus + ESP32 relay board output + -> external fused automotive relay or contactor trigger + -> fused load circuit -The built-in relays are currently planned for: - -- Starlink Mini -- 12V fridge - -External automotive relays remain a future option for higher-current loads. +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. ## 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 \ No newline at end of file +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. diff --git a/docs/protocol.md b/docs/protocol.md index 1e5de6b..1035587 100644 --- a/docs/protocol.md +++ b/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 diff --git a/docs/roadmap.md b/docs/roadmap.md index b07158e..7041871 100644 --- a/docs/roadmap.md +++ b/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 - -Goals: - -- 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
-- 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 +- LVGL project scaffold +- WiFi client to Cargo ESP32 AP +- Poll /status +- Display battery, relays, temps, and alarms - Send relay commands +- Handle offline/stale/failed-command states -Initial dashboard screens: +UI direction: -- Main overview -- Battery screen -- Temperature screen -- Relay control screen -- Settings screen +- Dark theme +- Large readable text +- Circular SOC gauge +- Card-based layout +- 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 -- Configure relay names -- Configure temperature names -- Configure BMS -- Run BLE scan workflow -- Save config -- Factory reset +- Install dedicated sender +- Read through exposed ADC or ADS1115 over I2C +- Convert resistance to temp with lookup interpolation +- Add alert thresholds -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 - -Possible inputs: - -- Ignition signal -- Vehicle battery voltage -- OBD-II -- CAN bus +- microSD logging - GPS - -Potential data: - -- Ignition state -- 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 \ No newline at end of file +- OTA updates +- Dashboard alert sounds +- More vehicle PIDs +- Historical charts diff --git a/docs/wiring.md b/docs/wiring.md index ebf6105..0922b2a 100644 --- a/docs/wiring.md +++ b/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 -- Raspberry Pi Pico 2 W dashboard -- CAT5/CAT6 cable between rear controller and dash -- 12V-to-5V buck converter in the dash enclosure +- `docs/HARDWARE.md` +- `docs/dashboard-esp32s3.md` + +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 --- diff --git a/hardware/bom.md b/hardware/bom.md index 23ff231..91fdd6c 100644 --- a/hardware/bom.md +++ b/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 -- CAT5 Cable +- Waveshare ESP32-S3-Touch-LCD-5 dashboard +- 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 2 W +- Pi Zero for long-term logging and local integrations - GPS Module - ELM327 OBD-II Interface - CAN Interface diff --git a/hardware/cat5-pinout.md b/hardware/cat5-pinout.md index d261f29..d4edd4c 100644 --- a/hardware/cat5-pinout.md +++ b/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 diff --git a/hardware/esp32-pinout.md b/hardware/esp32-pinout.md index ac20ec6..0af7d14 100644 --- a/hardware/esp32-pinout.md +++ b/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) diff --git a/hardware/pico-pinout.md b/hardware/pico-pinout.md index 836cf90..b36be02 100644 --- a/hardware/pico-pinout.md +++ b/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 diff --git a/hardware/uart-cat5-pinout.md b/hardware/uart-cat5-pinout.md index 7a3e2e4..b5933af 100644 --- a/hardware/uart-cat5-pinout.md +++ b/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