Clean up documentation structure

2026-06-04 04:07:28 -06:00
parent ff39a06ff4
commit 50410b1d0c
15 changed files with 550 additions and 40 deletions
@@ -0,0 +1,170 @@
+# ESP32 API and Serial Commands
+
+## HTTP API
+
+Base URL while connected to the ESP32 access point:
+
+    http://192.168.4.1
+
+## Status
+
+### GET /status
+
+Returns full controller status, including battery/BMS telemetry, relay states, temperature sensor states, alarms, system info, and current configuration.
+
+Relay states use generic IDs:
+
+    relay_1
+    relay_2
+
+Temperature sensors use generic IDs:
+
+    temp_1 through temp_8
+
+## Relay Control API
+
+    GET /relay/relay_1/on
+    GET /relay/relay_1/off
+    GET /relay/relay_2/on
+    GET /relay/relay_2/off
+
+Relay display names are configurable. Firmware and API clients should not assume what a relay controls.
+
+## Configuration API
+
+### GET /config
+
+Returns saved configuration.
+
+### POST /config/device
+
+Example:
+
+    {
+      "device_name": "Overland Controller"
+    }
+
+### POST /config/relay
+
+Example:
+
+    {
+      "id": "relay_1",
+      "name": "Aux Power",
+      "enabled": true
+    }
+
+### POST /config/bms
+
+Example:
+
+    {
+      "enabled": true,
+      "name": "House Battery",
+      "address": "aa:bb:cc:dd:ee:ff",
+      "address_type": "public"
+    }
+
+### POST /config/temp
+
+Example:
+
+    {
+      "id": "temp_1",
+      "name": "Cabin",
+      "address": "",
+      "enabled": true
+    }
+
+### POST /config/factory-reset
+
+Clears saved configuration and restores generic defaults.
+
+## Serial Monitor
+
+Baud:
+
+    115200
+
+Line ending:
+
+    Newline
+
+## Status and Config Commands
+
+    status
+    config
+    save
+    factory reset
+
+## Device Configuration Commands
+
+    devicename Overland Controller
+
+Run `save` after changing the device name.
+
+## Log Level Commands
+
+    log quiet
+    log info
+    log debug
+
+## Relay Control Commands
+
+    relay 1 on
+    relay 1 off
+    relay 2 on
+    relay 2 off
+
+## Relay Configuration Commands
+
+    relayname 1 Aux Power
+    relayname 2 Accessory Power
+
+Run `save` after changing names.
+
+## Temperature Sensor Configuration Commands
+
+    tempname 1 Cabin
+    tempname 2 Outside Air
+
+Run `save` after changing names.
+
+## BMS Configuration Commands
+
+    bmsname House Battery
+    bmsaddr aa:bb:cc:dd:ee:ff
+
+Run `save` after changing BMS config manually.
+
+## BMS Setup Mode Commands
+
+    enter setup
+    scan ble
+    select bms 1
+    exit setup
+
+Notes:
+
+- Some BMS modules advertise intermittently.
+- Multiple BLE scans may be required.
+- Once a BMS address is configured, BMS telemetry reconnects directly using the saved address.
+
+## Typical First-Time Setup Flow
+
+    log info
+    enter setup
+    scan ble
+    scan ble
+    select bms 1
+    relayname 1 Aux Power
+    relayname 2 Accessory Power
+    tempname 1 Cabin
+    tempname 2 Outside Air
+    save
+    config
+
+## Known Notes
+
+- DS18B20 sensors require a 4.7kΩ pull-up resistor on the 1-Wire data bus.
+- The firmware uses generic relay and temperature IDs. Installation-specific names belong in saved configuration only.