MQTT

Databoom provides the possibility to connect your own device with a server (broker) through MQTT protocol. In order to transmit the data, it is necessary to correctly set up a device in Databoom and creating a client that sends the parameters in the required format. Follows the procedure for Node.js.

Read also: How to communicate with Databoom using MQTTBox or MQTTLens

 

MQTT device configuration in Databoom

Before creating a MQTT client to forward data to Databoom, it is necessary to create a device in the platform and configuring it so it can communicate correctly. While creating a device select the MQTT type. Once the type has been selected, communication fields are shown.

ProjectsTopic where publish data and Topic where it's possible to recieve informations from Databoom can be customized by the user to form the topics to use for configurating MQTT client.

As example, consider MQTT as project, data as publication topic and info as subscription topic, the so-formed topic will be shown in thei:

  • MQTT/<unique arbitrary value>/data
  • MQTT/<unique arbitrary value>/info

The <unique arbitrary value> is a value chosen by the user that must be unique on the platform because it will be used, along with the user namespace, to form the MQTT client id (ClientId). 

It is possible to assign more topics to a single template by editing the Project part of the address and keeping the rest unchanged. 

Considering the previous example, it is possible to add other topics to a template like

  • Test/<unique arbitrary value>/data
  • Test/<unique arbitrary value>/info

Note that only the project part is changed, the rest is the same of other topics. 

mqtt module

For the creation of a MQTT client in Node.js the mqtt module is used

npm install mqtt

In your code the following fragment is then required:

var mqtt = require('mqtt');

Creation of a MQTT client in Node.js

Client creation follows the structure:

var settings = {
    clientId:"<user namespace>-<device token>", 
    username:"<Databoom username>",
    password:"<Databoom oAuth>"
};

var client = mqtt.connect("mqtt://mqtt.databoom.com:1883", settings);

The clientId is formed by the user namespace, viewable in the personal profile, and  the device token, viewable in its details page, following the <user namespace>-<device token> pattern. The so-formed clientId is viewable in the details page of the MQTT device in Databoom.

To connect to the broker it is also required to authenticate with the username and an OAuth token. It is possible to create an OAuth token in the Credentials sections, accessible from the Settings in side menu. Broker address is mqtt.databoom.com, on port 1883, so mqtt://mqtt.databoom.com:1883 is used.

Parameters format to forward

Parameters to forward must be in JSON format, in particular the following model is used:

{
"type": "data",
"message": { "device": "<device token>", "date": "<data>", "signals" : [ { "name": "<signal token>", "value": <signal value> } ] }
}

device is the device token while date is the detection date. Signals must be added to signals array, they are object with two properties: name is the signal token, value its value.

If you want to update a signal existing in Databoom, name must correspond to the existing token. If the signal doesn't exist in Databoom, it is newly created using name as token. The value must be unique.

Parameters are then converted to string so they can be correctly published on broker topic

 post_data = JSON.stringify(post_data); 

Publishing data on topic

Once the parameters creation has ended, it is possible to proceed with the publication on the topic of Databoom broker. Consider the example topic MQTT/<device token>/data

client.publish("MQTT/<device token>/data", JSON.stringify(post_data), function () {
    console.log(newDate().toISOString(), "\tDATA PUBLISHED ON", "MQTT/<device token>/data");
    console.log(JSON.stringify(post_data));
});

Publication topic can be retrieved in the device details page in Databoom, it must follow the pattern MQTT/<device token>/data (where MQTT and data are customizable by the user), data is ignored otherwise. post_data must be a string. In the callback some log messages are printed to confirm parameters forwarding.

It is also possible to subscribe to the events topic. It can be retrieved in the device details page in Databoom, it must follow the pattern MQTT/<token dispositivo>/info (where MQTT and data are customizable by the user).

client.on('connect', function () {
    console.log(newDate().toISOString(), "\tCLIENT CONNECTED TO DATABOOM BROKER")
    client.subscribe('MQTT/<device token>/info');
});

client.on('message', function (topic, message) {
    console.log(newDate().toISOString(), "\tDATA PUBLISHED ON", "MQTT/<device token>/info");
    console.log(message.toString());
})

Alarm creation

It is possible to create an alarm in Databoom by publishing on data topic. The syntax to use is the following: 

{
    "type": "alarm",
    "message":  {
      "dateOn": "2018-04-13T09:00:00+02:00",
      "description": "This is a MQTT alarm test",
      "note": "Extended alarm description",
      "status": "ON",
      "ack": "NACK"
    }
}

Fields to forward to create an alarm are the same fields visualized in Databoom. In particular:

  • status indicates if the alarm is active ON or deactivated OFF;
  • ack indicates if the alarm has been acknowledged ACK or less NACK.

Creating an event

It is also possible to create event by posting data following the schema:

{
    "type": "event",
    "message":  {
        "description": "MQTT event",
      "from": "2018-04-13T09:00:00+02:00",
      "to": "2018-04-13T10:00:00+02:00",
        "link": {
            "device": "<device token>",
            "signal": "<signal token>"
        },
      "tags": [
        "mqtt"
      ]
    }
}

Fields to forward to create an event are the same fields visualized in Databoom (in notes widget):

  • from and to represent start and end dates of the event;
  • link allows to link an element to the event;
  • tags allows to assign tags to the event.

Transformation function for published data

If published data content can't be customized according to Databoom accepted format, it is possible to specify a custom topic where data for the signal is publshed, without the need to include its token in the payload. Consider the example topic orders, publication topic will be MQTT/<token dispositivo>/data/orders

Content will be therefore processed by the transformation function and values stored in the signal.

The function must return one or more values (array []) in the accepted format:

{
    "date": <DATE>,
    "value": <VALUE>
}

Done!

Once the procedure has been completed, Databoom starts to record data sent with MQTT. To examine your data and have a correct representation, follow the instructions in Edit/validation of a signal.

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.