136 lines
3.1 KiB
Markdown
136 lines
3.1 KiB
Markdown
# IoT Bridge HTTP API
|
|
|
|
This document describes the HTTP endpoints exposed by the IoT Bridge config server.
|
|
|
|
Base URL: `http://<bridge-host>:8080`
|
|
|
|
## Authentication
|
|
|
|
Authentication is optional. If `BRIDGE_API_TOKEN` is set, all protected endpoints require:
|
|
|
|
```
|
|
Authorization: Bearer <token>
|
|
```
|
|
|
|
If the header is missing or invalid, the server responds with `401` or `403`.
|
|
|
|
## GET /health
|
|
|
|
Health check endpoint.
|
|
|
|
Response (200):
|
|
|
|
```json
|
|
{
|
|
"status": "ok",
|
|
"devices": 2,
|
|
"subscriptions": 2,
|
|
"last_config_update": "2026-02-12T19:40:18.123456"
|
|
}
|
|
```
|
|
|
|
## POST /config
|
|
|
|
Receives a full configuration payload from Odoo.
|
|
|
|
Request body:
|
|
|
|
```json
|
|
{
|
|
"devices": [
|
|
{
|
|
"device_id": "shelly-pm-workshop",
|
|
"machine_name": "CNC Mill (Workshop)",
|
|
"mqtt_topic": "shellypmminig3-48f6eeb73a1c/status/pm1:0",
|
|
"parser_type": "shelly_pm",
|
|
"session_config": {
|
|
"standby_threshold_w": 5.0,
|
|
"working_threshold_w": 50.0,
|
|
"start_debounce_s": 3.0,
|
|
"stop_debounce_s": 15.0,
|
|
"message_timeout_s": 20.0,
|
|
"heartbeat_interval_s": 300.0
|
|
}
|
|
}
|
|
],
|
|
"timestamp": "2026-02-12T19:40:18Z",
|
|
"version": "1.0"
|
|
}
|
|
```
|
|
|
|
Response (200):
|
|
|
|
```json
|
|
{
|
|
"status": "success",
|
|
"message": "Configuration applied",
|
|
"devices_configured": 1,
|
|
"timestamp": "2026-02-12T19:40:18.456789"
|
|
}
|
|
```
|
|
|
|
Behavior:
|
|
- Validates the schema (Pydantic models in `config_server.py`).
|
|
- Updates MQTT subscriptions based on device list.
|
|
- Persists config to `/data/config-active.yaml`.
|
|
|
|
Errors:
|
|
- `400` Validation errors from request schema.
|
|
- `401` Missing Authorization header (when auth is enabled).
|
|
- `403` Invalid token.
|
|
- `500` Failure applying configuration.
|
|
|
|
## GET /config
|
|
|
|
Returns the currently active configuration.
|
|
|
|
Response (200):
|
|
|
|
```json
|
|
{
|
|
"devices": [
|
|
{
|
|
"device_id": "shelly-pm-workshop",
|
|
"machine_name": "CNC Mill (Workshop)",
|
|
"mqtt_topic": "shellypmminig3-48f6eeb73a1c/status/pm1:0",
|
|
"parser_type": "shelly_pm",
|
|
"session_config": {
|
|
"standby_threshold_w": 5.0,
|
|
"working_threshold_w": 50.0,
|
|
"start_debounce_s": 3.0,
|
|
"stop_debounce_s": 15.0,
|
|
"message_timeout_s": 20.0,
|
|
"heartbeat_interval_s": 300.0
|
|
}
|
|
}
|
|
],
|
|
"timestamp": "2026-02-12T19:40:18Z",
|
|
"version": "1.0"
|
|
}
|
|
```
|
|
|
|
Errors:
|
|
- `404` If no configuration has been loaded yet.
|
|
|
|
## Schema Reference
|
|
|
|
Top-level fields:
|
|
- `devices`: Array of device configurations.
|
|
- `timestamp`: ISO timestamp set by Odoo or bridge.
|
|
- `version`: Schema version.
|
|
|
|
Device fields:
|
|
- `device_id`: Unique identifier.
|
|
- `machine_name`: Human-readable name.
|
|
- `mqtt_topic`: MQTT topic to subscribe to.
|
|
- `parser_type`: Parser identifier (default `shelly_pm`).
|
|
- `session_config`: Session thresholds and timing.
|
|
|
|
Session config fields:
|
|
- `standby_threshold_w`: Power threshold to detect standby.
|
|
- `working_threshold_w`: Power threshold to detect working state.
|
|
- `start_debounce_s`: Seconds before confirming a session start.
|
|
- `stop_debounce_s`: Seconds before confirming a session stop.
|
|
- `message_timeout_s`: Max silence before timeout event.
|
|
- `heartbeat_interval_s`: Aggregated event interval.
|