236 lines
3.9 KiB
Markdown
236 lines
3.9 KiB
Markdown
# 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.
|