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.
Controllino Cloud acts as an MQTT Broker that supports QoS levels 0 (at most once) and 1 (at least once) and a set of configurable topics.
You can find a large number of MQTT client libraries on the web. Examples in this article will be based on the most popular one: Mosquitto. Sometimes, we will also use the MQTT.js library if it makes technical sense.
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 – a combination of client id, username and password;
Possible return codes and their reasons during connect sequence:
By default, Controllino Cloud 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.0, "longKey":73, "jsonKey": { "someNumber": 42, "someArray": [1,2,3], "someNestedObject": {"key": "value"} } }
However, it is also possible to send data via Protocol Buffers, which will be explained in the Device Profiles article.
In order to publish telemetry data to Controllino Cloud, send a PUBLISH message to the following topic:
v1/devices/me/telemetry
The simplest supported data formats are:
{"key1":"value1", "key2":"value2"}
or
[{"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:
{"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’
# Publish data as an object without timestamp (server-side timestamp will be used) mosquitto_pub -d -q 1 -h "portal.controllino.cloud" -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 "portal.controllino.cloud" -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 "portal.controllino.cloud" -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 "portal.controllino.cloud" -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -f "telemetry-data-with-ts.json"
{ "stringKey": "value1", "booleanKey": true, "doubleKey": 42.0, "longKey": 73, "jsonKey": { "someNumber": 42, "someArray": [1,2,3], "someNestedObject": {"key": "value"} } }
[{"key1":"value1"}, {"key2":true}]
{ "ts": 1451649600512, "values": { "stringKey": "value1", "booleanKey": true, "doubleKey": 42.0, "longKey": 73, "jsonKey": { "someNumber": 42, "someArray": [1, 2, 3], "someNestedObject": { "key": "value" } } } }
Controllino Cloud Attributes API allows devices to
In order to publish client-side device attributes to Controllino Cloud, send PUBLISH message to the following topic:
v1/devices/me/attributes
# Publish client-side attributes update mosquitto_pub -d -h "portal.controllino.cloud" -t "v1/devices/me/attributes" -u "$ACCESS_TOKEN" -m "{"attribute1": "value1", "attribute2": true}" # Publish client-side attributes update from file mosquitto_pub -d -h "portal.controllino.cloud" -t "v1/devices/me/attributes" -u "$ACCESS_TOKEN" -f "new-attributes-values.json"
{ "attribute1": "value1", "attribute2": true, "attribute3": 42.0, "attribute4": 73, "attribute5": { "someNumber": 42, "someArray": [1,2,3], "someNestedObject": {"key": "value"} } }
In order to request client-side or shared device attributes to Controllino Cloud, 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, client need to subscribe to
v1/devices/me/attributes/response/+
The following example is written in JavaScript and 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
export TOKEN=$ACCESS_TOKEN node mqtt-js-attributes-request.js
mqtt-js-attributes-request.js
var mqtt = require('mqtt') var client = mqtt.connect('mqtt://portal.controllino.cloud',{ 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() })
Result
{"key1":"value1"}
Please note, the intersection of client-side and shared device attribute keys is bad practice. However, it is still possible to have the same keys for client, shared or even server-side attributes.
In order to subscribe to shared device attribute changes, send a SUBSCRIBE message to the following topic:
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:
Mosquitto
# Subscribes to attribute updates mosquitto_sub -d -h "portal.controllino.cloud" -t "v1/devices/me/attributes" -u "$ACCESS_TOKEN"
In order to subscribe to RPC commands from the server, send a SUBSCRIBE message to the following topic:
v1/devices/me/rpc/request/+
Once subscribed, the client will receive individual commands as a PUBLISH message to the corresponding topic:
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:
v1/devices/me/rpc/response/$request_id
The following example is again 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.
export TOKEN=$ACCESS_TOKEN node mqtt-js-rpc-from-server.js
mqtt-js-rpc-from-server.js
var mqtt = require('mqtt'); var client = mqtt.connect('mqtt://portal.controllino.cloud',{ 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); });
In order to send RPC commands to server, send a PUBLISH message to the following topic:
where $request_id is an integer request identifier. The response from server will be published to the following topic:
mqtt-js-rpc-from-client.js
var mqtt = require('mqtt'); var client = mqtt.connect('mqtt://portal.controllino.cloud', { 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()); });
This part of the tutorial will be added very soon. If you need more information on this topic though, please write us an email so we can give you instructions on how to do this.
