3.9 KiB
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.