Checkpoint current docs, BLE setup workflow, and generic config refactor

2026-06-04 04:03:00 -06:00
parent cb7a98080c
commit ff39a06ff4
4 changed files with 1164 additions and 54 deletions
@@ -0,0 +1,208 @@
+# CHANGELOG.md
+
+# Changelog
+
+All notable changes to Overland Controller will be documented in this file.
+
+The format loosely follows Keep a Changelog principles.
+
+---
+
+# [0.3.0] - 2026-06-04
+
+## Major Changes
+
+### Project Renaming
+
+- Renamed project from Xterra Controller to Overland Controller
+- Updated firmware naming
+- Updated repository naming
+- Updated documentation naming
+- Began removal of vehicle-specific assumptions
+
+### Generic Configuration Architecture
+
+Removed hardcoded installation-specific values from firmware.
+
+Firmware now uses generic identifiers:
+
+Relays:
+
+text id="4xvc8l" relay_1 relay_2 
+
+Temperature sensors:
+
+text id="xq2e8v" temp_1 temp_2 temp_3 temp_4 temp_5 temp_6 temp_7 temp_8 
+
+Installation-specific names now belong in saved configuration.
+
+### JSON Status API Improvements
+
+Reworked status response format.
+
+Changed from:
+
+json id="k8l5yx" {   "temps": {     "outside": 72.0   } } 
+
+To:
+
+json id="k3g0ey" {   "temps": [     {       "id": "temp_1",       "name": "Outside",       "temperature_f": 72.0     }   ] } 
+
+Benefits:
+
+- Dynamic sensor support
+- Generic architecture
+- Easier dashboard integration
+- Better future scalability
+
+### Relay Status Improvements
+
+Relay reporting converted to structured arrays.
+
+Example:
+
+json id="wh1f5k" {   "id": "relay_1",   "name": "Aux Power",   "state": false } 
+
+### BMS Integration
+
+Implemented:
+
+- JBD BLE communication
+- Xiaoxiang compatibility
+- Cell voltage reporting
+- SOC reporting
+- Current reporting
+- Capacity reporting
+- Temperature reporting
+- Cycle count reporting
+
+### BLE Setup Workflow
+
+Added:
+
+- Setup mode
+- BLE device scanning
+- BMS selection
+- Persistent BMS storage
+
+Known limitation:
+
+- Some BMS devices advertise infrequently and may require multiple scans before appearing.
+
+### Documentation
+
+Added:
+
+- README.md
+- API.md
+- SERIAL_COMMANDS.md
+- HARDWARE.md
+- ARCHITECTURE.md
+- CHANGELOG.md
+
+---
+
+# [0.2.x]
+
+## Initial Controller Development
+
+Implemented:
+
+- ESP32 firmware framework
+- Relay control
+- Configuration storage
+- Access Point mode
+- Web server
+- UART communications
+- JSON status reporting
+
+---
+
+# [0.1.x]
+
+## Project Foundation
+
+Initial proof-of-concept work.
+
+Implemented:
+
+- Repository structure
+- ESP32 firmware skeleton
+- Basic relay testing
+- Initial dashboard communications concept
+
+---
+
+# Upcoming
+
+## Planned for 0.4.x
+
+### Dashboard Development
+
+- Pico 2 W integration
+- Dashboard communications
+- Touchscreen support
+- Relay control interface
+
+### Temperature System
+
+- Sensor assignment workflow
+- Sensor discovery workflow
+- Improved diagnostics
+
+### Configuration System
+
+- Expanded configuration API
+- Additional runtime configuration
+- Improved validation
+
+### Documentation
+
+- Installation guide
+- Wiring guide
+- Development guide
+
+---
+
+## Planned for 0.5.x
+
+### Vehicle Integration
+
+Potential support for:
+
+- OBD-II
+- ELM327
+- CAN Bus
+
+### Data Logging
+
+Potential support for:
+
+- Historical battery data
+- Historical temperature data
+- Event logging
+
+### Integrations
+
+Potential support for:
+
+- MQTT
+- Home Assistant
+- Grafana
+- InfluxDB
+
+---
+
+## Long-Term Roadmap
+
+Potential future capabilities:
+
+- GPS support
+- Route logging
+- Multi-controller support
+- OTA updates
+- Alerting system
+- Mobile-friendly dashboard
+- Remote monitoring
+
+The roadmap is intentionally flexible and may change as the project evolves.
@@ -0,0 +1,366 @@
+# SERIAL_COMMANDS.md
+
+# Serial Console Reference
+
+The ESP32 controller exposes a serial console for setup, troubleshooting, diagnostics, and configuration.
+
+Default settings:
+
+text Baud Rate: 115200 Data Bits: 8 Parity: None Stop Bits: 1 Line Ending: Newline 
+
+---
+
+# General Commands
+
+## status
+
+Displays the complete system status as JSON.
+
+Example:
+
+text status 
+
+Returns:
+
+text {   "type": "status_response",   ... } 
+
+---
+
+## config
+
+Displays the current active configuration.
+
+Example:
+
+text config 
+
+---
+
+## save
+
+Saves the current configuration to non-volatile storage.
+
+Example:
+
+text save 
+
+Response:
+
+text OK configuration saved 
+
+---
+
+## factory reset
+
+Restores firmware defaults and clears saved configuration.
+
+Example:
+
+text factory reset 
+
+Response:
+
+text OK factory reset complete 
+
+Controller will reboot after reset.
+
+---
+
+# Device Configuration
+
+## devicename <name>
+
+Sets the controller display name.
+
+Example:
+
+text devicename Overland Controller save 
+
+Response:
+
+text OK device name updated 
+
+---
+
+# Relay Commands
+
+Relay IDs are firmware identifiers and do not change.
+
+Available relay IDs:
+
+text relay_1 relay_2 
+
+---
+
+## relay 1 on
+
+Turns relay 1 on.
+
+Example:
+
+text relay 1 on 
+
+Response:
+
+text OK relay 1 on 
+
+---
+
+## relay 1 off
+
+Turns relay 1 off.
+
+Example:
+
+text relay 1 off 
+
+Response:
+
+text OK relay 1 off 
+
+---
+
+## relay 2 on
+
+Turns relay 2 on.
+
+Example:
+
+text relay 2 on 
+
+---
+
+## relay 2 off
+
+Turns relay 2 off.
+
+Example:
+
+text relay 2 off 
+
+---
+
+# Relay Naming
+
+## relayname <relay_number> <name>
+
+Assigns a user-friendly name to a relay.
+
+Examples:
+
+text relayname 1 Aux Power relayname 2 Compressor save 
+
+Response:
+
+text OK relay renamed 
+
+---
+
+# Temperature Sensor Commands
+
+Temperature sensor IDs:
+
+text temp_1 temp_2 temp_3 temp_4 temp_5 temp_6 temp_7 temp_8 
+
+---
+
+## tempname <sensor_number> <name>
+
+Assigns a user-friendly name to a temperature sensor.
+
+Examples:
+
+text tempname 1 Cabin tempname 2 Fridge tempname 3 Outside save 
+
+Response:
+
+text OK temperature sensor renamed 
+
+---
+
+# BMS Configuration
+
+## bmsname <name>
+
+Sets the BMS display name.
+
+Example:
+
+text bmsname House Battery save 
+
+Response:
+
+text OK BMS name updated 
+
+---
+
+## bmsaddr <address>
+
+Manually sets the Bluetooth address of the BMS.
+
+Example:
+
+text bmsaddr AA:BB:CC:DD:EE:FF save 
+
+Response:
+
+text OK BMS address updated 
+
+---
+
+# BLE Setup Mode
+
+BLE setup mode is used to discover and select a Bluetooth BMS.
+
+This mode temporarily disconnects the active BMS connection so scans can run reliably.
+
+---
+
+## enter setup
+
+Enters BMS setup mode.
+
+Example:
+
+text enter setup 
+
+Response:
+
+text OK entered BMS setup mode 
+
+---
+
+## scan ble
+
+Scans for nearby Bluetooth devices.
+
+Example:
+
+text scan ble 
+
+Example output:
+
+text 1) House Battery | AA:BB:CC:DD:EE:FF | RSSI -65 2) Sensor Node | 11:22:33:44:55:66 | RSSI -82  Use: select bms <number> 
+
+Notes:
+
+- Some BMS devices advertise infrequently.
+- Multiple scans may be required before a device appears.
+- BLE scans may take up to 20 seconds.
+
+---
+
+## select bms <number>
+
+Selects one of the discovered BLE devices.
+
+Example:
+
+text select bms 1 
+
+Response:
+
+text OK selected BMS BMS will reconnect on next update cycle 
+
+Remember to save configuration afterward:
+
+text save 
+
+---
+
+## exit setup
+
+Leaves BMS setup mode.
+
+Example:
+
+text exit setup 
+
+Response:
+
+text OK exited BMS setup mode 
+
+---
+
+# Logging
+
+## log level info
+
+Sets console logging to informational messages.
+
+Example:
+
+text log level info 
+
+---
+
+## log level debug
+
+Enables verbose debugging output.
+
+Example:
+
+text log level debug 
+
+Useful when troubleshooting:
+
+- BLE scanning
+- BMS connections
+- Sensor discovery
+- API requests
+- Relay control
+
+---
+
+# Recommended Initial Setup
+
+Example workflow for a new installation:
+
+text factory reset  devicename Overland Controller  relayname 1 Aux Power relayname 2 Fridge  tempname 1 Cabin tempname 2 Refrigerator tempname 3 Exterior  enter setup scan ble select bms 1 exit setup  save 
+
+Verify configuration:
+
+text config status 
+
+---
+
+# Troubleshooting
+
+## BMS Not Found
+
+Try:
+
+text enter setup scan ble scan ble scan ble 
+
+Some BMS devices advertise slowly and may require multiple scans.
+
+---
+
+## Relay Testing
+
+Test outputs directly:
+
+text relay 1 on relay 1 off  relay 2 on relay 2 off 
+
+---
+
+## Verify Configuration
+
+text config 
+
+Displays all currently loaded settings.
+
+---
+
+## Verify Live Status
+
+text status 
+
+Returns complete runtime status including:
+
+- Battery data
+- Temperatures
+- Relay states
+- Alarms
+- Network state
+- System information
@@ -1,3 +1,235 @@
-# Overland Controller API
+# API.md

