Connect Your Application with MQTT

Connect your application with MQTT

ThingPark Connected, a quality label that clearly identifies your application as ThingPark compatible.

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.

Connect ThingPark to your MQTT server

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”,

Uplink messages will be published in actility/things/<Device EUI>/uplink
Downlink messages actility/things/<Device EUI>/downlink
Subscribing to “actility/#” will get you every message that goes through.

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.

Receive uplink messages

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:

Go to ThingPark Community in the category “Devices”>“Create” to create your device on ThingPark. Here is a link to a tutorial on how to create a device on ThingPark.
Once it is created, find it in the device list and click on it.

Click on “ADD AN APPLICATION” and select your newly created MQTT application.

Do not forget to confirm your choice to save it.

b. Fetch data

On the client side, to fetch your data, you have multiple options:

If you subscribe with “#”, you will receive every uplinks and downlinks from every app you created.
If you subscribe with “<Account prefix>/#”, you will get every uplinks and downlinks from the app corresponding to this prefix.
If you subscribe with “<Account prefix>/things/<Device EUI>/#”, you will get every uplinks and downlinks only from this device on the app corresponding to this prefix.
If you subscribe with “<Account prefix>/things/<Device EUI>/uplink”, you will get every uplink only from this device on the app corresponding to this prefix.
If you subscribe with “<Account prefix>/things/<Device EUI>/uplink/<topic>”, you will get every uplink that have the same FPort as the topic you chose from this device on the app corresponding to this prefix.

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.

Send downlink messages

a. How to transmit a downlink

On the client side, to transmit a message, you need to:

Select the channel you will be publishing on; it should follow the following pattern: <Account prefix>/things/<device EUI>/downlink

Create a message which is bounded by:

{
	"DevEUI_downlink": {
-------------------------------START MESSAGE CONTENT--------------------------------
--------------------------------END MESSAGE CONTENT----------------------------------
	}
}

Include in the message at least DevEUI, Payload and Time (the time must follow the date and time format of the ISO 8601. Example: 2021-02-16T19:13:52+02:00)

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:

If you subscribe with “#”, you will receive every uplinks and downlinks from every app you created.
If you subscribe with “<Account prefix>/#”, you will get every uplinks and downlinks from the app corresponding to this prefix.
If you subscribe with “<Account prefix>/things/<Device EUI>/#”, you will get every uplinks and downlinks only from this device on the app corresponding to this prefix.
If you subscribe with “<Account prefix>/things/<Device EUI>/uplink”, you will get every uplink only from this device on the app corresponding to this prefix.
If you subscribe with “<Account prefix>/things/<Device EUI>/uplink/<topic>”, you will get every uplink that have the same FPort as the topic you chose from this device on the app corresponding to this prefix.

In case you did not include the parameter “Confirm” in your downlink, you can still check if it was transmitted smoothly:

Return on the device list page.
Find your device in the list and click on it.
Scroll down to the “LAST 10 PACKETS” section.
Look for a packet with red arrow pointing down instead of the green one pointing up, this means that it is a downlink.

Once again, you will have to be patient as it can take a bit of time for the page to update.

Additional resources

For more parameters to put in your queries, you can check the following document: List of parameters

Learn about LoRaWAN®

What is LoRaWAN®?

Learn about Actility and ThingPark

Learn about Actility and ThingPark

Build your first end-to-end use case

Build your first end-to-end use case

Application provider

Application provider

Students and Academicians

Students and Academicians

Device maker

Device maker

System integrator

Solutions Partner

Hands on Labs

Application provider

Application provider

Students and Academicians

Students and Academicians

Device maker

Device maker

System integrator

Solutions Partner

Hands on Labs