MQTT Device API Reference

On this page

MQTT Device API Reference

Getting started

MQTT basics

MQTT is a lightweight publish-subscribe messaging protocol which probably makes it the most suitable for various IoT devices. You can find more information about MQTT here.

IoT Hub server nodes act as an MQTT Broker that supports QoS levels 0 (at most once) and 1 (at least once) and a set of configurable topics.

Client libraries setup

You can find a large number of MQTT client libraries on the web. Examples in this article will be based on Mosquitto and MQTT.js. In order to setup one of those tools, you can use instructions in our Hello World guide.

MQTT Connect

We will use access token device credentials in this article and they will be referred to later as $ACCESS_TOKEN. The application needs to send MQTT CONNECT message with username that contains $ACCESS_TOKEN. The alternative option is to use Basic MQTT Credentials - combination of client id, username and password;

Possible return codes and their reasons during connect sequence:

  • 0x00 Connected - Successfully connected to IoT Hub MQTT server.
  • 0x04 Connection Refused, bad user name or password - Username is empty.
  • 0x05 Connection Refused, not authorized - Username contains invalid $ACCESS_TOKEN.

Key-value format

By default, IoT Hub supports key-value content in JSON. Key is always a string, while value can be either string, boolean, double, long or JSON. For example:

1
2
3
4
5
6
7
8
9
10
11

{
 "stringKey":"value1", 
 "booleanKey":true, 
 "doubleKey":42.0, 
 "longKey":73, 
 "jsonKey": {
    "someNumber": 42,
    "someArray": [1,2,3],
    "someNestedObject": {"key": "value"}
 }
}

However, it is also possible to send data via Protocol Buffers. Please refer to the MQTT transport type configuration section in device profile article for more details.

Using custom binary format or some serialization framework is also possible. See protocol customization for more details.

Telemetry upload API

In order to publish telemetry data to IoT Hub server node, send PUBLISH message to the following topic:

1

v1/devices/me/telemetry

The simplest supported data formats are:

1

{"key1":"value1", "key2":"value2"}

or

1

[{"key1":"value1"}, {"key2":"value2"}]

Please note that in this case, the server-side timestamp will be assigned to uploaded data!

In case your device is able to get the client-side timestamp, you can use following format:

1

{"ts":1451649600512, "values":{"key1":"value1", "key2":"value2"}}

In the example above, we assume that “1451649600512” is a unix timestamp with milliseconds precision. For example, the value ‘1451649600512’ corresponds to ‘Fri, 01 Jan 2016 12:00:00.512 GMT’

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# for IoT Hub

# Publish data as an object without timestamp (server-side timestamp will be used)
mosquitto_pub -d -q 1 -h "iothub.magenta.at" -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -m "{"temperature":42}"
# Publish data as an object without timestamp (server-side timestamp will be used) using data from file
mosquitto_pub -d -q 1 -h "iothub.magenta.at" -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -f "telemetry-data-as-object.json"
# Publish data as an array of objects without timestamp (server-side timestamp will be used)  using data from file
mosquitto_pub -d -q 1 -h "iothub.magenta.at" -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -f "telemetry-data-as-array.json"
# Publish data as an object with timestamp (telemetry timestamp will be used)  using data from file
mosquitto_pub -d -q 1 -h "iothub.magenta.at" -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -f "telemetry-data-with-ts.json"

# for local IoT Hub

# Publish data as an object without timestamp (server-side timestamp will be used)
mosquitto_pub -d -q 1 -h "127.0.0.1" -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -m "{"temperature":42}"
# Publish data as an object without timestamp (server-side timestamp will be used) using data from file
mosquitto_pub -d -q 1 -h "127.0.0.1" -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -f "telemetry-data-as-object.json"
# Publish data as an array of objects without timestamp (server-side timestamp will be used) using data from file
mosquitto_pub -d -q 1 -h "127.0.0.1" -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -f "telemetry-data-as-array.json"
# Publish data as an object with timestamp (telemetry timestamp will be used) using data from file
mosquitto_pub -d -q 1 -h "127.0.0.1" -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -f "telemetry-data-with-ts.json"

1
2
3
4
5
6
7
8

# Publish data as an object without timestamp (server-side timestamp will be used)
mqtt pub -v -q 1 -h "iothub.magenta.at" -t "v1/devices/me/telemetry" -u '$ACCESS_TOKEN' -s -m "{"temperature":42}"
# Publish data as an object without timestamp (server-side timestamp will be used)
cat telemetry-data-as-object.json | mqtt pub -v -h "iothub.magenta.at" -t "v1/devices/me/telemetry" -u '$ACCESS_TOKEN' -s
# Publish data as an array of objects without timestamp (server-side timestamp will be used)
cat telemetry-data-as-array.json | mqtt pub -v -h "iothub.magenta.at" -t "v1/devices/me/telemetry" -u '$ACCESS_TOKEN' -s
# Publish data as an object with timestamp (telemetry timestamp will be used)
cat telemetry-data-with-ts.json | mqtt pub -v -h "iothub.magenta.at" -t "v1/devices/me/telemetry" -u '$ACCESS_TOKEN' -s

