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.

Topics of an MQTT device (and template) are: 

  • Topic where publish data, where the client will publish data in order for Databoom to receive and process them
  • Topic where it's possible to recieve informations from Databoom, where the client may subscribe in order to receive info from Databoom

Projects field allows to specify one or more strings that willl be used as roots in the topics. By inserting more projects therefore more topics will be available for publication and subscription.

MQTT device topics follow the structure <project>/<device token>/<topic>

The device token is used, along with the user namespace, to form the ClientId to set in the MQTT client, that will follow the structure <user namespace>-<device token>.

As example, consider MQTTTest as project, data as publication topic and info as subscription topic, the so-formed topic will be displayed:

  • MQTTTest/<device token>/data
  • MQTTTest/<device token>/info

 


 

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 authenticate to the MQTT broker you need your username an OAuth token generated in Databoom with Publish and Create permissiosn

  • In Settings -> Credentials side menu, click the Add OAuth button in the OAuth keys box
  • To grant better security we reccomend to create a new OAuth token for each istance of the template

Broker address is mqtt.databoom.com, on port 1883, so mqtt://mqtt.databoom.com:1883 is used.

 


 

Parameters format to forward

Parameters to forwarded to publication topic (MQTTTest/<device token>/data in the example) must be in JSON format, in particular the following model is used:

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

<device token> is displayed in the Info box in the device page.

date field isn't mandatory, if it's not specified reception date is used.

Signals tokens, <signal 1 token> and <signal 2 token> in the example, can be copied from the device page or in the corresponding signal detail pages.

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 MQTTTest/<device token>/data

client.publish("MQTTTest/<device token>/data", JSON.stringify(post_data), function () {
    console.log(newDate().toISOString(), "\tDATA PUBLISHED ON", "MQTTTest/<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 MQTTTest/<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 MQTTTest/<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('MQTTTest/<device token>/info');
});

client.on('message', function (topic, message) {
    console.log(newDate().toISOString(), "\tDATA PUBLISHED ON", "MQTTTest/<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
  • Alarm statuses are:
    • New, with status ON and ack NACK
    • Active, with status ON and ack ACK
    • Off, with status OFF and ack NACK
    • Solved, with status OFF and ack ACK
  • The message must contain dates according to the alarm status:
    • New (ON/NACK) requires dateOn
    • Active (ON/ACK) requires dateOn and dateAck
    • Off (OFF/NACK) requires dateOn and dateOff
    • Solved (OFF/ACK) requires dateOn, dateOff and dateAck
  • If dateAck is not present in the payload and the ack field is ACK, reception date is used instead
  • By adding a custom ref field in message, it is possible to refer an existing alarm and therefore update its status (without ref field a new alarm is created for each message)
    • Alarms generated with a ref field are listed with the field displayed in the description cell

 


 

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>
}

In the example you can see the function doIt 

function doIt(payload) {    
return { 'date': new Date(), 'value': (payload[1].charCodeAt(0) - 97)
}; }

payload parameter allows to access the published data and process them in order to return them in a compatible format. In the example the value is calculated by subtracting 97 to the code of the first character of the first payload component.

 


 

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.