-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
149 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,2 +1,149 @@ | ||
| # cumulocity-ttn-integration | ||
| Cumulocity Microservice to integrate devices and sensors from the The Things Network to Cumulocity. | ||
| # Cumulocity - The Things Network Integration | ||
|
|
||
| ##Summary | ||
|
|
||
| This Cumulocity Microservice enables your [Cumulocity IoT](https://www.softwareag.cloud/site/product/cumulocity-iot.html#/) tenant to integrate with the LoRa network provider [The Things Network (TTN)](https://www.thethingsnetwork.org ). This integration allows to receive uplink messages from TTN and process them within Cumulocity IoT, e.g. extract Measurements or Events from the message. Based on the data received from TTN you can use the viusalization and Streaming Analytics capabilities of Cumulocity for further processing. | ||
|
|
||
| The TTN integration is compatible with latest version of **The Things Stack V3**. | ||
|
|
||
| ##Some more details | ||
|
|
||
| The Microservice 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. | ||
|
|
||
| - `POST /` | ||
|
|
||
| accepts a message coming from TTN using the following format of The Things Stack V3. | ||
|
|
||
| ```json | ||
| { | ||
| "end_device_ids": { | ||
| "device_id": "device-id", | ||
| "application_ids": { | ||
| "application_id": "application-id" | ||
| }, | ||
| "dev_eui": "11111111111", | ||
| "join_eui": "0000000000000001" | ||
| }, | ||
| "correlation_ids": [ | ||
| "as:up:01F9TPEM71KNPH12323WGM44", | ||
| "rpc:/ttn.lorawan.v3.AppAs/SimulateUplink:1234567890-412e-1234-8316-83c3b6e993f9" | ||
| ], | ||
| "received_at": "2021-07-05T06:42:23.074340851Z", | ||
| "uplink_message": { | ||
| "f_port": 1, | ||
| "frm_payload": "BAsBAK0DCwYgBgIBQcjMzQNRASQ=", | ||
| "rx_metadata": [ | ||
| { | ||
| "gateway_ids": { | ||
| "gateway_id": "test" | ||
| }, | ||
| "rssi": 42, | ||
| "channel_rssi": 42, | ||
| "snr": 4.2 | ||
| } | ||
| ], | ||
| "settings": { | ||
| "data_rate": { | ||
| "lora": { | ||
| "bandwidth": 125000, | ||
| "spreading_factor": 7 | ||
| } | ||
| } | ||
| }, | ||
| "received_at": "0001-01-01T00:00:00Z" | ||
| }, | ||
| "simulated": true | ||
| } | ||
| ``` | ||
|
|
||
| For now the fields `device_id`, `application_id`, `dev_eui`, `received_at`, `f_port` and `frm_payload` are processed by the Microservice. | ||
|
|
||
| A device will automatically be created in Cumulocity if a message has been received for this device the first time but it isn't registered yet. For mapping the messages to the domain model of Cumulocity, the Microservice uses the [Device Protocol](https://cumulocity.com/guides/protocol-integration/lora-loriot/#create-loriot-device-protocols) feature of Cumulocity. Therefore, if a device has been newly registered in Cumulocity via the TTN integration Microservice the corresponding Device Protocol needs to be assigned to the respective device first. This needs to be done in the Device Management application of Cumulocity on the related device detail page, e.g: | ||
|
|
||
|  | ||
|
|
||
| The Microservice will pick up the related Device Protocol for the device. When a new message is being received from TTN for the device, the Microservice will use the Device Protocol to translate the message into the respective domain objects of Cumulocity. | ||
|
|
||
| ##How to run locally | ||
|
|
||
| The Microservice is based on the Cumulocity Java Microservice SDK. For an introduction and more information on the Java SDK have a look at the [documentation](https://cumulocity.com/guides/microservice-sdk/java/#java-microservice). The documentation also describes the necessary steps to run a Microservice locally. | ||
|
|
||
| 1. Create a new Microservice application on your Cumulocity IoT tenant | ||
|
|
||
| `POST https://{base-url}/application/applications` | ||
|
|
||
| Request body: | ||
|
|
||
| ```json | ||
| { | ||
| "key": "ttn-integration-key", | ||
| "name": "ttn-integration", | ||
| "contextPath": "ttn-integration", | ||
| "type": "MICROSERVICE", | ||
| "manifest":{}, | ||
| "requiredRoles": [ | ||
| "ROLE_INVENTORY_READ", | ||
| "ROLE_INVENTORY_CREATE", | ||
| "ROLE_INVENTORY_ADMIN", | ||
| "ROLE_MEASUREMENT_READ" | ||
| ], | ||
| "roles": [] | ||
| } | ||
| ``` | ||
|
|
||
| Make sure to provide the correct authorization for the request. | ||
|
|
||
| 2. Subscribe the Microservice application for your tenant via UI | ||
|
|
||
| 3. Acquire microservice bootstrap credentials | ||
|
|
||
| `GET https://{base-url}/application/applications/{applicationId}/bootstrapUser` | ||
|
|
||
| Response body: | ||
|
|
||
| ```json | ||
| { | ||
| "password": "************************", | ||
| "name": "servicebootstrap_ttn-integration", | ||
| "tenant": "<your tenant>" | ||
| } | ||
| ``` | ||
| Make sure to provide the correct authorization for the request. | ||
|
|
||
| 4. Provide bootstrap credentials | ||
|
|
||
| Add the bootstrap credentials to your `src/main/resources/application.properties` and uncomment all C8Y properties. | ||
|
|
||
| ```text | ||
| C8Y.baseURL= | ||
| C8Y.bootstrap.user= | ||
| C8Y.bootstrap.password= | ||
| C8Y.bootstrap.tenant= | ||
| ``` | ||
|
|
||
| 5. Run Microservice | ||
|
|
||
| Run the Microservice inside your IDE as a Spring Boot application. | ||
|
|
||
| ##How to deploy to Cumulocity | ||
|
|
||
| The Microservice comes with the `microservice-package-maven-plugin`, which enables the build of the Microservice using Maven, including a Docker image in case Docker is available on the build system. To trigger the build run `mvn clean install` for the project. To enable the build of the Docker Image set the property `<c8y.docker.skip>false</c8y.docker.skip>` in the `pom.xml` within the `./ttn-integration/c8y-ttn-integration` directory. | ||
|
|
||
| If the build has been successful the build artifacts can be found in the `target` directory. If the Docker build has been enabled the `target` directory also includes a zip archive. The zip archive consists of the Docker Image and the Cumulocity Microservice manifest. Upload the zip archive as Microservice application in the Administration application of Cumulocity to deploy the Microservice within Cumulocity. | ||
|
|
||
| For more information about deploying a Microservice check the [documentation](https://cumulocity.com/guides/microservice-sdk/java/#developing-microservice). | ||
|
|
||
| Check the release section for the latest build. | ||
|
|
||
| ## Disclaimer | ||
|
|
||
| These tools are provided as-is and without warranty or support. They do not constitute part of the Software AG product suite. Users are free to use, fork and modify them, subject to the license agreement. While Software AG welcomes contributions, we cannot guarantee to include every contribution in the master project. | ||
|
|
||
| ## Contact | ||
|
|
||
| For more information you can Ask a Question in the [TechCommunity Forums](http://tech.forums.softwareag.com/techjforum/forums/list.page?product=cumulocity). | ||
|
|
||
| You can find additional information in the [Software AG TechCommunity](http://techcommunity.softwareag.com/home/-/product/name/cumulocity). | ||
|
|
||
| _________________ | ||
| Contact us at [TechCommunity](mailto:technologycommunity@softwareag.com?subject=Github/SoftwareAG) if you have any questions. |