1
2
3
4
5
6
7
8
9
10
11

{
  "stringKey": "value1",
  "booleanKey": true,
  "doubleKey": 42.0,
  "longKey": 73,
  "jsonKey": {
    "someNumber": 42,
    "someArray": [1,2,3],
    "someNestedObject": {"key": "value"}
  }
}

1

[{"key1":"value1"}, {"key2":true}]

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{
  "ts": 1451649600512,
  "values": {
    "stringKey": "value1",
    "booleanKey": true,
    "doubleKey": 42.0,
    "longKey": 73,
    "jsonKey": {
      "someNumber": 42,
      "someArray": [1, 2, 3],
      "someNestedObject": {
        "key": "value"
      }
    }
  }
}

Attributes API

IoT Hub attributes API allows devices to

  • Upload client-side device attributes to the server.
  • Request client-side and shared device attributes from the server.
  • Subscribe to shared device attributes from the server.
Publish attribute update to the server

In order to publish client-side device attributes to IoT Hub server node, send PUBLISH message to the following topic:

1

v1/devices/me/attributes

1
2
3
4
5
6
7
8
9
10
11
12
13

# for IoT Hub

# Publish client-side attributes update
mosquitto_pub -d -h "iothub.magenta.at" -t "v1/devices/me/attributes" -u "$ACCESS_TOKEN" -m "{"attribute1": "value1", "attribute2": true}"
# Publish client-side attributes update from file
mosquitto_pub -d -h "iothub.magenta.at" -t "v1/devices/me/attributes" -u "$ACCESS_TOKEN" -f "new-attributes-values.json"

# for local IoT Hub

# Publish client-side attributes update
mosquitto_pub -d -h "127.0.0.1" -t "v1/devices/me/attributes" -u "$ACCESS_TOKEN" -m "{"attribute1": "value1", "attribute2": true}"
# Publish client-side attributes update from file
mosquitto_pub -d -h "127.0.0.1" -t "v1/devices/me/attributes" -u "$ACCESS_TOKEN" -f "new-attributes-values.json"

1
2

# Publish client-side attributes update
cat new-attributes-values.json | mqtt pub -d -h "127.0.0.1" -t "v1/devices/me/attributes" -u '$ACCESS_TOKEN' -s

1
2
3
4
5
6
7
8
9
10
11

{
  "attribute1": "value1",
  "attribute2": true,
  "attribute3": 42.0,
  "attribute4": 73,
  "attribute5": {
    "someNumber": 42,
    "someArray": [1,2,3],
    "someNestedObject": {"key": "value"}
  }
}
Request attribute values from the server

In order to request client-side or shared device attributes to IoT Hub server node, send PUBLISH message to the following topic:

1

v1/devices/me/attributes/request/$request_id

where $request_id is your integer request identifier. Before sending PUBLISH message with the request, client need to subscribe to

1

v1/devices/me/attributes/response/+

The following example is written in javascript and is based on mqtt.js. Pure command-line examples are not available because subscribe and publish need to happen in the same mqtt session.

1
2

export TOKEN=$ACCESS_TOKEN
node mqtt-js-attributes-request.js

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

var mqtt = require('mqtt')
var client  = mqtt.connect('mqtt://iothub.magenta.at',{
    username: process.env.TOKEN
})

client.on('connect', function () {
    console.log('connected')
    client.subscribe('v1/devices/me/attributes/response/+')
    client.publish('v1/devices/me/attributes/request/1', '{"clientKeys":"attribute1,attribute2", "sharedKeys":"shared1,shared2"}')
})

client.on('message', function (topic, message) {
    console.log('response.topic: ' + topic)
    console.log('response.body: ' + message.toString())
    client.end()
})

1

{"key1":"value1"}

Please note, the intersection of client-side and shared device attribute keys is a bad practice! However, it is still possible to have same keys for client, shared or even server-side attributes.

Subscribe to attribute updates from the server

In order to subscribe to shared device attribute changes, send SUBSCRIBE message to the following topic:

1

v1/devices/me/attributes

When a shared attribute is changed by one of the server-side components (such as the REST API or the Rule Chain), the client will receive the following update:

1

{"key1":"value1"}

1
2
3
4
5
6
7
8
9

# for IoT Hub

# Subscribes to attribute updates
mosquitto_sub -d -h "iothub.magenta.at" -t "v1/devices/me/attributes" -u "$ACCESS_TOKEN"

# for local IoT Hub

# Subscribes to attribute updates
mosquitto_sub -d -h "127.0.0.1" -t "v1/devices/me/attributes" -u "$ACCESS_TOKEN"

1
2

# Subscribes to attribute updates
mqtt sub -v "127.0.0.1" -t "v1/devices/me/attributes" -u '$ACCESS_TOKEN'

JSON value support

