overland-controller/docs/api-and-serial-commands.md

ESP32 API and Serial Commands

HTTP API

Base URL while connected to ESP32 AP:

http://192.168.4.1

---

Status

GET /status

Returns full controller status.

Example:

http://192.168.4.1/status

Includes:

• Battery/BMS telemetry
• Cell voltages
• Temperature readings
• Sensor health
• Relay states
• Vehicle state
• Network state
• Alarm state
• System info
• Current configuration

---

Relay Control

GET /relay/starlink/on

Turns relay 1 on.

GET /relay/starlink/off

Turns relay 1 off.

GET /relay/fridge/on

Turns relay 2 on.

GET /relay/fridge/off

Turns relay 2 off.

Current legacy names:

• starlink = relay 1 / GPIO16
• fridge = relay 2 / GPIO17

Future goal:

• Replace legacy names with generic relay IDs.

---

Configuration API

GET /config

Returns saved configuration.

Example:

http://192.168.4.1/config

---

POST /config/relay

Updates relay config.

Example body:

{
  "id": "relay_1",
  "name": "Starlink",
  "enabled": true
}

Valid IDs:

• relay_1
• relay_2

---

POST /config/bms

Updates BMS config.

Example body:

{
  "enabled": true,
  "name": "Greta",
  "address": "a5:c2:37:2c:05:dc",
  "address_type": "public"
}

---

POST /config/temp

Updates temperature sensor config.

Example body:

{
  "id": "temp_1",
  "name": "Fridge Zone 1",
  "address": "",
  "enabled": true
}

Valid IDs:

• temp_1
• temp_2
• temp_3
• temp_4
• temp_5
• temp_6
• temp_7
• temp_8

---

POST /config/factory-reset

Clears saved config and restores defaults.

---

Serial Monitor Commands

Serial baud:

115200

Line ending:

Newline

---

Status and Config

status

Prints full JSON status to Serial.

config

Prints current configuration to Serial.

save

Saves current in-memory configuration to NVS.

factory reset

Clears saved config and restores defaults.

---

Log Level

log quiet

Minimizes serial output.

log info

Normal serial output.

log debug

Enables recurring debug output such as BMS and sensor updates.

---

Relay Control

relay starlink on

Turns legacy Starlink relay on.

relay starlink off

Turns legacy Starlink relay off.

relay fridge on

Turns legacy Fridge relay on.

relay fridge off

Turns legacy Fridge relay off.

---

Relay Configuration

relayname 1 Starlink

Sets relay 1 display name.

relayname 2 Fridge

Sets relay 2 display name.

Run save after changing names.

---

Temperature Sensor Configuration

tempname 1 Fridge Zone 1

Sets temp sensor 1 display name.

tempname 2 Fridge Zone 2

Sets temp sensor 2 display name.

tempname 3 Rear Seat Area

Sets temp sensor 3 display name.

tempname 4 Outside Air

Sets temp sensor 4 display name.

Run save after changing names.

---

BMS Configuration

bmsname Greta

Sets BMS display name.

bmsaddr a5:c2:37:2c:05:dc

Sets BMS BLE address.

Run save after changing BMS config manually.

---

BMS Setup Mode

enter setup

Enters BMS setup mode.

Effects:

• Disconnects BMS client
• Pauses BMS reconnect
• Allows repeated BLE scans

scan ble

Scans for BLE devices.

Notes:

• JBD/Xiaoxiang BMS advertising can be intermittent.
• Multiple scans may be required.
• Greta may not appear every scan.

select bms 1

Selects BLE scan result 1 as the configured BMS.

This saves:

• BMS name
• BMS address
• BMS enabled state

exit setup

Leaves BMS setup mode and allows BMS reconnect.

---

Typical First-Time Setup Flow

log info
enter setup
scan ble
scan ble
scan ble
select bms 1
relayname 1 Starlink
relayname 2 Fridge
tempname 1 Fridge Zone 1
tempname 2 Fridge Zone 2
tempname 3 Rear Seat Area
tempname 4 Outside Air
save
config

---

Known Notes

• BMS telemetry works reliably once the address is configured.
• BLE scan works, but JBD/Xiaoxiang advertising is intermittent.
• DS18B20 sensors require a 4.7kΩ pull-up resistor on the 1-Wire data bus.
• Relay API still uses legacy names internally.
• Future work should move relay runtime commands to generic relay IDs.