Cumulocity Cloud Connection

The Cumulocity cloud connection add-on provides an ESF Cloud Connection implementation for the Cumulocity platform.
The bundle uses the MQTT protocol and SmartREST to interact with the cloud platform, and provides the following features:

• Allows applications to publish mesaurement data, alarms and events to the Cumulocity platform.
• Support for device registration.
• Support of Restart and Command operations.
• Support for synchronizing part of device state with inventory.
• Support for configuring device required availability.

Connection to the cloud platform

The first step required for connecting an ESF device to the Cumulocity platform is creating a new Cloud Connection instance.
This process is described in ESF documentation.
In order to create a Cumulocity Cloud Connection the following factory PID should be used:

• Cloud Connection Factory PID: com.eurotech.framework.cloudconnection.c8y.mqtt.CumulocityCloudEndpoint.

The connection to the cloud platform can be performed in two ways:

• Obtaining credentials from the cloud platform
• Specifying credentials manually

#### Obtaining credentials from the cloud platform

In order to request credentials to the cloud platform, the first step involves creating a device registration request, for example using the Device management -> Devices -> Registration section of Cumulocity web console.

See the description of the MQTTDataTransport -> Client-id parameter below for details of the value to be entered as DEVICE ID.

The Cloud Connection components can be configured as follows:

• CloudService tab:

  • Request device credentials: true

• MQTTDataTransport tab:

  • Broker-url: Url of the MQTT broker to connect to (e.g. mqtts://mqtt.cumulocity.com:8883 for a SSL connection or mqtt://mqtt.cumulocity.com:1883 for an unencrypted one).
  • Username: The "static" username received from Cumulocity support.
  • Password: The "static" password received from Cumulocity support.
  • Client-id: The value entered in this field must match the value specified as DEVICE ID when the device registration request has been created on the cloud platform.
    If this field is left empty, the device will use the value reported in the Device -> Profile section of the web ui (usually the MAC address of one of the network interfaces on the device.).

Once the parameters above has been filled on the device, the Connect Auto-on-startup in the DataService tab can be set to true to enable automatic connection.

Once device connects to the broker, it will perform the bootstrap process and update the CloudService and MQTTDataTransport configuration to use the received credentials. The device will automatically reconnect to the broker with the new credentials.

Specifying credentials manually

In order to specify credentials manually, the Request device credentials configuration parameter in the CloudService tab must be set to false.
Credentials can be entered manually in the MQTTDataTransport tab as explained before.

Publishing data

In order to publish data to the cloud platform, one or more Cumulocity Cloud Publisher instances must be created and bound to the publishing applications.

A Cumulocity Cloud Publisher instance is responsible of translating KuraMessages generated by ESF applications into the Cumulocity SmartRest MQTT format.

The process of creating and binding a publisher to an application is described in ESF documentation.
For example, a Kura Wires Publisher component can be bound to a Cumulocity Cloud Publisher by setting the CloudPublisher Target Filter configuration property of the wire component to the desired publisher id.

The data inside the payload of a KuraMessage is organized in key-value pairs (metrics). The desired mapping from Kura metrics to the CSV format can be specified in the publisher configuration, in form of a CSV template.

The default configuration of a Cumulocity Cloud Publisher contains the following example template:

200,acceleration,x,${accel.x},$?{accel.x.unit}
200,acceleration,y,${accel.y},$?{accel.y.unit}
200,acceleration,y,${accel.z},$?{accel.z.unit}
200,temperature,T,${temperature},C

This template generates four CSV rows representing measurements, using the SmartREST static template 200. The template allows to insert the value of specific KuraMessage metrics into CSV fields using the following syntax:

• ${metric1}: Inserts the value of metric1 in the produced CSV, if metric1 is not available in the KuraMessage the row will not be generated.

• $?{metric2}: Inserts the value of metric2 in the produced CSV, if metric2 is not available in the KuraMessage the row will be generated and the corresponding field will be empty.

Any SmartREST template can be referenced publisher configuration, this allows for example to set and clear alarms using the 30X static templates.

Operation Support

The Cumulocity support bundle allows to perform the Restart and Command operations from the Cloud platform.

The Command operation allows to execute shell commands on the device.

Support for Restart and Command operations can disabled in CumulocityCloudEndpoint configuration section.

Configuring required availability

The Cumulocity cloud platform allow to monitor device activity by setting a device specific required availability interval. If availability monitoring is enabled, and the device does not send data to the platform for an interval of time greater than the required availability interval, an alarm will be generated by the Cloud Platform

The following parameters in CumulocityCloudEndpoint allow to configure the device required availability interval:

• Publish required availability interval: Defines whether or not to report to the cloud platform the required availability interval.
• Required availability interval: Specifies the required availability interval in minutes. This parameter should be set appropriately basing on the expected publish rate of the applications installed on the device.