319 lines
4.3 KiB
Markdown
319 lines
4.3 KiB
Markdown
# 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.
|