How to communicate with Databoom using MQTTBox or MQTTLens

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 the username databoom is used
  • your own user namespace (from your profile in Databoom);
    • in the example the namespace aFk1 is used
  • an OAuth token (Settings 🡺 Credentials🡺 OAuth keys/Add OAuth);
    • in the example the fake token kQHpPRPtiJcPa7FQCFaKUrnRABx2Fe/TnzzzkZD9R9M= is used
  • your device token (from device details page).
    • in the example the fake token 0ewpu6ewmj is used
  • 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. 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.

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",
      "note": "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",
      "note": "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

The required fields to create a MQTT client are:

  • Connection Name, a name you choose to identify your client in the application;
  • Hostname, select tcp and type the Databoom MQTT broker address mqtt.databoom.com;
  • Port, broker port 1883;
  • Client ID, formed by user namespace and device token following the pattern <user namespace>-<device token>;
    • Example client id will be aFk1-0ewpu6ewmj
  • Username, Databoom user's username;
    • Example username is databoom
  • Password, an OAuth token created by the user.
    • Example token is kQHpPRPtiJcPa7FQCFaKUrnRABx2Fe/TnzzzkZD9R9M=

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",
      "note": "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",
      "note": "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"
      ]
    }
}
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.