MQTT template

MQTT template configuration

By selecting the MQTT type of device among the available template types, the filelds required for the communication and creation of devices 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 template topics follow the structure <project>/<unique arbitrary value>/<topic>

The unique arbitrary value is a value chosen by the user to identify the device uniquely, it will be used, along with the user namespace, to form the ClientId to set in the MQTT client.

The unique arbitrary value is also used as description and token for the new device to be created in Databoom, following the format <template token>-<unique arbitrary value>

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

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

Transmitting to a template

Once all the configuration fields of a template are set, it is possible to begin communication and therefore devices generation.

To authenticate to the MQTT broker you need 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

Data format to use to forward data to the piblication topic (MQTTTest/<unique arbitrary value>/data in the example) is the following:

{
    "type": "data",
    "message":  [
      {
        "template": "<MQTT template token>",
        "date": "2018-04-12T15:00:00.000Z",
        "signals": [
          {
            "name": "<signal 1 token>",
            "value": <signal 1 value>
          },
          {
            "name": "<signal 2 token>",
            "value": <signal 2 value>
          }
        ]
      }
    ]
}

<MQTT template 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, by clicking the copy icon next to the corresponding label.

Data publication implies:

• If there weren't previous communications:
  • the creation of a new device with the token <MQTT template token>-<unique arbitrary value>. The device will be populated withe the same signals of the template (new signals with the same tokens), regardless their values being sent or less. The signals are already validated and ready to communicate. If signals contains signals not appearing in the template, they're added only to the device, waiting for validation;
• If there were previous communications:
  • the update of <template token>-<unique arbitrary value> with values in signals. If a new signal has been added to the template, it is also created in the device;

message is an array, is therefore possible to create/communicate with more devices per publication, provided that they refer to different devices.

Transformation function for published data

If published data content can't be customized according to Databoom accepted format (in the previous paragraph), it is possible to specify, in signal edit page, a transformation function to process the payload an make it compatible to the platform.

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

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

o

{
    'value': <VALUE>
}

o

<VALUE>

In case of array, components can use different formats.

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.