ThingPark offers multiple options to connect to IoT applications: if you chose MQTT as the application to retrieve the data of your devices, this guide is for you!
In this page, we will see point by point how to connect ThingPark to your MQTT broker and how to handle uplinks and downlinks messages.
To access the creation form of the MQTT application, you need to go to the “Application” menu in ThingPark Community, click on “Create” button that appeared under and finally on MQTT. To link ThingPark to your MQTT broker, you will need to fill all the fields that end with and asterisk as well as either the Username / Password, the Certificate / Private key or both. Here are the explanations and example for each field:
Name:
Identity of your application on your IoT network.
Example: MQTT_Application
Content Type:
Two possibilities: JSON enriched document and JSON legacy document.
We recommend the “JSON enriched” option since it will return what the received message corresponds to (uplink, downlink, downlink acknowledgment…). The JSON legacy document option is only here for the sake of backward compatibility
Downlink Port:
The downlink port is the default port which will be used is you do not add any information in the code. It is an integer between 1 and 224 that is useful to define only if the port is present in the uplink.
The syntax for the downlink will have to be the following: “FPort” : 1
Hostname:
The hostname or IP address of your server followed by the port which are either 1883 or 8883 (1883 is the default port for MQTT and 8883 is the port of MQTT over TLS). It will have to follow the syntax hereafter: the.hostname.com:port or IP:port
Example: app.actility.com:1883
Account Prefix:
The account prefix allows you to create a “category” in your message broker containing all the messages published by the devices’ you linked to your application.
Example: If we set the account prefix to “actility”,
Protocol:
Three options are available to accommodate the configuration of your MQTT broker: SSL, WSS and TCP.
Both SSL and WSS require either the certificate (X.509 file in .crt format) and key (PKCS#8 format) to work OR the login and password (it depends on the broker configuration). The TCP only requires username/password.
Username & password:
Those are the identifiers you will need to connect to your MQTT server depending on the protocol you chose to connect with and the broker you picked.
Certificate & private key:
Those are the identifiers you will need to connect to your MQTT server if you either chose SSL or WSS protocol.
Topics:
Topics allows segmentation of message storage depending on their LoRaWAN娪 port. This field is optional and not recommended for the most common use-cases.
Example: If you put “Geoloc” as the topic name of port 4, your account prefix is “actility” and your device number is “20635F010800167C” for example, to see the uplinks that go through port 4 will have to subscribe to “actility/things/ 20635F010800167C /uplink/Geoloc”
Additional information:
Any detail you want to add to your application that you want to remember. This field is also optional.
a. Publish uplink messages to your MQTT broker
Now that your ThingPark application is created and that you have linked it to your broker and server, you need to link your device to your application.
In order to do that:
b. Fetch data
On the client side, to fetch your data, you have multiple options:
c. Uplink example
A classic uplink would look like this:
{
"DevEUI_uplink" : {
"Time" : "2021-03-01T15:26:08.209+01:00",
"DevEUI" : "20635F010800167C",
"FPort" : 17,
"FCntUp" : 27,
"MType" : 2,
"FCntDn" : 1,
"payload_hex" : "0a2cee8ba001",
"Lrcid" : "00000127",
"LrrRSSI" : -51.0,
"LrrSNR" : 8.25,
"SpFact" : 12,
"SubBand" : "G1",
"Channel" : "LC2",
"DevLrrCnt" : 2,
"Lrrid" : "1000027B",
"Lrrs" : {
"Lrr" : {
"Lrrid" : "1000027B",
"Chain" : 0,
"LrrRSSI" : -51.0,
"LrrSNR" : 8.25,
"LrrESP" : -51.605556
}
},
"CustomerID" : "100133870",
"CustomerData" : {
"alr" : {
"pro" : "ABEE/APY",
"ver" : "1"
}
},
"ModelCfg" : "1:TWA_100133870.16171.AS",
"DriverCfg" : {
"mod" : {
"pId" : "abeeway",
"mId" : "micro-tracker",
"ver" : "3"
},
"app" : {
"pId" : "abeeway",
"mId" : "asset-tracker",
"ver" : "2"
},
"id" : "abeeway:asset-tracker:2"
},
"InstantPER" : 0.0,
"MeanPER" : 0.0,
"DevAddr" : "040007F8",
"AckRequested" : 0,
"rawMacCommands" : "",
"TxPower" : 16.0,
"NbTrans" : 1,
"Frequency" : 868.3,
"DynamicClass" : "A",
"payload" : {
"messageType" : "EVENT",
"trackingMode" : "MOTION_TRACKING",
"batteryVoltage" : 4.11,
"ackToken" : 10,
"periodicPosition" : false,
"temperatureMeasure" : 26.3,
"sosFlag" : 0,
"appState" : 1,
"dynamicMotionState" : "MOVING",
"onDemand" : false,
"deviceConfiguration" : {
"mode" : "MOTION_TRACKING"
},
"eventType" : "MOTION_START"
}
}
}
The message is divided in three parts: first, all the information about the message (when it was sent, from which device, what was the SNR…) then, the information about the device (its model, its version…) and finally, the payload deciphered at the end of the message.
a. How to transmit a downlink
On the client side, to transmit a message, you need to:
{
"DevEUI_downlink": {
-------------------------------START MESSAGE CONTENT--------------------------------
--------------------------------END MESSAGE CONTENT----------------------------------
}
}
Here is an example of a typical downlink message:
{
"DevEUI_downlink": {
"Time": "2018-10-17T15:38:46.882+02:00",
"DevEUI": "0018B20000000B20",
"FPort": "8",
"payload_hex": "0105",
"Confirmed": "1",
"FlushDownlinkQueue": "1"
}
}
IMPORTANT: the “FPort” is not mandatory in the downlink but is recommended. If it is not included, it will pick the default port specified during the app creation.
b. The aknowledgment message
Once you have transmitted your downlink, if it is well structured and you have added the parameter “Confirmed”:”1” as above, you should see a downlink acknowledgment message appear in your uplink feed.
{
"DevEUI_downlink_Sent": {
"Time": "2019-08-22T16:48:02.000+02:00",
"DevEUI": "0018B20000000D48",
"FPort": 1,
"FCntDn": 47,
"FCntUp": 39,
"Lrcid": "0000000F",
"SpFact": 7,
"SubBand": "G1",
"Channel": "LC2",
"Lrrid": "FF0106DE",
"DeliveryStatus": 0,
"DeliveryFailedCause1": "B0",
"DeliveryFailedCause2": "00",
"DeliveryFailedCause3": "00",
"CustomerID": "199983788",
"CustomerData": {
"alr": {
"pro": "ADRF/DEMO",
"ver": "2"
}
},
"TransmissionSlot": 1,
"Frequency": 868.3
}
}
Don’t stress if it takes a bit of time to arrive, if your device is a class A for example, it will arrive with the next uplink.
c. The verification
On the client side, to fetch your data, you have multiple options:
In case you did not include the parameter “Confirm” in your downlink, you can still check if it was transmitted smoothly:
For more parameters to put in your queries, you can check the following document: List of parameters