# ESP32 API and Serial Commands

## HTTP API

Base URL while connected to the ESP32 access point:

    http://192.168.4.1

---

## Status

### GET /status

Returns full controller status.

Includes:

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

Relay states use generic relay IDs:

    relay_1
    relay_2

Temperature sensors use generic sensor IDs:

    temp_1
    temp_2
    temp_3
    temp_4
    temp_5
    temp_6
    temp_7
    temp_8

---

## Relay Control API

### GET /relay/relay_1/on

Turns relay 1 on.

### GET /relay/relay_1/off

Turns relay 1 off.

### GET /relay/relay_2/on

Turns relay 2 on.

### GET /relay/relay_2/off

Turns relay 2 off.

Relay display names are configurable. The firmware should not assume what a relay controls.

---

## Deprecated Relay Aliases

These legacy routes may still exist for compatibility during development, but should not be used by new clients:

    /relay/starlink/on
    /relay/starlink/off
    /relay/fridge/on
    /relay/fridge/off

Future work should remove these aliases after the Pico/dashboard clients use generic relay IDs.

---

## Configuration API

### GET /config

Returns saved configuration.

---

### POST /config/relay

Updates relay config.

Example body:

    {
      "id": "relay_1",
      "name": "Aux Power",
      "enabled": true
    }

Valid IDs:

- relay_1
- relay_2

---

### POST /config/bms

Updates BMS config.

Example body:

    {
      "enabled": true,
      "name": "House Battery",
      "address": "aa:bb:cc:dd:ee:ff",
      "address_type": "public"
    }

---

### POST /config/temp

Updates temperature sensor config.

Example body:

    {
      "id": "temp_1",
      "name": "Cabin",
      "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 generic defaults.

---

## Serial Monitor

Baud:

    115200

Line ending:

    Newline

---

## Status and Config Commands

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

### log quiet

Minimizes serial output.

### log info

Normal serial output.

### log debug

Enables recurring debug output.

---

## Relay Control Commands

Legacy relay control commands may still exist during development:

    relay starlink on
    relay starlink off
    relay fridge on
    relay fridge off

Future work should replace these with generic serial relay commands.

---

## Relay Configuration Commands

### relayname 1 Aux Power

Sets relay 1 display name.

### relayname 2 Accessory Power

Sets relay 2 display name.

Run `save` after changing names.

---

## Temperature Sensor Configuration Commands

### tempname 1 Cabin

Sets temp sensor 1 display name.

### tempname 2 Outside Air

Sets temp sensor 2 display name.

Run `save` after changing names.

---

## BMS Configuration Commands

### bmsname House Battery

Sets BMS display name.

### bmsaddr aa:bb:cc:dd:ee:ff

Sets BMS BLE address.

Run `save` after changing BMS config manually.

---

## BMS Setup Mode Commands

### enter setup

Enters BMS setup mode.

Effects:

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

### scan ble

Scans for BLE devices.

Notes:

- Some BMS modules advertise intermittently.
- Multiple scans may be required.

### 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
    select bms 1
    relayname 1 Aux Power
    relayname 2 Accessory Power
    tempname 1 Cabin
    tempname 2 Outside Air
    save
    config

---

## Known Notes

- BMS telemetry is reliable once a BMS address is configured.
- BLE discovery depends on how often the BMS advertises.
- DS18B20 sensors require a 4.7kΩ pull-up resistor on the 1-Wire data bus.
- Some legacy relay names still exist internally and should be removed in a future cleanup.