Dataserver Cumulocity IoT

  • Updated on Jan 29, 2025
  • Published on Dec 17, 2024
  • 4 minute(s) read
  • SE
  • TA
  • PL

The purpose of this article is to serve as a reference guide for using Cumulocity as a data server in the Data Collection Module.

This guide is part of the complete documentation for the Data Collection Module feature in SiteManager.

The Cumulocity IoT dataserver is used to send collected samples (data points) to a Cumulocity IOT cloud instance (a trial subscription is OK). To use the Device Report feature, SiteManager firmware version 11.4 or newer.

Information

First time users might benefit from using the Setting up Cumulocity IoT guide.

Configuration

The data server configuration consist of the fields described below.

Main section

The top level of the data server contains the following fields:

Function Type Importance Description
DatasrvName string mandatory Unique (within this configuration file) name for each data server this SiteManager delivers data to. Follows the normal rules for names.
DatasrvDesription string optional A description of this data server. For your future reference.
SampleList array of strings optional This array contains the list of sampleref this data server will deliver data from. If it is not present, all sample values in this configuration will be delivered. Since this object is not a Collector's object, the CollectorName part of the sampleref field is mandatory. If the SampleName part of the sampleref is left blank, all samples from that collector are delivered.
IOPin boolean optional If set to true, the Output I/O pins configured to follow DCM data loss will be controlled by this datasrv. If multiple data servers control the I/O pins, then the value will be the logical OR of all data servers in data loss state. (I.e. If any data server is in data loss, the I/O pins will be in logical high). If not set, the value is false.
DatasrvProtocol string-enum mandatory Designates the protocol used to deliver data from the Store and Forward database to data servers, aka Cloud Systems. For Cumulocity use C8Y/REST. Currently 6 possible values exist: AWS/MQTT, AZURE/IOTHUB, SCI/SPD, C8Y/REST, SEMA/REST or SIMULATOR/NONE.
ConnectRetryMin integer > 0 mandatory Minimum number of seconds before trying to reestablish a connection to the data server for data delivery. An exponential back-off algorithm is used to retry connection establishment, starting after ConnectRetryMin and increasing to ConnectRetryMax.
ConnectRetryMax integer > 0 mandatory Maximum number of seconds before trying to reestablish a connection to the data server for data delivery.
C8YParams object mandatory Contains all the for Cumulocity parameters needed to deliver (publish) data to the Cumulocity Cloud service. Mandatory if DatasrvProtocol has the value C8Y/REST.

C8YParams

The C8YParams object contains the following fields:

Function Type Importance Description
C8YRegisterURL string mandatory The URL of the Cumulocity Cloud for registering new devices.
C8YRootCAName string optional The certname of the Cumulosity Root-CA certificate. If the certname cannot be found only unsecured HTTP server connections can be used. If not specified, the first Cumulocity ROOT-CA found in the cert repository will be used.
RegName string optional The certname of the Cumulosity Device Registration Information for this connection. If not specified, the first Cumulosity Device Registration Information found in the cert repository will be used.
PushInterval integer >= 0 mandatory The interval in seconds between each delivery of new data from the Store and Forward database. The value 0 means that data is delivered as fast as possible.
UseChildDevices boolean optional Control whether collector data is reported in a child device of the SiteManager, or reported in the SiteManager. Default is true, equaling report in child device.
DeviceReport object optional Parameters to configure the extra capability to report some SiteManager internal data directly to Cumulocity.

Below is an example of a Cumulocity data server configuration:

{
    "DatasrvName": "secomea_c8y",
    "DatasrvProtocol": "C8Y/REST",
    "ConnectRetryMin": 2,
    "ConnectRetryMax": 10,
    "C8YParams": {
        "C8YRegisterURL": "https://SecomeaPresales.cumulocity.com",
        "RegName": "c8yreg",
        "C8YRootCAName": "cumulocityROOTCA",
        "PushInterval": 30
    }
}

Device Report

Disclaimer

This Feature will be available in SiteManager Firmware: 11.5

The Cumulocity data server also have the capability to relay SiteManager internal values without use of the DCM 'Collector SiteManager Internal', the DeviceReport object contains:

Function Type Importance Description
ReportInterval integer > 5 maybe-optional The frequency in seconds of reporting the selected data items to Cumulocity. The frequency may be impacted by the GNSSGeographicDistance parameter. Minimum value is 5. Becomes mandatory when the DeviceReport is used.
ReportName string optional Name of the data group used when reporting to Cumulocity. Default name is Device Report.
GNSSGeographicDistance double > 1.0 optional Parameter which determines when a newly read GNSS position is considered as new, and thus reported to Cumulocity. Default is 100 meter.
Items array of string-enums maybe-optional List of data items that should be reported to Cumulocity. For defined items, see table Device Report Items. Becomes mandatory when the DeviceReport is used.

Device Report Items

Item Description
SystemTemperature Internal temperature in Celsius.
CPULoad The CPU load in percent.
FreeMemory The available memory in kB.
IngressRate Incoming data rate in bytes/s, see note x).
EgressRate Outgoing data rate in bytes/s, see note x).
DBCacheSize Size in bytes of database cache.
DBSize Size in bytes of the database.
GnssPosition Updates the device position (Location) in Cumulocity. The position is only reported when the position has changed more than the GNSSGeographicDistance parameter or its default.
GnssTracking Send tracking updates to Cumulocity, when the position has changed more than the GNSSGeographicDistance parameter or its default.

x) The Ingress and Egress rates will not be the same, as data formats are different of collectors and the data server.

Example of a Cumulocity data server configuration, with device reporting:

{
    "DatasrvName": "secomea_c8y",
    "DatasrvProtocol": "C8Y/REST",
    "ConnectRetryMin": 2,
    "ConnectRetryMax": 10,
    "C8YParams": {
        "C8YRegisterURL": "https://SecomeaPresales.cumulocity.com",
        "RegName": "c8yreg",
        "C8YRootCAName": "cumulocityROOTCA",
        "PushInterval": 30,
        "DeviceReport": {
            "ReportInterval": 60,
            "GNSSGeographicDistance": 99,
            "Items": [
                "GnssTracking"
            ]
        }
      }
}