How to communicate with Databoom using MQTT.fx

It is possible to connect to Databoom MQTT broker using MQTTfx.

For the MQTT device configuration in Databoom read also: MQTT

 


 

Before starting

To connect to MQTT broker it is required to note from Databoom:

  • your own username;
    • in the example we use the username: 
      • databoomtest
  • your own user namespace (from your profile in Databoom);
    • in the example we use the namespace: 
      • V9Gg
  • an OAuth token (Settings 🡺 Credentials🡺 OAuth keys/Add OAuth);
    • in the example we use the fake token:
      • kQHpPRPtiJcPa7FQCFaKUrnRABx2Fe/TnzzzkZD9R9M= 
  • your device token (from device details page).
    • in the example we use the fake token:
      • 0kvt8awd1v
  • the topics for publication/subscription of your device (from your device details page);
    • in the example the following fake topics are used:
      • MQTTfx/0kvt8awd1v/data for publication
      • MQTTfx/0kvt8awd1v/info for subscription

TIP! It is strongly recommended to create a different OAuth token for each client, to grant a better security.

 


 

Data format

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. If the date isn't specified, value reception date is used.

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. 

  • With example values we'll have:

    {
     "type": "data",
     "message": {
         "device": "0kvt8awd1v",
         "date": "2020-03-05T14:50:00+01:00",
         "signals" : [
           {
             "name": "MQTT_signal",
             "value": 123  
           }
         ]
       }
    }

 


 

MQTT.fx

The required fields to create a MQTT client are:

  • Profile Name,  a name you choose to identify your client in the application;
  • Profile Type is MQTT Broker;
  • Broker Address is mqtt.databoom.com;
  • Broker Port is 1883;
  • Client ID, formed by user namespace and device token following the pattern <user namespace>-<device token>
    • Example client id will be:
      • V9Gg-0kvt8awd1v
  • User Credentials
    • Username, your Databoom username;
      • Example username is:
        • databoomtest
    • Password, an OAuth token created by the user;
      • Example token is:
        • kQHpPRPtiJcPa7FQCFaKUrnRABx2Fe/TnzzzkZD9R9M=

It is also possible to authenticate using certificates, generated in Databoom when an MQTT device is created::

  • Broker Address is mqttcert.databoom.com;
  • Broker Port is 8883;
  • SSL / TLS
    • Select Enable SSL/TLS 
    • Protocol iTLSv1.2
    • Self signed certificates
      • CA file, Client certificate file, Client key file are the fields where to upload the certificates downloaded from Databoom device

Once the connection with the broker is established, it is possible to publish some data or to subscribe to the topic to supervise device events.

Publishing topic consists of <project>/<device token>/<topic>. Data format is a JSON containing the device token and the signals with their values, as in the top of the page. 

  • With example data:
    • MQTTfx/0kvt8awd1v/data

Subscription topic consists of <project>/<device token>/<topic>. By subscribing to  a device, all its events will show, as for example the received data confirmation.

  • With example data:
    • MQTTfx/0kvt8awd1v/info

By publishing on the data topic it is also possible to create alarms or events by following the respective formats:

{
    "type": "alarm",
    "message":  {
      "dateOn": "2020-03-05T14:50:00+01:00",
      "description": "This is an alarm test from MQTT",
      "note": "Full alarm description",
      "status": "ON",
      "ack": "NACK"
    }
}
{
    "type": "event",
    "message":  {
        "description": "This is an event test from MQTT",
      "from": "2020-03-05T14:50:00+01:00",
      "to": "2020-03-05T16:50:00+01:00",
        "link": {
            "device": "<device token>",
            "signal": "<signal token>"
        },
      "tags": [
        "mqtt"
      ]
    }
}
  • With example data we'll have:

    {
        "type": "alarm",
        "message":  {
          "dateOn": "2020-03-05T14:50:00+01:00",
          "description": "This is an alarm test from MQTT",
          "note": "Full alarm description",
          "status": "ON",
          "ack": "NACK"
        }
    }
    {
        "type": "event",
        "message":  {
            "description": "This is an event test from MQTT",
          "from": "2020-03-05T14:50:00+01:00",
          "to": "2020-03-05T16:50:00+01:00",
            "link": {
                "device": "0kvt8awd1v",
                "signal": "MQTT_signal"
            },
          "tags": [
            "mqtt"
          ]
        }
    }

 

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.