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