odoo_mqtt/iot_bridge/API.md

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):

{
  "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:

{
  "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):

{
  "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):

{
  "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.