Clean up documentation structure

docs/API.md

@@ -0,0 +1,235 @@
+# API.md
+
+# 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.