-See `docs/api-and-serial-commands.md` for the current HTTP API and Serial command reference.
+# HTTP API Reference
+
+The ESP32 controller exposes a local HTTP API used by dashboards, management interfaces, and future integrations.
+
+Default access point address:
+
+text http://192.168.4.1 
+
+All responses are JSON.
+
+---
+
+# GET /status
+
+Returns complete controller status.
+
+Includes:
+
+- Battery telemetry
+- Temperature sensor status
+- Relay status
+- Vehicle status
+- Network status
+- Alarm status
+- System information
+- Current configuration
+
+Example:
+
+json {   "type": "status_response",   "battery": {},   "temps": [],   "relays": [],   "vehicle": {},   "network": {},   "alarms": {},   "system": {},   "config": {} } 
+
+---
+
+# Temperature Sensors
+
+Temperature sensors are returned as an array.
+
+Example:
+
+json {   "id": "temp_1",   "name": "Cabin",   "enabled": true,   "online": true,   "temperature_f": 72.4 } 
+
+Fields:
+
+| Field | Description |
+|---------|---------|
+| id | Internal sensor identifier |
+| name | User configured name |
+| enabled | Sensor enabled |
+| online | Sensor currently detected |
+| temperature_f | Current temperature |
+
+Valid IDs:
+
+text temp_1 temp_2 temp_3 temp_4 temp_5 temp_6 temp_7 temp_8 
+
+---
+
+# Relays
+
+Relay states are returned as an array.
+
+Example:
+
+json {   "id": "relay_1",   "name": "Aux Power",   "pin": 16,   "enabled": true,   "state": false } 
+
+Fields:
+
+| Field | Description |
+|---------|---------|
+| id | Internal relay identifier |
+| name | User configured name |
+| pin | GPIO pin |
+| enabled | Relay enabled |
+| state | Current output state |
+
+Valid IDs:
+
+text relay_1 relay_2 
+
+Future firmware versions may support additional relay outputs.
+
+---
+
+# Battery Object
+
+Example:
+
+json {   "source": "jbd_bms",   "connected": true,   "soc": 70,   "voltage": 13.34,   "current": 0.0,   "remaining_ah": 104.8,   "capacity_ah": 150.0,   "temperature_f": 76.5,   "cycle_count": 3 } 
+
+Additional fields may include:
+
+text cell_count cell_voltages cell_min_voltage cell_max_voltage cell_delta_mv runtime_hours ntc_count cells_valid 
+
+---
+
+# GET /config
+
+Returns the current saved configuration.
+
+Example:
+
+json {   "device_name": "Overland Controller",   "relays": [],   "temperature_sensors": [],   "bms": {} } 
+
+---
+
+# Relay Control
+
+## Turn Relay On
+
+text GET /relay/relay_1/on 
+
+Example response:
+
+json {   "ok": true,   "id": "relay_1",   "state": true } 
+
+---
+
+## Turn Relay Off
+
+text GET /relay/relay_1/off 
+
+Example response:
+
+json {   "ok": true,   "id": "relay_1",   "state": false } 
+
+---
+
+# Device Configuration
+
+## POST /config/device
+
+Updates the controller device name.
+
+Example request:
+
+json {   "device_name": "Overland Controller" } 
+
+Example response:
+
+json {   "ok": true } 
+
+---
+
+# Relay Configuration
+
+## POST /config/relay
+
+Updates relay settings.
+
+Example request:
+
+json {   "id": "relay_1",   "name": "Aux Power",   "enabled": true } 
+
+Fields:
+
+| Field | Required |
+|---------|---------|
+| id | Yes |
+| name | No |
+| enabled | No |
+
+---
+
+# Temperature Sensor Configuration
+
+## POST /config/temp
+
+Updates temperature sensor settings.
+
+Example request:
+
+json {   "id": "temp_1",   "name": "Cabin",   "enabled": true,   "address": "" } 
+
+Fields:
+
+| Field | Required |
+|---------|---------|
+| id | Yes |
+| name | No |
+| enabled | No |
+| address | No |
+
+---
+
+# BMS Configuration
+
+## POST /config/bms
+
+Updates BMS settings.
+
+Example request:
+
+json {   "enabled": true,   "name": "House Battery",   "address": "AA:BB:CC:DD:EE:FF",   "address_type": "public" } 
+
+Address types:
+
+text public random 
+
+---
+
+# Factory Reset
+
+## POST /config/factory-reset
+
+Clears stored configuration and restores firmware defaults.
+
+Example response:
+
+json {   "ok": true } 
+
+---
+
+# Error Responses
+
+Example:
+
+json {   "ok": false,   "error": "invalid relay id" } 
+
+Typical errors:
+
+text invalid relay id invalid sensor id invalid request missing parameter configuration save failed 
+
+---
+
+# Versioning
+
+Current firmware:
+
+text 0.3.x 
+
+Future firmware versions may add fields while maintaining backward compatibility.
+
+Consumers should ignore unknown fields.
@@ -1,76 +1,380 @@
-# Xterra Overland Power & Monitoring Dashboard
+# ARCHITECTURE.md

