The Cumulocity Connector connects SIA Connect to a Cumulocity IoT tenant through thin-edge.io. Use it to onboard SIA Connect as a managed device, send measurements and alarms, create child devices from mapped source instances, synchronize the gateway location, and receive write operations from Cumulocity.

Before you begin

Prepare the following:

• A Cumulocity IoT tenant that SIA Connect can reach.
• Permission to onboard a device in the tenant.
• A one-time password or access to the tenant's certificate-onboarding workflow.
• The Cumulocity Connector package that matches the SIA Connect architecture.
• Any source Connector, instance, and items that will provide data to Cumulocity.

The Connector requires SIA Connect system version 1.1.1 or newer. Packages are available for SIA Connect Standalone, SIA Connect Standalone Plus, and x86-based SIA Connect ANY-Ware installations.

Install the Connector

1. Sign in to the Edge Portal.
2. Expand Configuration in the sidebar.
3. Select Connectors.
4. Find Cumulocity.
5. Select Install when the Connector is available from the repository. If you have a local package, select Upload connector and choose the matching .sia file.
6. Wait until Cumulocity appears as an installed and enabled Connector.

Create a Cumulocity instance

1. Open the installed Cumulocity Connector.
2. Select Add instance.
3. Enter a descriptive instance name.
4. Enter the Cumulocity tenant URL in Address.
5. Configure the Connector-specific parameters described below.
6. Select Save instance.

The Connector starts onboarding after the instance is saved. It also installs and configures the required thin-edge.io services when they are not already available.

Instance parameters

Location behavior: A location where latitude, longitude, and altitude are all zero is ignored. The Connector does not repeatedly overwrite a location that was changed directly in Cumulocity unless the location values in SIA Connect are changed again.

Onboard with a one-time password

1. Obtain a one-time device password from your Cumulocity tenant administrator or onboarding workflow.
2. Set Onboarding Mode to One-time password (OTP).
3. Enter the password in One Time Password.
4. Save the instance.
5. Wait while the Connector downloads the device certificate and tests the connection.
6. Confirm that the instance no longer reports a connection error and that the device appears in Cumulocity.

A failed certificate-download attempt is delayed before the Connector retries. The instance error shows how long remains before the next attempt.

Onboard with a manual certificate

1. Set Onboarding Mode to Manual certificate.
2. Save the instance. The Connector creates a device certificate and private key for its dedicated profile.
3. Return to the Cumulocity Connector and expand Files.
4. Download the public file named Cumulocity certificate.
5. Approve or upload the certificate through the certificate-onboarding workflow provided by your Cumulocity tenant.
6. Return to the instance and wait for the connection to be tested again.
7. Confirm that the device appears in Cumulocity and that the instance no longer reports a certificate or connection error.

Use the automatically created items

Each Cumulocity instance automatically creates three internal items:

Do not change the UIDs of these automatically created items. The Connector uses their UIDs to select the correct Cumulocity message type.

Send measurements

1. Create or open the source instance that provides the data.
2. Create the required source items.
3. Create a mapping from a source item to the Cumulocity instance's Telemetry item.
4. Wait for the source item to produce a value.
5. Open the managed device or child device in Cumulocity and confirm that the measurement arrives.

Scalar values are converted to JSON using the source item name as the key. A valid JSON object is forwarded as a compact JSON object. Unsupported characters in measurement names and MQTT topic identifiers are replaced with underscores.

When Use Child Devices is Yes, the source instance name is used as the readable child-device name. The Connector also synchronizes the child type and adds a required-availability response interval of 60 minutes when that setting is missing. A response interval that was later changed in Cumulocity is not overwritten during normal metadata synchronization.

Create and clear alarms

1. Create a mapping from the source alarm item to the Cumulocity instance's Alarm item.
2. Use a custom mapping value when you need to send a JSON alarm object.
3. Create another mapping from the same source alarm type to Clear Alarm when the alarm should be cleared.
4. Trigger the source item and verify the alarm state in Cumulocity.

A custom alarm mapping can send a JSON object such as:

{
  "severity": "major",
  "text": "Motor overheated",
  "message": "Inspect the motor temperature"
}

If the alarm value is not a JSON object, the Connector normally sends the default alarm payload. A scalar value produced by a custom mapping or item pre-script is sent as the alarm message.

Receive write operations from Cumulocity

The Connector registers the custom operation c8y_SetSiaValue. Enabled Cumulocity instance items configured as Read Only or Read and Write are exported to the main managed object in the siaWritableItems fragment.

Items configured as Write Only and the three internal helper items are not exported as Cumulocity write targets.

The operation accepts a target by exported ID, item UID, uid:<uid>, or unique item name. Name-based targeting is rejected when more than one eligible item has the same name.

{
  "c8y_SetSiaValue": {
    "target": "uid:control_setpoint",
    "value": "123"
  }
}

The stock Cumulocity Device Management interface does not automatically create a custom form for this operation. Create it through the Cumulocity REST API or through a custom tenant application. The Connector emits the accepted value into the selected Cumulocity item, where a normal SIA Connect mapping can forward it to the destination device.

Identity and certificate behavior

• Changing Address or Device Id resets the Connector identity and starts a new onboarding process.
• Switching onboarding mode creates a new certificate and key when required.
• Deleting the last Cumulocity instance removes the identity created for the dedicated Connector profile.
• An expired Connector certificate prevents the connection until the device is onboarded again.
• The Connector only resets files that belong to its own Cumulocity profile. Other thin-edge profiles and Fleet Management certificates are not removed.

Troubleshoot the Connector

Related articles

• Install and manage Connectors
• Create and edit instances
• Create and edit items
• Create and edit mappings
• Manage and configure Connector files and certificates
• Troubleshoot Connector, instance, item, and mapping errors
• Cumulocity - Connecting PLCs and Industrial assets