From dbc40ee2c1dbb3ba5f1eab328781362a5c1f6dd6 Mon Sep 17 00:00:00 2001
From: nick <coachward0742@gmail.com>
Date: Thu, 4 Jun 2026 02:52:35 -0600
Subject: [PATCH] Document ESP32 API and serial commands

---
 docs/api-and-serial-commands.md | 324 ++++++++++++++++++++++++++++++++
 1 file changed, 324 insertions(+)
 create mode 100644 docs/api-and-serial-commands.md

diff --git a/docs/api-and-serial-commands.md b/docs/api-and-serial-commands.md
new file mode 100644
index 0000000..1bbfd45
--- /dev/null
+++ b/docs/api-and-serial-commands.md
@@ -0,0 +1,324 @@
+# ESP32 API and Serial Commands
+
+## HTTP API
+
+Base URL while connected to ESP32 AP:
+
+    http://192.168.4.1
+
+---
+
+## Status
+
+### GET /status
+
+Returns full controller status.
+
+Example:
+
+    http://192.168.4.1/status
+
+Includes:
+
+- Battery/BMS telemetry
+- Cell voltages
+- Temperature readings
+- Sensor health
+- Relay states
+- Vehicle state
+- Network state
+- Alarm state
+- System info
+- Current configuration
+
+---
+
+## Relay Control
+
+### GET /relay/starlink/on
+
+Turns relay 1 on.
+
+### GET /relay/starlink/off
+
+Turns relay 1 off.
+
+### GET /relay/fridge/on
+
+Turns relay 2 on.
+
+### GET /relay/fridge/off
+
+Turns relay 2 off.
+
+Current legacy names:
+
+- starlink = relay 1 / GPIO16
+- fridge = relay 2 / GPIO17
+
+Future goal:
+
+- Replace legacy names with generic relay IDs.
+
+---
+
+## Configuration API
+
+### GET /config
+
+Returns saved configuration.
+
+Example:
+
+    http://192.168.4.1/config
+
+---
+
+### POST /config/relay
+
+Updates relay config.
+
+Example body:
+
+    {
+      "id": "relay_1",
+      "name": "Starlink",
+      "enabled": true
+    }
+
+Valid IDs:
+
+- relay_1
+- relay_2
+
+---
+
+### POST /config/bms
+
+Updates BMS config.
+
+Example body:
+
+    {
+      "enabled": true,
+      "name": "Greta",
+      "address": "a5:c2:37:2c:05:dc",
+      "address_type": "public"
+    }
+
+---
+
+### POST /config/temp
+
+Updates temperature sensor config.
+
+Example body:
+
+    {
+      "id": "temp_1",
+      "name": "Fridge Zone 1",
+      "address": "",
+      "enabled": true
+    }
+
+Valid IDs:
+
+- temp_1
+- temp_2
+- temp_3
+- temp_4
+- temp_5
+- temp_6
+- temp_7
+- temp_8
+
+---
+
+### POST /config/factory-reset
+
+Clears saved config and restores defaults.
+
+---
+
+## Serial Monitor Commands
+
+Serial baud:
+
+    115200
+
+Line ending:
+
+    Newline
+
+---
+
+## Status and Config
+
+### status
+
+Prints full JSON status to Serial.
+
+### config
+
+Prints current configuration to Serial.
+
+### save
+
+Saves current in-memory configuration to NVS.
+
+### factory reset
+
+Clears saved config and restores defaults.
+
+---
+
+## Log Level
+
+### log quiet
+
+Minimizes serial output.
+
+### log info
+
+Normal serial output.
+
+### log debug
+
+Enables recurring debug output such as BMS and sensor updates.
+
+---
+
+## Relay Control
+
+### relay starlink on
+
+Turns legacy Starlink relay on.
+
+### relay starlink off
+
+Turns legacy Starlink relay off.
+
+### relay fridge on
+
+Turns legacy Fridge relay on.
+
+### relay fridge off
+
+Turns legacy Fridge relay off.
+
+---
+
+## Relay Configuration
+
+### relayname 1 Starlink
+
+Sets relay 1 display name.
+
+### relayname 2 Fridge
+
+Sets relay 2 display name.
+
+Run `save` after changing names.
+
+---
+
+## Temperature Sensor Configuration
+
+### tempname 1 Fridge Zone 1
+
+Sets temp sensor 1 display name.
+
+### tempname 2 Fridge Zone 2
+
+Sets temp sensor 2 display name.
+
+### tempname 3 Rear Seat Area
+
+Sets temp sensor 3 display name.
+
+### tempname 4 Outside Air
+
+Sets temp sensor 4 display name.
+
+Run `save` after changing names.
+
+---
+
+## BMS Configuration
+
+### bmsname Greta
+
+Sets BMS display name.
+
+### bmsaddr a5:c2:37:2c:05:dc
+
+Sets BMS BLE address.
+
+Run `save` after changing BMS config manually.
+
+---
+
+## BMS Setup Mode
+
+### enter setup
+
+Enters BMS setup mode.
+
+Effects:
+
+- Disconnects BMS client
+- Pauses BMS reconnect
+- Allows repeated BLE scans
+
+### scan ble
+
+Scans for BLE devices.
+
+Notes:
+
+- JBD/Xiaoxiang BMS advertising can be intermittent.
+- Multiple scans may be required.
+- Greta may not appear every scan.
+
+### select bms 1
+
+Selects BLE scan result 1 as the configured BMS.
+
+This saves:
+
+- BMS name
+- BMS address
+- BMS enabled state
+
+### exit setup
+
+Leaves BMS setup mode and allows BMS reconnect.
+
+---
+
+## Typical First-Time Setup Flow
+
+    log info
+    enter setup
+    scan ble
+    scan ble
+    scan ble
+    select bms 1
+    relayname 1 Starlink
+    relayname 2 Fridge
+    tempname 1 Fridge Zone 1
+    tempname 2 Fridge Zone 2
+    tempname 3 Rear Seat Area
+    tempname 4 Outside Air
+    save
+    config
+
+---
+
+## Known Notes
+
+- BMS telemetry works reliably once the address is configured.
+- BLE scan works, but JBD/Xiaoxiang advertising is intermittent.
+- DS18B20 sensors require a 4.7kΩ pull-up resistor on the 1-Wire data bus.
+- Relay API still uses legacy names internally.
+- Future work should move relay runtime commands to generic relay IDs.