Tutorial: Using with Live Objects

MQTT Gateway (beta) Using with Live Objects

This web page shows an example using Webcom MQTT Gateway with Live Objects. It is strongly recommended to read this page first, then this one before reading this tutorial.

Table of contents:

Use case overview

In this example, we are going to:

  • simulate a Live Objects device, from which we will publish data
  • make part of these data available in our "mqtt-demo" Webcom application

Data published from Live Objects device looks like MQTT message format we already used:

"room": {
    "name":"kitchen",
    "data": {
        "temp":25,
        "hygro":75,
        "status":"normal"
    }
}

And we are going to store it in Webcom as follows:

 |
 |- home
     |
     |- <dd-mm-yyyy>
            |
            |- kitchen
                  |
                  |- <hh:mm:ss>
                          |
                          |- temp: 25
                          |- hygro: 75
                          |- status: normal

Set up Live Objects

First of all, you have to be aware of some terminology used in the Live Objects ecosystem, detailed in their documentation.

Live Objects, as an MQTT broker, is designed to handle data published by devices, and allow subscribers (as the Webcom MQTT Gateway) to retrieve this data through different modes. Please, read the Message bus chapter of their documentation.

We think that the best way to use Webcom MQTT Gateway with Live Objects should involve their FIFO mode, as this is the only mode that guarantees MQTT messages are always delivered to the consumer. Even if Webcom MQTT Gateway cannot reach Live Objects for some reason (server down, network failure...) while devices publish MQTT messages, these messages are stored in FIFOs. As soon as Live Objects is reachable again, Webcom MQTT Gateway will automatically subscribe to previous FIFO topics and actually receive MQTT messages that would have been lost otherwise...

In this chapter, we create a device and we bind data it sends to Live Objects, to a FIFO we can subscribe to.

Create an account

Go to Live Objects sign up page and follow the instructions. Notice that there is no need for this tutorial to request the use of LoRa network.

Create API keys

First thing we need is two API keys, one for our device and one for the FIFO we are going to play with.

Once logged in, you should see tabs at the top of the page

configuration tab

Choose "Configuration" as shown above, then choose "API Keys" on the left side menu that appears:

API Keys

On the right side, there is an empty listing of API keys that we are going to populate using the Add an API key button.

A new right side panel appears where you can choose the name, description and profile of our new API key. Please, choose the "MQTT Device" profile as shown below:

new device API key

Below the profile, you can see the different roles it applies to (that we do not show on this tutorial as it is a long list) and a "Create / Cancel" group of buttons. Please, click on the Create button, a small window like below should pop up:

API key generated pop up

Please, copy this API key in a safe place now, before closing the pop up, as there is no way to retrieve it afterwards.

We now have an API key usable with devices. Create another API key, but choose the "Application" profile this time, it will be useful for playing with FIFOs. Now, our API keys listing should look like the following:

API keys listing

Create a device

devices tab

Choose "Devices" as shown above on top page tabs, an empty listing of devices should appear that we are going to populate using the Add device button. A form appears where you can choose a namespace, an id a name and a description like below:

new device

Use the Register button, our listing is now fulfilled:

devices listing

As you can see, the device now has a "client ID" (sometimes named "device ID") made of urn:lo:nsid:<namespace>:<id>.

Create a FIFO and a routing rule

devices tab

Choose "Data" as shown above on top page tabs, and choose "FIFO" on the left side menu:

Message Bus

On the right side panel, named "FIFO queues" and containing an empty listing, click on the Add a FIFO queue button, a small window pops up where you only have to choose a name for our FIFO:

new FIFO

Use the Register button, our listing is now fulfilled:

FIFO listing

Now, choose "Routing" on the left side menu:

Message Bus

On the right side panel, named "Routing rules" and containing an empty listing, click on the Add a routing rule button and choose a name for our new rule:

new Routing key

Click on the Next button and choose "All devices messages" as the filter for messages you wish to route:

new Routing key

Click on the Next button, then on the + FIFO button in the "Actions" area:

new Routing key

Select our previously created FIFO then click on the Complete button:

new Routing key

Our listing is now fulfilled:

Routing keys listing

Check the configuration

Before interacting with Webcom, let us use the well known MQTT.fx client to check our configuration.

We process in two steps:

  • we use the client to publish data to the device
  • we then use the client to subscribe to FIFO

