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
Choose "Configuration" as shown above, then choose "API Keys" on the left side menu that appears:
On the right side, there is an empty listing of API keys that we are going to populate using the 
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:
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 
button, a small window like below should 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:
Create a device
Choose "Devices" as shown above on top page tabs, an empty listing of devices should appear that we are going to populate using the 
button. A form appears where you can choose a namespace, an id a name and a description like below:
Use the 
button, our listing is now fulfilled:
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
Choose "Data" as shown above on top page tabs, and choose "FIFO" on the left side menu:
On the right side panel, named "FIFO queues" and containing an empty listing, click on the 
button, a small window pops up where you only have to choose a name for our FIFO:
Use the button, our listing is now fulfilled:
Now, choose "Routing" on the left side menu:
On the right side panel, named "Routing rules" and containing an empty listing, click on the 
button and choose a name for our new rule:
Click on the 
button and choose "All devices messages" as the filter for messages you wish to route:
Click on the button, then on the 
button in the "Actions" area:
Select our previously created FIFO then click on the 
button:
Our listing is now fulfilled:
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
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 
button, use the "Publish" tab (selected by default) to enter data as follows:
Click on the 
button and go back to our Live Objects "FIFO queues" listing:
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
After clicking on the button, use the "Subscribe" tab to monitor the fifo/webcomDemoFifo topic:
Click on the 
button:
Then, go back to our Live Objects "FIFO queues" listing:
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 
button, then on 
tab. On the page, you should see something like this that we call the 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 
tab and create there a secret key (we strongly recommend not to use the default one) through the 
button at the bottom of the page. Click on 
button and copy the key.
Back to our main form, paste the key in "Authentication key" input text box and click on 
button.
Subscribe to MQTT -> Put/Push to Datasync configuration
On the main form, click on 
link, then on the 
link and enter a name and a description for your new Subscribe to MQTT -> Put/Push to Datasync configuration:
Now click on the 
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-----
Go back, click on the 
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
Go back, be sure to check the "Available" check box and to click on 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":
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:
Then go to Webcom, use the 
tab on top of the page, and check the message you just published has actually been handled by Webcom MQTT Gateway:
