Add API specification

docs/api.md

@@ -0,0 +1,238 @@
+# Xterra Overland Dashboard API Specification
+
+## Overview
+
+The ESP32 acts as the system controller and provides status and control endpoints.
+
+Primary communication is RS-485.
+
+WiFi HTTP API is provided for:
+
+* Web dashboard
+* Mobile access
+* Configuration
+* Future Home Assistant integration
+
+---
+
+# GET /status
+
+Returns complete current system status.
+
+Example:
+
+```json
+{
+  "timestamp": 1748910000,
+
+  "battery": {
+    "soc": 82,
+    "voltage": 13.2,
+    "current": -6.4,
+    "remaining_ah": 82.5,
+    "runtime_hours": 11.2,
+    "temperature_f": 77.4
+  },
+
+  "temps": {
+    "fridge_zone_1": 35.8,
+    "fridge_zone_2": 12.1,
+    "rear_seat": 78.0,
+    "outside": 88.4
+  },
+
+  "relays": {
+    "starlink": false,
+    "fridge": true
+  },
+
+  "network": {
+    "wifi_enabled": false,
+    "rs485_connected": true
+  }
+}
+```
+
+---
+
+# GET /battery
+
+Returns detailed battery information.
+
+Example:
+
+```json
+{
+  "soc": 82,
+  "voltage": 13.2,
+  "current": -6.4,
+  "power_w": -84.5,
+  "remaining_ah": 82.5,
+  "runtime_hours": 11.2,
+  "temperature_f": 77.4,
+
+  "cells": [
+    3.299,
+    3.301,
+    3.300,
+    3.298
+  ],
+
+  "cell_delta_mv": 3
+}
+```
+
+---
+
+# GET /temps
+
+Returns all temperature sensors.
+
+Example:
+
+```json
+{
+  "fridge_zone_1": 35.8,
+  "fridge_zone_2": 12.1,
+  "rear_seat": 78.0,
+  "outside": 88.4
+}
+```
+
+---
+
+# GET /relays
+
+Returns relay states.
+
+Example:
+
+```json
+{
+  "starlink": false,
+  "fridge": true
+}
+```
+
+---
+
+# POST /relay/starlink
+
+Request:
+
+```json
+{
+  "state": true
+}
+```
+
+Response:
+
+```json
+{
+  "success": true,
+  "starlink": true
+}
+```
+
+---
+
+# POST /relay/fridge
+
+Request:
+
+```json
+{
+  "state": true
+}
+```
+
+Response:
+
+```json
+{
+  "success": true,
+  "fridge": true
+}
+```
+
+---
+
+# GET /network
+
+Returns network status.
+
+Example:
+
+```json
+{
+  "wifi_enabled": false,
+  "rs485_connected": true,
+  "starlink_enabled": false
+}
+```
+
+---
+
+# POST /network/wifi
+
+Enable WiFi temporarily.
+
+Request:
+
+```json
+{
+  "minutes": 10
+}
+```
+
+Response:
+
+```json
+{
+  "success": true,
+  "expires_minutes": 10
+}
+```
+
+---
+
+# Future Endpoints
+
+## Vehicle Data
+
+GET /vehicle
+
+```json
+{
+  "speed_mph": 62,
+  "rpm": 2200,
+  "coolant_temp_f": 192,
+  "fuel_percent": 48
+}
+```
+
+## GPS
+
+GET /gps
+
+```json
+{
+  "lat": 43.6629,
+  "lon": -116.6874,
+  "speed_mph": 0,
+  "heading": 0
+}
+```
+
+## Historical Data
+
+GET /history
+
+GET /history/temps
+
+GET /history/battery
+
+## Home Assistant
+
+MQTT integration planned.