ThingPark offers multiple options to connect to IoT applications: if you chose HTTPS as the protocol 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 application using HTTPS and how to handle uplinks and downlinks messages.
To create an HTTPS connection with your application, go to the Application menu on ThingPark admin console, click on Create and select HTTPS – Generic Application. To complete the creation of the connection, complete the form with the required information and Save.
Name:
Friendly Name to Identify your application on ThingPark.
Example: My_Application
URL:
URL of the application server where your device data will be sent. On ThingPark Community, it must be an HTTPS URL.
Content Type:
3 possibilities: JSON, JSON untyped and XML. JSON is the recommended option, unless your application does not support it.
Tunnel Interface Authentication Key:
This key is automatically generated by ThingPark and is used to secure communications between ThingPark and your application. Save it NOW as this key can not be retrieved at a later stage – a new one can be generated though.
Additional information:
Any detail you want to add to your application that you want to remember. This field is also optional.
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:
In case of uplink messages (NS to AS) – beyond the information of the XML/JSON message bodies – the NS provides further data as query parameters. This is represented by the following curl command.
curl \
-X POST \
-H "Content-type:application/json" \
-d '{ "DevEUI_uplink": { ... "DevEUI": "000000000F1D8693", "FPort": "2", "FCntUp": "7011", "payload_hex": "0027bd00", "CustomerID": "100000507" ... } }' \
"
Please note that Thinkpark does not use curl for sending POST messages. The above code snippet is used only for demonstration purpose. The information provided as query parameters can be used to verify the integrity of the message body. This will be explained later under the “Securing the HTTP connection” title. If you want to set up a “quick and dirty” demo environment without security, you can ignore query parameters.
A typical AS to NS message is a Downlink Frame Request message that can be sent by the following curl command.
curl \
-X POST \
-H "Content-type:application/x-www-form-urlencoded" \
"
All parameters that are supposed to be part of the message body are provided as query parameters. This is optional. Using query parameters instead of JSON message body would just makes a bit easier to write the curl command in a command line interface.
The obvious way of securing a HTTP REST API is utilizing the PKI infrastructure and accessing the AS via HTTPS. HTTPS enabled web sites require a certificate validated by a CA that is part of the PKI infrastructure. If your AS does not have a certificate yet, you can get one for free from Let’s Encrypt.
Utilizing HTTPS and the PKI infrastructure for uplink messages will just secure the identity of the AS. This is not enough. We also need a way to secure the identity of the NS. The AS has to be able to check if the received message was really sent by the NS and not by someone else.
For that the NS generates a unique Token for every uplink message and sends it as a query parameter like it was illustrated by the above presented curl command.
Once the AS receives a new message it has to recalculate the token and compare it with the one received as a query parameter. If the 2 tokens are the same, the message integrity is correct, otherwise the AS has to drop the message.
The Token Verification Procedure is as follows:
curl \
-X POST \
-H "Content-type:application/json" \
-d '{ "DevEUI_uplink": { ... "DevEUI": "000000000F1D8693", "FPort": "2", "FCntUp": "7011", "payload_hex": "0027bd00", "CustomerID": "100000507" ... } }' \
"
queryParameters =
"LrnDevEui=000000000F1D8693&LrnFPort=2&LrnInfos=UPHTTP_LAB_LORA&AS_ID=app1.sample.com&Time=2016-01-11T14%3A11%3A11.333%2B02%3A00"
bodyElements = CustomerID + DevEUI + FPort + FCntUp + payload_hex
Token = SHA-256(bodyElements + queryParameters + AsKey)
Where: AsKey is the 128 bits pre-shared Tunnel Interface Authentication Key (lower case hexadecimal string representation) between the AS and the NS as defined in the Generic Application configuration.
ThingPark Network Server (tpNS) sends/receives the following types of messages to/from the application server (AS). Regardless of the applied integration option (http, mqtt, etc.) the message bodies are always text documents in either JSON or XML format.
Direction: tpNS→AS
Uplink Frame Reports include information about standard LoRaWAN® Data Uplink messages including the Payload, FPort, and RF parameters.
Message body examples: uplink_frame.xml, uplink_frame.json
Direction: tpNS→AS
Notification Reports notify the AS about “Device Reset” event, “Successful Join Procedure” event and “Battery status”.
Message body examples: notification_report.xml, notification_report.json
Direction: tpNS→AS
In case Network Geo-localisation Service is active, ThingPark sends location reports to the AS.
Message body examples: location_report.xml, location_report.json
Direction: AS→tpNS
Downlink Frame Requests are sent by the AS to the NS to schedule a downlink message on the NS. The NS will enqueue the message and send it as soon as all earlier messages in the queue have been sent and the device opened an RX window.
Message body examples: downlink_frame.xml, downlink_frame.json
Direction: tpNS→AS
A Downlink Frame Sent Report notifies the AS about the event that the Network Server has sent a scheduled downlink message to a device. Please note that this notification does not necessarily mean that the device has successfully received the downlink message.
Message body examples: downlink_frame_sent_report.xml, downlink_frame_sent_report.json
For more parameters to put in your queries, you can check the following document: List of parameters
