Cumulocity Agent for Eclipse Hono

Description

This is an agent/microservice that integrates with Eclipse Hono. Hono is an IoT Hub which handles the Connectivity & Messaging of IoT Devices including Telemetry Data and Command & Control Data. This Microservice will act as a Consumer Application, listens to all Telemetry & Event Data provided by Hono and forward the Data to Cumulocity. Vice Versa it transforms Cumulocity Operations to Hono Commands.

Each Hono Tenant is mapped to one Cumulocity Tenant. Therefore the Microservice isolation level is "Per-Tenant" which means that for each Tenant an own microservice instance will be created. This Microservice uses the Hono Client and is based on Example Code from IoT Hub Examples by Bosch Software Innovations GmbH.

The Cumulocity Microservice SDK version 1005.6.1 in combination with Java 8 + Spring Boot 1.5 are used.

Hono Cumulocity Data Mapping

Hono itself is totally payload agnostic. Cumulocity provides a flexible Domain Model. In the following it is described how the Data Mapping is done for Telemetry & Event Data and Command & Control Data.

Telemetry & Events

When receiving Telemetry & Event Data the Microservice will create Devices with the Hono Device Id in Cumulocity. When the Device is already existing the Device will be updated. Also the payload of the Hono Message will be sent to Cumulocity as Event of Type hono_Event or hono_Telemetry. All the payload of Hono will be stored in the Property hono_Content.

For simplification it is assumed that JSON only will be sent by Hono. This can be adapted if needed.

Example of Hono Event in Cumulocity:

{
    "creationTime": "2019-12-16T10:45:51.920Z",
    "source": {
        "self": "https://t86833178.cumulocity.com/inventory/managedObjects/1418779",
        "id": "1418779"
    },
    "type": "hono_Telemetry",
    "self": "https://t86833178.cumulocity.com/event/events/1431569",
    "time": "2019-12-16T10:45:51.914Z",
    "text": "Hono Telemetry Message",
    "id": "1431569",
    "hono_Content": {
        "temp": 20.5
    }
}

As Hono is totally payload agnostic, no static Mapping is added to the Microservice.

Apama allows dynamical decoding of the Hono Messages Payload without touching the code of this Microservice. You can find an Apama Monitor Example to map Hono Temperature Telemetry Data to a Cumulocity Temperature Measurement here

Example: Hono sends {"temp": 20.5}. The Apama Example Monitor will create a Temperature Measurement of Type c8y_TemperatureMeasurement with the same value and Timestamp of the system (as no timestamp is provided).

Command & Control

For Command & Control the Data Mapping is mainly done be defining the Data Model of the Operation so that the Hono Command & Control/Device can interpret and execute that command. The following Properties/Fragments should be maintained in the Operation:

• hono_Command (Required) - The command sent by the Platform.
• hono_OneWay (Optional) - If Set to true One-Way Commands will be sent to Hono. The Operation will be set to SUCCESSFUL or FAILED when delivered to Hono
• hono_Data (Optional) - Additional data to be used by the command e.g. Software List etc.
• hono_ContentType (Optional) - The Content Type of the hono_Data. Should be maintained when Data is available.
• hono_Headers (Optional) - Any additional Headers which should be sent to the Device. Here is an example of an interpretable Cumulocity Operation:

{
  "deviceId" : "1418779",
  "hono_Command": "switch",
  "hono_Data": "on",
  "hono_OneWay": true,
  "description": "Hono Command Example"
}

Operations can be created by either adding c8y_SupportedOperations on the Device in Cumulocity or using the API to define and create Operations with custom Fragments.

Prerequisites

• An Hono Instance or a Tenant in the Hono Sandbox is required.
• A Cumulocity Tenant with Admin Privileges, Apama and Microservice Deployment Feature is required. You can request a free trial here.

Preparations & Setup

1. Make sure you have the following Hono Configuration Data at hand:

   • hono.host - Hostname of AMQP Host
   • hono.port - Port of AMQP Host
   • hono.username - Hono Username
   • hono.password - Hono Password
   • hono.tenantid - The Id of the Hono Tenant that should be matched to the Cumulocity Tenant

2. You can store/change the above configuration in 2 ways.

   • In Cumulocity Tenant Options.
   • In the properties file of the Microservice.

   It is preferred to store the above configuration in the Tenant Options. Just make sure you create them for the category hono. The key should be the above mentioned configuration in lowercase. For the password please use the key credentials.password to encrypt the password. You can find the Tenant Options API Description here.

   Example Payload for Tenant Options:

   {
       "category": "hono",
       "key": "host",
       "value": "hono.eclipse.org"
   }

   As an alternative you can just add the hono configuration to the application.properties in the resources folder. You can find an example in the resources folder.

Build

Make sure that Docker and Apache Maven are installed and running on your Computer. Run mvn clean package to build the Microservice which will create a ZIP archive you can upload to Cumulocity.

Deploy

1. Login to your Cumulocity Tenant. Go to Administration -> Applications. Click on "Add Application" and "Upload Microservice".
2. Select the zip archive generated by the Build.

   NOTE: Rename the zip archive to "hono-agent.zip" before uploading it

3. Wait until the Microservice is uploaded and started. You can check that under the application and Status.
4. In the "Log" Tab you can check the Logfiles of the Agent.

---

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.

---

For more information you can Ask a Question in the TECHcommunity Forums.

You can find additional information in the Software AG TECHcommunity.

---

Contact us at TECHcommunity if you have any questions.