-## Purpose
+# System Architecture

-A custom monitoring and control system for a Nissan Xterra using a Raspberry Pi Pico 2 W dashboard interface and an ESP32 cargo-area controller.
+Overland Controller is built as a distributed monitoring and control platform for overland vehicles, campers, trailers, and mobile power systems.

-The system provides:
+The architecture intentionally separates user interface functions from monitoring and control functions.

- House battery monitoring
- Fridge monitoring
- Temperature monitoring
- Power control
- Alarm management
- Future vehicle telemetry
+This improves reliability, modularity, and future expandability.

-## Dashboard Module
+---

-### Hardware
+# High-Level Overview

- Raspberry Pi Pico 2 W
- 3.5" SPI Capacitive Touchscreen
- UART-over-CAT5 communications
- WiFi backup communications
+text                         User                           │                           ▼                 +----------------+                 | Dashboard UI   |                 | Pico 2 W       |                 +----------------+                           │                           │ UART / WiFi                           ▼                 +----------------+                 | ESP32 Controller|                 +----------------+                   │      │      │                   │      │      │                   ▼      ▼      ▼                BMS   Sensors  Relays 

-### Responsibilities
+The ESP32 is the system authority.

- Touchscreen user interface
- Local web dashboard
- Alarm display
- Configuration management
- Relay control interface
- Data visualization
+The dashboard acts as a user interface only.

