MQTT API
Overview
The myDevices MQTT API is used to connect any device that you have with the myDevices Cloud. After connecting your device you can send data from your device to the myDevices dashboard and display it using widgets. You may also receive commands from myDevices, allowing remote control and automation of your devices.
About MQTT
MQTT is a lightweight messaging protocol designed to be used on top of TCP/IP. It uses an event and message (publish-subscribe) methodology that was designed especially for connections where small footprints, unreliable and/or limited bandwidth connections are found. This type of pattern is especially suited for IoT devices that get deployed in the field and often run on battery power and on constrained networks. With MQTT, the publish-subscribe pattern makes use of a broker that is responsible for distributing messages to clients.Clients can subscribe to varying levels of messages, depending upon how much or what kind of data they are interested.
MQTT Libraries
MQTT is the preferred transport and API for sending data to the myDevices Cloud, or for devices that receive commands from myDevices. The myDevices Cloud acts as a broker, managing the various sensor and actuator client devices that wish to send and receive data using the myDevices Cloud.
myDevices MQTT is straightforward and easy to use, offering several different ways of connecting your data to myDevices.
Using one of our libraries is the easiest way to get started using MQTT with myDevices. The myDevices libraries bundle an MQTT clientand all of the code examples you'll need to get your board connected and using MQTT with myDevices.
We have prepared libraries for some of the most common toolchain/IDE combinations to help get you up and running as quickly as possible.
MQTT API functions
If you are integrating myDevices into your existing or custom program, you may wish to only use raw MQTT calls for interacting with myDevices. Typically you will have already chosen your own MQTT client, will already have implemented your own networking code, and you just need the Publish-Subscribe details for myDevices’s MQTT API.
If you fall into this camp, you can jump straight to the MQTT Messaging Topics section where you’ll find the details for myDevices's MQTT calls. We have also prepared a tutorial for using an MQTT client to manually publish and subscribe data so that you can test out using MQTT with myDevices.
MQTT Clients
To interact with an MQTT broker you’ll need an MQTT client. Here’s a quick list of MQTT clients and resources:
Paho: The Eclipse Paho project provides open-source MQTT clients for C/C++, Python, Java, Javascript, Go and C#.
MQTT.fx: A JavaFX based MQTT Client.
MQTT Messaging Topics
MQTT is the preferred API protocol to send and receive data to and from myDevices dashboard. Payloads are plain text based or JSON, and topics follow a tree composed of a Username, a Client ID and a Channel ID, allowing for fine filtration and control. Therefore, MQTT does not require the use of a provisioning API. Data that is published to a backend topic can also be subscribed to by a user’s third party application.
Publish Sensor data as JSON
Message definition
| Topic | PUB | SUB | |
|---|---|---|---|
| v1/username/things/clientID/data/json | X | X |
A JSON string as payload:
[
{
"channel": 1,
"value": 16.4,
"type": "temp",
"unit": "c"
},
{
"channel": 2,
"value": 75,
"type": "rel_hum",
"unit": "p"
},
{
"channel": 5,
"value": 75,
"type": "batt",
"unit": "v"
}
]
The data property must be a JSON array of objects, each element having channel, value, type and unit porperties. Refer to the list of our
supported data types for the type and unit properties.
Publish individual Sensor data
In order to send data, the channel ID needs to be appended to the data topic.
| Topic | PUB | SUB | |
|---|---|---|---|
| v1/username/things/clientID/data/channel | X | X |
The data type and/or unit can be added to prefix the value, allowing the backend to process and display data without the need of configuring the data channel from the dashboard:
- (string)
type,unit=value
Receive Actuator command
In order to receive a command for a given data channel, the device must subscribe to the “cmd” topic.
| Topic | PUB | SUB | |
|---|---|---|---|
| v1/username/things/clientID/cmd/channel | X |
Payload will contain a command sequence number followed by the value. The Developer is responsible for managing the value format.
- (string)
seq,value
Send Actuator Updated Value
In order to let the dashboard know of the current status of an actuator, the device must publish that value to the corresponding channel. This will ensure that the widget state (on/off) remains consistent with the state of the actuator.
| Topic | PUB | SUB | |
|---|---|---|---|
| v1/username/things/clientID/data/channel | X |
Payload must contain simply the true binary value of a digital actuator (1/0) or numerical value for analog actuators.
- (string)
1 - (string)
0.8
Send command response
In order to let the system know of an actuator command, the device must publish a response on a common response topic.
| Topic | PUB | SUB | |
|---|---|---|---|
| v1/username/things/clientID/response | X |
Payload must contain the status “ok” or “error”, as well as the command sequence number and an optional message that will be displayed to the user in case of error.
- (string)
ok,seq - (string)
error,seq=message
Examples
Send Sensor Data to Channel 2
- Action:
Publish - Topic:
v1/A1234B5678C/things/0123-4567-89AB-CDEF/data/2 - Payload:
temp,c=20.7
Receive Actuator Command on Channel 3
- Action:
Subscribe - Topic:
v1/A1234B5678C/things/0123-4567-89AB-CDEF/cmd/3 - Payload:
2otoExGxnMJz0Jn,0
Send updated Actuator value on Channel 3
- Action:
Publish - Topic:
v1/A1234B5678C/things/0123-4567-89AB-CDEF/digital/3 - Payload:
1
Send a Command Response - OK
- Action:
Publish - Topic:
v1/A1234B5678C/things/0123-4567-89AB-CDEF/response - Payload:
ok,2otoExGxnMJz0Jn
Send a Command Response - Error
- Action:
Publish - Topic:
v1/A1234B5678C/things/0123-4567-89AB-CDEF/response - Payload:
error,2otoExGxn=ERROR MESSAGE