MQTT protocol

The ThingsLinker library does all of this for you. Read this page if you write your own client: firmware for another platform, a gateway, or a test tool.

Broker

Host	mqtt.thingslinker.com
Port	8883, MQTT over TLS
WebSocket	wss://mqtt.thingslinker.com:8084/mqtt, for browsers
Login	None needed: the ThingsLinker broker accepts devices without a username or password.
Client ID	Must be unique per connection, for example ThingsLinker_<chip ID>. Two clients with the same ID disconnect each other.

Topics

device/{WidgetType}/{BlueprintKey}/{AuthToken}/{Pin}/
device/status/{BlueprintKey}/{AuthToken}/

Part	Value
WidgetType	The widget type's exact name, case-sensitive and with spaces where the name has them: Button, Switch, LED, Slider, Gauge, Chart, Label, Value Display, Terminal, RGB, Timer, Map, Joystick, Status, Selector, Number Input, Progress Bar, Text Input, Keypad.
BlueprintKey	The blueprint's key, starting with BLUE. Not the blueprint's ID.
AuthToken	The device's auth token.
Pin	V0 to V124.

The trailing slash is part of the topic. Example:

device/Chart/BLUEbV7N2u5diuUi/YOUR_AUTH_TOKEN/V1/

The same topic carries both directions: the device publishes readings on it and the dashboards publish commands on it. Subscribe to the topics of the controls your device handles.

Payload

{"v": 23.5, "t": 1792609250}

Field	Meaning
v	The value, in the JSON type that matches the widget's data type: Integer 42, Float 23.5, Boolean 1 or 0, String "text".
t	When the value was taken, as a Unix timestamp in seconds.

Never send numbers as strings: "123" is text, and charts and alerts ignore text.

Complex widgets add fields next to v, never inside it:

Widget	Payload
RGB	{"v": 1, "t": ts, "r": 255, "g": 128, "b": 0, "count": 8, "pattern": "Solid"} (v: 1 on, 0 off)
Joystick	{"v": 0, "t": ts, "x": 0.5, "y": -0.3}
Map	{"v": 23.0225, "t": ts, "lat": 23.0225, "lng": 72.5714}
Terminal	{"v": "text", "t": ts}

Online status

• When the device connects, publish ONLINE to its status topic with retain set.
• Set the connection's last will to OFFLINE on the same topic, with retain, so ThingsLinker marks the device offline if it drops.
• Subscribe to your own status topic. If you receive OFFLINE while connected (a late last will from an earlier connection), publish ONLINE again.

Commands to the device

device/command/{BlueprintKey}/{AuthToken}/

The ThingsLinker server sends commands here, sent once and not retained. There is one command today:

Command	Payload	What the device does
Reset WiFi	{"cmd": "reset_wifi", "t": 1792609250}	Erases its saved network and restarts into Bluetooth setup mode

A device should ignore a command whose t is more than a couple of minutes from its own clock, and clear the topic (publish an empty retained message) before subscribing, so that an old command cannot act on it later. The ThingsLinker library does both.

Retained messages

• Devices publish readings without retain.
• Dashboards publish commands with retain, except Keypad and Text Input, so a device that connects receives the last setting of each control. Handle these on connect like any other command.
• A device receives its own publications back on topics it subscribes to. Ignore messages identical to ones you just sent.