Please, be aware that some corporate proxies do not allow network traffic through the 1883 port used by Live Objects.

Publish on device

First of all, we have to connect this client to Live Objects using the following settings, as shown in Live Objects documentation:

  • Broker Address: liveobjects.orange-business.com
  • Broker Port: 1883
  • Client ID: urn:lo:nsid:WebcomMqttDemoDeviceNamespace:WebcomMqttDemoDeviceId (this is our device "client ID")
  • Keep Alive Interval: 30 seconds (do not keep the default 60 seconds value)
  • User Name: json+device, for device mode MQTT connection
  • Password: the first API key we just created with the "MQTT Device" profile

MQTT.fx connection settings (device)

MQTT.fx connection credentials (device)

According to Live Objects documentation we should publish data on dev/data topic with the following format:

{
"s" : "urn:lo:nsid:dongle:00-14-22-01-23-45!temperature",
"ts" : "2016-07-10T10:02:44.907Z",
"loc" : [44.1, -1.5],
"m" : "temperatureDevice_v0",
"v" : {
  "temp" : 17.25
 },
"t" : [ "City.NYC", "Model.Prototype" ]
}

However, only the "v" field is mandatory for our tutorial, so let us publish the following simpler message:

{
"v": {  "room": {
            "name":"kitchen",
            "data": {
                "temp":20,
                "hygro":75,
                "status":"normal"
            }
        }
     }
}

After clicking on the Connect button, use the "Publish" tab (selected by default) to enter data as follows:

Publish data

Click on the Publish button and go back to our Live Objects "FIFO queues" listing:

FIFO listing (one message ready)

As you can see, there is one "message ready" and no "consumer".

Subscribe to FIFO

Now, we must connect the MQTT.fx client to Live Objects using different settings, as shown in Live Objects documentation:

  • Broker Address: liveobjects.orange-business.com
  • Broker Port: 1883
  • Client ID: unused (but we have to set something for MQTT.fx to work properly)
  • Keep Alive Interval: 30 seconds (do not keep the default 60 seconds value)
  • User Name: payload, for "bridge" mode with JSON encoding to collect data messages
  • Password: the second API key we just created with the "Application" profile

MQTT.fx connection settings (FIFO)

MQTT.fx connection credentials (FIFO)

After clicking on the Connect button, use the "Subscribe" tab to monitor the fifo/webcomDemoFifo topic:

Subscribe to topic

Click on the Subscribe button:

Subscribe result

Then, go back to our Live Objects "FIFO queues" listing:

FIFO listing (one consumer)

As you can see, there is no more "message ready" and one "consumer" that will disappear as soon as we disconnect from MQTT.fx client...

Notice the way Live Objects has enriched the MQTT message for us:

{
"timestamp": "2018-12-05T14:54:06.112Z",
"value": { "room": {
               "name": "kitchen",
               "data": {
                   "temp": 20,
                   "hygro": 75,
                   "status": "normal"
               }
           }
         },
"metadata": { "source": "urn:lo:nsid:WebcomMqttDemoDeviceNamespace:WebcomMqttDemoDeviceId",
              "connector": "mqtt"
            }
}

This may be useful, particularly when setting the template in Webcom settings, as explained below. Notice the "value" field name, corresponding to our previous "v" field...

Configure Webcom MQTT Gateway

Please, refer to this page to fully understand the way our configuration tool works.

Once logged in, choose your favorite Webcom application, also known as "namespace", click on the "manage" button, then on "labs zone" tab. On the page, you should see something like this that we call the main form:

empty main form

Authentication key

Below, you have to provide an "Authentication key" shared by all Webcom MQTT Gateway settings for this Webcom application. For now, this key is one of the secrets keys of your Webcom application, that should be replaced in the future by some more secured type of key...

So, back to the top of the page, choose the "authentication" tab and create there a secret key (we strongly recommend not to use the default one) through the "add a secret" button at the bottom of the page. Click on "show" button and copy the key.

Back to our main form, paste the key in "Authentication key" input text box and click on "Save" button.

Subscribe to MQTT -> Put/Push to Datasync configuration

On the main form, click on "Subscribe to MQTT -> Put/Push to Datasync" link, then on the "New..." link and enter a name and a description for your new Subscribe to MQTT -> Put/Push to Datasync configuration:

