nick/overland-controller
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1ee73ad00d4bc05cd40fb022abd3764750916900
overland-controller/docs/API.md
T

10 KiB
Raw Blame History

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

runtime_hours is discharge runtime from the ESP32 status payload. The WebUI derives charging time-to-full from capacity_ah, remaining_ah, and positive incoming current without changing the API shape.

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.

Embedded Dashboard

The ESP32 is planned to serve a lightweight mobile dashboard at:

GET /

When connected directly to the ESP32 AP:

http://192.168.4.1/

The page should:

  • Poll /status
  • Display battery state
  • Display temperature sensors
  • Display relay states
  • Show alarms
  • Allow basic relay control

Design limits:

  • Small inline HTML/CSS/JS
  • No external libraries
  • No large assets
  • No heavy JavaScript framework

The embedded dashboard is intended as a convenient phone view, not a replacement for the physical Pico dashboard.

Future WiFi API

Future configuration may include WiFi management endpoints.

Possible future endpoints:

GET  /config/wifi
POST /config/wifi
POST /config/wifi/add
POST /config/wifi/remove
POST /config/wifi/reorder

Potential config model:

ap_enabled
sta_enabled
hostname
saved_networks

Saved networks should support priority order.

Example:

Starlink
Home WiFi
Shop WiFi

The AP should remain enabled even when connected to STA WiFi.

HTTP / UART Parity Endpoints

These endpoints mirror UART setup/control messages.

Save Config

POST /config/save

Equivalent UART message:

{"type":"save_config"}

BMS Setup Mode

Enter BMS setup mode:

POST /bms/setup/enter

Equivalent UART message:

{"type":"enter_bms_setup"}

Exit BMS setup mode:

POST /bms/setup/exit

Equivalent UART message:

{"type":"exit_bms_setup"}

BLE Scan

Scan for BLE devices:

POST /bms/scan

Equivalent UART message:

{"type":"scan_ble"}

Response:

{
  "type": "ble_scan_response",
  "devices": [
    {
      "index": 1,
      "name": "House Battery",
      "address": "aa:bb:cc:dd:ee:ff",
      "rssi": -65
    }
  ]
}

Select BMS

Select a BMS from the most recent scan:

POST /bms/select

Request body:

{
  "index": 1
}

Equivalent UART message:

{"type":"select_bms","index":1}

Preferred Relay Command Endpoint

The preferred relay control endpoint is:

POST /relay/set

Request body:

{
  "id": "relay_1",
  "state": true
}

Example:

curl -X POST http://192.168.88.108/relay/set \
  -H "Content-Type: application/json" \
  -d '{"id":"relay_1","state":true}'

Equivalent UART message:

{"type":"set_relay","relay":"relay_1","enabled":true}

Legacy GET relay routes may remain for compatibility:

GET /relay/relay_1/on
GET /relay/relay_1/off
GET /relay/relay_2/on
GET /relay/relay_2/off

WiFi Configuration API

Get WiFi Config

GET /config/wifi

Set WiFi Config

POST /config/wifi

Request body:

{
  "ssid": "Starlink",
  "password": "password_here"
}

Connect STA WiFi

POST /wifi/connect

Clear WiFi Config

POST /wifi/clear

The ESP32 AP remains available even when STA WiFi is configured.

Equivalent UART messages:

{"type":"wifi_request"}

{"type":"config_wifi","ssid":"Starlink","password":"password_here"}

{"type":"wifi_connect"}

{"type":"wifi_clear"}

WiFi Priority and Runtime Failover

Saved WiFi networks support priority.

Lower priority numbers are attempted first.

Example:

{
  "networks": [
    {
      "ssid": "Starlink",
      "password": "starlink_password",
      "priority": 1
    },
    {
      "ssid": "Home WiFi",
      "password": "home_password",
      "priority": 2
    }
  ]
}

The ESP32 behavior is:

AP always stays enabled
STA tries saved networks by priority
If disconnected at runtime, STA retries saved networks every 30 seconds
If all STA networks fail, AP remains available at 192.168.4.1

API Parity Notes

The HTTP API is intended to mirror the UART JSON protocol where practical.

Preferred Relay Control

Preferred endpoint:

POST /relay/set

Request:

{
  "id": "relay_1",
  "state": true
}

Response:

{
  "type": "relay_response",
  "ok": true,
  "id": "relay_1",
  "state": true
}

Legacy relay routes may remain available for compatibility:

GET /relay/relay_1/on
GET /relay/relay_1/off
GET /relay/relay_2/on
GET /relay/relay_2/off

WiFi Parity

WiFi configuration supports multiple saved STA networks.

Request:

POST /config/wifi

Body:

{
  "networks": [
    {
      "ssid": "Starlink",
      "password": "starlink_password",
      "priority": 1
    },
    {
      "ssid": "Home WiFi",
      "password": "home_password",
      "priority": 2
    }
  ]
}

Lower priority numbers are attempted first.

Runtime behavior:

AP always remains enabled.
STA tries saved networks by priority.
If STA disconnects, saved networks are retried every 30 seconds.

Temperature Probe Setup API

Scan Temperature Sensors

POST /temps/scan

Response:

{
  "type": "temp_scan_response",
  "ok": true,
  "devices": [
    {
      "index": 1,
      "address": "28:AA:BB:CC:DD:EE:FF:00"
    }
  ]
}

Assign Temperature Sensor

POST /temps/assign

Request:

{
  "id": "temp_1",
  "index": 1
}

Alternative request:

{
  "slot": 1,
  "index": 1
}

Clear Temperature Sensor

POST /temps/clear

Request:

{
  "id": "temp_1"
}

Alternative request:

{
  "slot": 1
}

Version 0.4.0 Notes

The WebUI Config tab now exposes the preferred setup workflow.

Important endpoints used by the WebUI:

GET  /status
GET  /config

POST /config/device
POST /config/relay
POST /config/temp
POST /config/bms
POST /config/save
POST /config/factory-reset

POST /relay/set

POST /temps/scan
POST /temps/assign
POST /temps/clear

POST /config/wifi
POST /wifi/connect
POST /wifi/clear

POST /bms/reconnect
POST /system/restart

The preferred relay command endpoint remains:

POST /relay/set

Request:

{
  "id": "relay_1",
  "state": true
}\n\n### Weather temperature sensor flag

Temperature sensor config entries now include weather: true.

When a configured temp sensor has weather: true, the WebUI may show it as the outside/weather temperature badge. The /status temp objects also include this flag so HTTP, UART, USB serial, and future Pico clients can identify the selected outside-air sensor without guessing from the sensor name.\n

Reference in New Issue View Git Blame Copy Permalink