-## Cargo Module
+---

-### Hardware
+# Core Design Principles

- ESP32 Relay Controller
- UART-over-CAT5 interface
- House Battery Interface
- DS18B20 Temperature Sensor Bus
- Bosch Relay Drivers
+## Local First

-### Responsibilities
+The system must function completely offline.

- Sensor collection
- Relay control
- Alarm processing
- Communications server
+Requirements:
+
+- No cloud dependency
+- No internet requirement
+- No third-party service requirement
+- No account requirement
+
+---
+
+## Controller First
+
+The ESP32 is responsible for:
+
+- Data collection
+- Device control
 - Configuration storage
+- State management

-## Communications
+The dashboard should never be required for normal operation.

-Primary:
- UART over CAT5
+---

-Backup:
- WiFi HTTP API
+## Generic Hardware Naming
+
+The firmware should never assume installation-specific names.
+
+Avoid:
+
+text Fridge Starlink Greta Outside Rear Seat 
+
+Instead use:
+
+text relay_1 relay_2  temp_1 temp_2 temp_3 temp_4 
+
+User-specific naming belongs in configuration.
+
+---
+
+## API Driven
+
+All data should be exposed through structured APIs.
+
+Benefits:
+
+- Dashboard independence
+- Future Home Assistant integration
+- Future MQTT support
+- Easier testing
+- Easier automation
+
+---
+
+# ESP32 Controller
+
+The ESP32 is the primary controller.
+
+Responsibilities:
+
+## Battery Monitoring
+
+Source:
+
+text JBD / Xiaoxiang BLE BMS 
+
+Provides:
+
+- State of charge
+- Voltage
+- Current
+- Capacity
+- Temperature
+- Cell data
+
+---
+
+## Temperature Monitoring
+
+Source:
+
+text DS18B20 Sensors 
+
+Provides:
+
+- Temperature readings
+- Sensor health
+- Online/offline status
+
+---
+
+## Relay Control
+
+Provides:
+
+- Output control
+- State reporting
+- Future automation logic
+
+---
+
+## Configuration Storage
+
+Stores:
+
+- Device name
+- Relay configuration
+- Temperature sensor configuration
+- BMS configuration
+
+Configuration survives reboot.
+
+---
+
+## Local Web Server
+
+Provides:
+
+- Status endpoint
+- Configuration endpoint
+- Relay control endpoint
+
+Current transport:
+
+text HTTP JSON 
+
+---
+
+# Dashboard
+
+Current target:
+
+text Raspberry Pi Pico 2 W 
+
+Responsibilities:
+
+- Display information
+- User interaction
+- Relay control
+- Configuration management
+
+The dashboard should not contain critical business logic.
+
+---
+
+# Data Flow
+
+## Battery Data
+
+text BMS  │  ▼ ESP32  │  ▼ Status API  │  ▼ Dashboard 
+
+---
+
+## Temperature Data
+
+text DS18B20  │  ▼ ESP32  │  ▼ Status API  │  ▼ Dashboard 
+
+---
+
+## Relay Control
+
+text User  │  ▼ Dashboard  │  ▼ ESP32 API  │  ▼ Relay Output 
+
+Future automation may bypass the dashboard entirely.
+
+---
+
+# Communications
+
+## Current
+
+### BMS → ESP32
+
+text BLE 
+
+### Dashboard → ESP32
+
+text UART 
+
+### Browser → ESP32
+
+text HTTP 
+
+---
+
+## Future
+
+Potential future transports:
+
+text WiFi MQTT WebSockets CAN Bus 
+
+---
+
+# Configuration Model
+
+Configuration exists in three layers.
+
+## Firmware Defaults
+
+Built into firmware.
+
+Example:
+
+text relay_1 relay_2  temp_1 temp_2 
+
+Used when no configuration exists.
+
+---
+
+## Stored Configuration
+
+Saved in non-volatile storage.
+
+Contains:
+
+- User names
+- Addresses
+- Enable states
+
+Persists through reboot.
+
+---
+
+## Runtime State
+
+Current operational values.
+
+Examples:
+
+text Battery voltage Relay state Temperature readings Alarm status 
+
+Generated dynamically.
+
+Never stored permanently.
+
+---
+
+# Status Model
+
+The status API contains six major sections.
+
+## Battery
+
+Battery telemetry.
+
+---
+
+## Temperatures
+
+Temperature sensor readings.
+
+---
+
+## Relays
+
+Relay states.
+
+---
+
+## Vehicle
+
+Vehicle telemetry.
+
+Currently minimal.
+
+Future expansion point.
+
+---
+
+## Alarms
+
+System alarm state.
+
+Examples:
+
+text Low battery High temperature BMS disconnected Cell imbalance 
+
+---
+
+## System
+
+Controller information.
+
+Examples:
+
+text Firmware version Build date Build time Uptime 
+
+---
+
+# Future Expansion
+
+## Vehicle Integration
+
+Potential sources:
+
+text OBD-II ELM327 CAN Bus 
+
+Potential data:
+
+- RPM
+- Fuel level
+- Coolant temperature
+- Vehicle speed
+- Trouble codes
+
+---
+
+## GPS
+
+Potential features:
+
+- Location
+- Trip logging
+- Route history
+
+---
+
+## MQTT
+
+Potential integrations:

-Future:
- MQTT
 - Home Assistant
+- Node-RED
 - Grafana
 - InfluxDB

-## Future Expansion
+---

- JBD/Xiaoxiang BLE Battery Monitoring
- OBD-II
- CAN Bus
- GPS
- Trip Logging
- Fuel Level
- Coolant Temperature
- RPM
- Starlink Diagnostics
+## Data Logging
+
+Potential storage:
+
+text SD Card Internal Flash Network Storage 
+
+Potential data:
+
+- Battery history
+- Temperature history
+- Relay history
+- Vehicle telemetry
+
+---
+
+# Long-Term Vision
+
+The long-term goal is a modular platform capable of monitoring and controlling nearly every subsystem in an overland vehicle while remaining:
+
+- Offline capable
+- Self-hosted
+- Hardware independent
+- Expandable
+- Easy to troubleshoot
+- Easy to maintain
+- Free from cloud dependencies