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.

IIoTNext Platform 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 set up 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 an MQTT CONNECT message with a username that contains $ACCESS_TOKEN. The alternative option is to use Basic MQTT Credentials – a combination of client id, username, and password;

Download the zip file, extract and get the certificates.

Possible return codes and their reasons during connect sequence:

• 0x00 Connected – Successfully connected to IIoTNext Platform 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, IIotNext PLatform supports key-value content in JSON. Key is always a string, while value can be either string, boolean, double, long, or JSON. For example:

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

Telemetry upload API

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

v1/devices/me/telemetry

The simplest supported data formats are:

{"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 the following format:

{"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’

telemetry-data-as-object.json:

{
  "ts": 1631001003000,
  "GatwayType": "NODEX",
  "deviceId": "NX100589",
  "deviceTypeId": "WSTATION3",
  "poa": {
    "value": 987,
    "status": 1
  }
}

telemetry-data-as-array.json:

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

telemetry-data-with-ts.json:

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

 

Mosquitto

# Publish data as an object without timestamp (server-side timestamp will be used)
mosquitto_pub -d -q 1 -h "mqtt.iiotnext.com" -p 8883 -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" --cafile iiotnext.pub.pem -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 "mqtt.iiotnext.com" -p 8883 -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" --cafile iiotnext.pub.pem -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 "mqtt.iiotnext.com" -p 8883 -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" --cafile iiotnext.pub.pem -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 "mqtt.iiotnext.com" -p 8883 -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" --cafile iiotnext.pub.pem -f "telemetry-data-with-ts.json"

Attributes API

• Upload client-side device attributes to the server.
• Request client-side and shared device attributes from the server.

Publish attribute update to the server

In order to publish client-side device attributes to IIoTNext Platform send PUBLISH message to the following topic:

v1/devices/me/attributes

new-attributes-values.json:

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

Linux Shell commands using mosquitto client:

# for IIoTNext Platform

# Publish client-side attributes update
mosquitto_pub -d -h "mqtt.iiotnext.com" -p 8883 -t "v1/devices/me/attributes" -u "$ACCESS_TOKEN" --cafile iiotnext.pub.pem -m "{"attribute1": "value1", "attribute2": true}"
# Publish client-side attributes update from file
mosquitto_pub -d -h "mqtt.iiotnext.com" -p 8883 -t "v1/devices/me/attributes" -u "$ACCESS_TOKEN" --cafile iiotnext.pub.pem -f "new-attributes-values.json"

Request attribute values from the server

In order to request client-side or shared device attributes to IIoTNext Platform, send PUBLISH message to the following topic:

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

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

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.

mqtt-js-attributes-request.js:

var mqtt = require('mqtt')
var client  = mqtt.connect('mqtt://mqtt.iiotnext.com',{
    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()
})

Executing the above javascript program in shell:

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

Result:

{"key1":"value1"}

Subscribe to attribute updates from the server

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

v1/devices/me/attributes

# for IIoTNext Platform


# Subscribes to attribute updates
mosquitto_sub -d -h "mqtt.iiotnext.com" -p 1883 -t "v1/devices/me/attributes" -u "$ACCESS_TOKEN" --cafile iiotnext.pub.pem 

var mqtt = require('mqtt');
var client  = mqtt.connect('mqtt://mqtt.iiotnext.com',{
    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);
});

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