Cumulocity IoT and The Things Network
Cumulocity IoT already integrates with the LoRa network server providers Actility ThingsPark and Loriot out of the box to integrate your LoRa devices using these providers. Next to Actility ThingsPark and Loriot, there also exist other network server providers. One of them is The Things Network (TTN). With its The Things Stack Community Edition The Things Network offers a free network server which is driven by the public community LoRaWAN network. This network consist of more than 21.000 LoRa Gateways, which are connected to TTN and distributed around the world. This free network is a great opportunity for developers to familiarize themselves with the LoRaWAN technology without having to pay for a commercial account. In addition, you can check on the Community page, whether there is a community for your location and if there are already LoRa gateways nearby, to which you can connect your LoRa devices.
The Open Source project Cumulocity - The Things Network Integration enables your Cumulocity IoT tenant to easily integrate with The Things Network. It is part of Software AG Open Source. Using this integration you can connect LoRa devices from TTN to Cumulocity IoT and monitor them using Cumulocity’s visualizations and streaming analytics capabilities.
How does the integration work?
General Prerequisites
To describe how the integration between Cumulocity IoT and The Things Network actually works the WILSEN.sonic.level sensor from Pepperl+Fuchs, who are a hardware partner of Software AG, will be used as an illustrative example. The WILSEN sensor is an industrial ultrasonic sensor, which can be installed in containers to measure their fill level. Typical use cases for the sensor are in the IoT area of Smart City, Smart Logistic, Smart Environment and Smart Farming.
If you are interested in testing the WILSEN.sonic.level sensor from Pepperl+Fuchs together with Cumulocity IoT, you can order a free Trial Kit by using this contact form. The Trial Kit consists of the WILSEN sensor and a Cumulocity IoT instance, which is already configured to integrate the WILSEN sensor from The Things Network.
For the integration from TTN to Cumulocity IoT the TTN Integration Microservice is used, which can be downloaded from the release section of the github project. The Microservice can receive uplink messages from TTN and process them, e.g. extract Measurements or Events from the message. It exposes a single REST endpoint. This endpoint will be used in TTN for the Webhooks integration to forward data received from devices in TTN to Cumulocity IoT.
For this integration to work there are some prerequisites:
- the LoRa device is registered in The Things Network
- to upload the TTN Integration Microservice to your tenant you need to have the
feature-microservice-hostingfeature subscribed - LoRa Device Protocols need to be enabled for the tenant
- Option 1: Subscribe either the
actilityfeature or theloriot-agentfeature - Option 2: Download the custom DeviceManagement application from the release section and upload it as Web Application to override the existing DeviceManagement application. Once the TTN Microservice has been uploaded the LoRa Device Protocols feature will be activated.
- Option 1: Subscribe either the
Setting up a custom Webhook in TTN
If all of these prerequisites have been fulfilled, you can start to set up the integration to Cumulocity IoT in TTN. First, add a new HTTP integration for your TTN application in which the HTTP REST interface of the Cumulocity TTN Integration Microservice is registered so that TTN can forward messages from the LoRa sensor to Cumulocity IoT. To do this, navigate to the Webhooks section in your application via the Integrations menu item. Then click on the button Add webhook to set up a new HTTP integration for your application. Select the Custom webhook template from the list.
Configure following fields for your custom Webhook:
- Webhook ID : freely selectable
- Webhook format : JSON
- Base URL : {{host}}/service/ttn-integration
- Replace the placeholder
{{host}}with the URL of your Cumulocity instance. - The endpoint
/service/ttn-integrationspecifies the interface of the TTN Microservice, which can process messages from TTN .
- Replace the placeholder
- Downlink API key : leave blank
- Additional headers :
- Click on the Add header entry button to create a new header for the authorization.
- For each access to Cumulocity IoT, Cumulocity IoT checks whether the access is authorized and has the necessary permissions. This also applies for the integration of TTN to Cumulocity . For the HTTP REST interface in Cumulocity IOT , Basic Authentication is used to verify access. With Basic Authentication, the credentials are sent in a Base64 encoded string as an additional HTTP header for each request.
- Enter the following value in the first input field: Authorization
- Convert your Cumulocity IoT credentials into a Base64 encoded string. The access data must follow this structure: username:password, for example: john.doe@softwareag.com:ycias12is. Here
john.doe@softwareag.comis the username andycias12isis the password. The Base64 encoded string generated from this is: am9obi5kb2VAc29mdHdhcmVhZy5jb206eWNpYXMxMmlz. The following value would then be entered in the second text field:
Basic am9obi5kb2VAc29mdHdhcmVhZy5jb206eWNpYXMxMmlz - IMPORTANT: In case you change your password for Cumulocity IoT afterwards, it is necessary to update the authorization in TTN .
- Uplink message : Select the check box. Leave the input field empty.
- Remaining check boxes : Do not select
Save the HTTP integration. If the HTTP integration to Cumulocity IoT is set up correctly, the sensor is automatically registered in Cumulocity IoT as soon as the sensor sends a new message to TTN. Using the Webhook integration TTN will forward the message to the corresponding Cumulocity IoT instance.
Create a LoRa Device Protocol
In order for Cumulocity IoT to understand the incoming messages from the LoRa devices, you need to create a LoRa device protocol which is being used by the TTN Integration Microservice to map the message to the corresponding domain objects of Cumulocity, such as measurements or events. You will find extensive information on how to create such LoRa device protocols in the official documentation.
Let’s take the WILSEN sensor as an example. The WILSEN sensor sends information about the battery charge, distance, fill level and temperature in one single uplink message. The payload for such an uplink message with the FPort 1 can look like this:
Based on the payload description of the WILSEN sensor, you can create the according LoRa device protocol in Cumulocity to map the fields, which you are interested in:
The distance, fill level, temperature and battery charge received by the WILSEN sensor will be translated into corresponding measurements in Cumulocity based on this mapping.
In the next step, the appropriate device protocol needs to be assigned to the LoRa device in Cumulocity IoT so that the TTN Microservice can process the received messages for the LoRa device from TTN. Navigate to the LPWAN section on the detail page of your device in the Device Management application. Select your newly created device protocol as the LoRa device protocol and save it.
This mapping enables Cumulocity IoT to translate the received message from the WILSEN sensor into the domain model of Cumulocity IoT. If the mapping is successful, you will see a new tab called Measurements for your sensor after Cumulocity IoT has received further messages from the WILSEN sensor.
What’s next?
Once you are done with the integration of your LoRa devices from TTN to Cumulocity IoT, you can use Cumulocity’s visualization and analytics capabilities to implement your IoT use cases. Use the Application Builder to implement your own applications and dashboards, on which you can also use custom widgets from Software AG’s Open Source project. In addition, you might want to have a look at the Streaming Analytics feature to build your own rules to monitor the condition of your LoRa devices.