We added support of JSON data structures to telemetry and attributes API to simplify work with device configuration. JSON support allows you to both upload from the device, and push to device nested objects. You can store one configuration JSON as a shared attribute and push it to the device. You can also process the JSON data in the rule engine and raise alarms, etc.

Therefore, this improvement minimizes the number of Database operations when IoT Hub stores the data. For example, “temperature” and “humidity” would be stored as separate rows in SQL or NoSQL databases in order to efficiently aggregate this data for visualization. Since there is no need to aggregate JSON data, we can store all the content as one row instead of separate rows for each configuration item. In some of our environments, it is possible to decrease the number of database operations more than 10 times by aggregating multiple parameters within one JSON.

Learn more about JSON value support with the video.

RPC API

Server-side RPC

In order to subscribe to RPC commands from the server, send SUBSCRIBE message to the following topic:

1

v1/devices/me/rpc/request/+

Once subscribed, the client will receive individual commands as a PUBLISH message to the corresponding topic:

1

v1/devices/me/rpc/request/$request_id

where $request_id is an integer request identifier.

The client should publish the response to the following topic:

1

v1/devices/me/rpc/response/$request_id

The following example is written in javascript and is based on mqtt.js. Pure command-line examples are not available because subscribe and publish need to happen in the same mqtt session.

1
2

export TOKEN=$ACCESS_TOKEN
node mqtt-js-rpc-from-server.js

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

var mqtt = require('mqtt');
var client  = mqtt.connect('mqtt://iothub.magenta.at',{
    username: process.env.TOKEN
});

client.on('connect', function () {
    console.log('connected');
    client.subscribe('v1/devices/me/rpc/request/+')
});

client.on('message', function (topic, message) {
    console.log('request.topic: ' + topic);
    console.log('request.body: ' + message.toString());
    var requestId = topic.slice('v1/devices/me/rpc/request/'.length);
    //client acts as an echo service
    client.publish('v1/devices/me/rpc/response/' + requestId, message);
});

Client-side RPC

In order to send RPC commands to server, send PUBLISH message to the following topic:

1

v1/devices/me/rpc/request/$request_id

where $request_id is an integer request identifier. The response from server will be published to the following topic:

1

v1/devices/me/rpc/response/$request_id

The following example is written in javascript and is based on mqtt.js. Pure command-line examples are not available because subscribe and publish need to happen in the same mqtt session.

1
2

export TOKEN=$ACCESS_TOKEN
node mqtt-js-rpc-from-client.js

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

var mqtt = require('mqtt');
var client = mqtt.connect('mqtt://127.0.0.1', {
    username: process.env.TOKEN
});

client.on('connect', function () {
    console.log('connected');
    client.subscribe('v1/devices/me/rpc/response/+');
    var requestId = 1;
    var request = {
        "method": "getTime",
        "params": {}
    };
    client.publish('v1/devices/me/rpc/request/' + requestId, JSON.stringify(request));
});

client.on('message', function (topic, message) {
    console.log('response.topic: ' + topic);
    console.log('response.body: ' + message.toString());
});

Claiming devices

Please see the corresponding article to get more information about the Claiming devices feature.

In order to initiate claiming device, send PUBLISH message to the following topic:

1

v1/devices/me/claim

The supported data format is:

1

{"secretKey":"value", "durationMs":60000}

Please note that the above fields are optional. In case the secretKey is not specified, the empty string as a default value is used. In case the durationMs is not specified, the system parameter device.claim.duration is used (in the file /etc/thingsboard/conf/thingsboard.yml).

Device provisioning

Please see the corresponding article to get more information about the Device provisioning feature.

In order to initiate device provisioning, send Provisioning request to the following topic:

1

/provision

Also, you should set username or clientId to provision.

The supported data format is:

1
2
3
4
5

{
  "deviceName": "DEVICE_NAME",
  "provisionDeviceKey": "u7piawkboq8v32dmcmpp",
  "provisionDeviceSecret": "jpmwdn8ptlswmf4m29bw"
}

Firmware API

When IoT Hub initiates an MQTT device firmware update, it sets the fw_title, fw_version, fw_checksum, fw_checksum_algorithm shared attributes. To receive the shared attribute updates, the device has to subscribe to

1

v1/devices/me/attributes/response/+

Where

+ is the Wildcard character.

When the MQTT device receives updates for fw_title and fw_version shared attributes, it has to send PUBLISH message to

1

v2/fw/request/${requestId}/chunk/${chunk}

Where ${requestId} - number corresponding to the number of firmware updates. The ${requestId} has to be different for each firmware update.
${chunk} - the size of the firmware in bytes. The chunks are counted from 0. The device must increment the chunk index for each request until the chunk size is zero.

For each new firmware update, you need to change the request ID and subscribe to

1

v2/fw/response/+/chunk/+

Where

+ is the Wildcard character.

Protocol customization

MQTT transport can be fully customized for specific use-case by changing the corresponding module.

Next steps