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

Add versioned HTTP API routes

Browse Source
This commit is contained in:
nick
2026-06-07 10:24:08 -06:00
parent ec39182bbd
commit d87080d23f
11 changed files with 226 additions and 137 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/API.md
+58 -50
View File
@@ -8,6 +8,12 @@ Default AP address:
http://192.168.4.1
```
Current API base path:
```text
/api/v1
```
All documented endpoints are local-first and must continue to work without internet access. Consumers should ignore unknown response fields for forward compatibility.
Current firmware version:
@@ -20,34 +26,36 @@ Current firmware version:
```text
GET /
GET /status
GET /config
GET /api/v1/status
GET /api/v1/config
POST /relay/set
POST /api/v1/relay/set
POST /config/device
POST /config/relay
POST /config/temp
POST /config/bms
POST /config/save
POST /config/factory-reset
POST /api/v1/config/device
POST /api/v1/config/relay
POST /api/v1/config/temp
POST /api/v1/config/bms
POST /api/v1/config/save
POST /api/v1/config/factory-reset
GET /config/wifi
POST /config/wifi
POST /wifi/connect
POST /wifi/clear
GET /api/v1/config/wifi
POST /api/v1/config/wifi
POST /api/v1/wifi/connect
POST /api/v1/wifi/clear
POST /temps/scan
POST /temps/assign
POST /temps/clear
POST /api/v1/temps/scan
POST /api/v1/temps/assign
POST /api/v1/temps/clear
POST /bms/setup/enter
POST /bms/setup/exit
POST /bms/scan
POST /bms/select
POST /api/v1/bms/setup/enter
POST /api/v1/bms/setup/exit
POST /api/v1/bms/scan
POST /api/v1/bms/select
```
Legacy relay routes remain available:
Pre-versioned root routes remain registered as compatibility aliases for existing local clients. New clients should use `/api/v1`.
Legacy GET relay routes remain available only as root compatibility aliases:
```text
GET /relay/relay_1/on
@@ -61,15 +69,15 @@ GET /relay/relay_2/off
The Waveshare ESP32-S3 dashboard MVP should use only:
```text
GET /status
POST /relay/set
GET /api/v1/status
POST /api/v1/relay/set
```
The dashboard is a client only. It may cache last-known values for display, but the Cargo ESP32 remains the source of truth for relay state, BMS state, alarms, and configuration.
## Status
### GET /status
### GET /api/v1/status
Returns complete controller status.
@@ -144,7 +152,7 @@ Fields:
| `online` | Current sensor detection state |
| `temperature_f` | Current Fahrenheit value, or `null` when offline |
Config supports `temp_1` through `temp_8`. Current `/status` runtime output is limited to the configured count capped at four sensors.
Config supports `temp_1` through `temp_8`. Current `/api/v1/status` runtime output is limited to the configured count capped at four sensors.
### relays
@@ -228,11 +236,11 @@ The AP remains enabled even when STA WiFi is configured or connected.
### config
`/status.config` embeds the same core configuration model used by `GET /config`.
`/api/v1/status.config` embeds the same core configuration model used by `GET /api/v1/config`.
## Configuration
### GET /config
### GET /api/v1/config
Returns saved controller configuration.
@@ -264,9 +272,9 @@ Returns saved controller configuration.
}
```
Note: current `GET /config` omits the `weather` field, while `/status.config.temperature_sensors[]` includes it.
Note: current `GET /api/v1/config` omits the `weather` field, while `/api/v1/status.config.temperature_sensors[]` includes it.
### POST /config/device
### POST /api/v1/config/device
Updates the controller display name.
@@ -278,7 +286,7 @@ Updates the controller display name.
Returns the updated config.
### POST /config/relay
### POST /api/v1/config/relay
Updates relay configuration.
@@ -300,7 +308,7 @@ Fields:
Returns the updated config.
### POST /config/temp
### POST /api/v1/config/temp
Updates temperature sensor configuration.
@@ -326,7 +334,7 @@ Fields:
Returns the updated config.
### POST /config/bms
### POST /api/v1/config/bms
Updates BMS configuration.
@@ -348,13 +356,13 @@ random
Returns the updated config.
### POST /config/save
### POST /api/v1/config/save
Persists the current active configuration.
Returns the current config.
### POST /config/factory-reset
### POST /api/v1/config/factory-reset
Clears saved configuration and restores firmware defaults.
@@ -362,7 +370,7 @@ Returns the reset config.
## Relay Control
### POST /relay/set
### POST /api/v1/relay/set
Preferred relay command endpoint.
@@ -407,7 +415,7 @@ Response:
## WiFi
### GET /config/wifi
### GET /api/v1/config/wifi
Returns AP/STA WiFi configuration status. Passwords are not returned.
@@ -435,7 +443,7 @@ Returns AP/STA WiFi configuration status. Passwords are not returned.
}
```
### POST /config/wifi
### POST /api/v1/config/wifi
Preferred multi-network request:
@@ -473,13 +481,13 @@ Runtime behavior:
- Lower priority numbers are tried first.
- If STA disconnects, saved networks are retried by priority.
### POST /wifi/connect
### POST /api/v1/wifi/connect
Attempts STA connection using saved networks by priority.
Returns WiFi config status.
### POST /wifi/clear
### POST /api/v1/wifi/clear
Clears saved STA WiFi networks.
@@ -487,7 +495,7 @@ Returns WiFi config status.
## Temperature Probe Setup
### POST /temps/scan
### POST /api/v1/temps/scan
Scans the DS18B20 bus and returns unassigned probe addresses.
@@ -506,7 +514,7 @@ Scans the DS18B20 bus and returns unassigned probe addresses.
Already-assigned probe addresses are hidden from scan results until cleared.
### POST /temps/assign
### POST /api/v1/temps/assign
Assigns a scanned probe to a logical temperature slot.
@@ -530,7 +538,7 @@ By slot number:
Returns the updated config.
### POST /temps/clear
### POST /api/v1/temps/clear
Clears one or all temperature assignments.
@@ -560,7 +568,7 @@ Returns the updated config.
These endpoints are for BMS discovery and selection. Do not change JBD/Xiaoxiang BLE behavior without explicit approval.
### POST /bms/setup/enter
### POST /api/v1/bms/setup/enter
Enters BMS setup mode.
@@ -574,7 +582,7 @@ Response:
}
```
### POST /bms/setup/exit
### POST /api/v1/bms/setup/exit
Exits BMS setup mode.
@@ -588,7 +596,7 @@ Response:
}
```
### POST /bms/scan
### POST /api/v1/bms/scan
Scans for BLE devices.
@@ -610,7 +618,7 @@ Response:
Some BMS devices advertise intermittently. Repeated scans may be needed.
### POST /bms/select
### POST /api/v1/bms/select
Selects a BMS from the most recent scan result.
@@ -676,9 +684,9 @@ Some serial/UART errors use `message` instead of `error`; HTTP clients should re
## Compatibility
Current stable route prefix is the root API path, for example `GET /status`.
Current stable API prefix is `/api/v1`, for example `GET /api/v1/status`.
Future versioning may move to `/api/v1`. Do not introduce versioned routes until consumers and docs are updated together.
Pre-versioned root routes remain registered as local compatibility aliases. Do not add new root-only HTTP API routes.
New fields may be added to existing JSON objects. Consumers should ignore unknown fields.
@@ -687,8 +695,8 @@ New fields may be added to existing JSON objects. Consumers should ignore unknow
These routes are not part of the current registered HTTP API:
```text
POST /bms/reconnect
POST /system/restart
POST /api/v1/bms/reconnect
POST /api/v1/system/restart
```
If added later, update this document and add contract tests.
docs/ARCHITECTURE.md
+4 -4
View File
@@ -93,11 +93,11 @@ HTTP is the primary integration contract for:
Preferred direction:
GET /status
GET /config
POST /relay/set
GET /api/v1/status
GET /api/v1/config
POST /api/v1/relay/set
Future versioning may move to /api/v1.
Pre-versioned root routes remain registered as compatibility aliases for existing local clients.
## Generic IDs
docs/CHANGELOG.md
+1 -1
View File
@@ -21,7 +21,7 @@
- WiFi priority and runtime reconnect behavior.
- HTTP/UART/USB serial command parity documentation.
- DS18B20 configurable temperature probe support.
- Preferred relay command endpoint: `POST /relay/set`.
- Preferred relay command endpoint: `POST /api/v1/relay/set`.
### Changed
docs/CONFIGURATION.md
+5 -5
View File
@@ -38,7 +38,7 @@ Serial command:
HTTP endpoint:
POST /config/device
POST /api/v1/config/device
## Relay Configuration
@@ -67,7 +67,7 @@ Serial commands:
HTTP endpoint:
POST /config/relay
POST /api/v1/config/relay
## Temperature Sensor Configuration
@@ -102,7 +102,7 @@ Serial commands:
HTTP endpoint:
POST /config/temp
POST /api/v1/config/temp
## BMS Configuration
@@ -127,7 +127,7 @@ Serial commands:
HTTP endpoint:
POST /config/bms
POST /api/v1/config/bms
## BMS Setup Mode
@@ -157,7 +157,7 @@ Serial command:
HTTP endpoint:
POST /config/factory-reset
POST /api/v1/config/factory-reset
After factory reset:
docs/PARITY_MATRIX.md
+10 -10
View File
@@ -12,14 +12,14 @@ Control surfaces:
| Feature | USB Serial | UART JSON | HTTP API | Notes |
|---|---:|---:|---:|---|
| Status | Yes | Yes | Yes | `/status` equals `status_request` |
| Config view | Yes | Yes | Yes | `/config` equals `config_request` |
| Relay control | Yes | Yes | Yes | Preferred HTTP endpoint is `POST /relay/set` |
| Device name config | Yes | Yes | Yes | `devicename`, `config_device`, `/config/device` |
| Relay config | Yes | Yes | Yes | `relayname`, `config_relay`, `/config/relay` |
| Temperature config | Yes | Yes | Yes | `tempname`, `config_temp`, `/config/temp` |
| BMS config | Yes | Yes | Yes | `bmsname`/`bmsaddr`, `config_bms`, `/config/bms` |
| Save config | Yes | Yes | Yes | `save`, `save_config`, `/config/save` |
| Status | Yes | Yes | Yes | `/api/v1/status` equals `status_request` |
| Config view | Yes | Yes | Yes | `/api/v1/config` equals `config_request` |
| Relay control | Yes | Yes | Yes | Preferred HTTP endpoint is `POST /api/v1/relay/set` |
| Device name config | Yes | Yes | Yes | `devicename`, `config_device`, `/api/v1/config/device` |
| Relay config | Yes | Yes | Yes | `relayname`, `config_relay`, `/api/v1/config/relay` |
| Temperature config | Yes | Yes | Yes | `tempname`, `config_temp`, `/api/v1/config/temp` |
| BMS config | Yes | Yes | Yes | `bmsname`/`bmsaddr`, `config_bms`, `/api/v1/config/bms` |
| Save config | Yes | Yes | Yes | `save`, `save_config`, `/api/v1/config/save` |
| Factory reset | Yes | Yes | Yes | AP remains recovery path |
| BMS setup enter | Yes | Yes | Yes | Setup pauses normal BMS reconnect behavior |
| BMS setup exit | Yes | Yes | Yes | Returns to normal mode |
@@ -58,9 +58,9 @@ Legacy UART relay fields may still be accepted:
Preferred HTTP relay endpoint:
POST /relay/set
POST /api/v1/relay/set
Legacy HTTP relay routes may remain for compatibility:
Legacy root HTTP relay routes remain for compatibility:
GET /relay/relay_1/on
GET /relay/relay_1/off
docs/dashboard-esp32s3.md
+9 -9
View File
@@ -47,15 +47,15 @@ All grounds remain common.
## API endpoints consumed
Minimum dashboard MVP:
- GET /status
- POST /relay/set
- GET /api/v1/status
- POST /api/v1/relay/set
Potential later use:
- GET /config
- POST /config/save
- POST /temps/scan
- POST /temps/assign
- POST /temps/clear
- GET /api/v1/config
- POST /api/v1/config/save
- POST /api/v1/temps/scan
- POST /api/v1/temps/assign
- POST /api/v1/temps/clear
## MVP Display Goals
@@ -120,10 +120,10 @@ Then interactive:
1. Dashboard boots.
2. Connects to cargo ESP32 AP.
3. Polls GET /status.
3. Polls GET /api/v1/status.
4. Shows disconnected state until valid JSON is received.
5. Updates dashboard on a fixed interval.
6. Relay buttons call POST /relay/set.
6. Relay buttons call POST /api/v1/relay/set.
## Polling Guidance