Skip to content

MQTT

Devices can send data to, and receive commands from, the platform over MQTT. The platform's MQTT client subscribes to everything under interface/#, keeps the most recent messages of each device in memory and exposes them through the REST endpoints and a WebSocket stream below.

Broker and topics

Item Value
Broker host spoilerinterface.com
MQTT port 1883 (plain MQTT, anonymous connections allowed)
WebSocket port 9001 is published by the container, but the Mosquitto WebSocket listener is disabled in the default mosquitto.conf
Data topic (device to platform) interface/<device_type>/<device_id>/data
Command topic (platform to device) interface/<device_type>/<device_id>/command
  • <device_type> is a canonical type (table below) and <device_id> is the numeric ID of an existing device.
  • Messages on any sub-topic interface/<device_type>/<device_id>/... are kept in the device's live buffer. Messages for topics that do not map to an existing device are dropped.
  • Payloads are parsed as JSON when possible, otherwise kept as text.
  • The live buffer holds the last 200 messages per device, in memory only (it is cleared when the service restarts). MQTT messages are shown in the live view; they are not written to the device history.

Device types:

Canonical type Aliases accepted by the API Device
sensor Sensor
switch Switch
gps GPS
workstation ws Workstation
met meteorological, meteo Meteorological
batmon Battery monitor
ping device Device (ping)
dynamic interface Dynamic interface

Aliases are accepted in API requests (case-insensitive); topics always use the canonical type, e.g. interface/workstation/301659085216623/data.

Publishing from a device (example):

mosquitto_pub -h spoilerinterface.com -p 1883 -t interface/sensor/301659085216623/data -m '{"value": 21.5}'

Authentication and errors

All REST endpoints and the WebSocket use the api_key (query parameter api_key or the api_key cookie). Every endpoint that takes a device_type / device_id also checks that the device belongs to the caller.

Errors are returned with an HTTP status code and the message under both an error and a failed key:

{
    "error": "Device not found or not owned by you",
    "failed": "Device not found or not owned by you"
}
Status Cause
400 Unknown device_type
401 Missing/invalid api_key (body is {"failed": "[Auth]: Failed to validate the api_key. Try to login again."}) or user not found
403 Device not found or not owned by you; publish topic outside the device's namespace
404 Device not found when creating a topic

List topics

GET/mqtt/topics

Returns the broker status and the topics of the user's devices that the platform is tracking

Request

Auth: api_key (query param or cookie)

Request body:

None

Request example:

https://spoilerinterface.com/interface/mqtt/topics?api_key=8f14e45fceea167a5a36dedd4bea2543

Response

{
    "success": {
        "status": {
            "broker": "127.0.0.1:1883",
            "host": "127.0.0.1",
            "port": 1883,
            "connected": true,
            "topics_count": 3,
            "created_topics": 1,
            "live_subscribers": 0
        },
        "topics": [
            {
                "topic": "interface/sensor/301659085216623/data",
                "command_topic": "interface/sensor/301659085216623/command",
                "device_type": "sensor",
                "device_id": "301659085216623",
                "created": true,
                "last_seen": 1716553472123,
                "message_count": 12,
                "last": {
                    "topic": "interface/sensor/301659085216623/data",
                    "payload": {"value": 21.5},
                    "raw": "{\"value\": 21.5}",
                    "timestamp": 1716553472123,
                    "retained": false
                },
                "device_name": "Door sensor"
            }
        ]
    }
}

Field description

Field name Description Type
status Broker status (see Broker status). topics_count / created_topics count all tracked devices, not only yours json
topic Data topic of the device str
command_topic Command topic of the device str
created true if the topic was explicitly created with Create topic; false if it was discovered from incoming messages bool
last_seen Time of the last message (epoch milliseconds) int
message_count Messages in the live buffer int
last Most recent message json
device_name Name of the device str

Broker status

GET/mqtt/status

Returns the status of the platform's connection to the MQTT broker

Request

Auth: api_key (query param or cookie)

Request body:

None

Request example:

https://spoilerinterface.com/interface/mqtt/status?api_key=8f14e45fceea167a5a36dedd4bea2543

Response

{
    "success": {
        "broker": "127.0.0.1:1883",
        "host": "127.0.0.1",
        "port": 1883,
        "connected": true,
        "topics_count": 3,
        "created_topics": 1,
        "live_subscribers": 0
    }
}

Field description

Field name Description Type
broker / host / port Broker address used by the platform's internal client str
connected Whether the platform client is connected bool
topics_count Number of tracked device topics int
created_topics Number of explicitly created topics int
live_subscribers Open WebSocket live views int

Live messages

GET/mqtt/live

Returns the recent messages in a device's live buffer

Request

Auth: api_key (query param or cookie); device must be owned by the caller

Request body:

Query parameters:

Field name Description Type
device_type Device type (canonical or alias) str
device_id Device ID int
limit [Optional] Maximum number of messages to return (default 50, buffer holds 200) int

