How to communicate with Databoom using MQTTBox or MQTTLens – Databoom

It is possible to connect to Databoom MQTT broker using online utilities like MQTTBox or MQTTLens.

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:
  - databoom
your own user namespace (from your profile in Databoom);
- in the example we use the namespace:
  - aFk1
an OAuth token (Settings 🡺 Credentials🡺 OAuth keys/Add OAuth);
- in the example we use the fake token:
  - kQHpPRPtiJcPa7FQCFaKUrnRABx2Fe/TnzzzkZD9R9M= i
your device token (from device details page).
- in the example we use the fake token:
  - 0ewpu6ewmj
the topics for publication/subscription of your device (from your device details page);
- in the example the following fake topics are used:
  - MQTT/0ewpu6ewmj/data for publication
  - MQTT/0ewpu6ewmj/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 date isn't specified, value recepiton 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": "0ewpu6ewmj",
     "date": "2018-04-13T09:00:00+02:00",
     "signals" : [
       {
         "name": "MQTT_signal",
         "value": 123  
       }
     ]
   }
}

MQTTBox

The required fields to create a MQTT client are:

MQTT Client Name, a name you choose to identify your client in the application;
MQTT Client Id, formed by user namespace and device token following the pattern <user namespace>-<device token>;
- Example client id will be:
  - aFk1-0ewpu6ewmj
Protocol, mqtt / tcp or mqtts / tls are allowed;
Host, Databoom broker address mqtt.databoom.com and the used port (1883 if tcp, 8883 if tls);
Username, Databoom user's username;
- Example username is:
  - databoom
Password, an OAuth token created by the user;
- Example token is:
  - kQHpPRPtiJcPa7FQCFaKUrnRABx2Fe/TnzzzkZD9R9M=
Append timestamp to MQTT client id must be deselected.

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

Protocol is mqtts / tls
Host is mqttcert.databoom.com:8883
SSL / TLS Version is TLSv1.2
SSL / TLS Certificate Type is 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:
- MQTT/0ewpu6ewmj/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:
- MQTT/0ewpu6ewmj/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": "2018-04-13T09:00:00+02:00",
      "description": "This is an alarm test from MQTT",
      "comment": "Full alarm description",
      "status": "ON",
      "ack": "NACK"
    }
}

{
    "type": "event",
    "message":  {
        "description": "This is an event test from MQTT",
      "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"
      ]
    }
}

With example data we'll have:

{
    "type": "alarm",
    "message":  {
      "dateOn": "2018-04-13T09:00:00+02:00",
      "description": "This is an alarm test from MQTT",
      "comment": "Full alarm description",
      "status": "ON",
      "ack": "NACK"
    }
}

{
    "type": "event",
    "message":  {
        "description": "This is an event test from MQTT",
      "from": "2018-04-13T09:00:00+02:00",
      "to": "2018-04-13T10:00:00+02:00",
        "link": {
            "device": "0ewpu6ewmj",
            "signal": "MQTT_signal"
        },
      "tags": [
        "mqtt"
      ]
    }
}

MQTTLens