API Documentation- Device-mqtt-api

Device MQTT API

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.

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

Telemetry

 In order to publish telemetry data to Cloudchip server node, send 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 2019 12:00:00.512 GMT’

Attibutes

Cloudchip 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 Cloudchip server node, send PUBLISH message to the following topic:

v1/devices/me/attributes

 

Request attribute values from the server

In order to request client-side or shared device attributes to Cloudchip server node, 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 is based on mqtt.js. Pure command-line examples are not available because subscribe and publish need to happen in the same mqtt session.
 

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

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:
{“key1”:“value1”}

Remote Procedure Call

 Server-side RPC

In order to subscribe to RPC commands from the server, send 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 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.

 

Client-side RPC:

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

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:

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.

Publish data as an object:

Command: mosquitto_pub -d -h “web.cloudchip.io” -t “v1/devices/me/telemetry” -u “$ACCESS_TOKEN” -f “telemetry-data-as-object.json”

Response: {“key1”:“value1”, “key2”:true, “key3”: 3.0, “key4”: 4}

Publish data as an array of objects :

Command: mosquitto_pub -d -h “web.cloudchip.io” -t “v1/devices/me/telemetry” -u “$ACCESS_TOKEN” -f “telemetry-data-as-array.json”

Response: [{“key1”:“value1”}, {“key2”:true}]

Publish data as an object ( timestamp):

Command: mosquitto_pub -d -h “web.cloudchip.io” -t “v1/devices/me/telemetry” -u “$ACCESS_TOKEN” -f “telemetry-data-with-ts.json”
Response: {“ts”:1451649600512, “values”:{“key1”:“value1”, “key2”:“value2”}}

Publish client-side attributes update

Command: mosquitto_pub -d -h “web.cloudchip.io” -t “v1/devices/me/attributes” -u “$ACCESS_TOKEN” -f “new-attributes-values.json”

Resposne: {“attribute1”:“value1”, “attribute2”:true, “attribute3”:42.0, “attribute4”:73}

Publish client-side attributes update

mqtt-js-rpc-from-server.js:

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/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()
})

Response: {“key1”:“value1”}

Subscribe Attributes:

Command: mosquitto_sub -d -h “web.cloudchip.io” -t “v1/devices/me/attributes” -u “$ACCESS_TOKEN”

mqtt-js-attributes-subscribe.sh:

mqtt sub -v “127.0.0.1” -t “v1/devices/me/attributes” -u ‘$ACCESS_TOKEN’

Remote Procedure Call from Server:

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/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);
});

 

Remote Procedure Call from Client:

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());
});