"Subscribe to MQTT -> Put/Push to Datasync" main form

Now click on the "MQTT Config" button and enter the following settings:

  • URL: wss://liveobjects.orange-business.com:443/mqtt (yes, we use Live Object Web Socket access in secure mode)
  • Topic: fifo/webcomDemoFifo (looks familiar ?)
  • Client ID: anything (we choose "webcom")
  • User name: payload
  • Password: the API key we previously created with the "Application" profile
  • SSL certificate: can be retrieved here
-----BEGIN CERTIFICATE-----
MIIDrzCCApegAwIBAgIQCDvgVpBCRrGhdWrJWZHHSjANBgkqhkiG9w0BAQUFADBh
MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3
d3cuZGlnaWNlcnQuY29tMSAwHgYDVQQDExdEaWdpQ2VydCBHbG9iYWwgUm9vdCBD
QTAeFw0wNjExMTAwMDAwMDBaFw0zMTExMTAwMDAwMDBaMGExCzAJBgNVBAYTAlVT
MRUwEwYDVQQKEwxEaWdpQ2VydCBJbmMxGTAXBgNVBAsTEHd3dy5kaWdpY2VydC5j
b20xIDAeBgNVBAMTF0RpZ2lDZXJ0IEdsb2JhbCBSb290IENBMIIBIjANBgkqhkiG
9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4jvhEXLeqKTTo1eqUKKPC3eQyaKl7hLOllsB
CSDMAZOnTjC3U/dDxGkAV53ijSLdhwZAAIEJzs4bg7/fzTtxRuLWZscFs3YnFo97
nh6Vfe63SKMI2tavegw5BmV/Sl0fvBf4q77uKNd0f3p4mVmFaG5cIzJLv07A6Fpt
43C/dxC//AH2hdmoRBBYMql1GNXRor5H4idq9Joz+EkIYIvUX7Q6hL+hqkpMfT7P
T19sdl6gSzeRntwi5m3OFBqOasv+zbMUZBfHWymeMr/y7vrTC0LUq7dBMtoM1O/4
gdW7jVg/tRvoSSiicNoxBN33shbyTApOB6jtSj1etX+jkMOvJwIDAQABo2MwYTAO
BgNVHQ8BAf8EBAMCAYYwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUA95QNVbR
TLtm8KPiGxvDl7I90VUwHwYDVR0jBBgwFoAUA95QNVbRTLtm8KPiGxvDl7I90VUw
DQYJKoZIhvcNAQEFBQADggEBAMucN6pIExIK+t1EnE9SsPTfrgT1eXkIoyQY/Esr
hMAtudXH/vTBH1jLuG2cenTnmCmrEbXjcKChzUyImZOMkXDiqw8cvpOp/2PV5Adg
06O/nVsJ8dWO41P0jmP6P6fbtGbfYmbW0W5BjfIttep3Sp+dWOIrWcBAI+0tKIJF
PnlUkiaY4IBIqDfv8NZ5YBberOgOzW6sRBc4L0na4UU+Krk2U886UAb3LujEV0ls
YSEY1QSteDwsOoBrp+uvFRTp2InBuThs4pFsiv9kuXclVzDAGySj4dzp30d8tbQk
CAUw7C29C79Fv1C5qfPrmAESrciIxpg0X40KPMbp1ZWVbd4=
-----END CERTIFICATE-----

"Subscribe to MQTT -> Put/Push to Datasync" MQTT form

Go back, click on the "Datasync Config" button and enter the following settings:

  • Front path: /home
  • Overwrite: true
  • Template: $day-$month-$year/$payload.value.room.name/$hour:$minute:$second/$payload.value.room.data
  • Use JSON: true

"Subscribe to MQTT -> Put/Push to Datasync" Datasync form

Go back, be sure to check the "Available" check box and to click on "Save" button when back at the main form.

Check your Live Objects FIFO:

Back to our Live Objects "FIFO queues" listing, we should now see that we have one "consumer":

FIFO listing (one consumer)

Run some end to end tests

Use the same process we described before in Publish on device chapter to pretend some device (actually the MQTT.fx client) publishes data to Live Objects:

Publish data

Then go to Webcom, use the Data tab on top of the page, and check the message you just published has actually been handled by Webcom MQTT Gateway:

Check data