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¶
/mqtt/topicsReturns 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¶
/mqtt/statusReturns 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¶
/mqtt/liveReturns 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¶
/mqtt/topicRegisters 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¶
/mqtt/topicRemoves 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¶
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¶
/mqtt/publishPublishes 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/mqtt/liveStreams 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:
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.