nick/overland-controller
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Make ESP32 firmware API fully generic

Browse Source
This commit is contained in:
nick
2026-06-04 03:33:36 -06:00
parent dc42284d87
commit cc1909faaf
8 changed files with 159 additions and 711 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api-and-serial-commands.md
+37 -199
View File
@@ -6,79 +6,29 @@ Base URL while connected to the ESP32 access point:
http://192.168.4.1
---
## Status
### GET /status
Returns full controller status.
Returns full controller status, including battery/BMS telemetry, relay states, temperature sensor states, alarms, system info, and current configuration.
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 states use generic IDs:
relay_1
relay_2
Temperature sensors use generic sensor IDs:
Temperature sensors use generic IDs:
temp_1
temp_2
temp_3
temp_4
temp_5
temp_6
temp_7
temp_8
---
temp_1 through temp_8
## Relay Control API
### GET /relay/relay_1/on
GET /relay/relay_1/on
GET /relay/relay_1/off
GET /relay/relay_2/on
GET /relay/relay_2/off
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.
---
Relay display names are configurable. Firmware and API clients should not assume what a relay controls.
## Configuration API
@@ -86,13 +36,9 @@ Future work should remove these aliases after the Pico/dashboard clients use gen
Returns saved configuration.
---
### POST /config/relay
Updates relay config.
Example body:
Example:
{
"id": "relay_1",
@@ -100,18 +46,9 @@ Example body:
"enabled": true
}
Valid IDs:
- relay_1
- relay_2
---
### POST /config/bms
Updates BMS config.
Example body:
Example:
{
"enabled": true,
@@ -120,13 +57,9 @@ Example body:
"address_type": "public"
}
---
### POST /config/temp
Updates temperature sensor config.
Example body:
Example:
{
"id": "temp_1",
@@ -135,24 +68,9 @@ Example body:
"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.
---
Clears saved configuration and restores generic defaults.
## Serial Monitor
@@ -164,135 +82,59 @@ 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.
---
status
config
save
factory reset
## Log Level Commands
### log quiet
Minimizes serial output.
### log info
Normal serial output.
### log debug
Enables recurring debug output.
---
log quiet
log info
log debug
## 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 1 on
relay 1 off
relay 2 on
relay 2 off
## Relay Configuration Commands
### relayname 1 Aux Power
Sets relay 1 display name.
### relayname 2 Accessory Power
Sets relay 2 display name.
relayname 1 Aux Power
relayname 2 Accessory Power
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.
tempname 1 Cabin
tempname 2 Outside Air
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.
bmsname House Battery
bmsaddr aa:bb:cc:dd:ee:ff
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.
enter setup
scan ble
select bms 1
exit setup
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.
---
- Multiple BLE scans may be required.
- Once a BMS address is configured, BMS telemetry reconnects directly using the saved address.
## Typical First-Time Setup Flow
@@ -308,11 +150,7 @@ Leaves BMS setup mode and allows BMS reconnect.
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.
- The firmware uses generic relay and temperature IDs. Installation-specific names belong in saved configuration only.
docs/api.md
+2 -237
View File
@@ -1,238 +1,3 @@
# Xterra Overland Dashboard API Specification
# Overland Controller API
## Overview
The ESP32 acts as the system controller and provides status and control endpoints.
Primary communication is UART over CAT5. WiFi HTTP API is the backup communication path.
WiFi HTTP API is provided for:
* Web dashboard
* Mobile access
* Configuration
* Future Home Assistant integration
---
# GET /status
Returns complete current system status.
Example:
```json
{
"timestamp": 1748910000,
"battery": {
"soc": 82,
"voltage": 13.2,
"current": -6.4,
"remaining_ah": 82.5,
"runtime_hours": 11.2,
"temperature_f": 77.4
},
"temps": {
"fridge_zone_1": 35.8,
"fridge_zone_2": 12.1,
"rear_seat": 78.0,
"outside": 88.4
},
"relays": {
"starlink": false,
"fridge": true
},
"network": {
"wifi_enabled": false,
"uart_connected": true
}
}
```
---
# GET /battery
Returns detailed battery information.
Example:
```json
{
"soc": 82,
"voltage": 13.2,
"current": -6.4,
"power_w": -84.5,
"remaining_ah": 82.5,
"runtime_hours": 11.2,
"temperature_f": 77.4,
"cells": [
3.299,
3.301,
3.300,
3.298
],
"cell_delta_mv": 3
}
```
---
# GET /temps
Returns all temperature sensors.
Example:
```json
{
"fridge_zone_1": 35.8,
"fridge_zone_2": 12.1,
"rear_seat": 78.0,
"outside": 88.4
}
```
---
# GET /relays
Returns relay states.
Example:
```json
{
"starlink": false,
"fridge": true
}
```
---
# POST /relay/starlink
Request:
```json
{
"state": true
}
```
Response:
```json
{
"success": true,
"starlink": true
}
```
---
# POST /relay/fridge
Request:
```json
{
"state": true
}
```
Response:
```json
{
"success": true,
"fridge": true
}
```
---
# GET /network
Returns network status.
Example:
```json
{
"wifi_enabled": false,
"uart_connected": true,
"starlink_enabled": false
}
```
---
# POST /network/wifi
Enable WiFi temporarily.
Request:
```json
{
"minutes": 10
}
```
Response:
```json
{
"success": true,
"expires_minutes": 10
}
```
---
# Future Endpoints
## Vehicle Data
GET /vehicle
```json
{
"speed_mph": 62,
"rpm": 2200,
"coolant_temp_f": 192,
"fuel_percent": 48
}
```
## GPS
GET /gps
```json
{
"lat": 43.6629,
"lon": -116.6874,
"speed_mph": 0,
"heading": 0
}
```
## Historical Data
GET /history
GET /history/temps
GET /history/battery
## Home Assistant
MQTT integration planned.
See `docs/api-and-serial-commands.md` for the current HTTP API and Serial command reference.