# 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.