Request example:

https://spoilerinterface.com/interface/mqtt/live?api_key=8f14e45fceea167a5a36dedd4bea2543&device_type=sensor&device_id=301659085216623&limit=20

Response

{
    "success": {
        "device_type": "sensor",
        "device_id": "301659085216623",
        "data_topic": "interface/sensor/301659085216623/data",
        "command_topic": "interface/sensor/301659085216623/command",
        "created": true,
        "messages": [
            {
                "topic": "interface/sensor/301659085216623/data",
                "payload": {"value": 21.5},
                "raw": "{\"value\": 21.5}",
                "timestamp": 1716553472123,
                "retained": false
            }
        ]
    }
}

Field description

Field name Description Type
created Whether a topic record exists for the device bool
messages Messages oldest-first. payload is parsed JSON (or text), raw the original text (max 8000 characters), timestamp in epoch milliseconds, retained the MQTT retain flag arr

Create topic

POST/mqtt/topic

Registers a device's topic so it is listed even before the device sends data

Request

Auth: api_key (query param or cookie); device must be owned by the caller · Content-type: application/x-www-form-urlencoded

Request body:

The request body should be sent as form data:

Field name Description Type
device_type Device type (canonical or alias) str
device_id Device ID int

Request example:

device_type=sensor&device_id=301659085216623

Response

{
    "success": {
        "topic": "interface/sensor/301659085216623/data",
        "command_topic": "interface/sensor/301659085216623/command",
        "record": {
            "topic": "interface/sensor/301659085216623/data",
            "command_topic": "interface/sensor/301659085216623/command",
            "device_type": "sensor",
            "device_id": "301659085216623",
            "created": true,
            "last_seen": null,
            "message_count": 0,
            "last": null
        }
    }
}

Delete topic

DELETE/mqtt/topic

Removes a device's topic record and clears its live buffer

Request

Auth: api_key (query param or cookie); device must be owned by the caller · Content-type: application/x-www-form-urlencoded

Request body:

The request body should be sent as form data:

Field name Description Type
device_type Device type (canonical or alias) str
device_id Device ID int

Request example:

device_type=sensor&device_id=301659085216623

Response

{
    "success": {
        "deleted": true
    }
}

Note: The platform keeps listening on interface/#, so a record is created again (with created: false) as soon as the device sends another message.

Publish

POST/mqtt/publish

Publishes a message to one of the device's topics (by default its command topic)

Request

Auth: api_key (query param or cookie); device must be owned by the caller · Content-type: application/x-www-form-urlencoded

Request body:

The request body should be sent as form data:

Field name Description Type
device_type Device type (canonical or alias) str
device_id Device ID int
topic [Optional] Topic to publish to. Defaults to interface/<type>/<id>/command. Must start with interface/<type>/<id>/ and must not contain # or + str
payload [Optional] Message body. Sent as JSON if it parses as JSON, otherwise as text. Default {} str
qos [Optional] MQTT QoS level 0, 1 or 2 (default 0) int
retain [Optional] MQTT retain flag (default false) bool

Request example:

device_type=switch&device_id=301659085216623&payload={"state":true}&qos=1

Response

{
    "success": {
        "topic": "interface/switch/301659085216623/command",
        "device_type": "switch",
        "device_id": "301659085216623",
        "published": true
    }
}

A topic outside the device's namespace returns 403 with Topic must start with interface/<type>/<id>/.

WebSocket live view

WS/ws/mqtt/live

Streams a device's MQTT messages to the client in real time

Request

Auth: api_key (query param or cookie); device must be owned by the caller

Query parameters:

Field name Description Type
api_key Session API key str
device_type Device type (canonical or alias) str
device_id Device ID int

Close codes (sent before the connection is accepted):

Code Meaning
4001 Missing or invalid api_key
4003 Unknown device type, or device not found / not owned by you

Server frames

All frames are JSON text. Right after connecting the server sends a ready frame:

{
    "type": "ready",
    "device_type": "sensor",
    "device_id": 301659085216623,
    "data_topic": "interface/sensor/301659085216623/data",
    "command_topic": "interface/sensor/301659085216623/command"
}

Each new message for the device is pushed as a message frame:

{
    "type": "message",
    "topic": "interface/sensor/301659085216623/data",
    "payload": {"value": 21.5},
    "raw": "{\"value\": 21.5}",
    "timestamp": 1716553472123,
    "retained": false
}

Client frames

To fetch the buffered messages, send:

{
    "action": "history",
    "limit": 50
}

The server answers with:

{
    "type": "history",
    "messages": [
        {
            "topic": "interface/sensor/301659085216623/data",
            "payload": {"value": 21.5},
            "raw": "{\"value\": 21.5}",
            "timestamp": 1716553472123,
            "retained": false
        }
    ]
}

limit defaults to 50. Other client frames are ignored.