Cumulocity IoT's domain model

The following section describes the general technical concepts behind Cumulocity IoT.

Overview

The following image shows the relevant aspects of devices and assets in the Internet of Things:

model

One of the great innovations in Cumulocity IoT is its standardized representation of common devices and sensors as well as concepts for flexibly extending and modifying this representation. By default, Cumulocity IoT comes with detailed visualizations of sensors, smart meters, trackers and other devices. It has many options to fit in local customizations.

As a result, Internet of Things applications can be written independently from connected devices and underlying sensor networks, customized for specific cases in different web configurations or different devices from manufacturers.

The following sections are a walk-through of these concepts and will describe the ideas behind it and give you examples which use Cumulocity IoT’s REST APIs as format. To use them with different programming languages, refer to the specified samples in the Cumulocity IoT OpenAPI Specification.

Inventory

Managed objects

The inventory stores devices and other assets relevant to your IoT solution. We refer to them as managed objects.

Managed objects can be “smart objects” such as smart electricity meters, home automation gateways and GPS devices. They can be assets you would like to monitor, such as rooms in which sensors are installed, or cars containing GPS devices.

The following JSON code shows a small example of a managed object in the inventory, in this case a simple switch.

{
    "id": "47635",
    "name": "Smart switch",
    "type": "ge_45609",
    "c8y_Relay": {
        "state" : "OPEN"
    }
}

An example for another asset stored in the inventory could be a room in which a switch is installed (compare the id property of the above switch with the managedObject in the child asset reference below).

{
    "id": "59436",
    "type": "resortenergymgmt_Room",
    "name": "Sauna room",
    "childAssets": {
        "references" : [
            {
                "managedObject": {
                    "id": "47635"
                }
            }
        ]
    },
    "resortenergymgmt_RoomProperty": {
		"size": 56
    }
}

In general, each managed object consists of:

Fragments

Imagine, for example, that you want to describe electric meters from different vendors. Depending on the make of the meter, one may have a relay and one may be able to measure a single phase or three phases. These characteristics are identified by storing fragments for each of them:

{
    "id": "47035",
    "type": "elstermetering_AS220",
    "lastUpdated": "2010-11-13T18:28:36.000Z",
    "c8y_Position": {
        "alt": 67,
        "lng": 6.15173,
        "lat": 51.211977
    },
    "c8y_ThreePhaseElectricitySensor": {},
    "c8y_Relay": {
        "state": "CLOSED"   
    }
}

In this example, a fragment c8y_ThreePhaseElectricitySensor identifies a three phase electric meter. In addition, the device includes a relay, which can be used to turn the power supply on and off.

Using this approach, the modeling devices can make a difference between modeling elementary sensors and controls as fragments, and modeling the entire device as a combination of sensors, controls and possibly proprietary aspects of the device.

The approach also enables developing generic application components. For example, as soon as a managed object has a position fragment (c8y_Position), it can be placed on a map. As soon as it has a relay (c8y_Relay), it can be switched on and off using the respective device control command as described below.

For more information on fragments and how managed objects are structured, see the Device management library in the Reference guide.

Info

While designing the data model for the inventory managed object consider the following:

  1. There is no size or length constraint for a single fragment, but there is a limitation for the overall JSON document size, which may not exceed 16MiB for a single managed object entry within the inventory collection. We recommend you to keep it below 1 MiB.
  2. When you include arrays of elements within fragments, keep the length of such collections below 1k elements.
  3. Each consecutive fragment added to the managed object at root level imposes a certain delay on querying such an item. If the performance of a query matters, it is recommended to nest custom fragments with information within a chosen single fragment effectively limiting the root fragments number. For example:
{
    "id": "47035",
    "type": "elstermetering_AS220",
    "lastUpdated": "2010-11-13T18:28:36.000Z",
    "c8y_ThreePhaseElectricitySensor": {},
    "c8y_DeviceMetrics": {
        "c8y_ConnectionMetrics": {
            "failures": 0,
            "successful": 1403,
            "total": 1403
        },
        "c8y_Alarms": {
            "requested": 100,
            "successful": 100
        },
        "c8y_Measurements": {
            "requested": 1303,
            "successful": 1303
        }
    },
    "c8y_DeviceMetricsConfiguration": {
        "deviceRepresentationUpdateIntervalCron": "0 22 * * *",
        "monitorApi": [
            "measurements",
            "alarms"
        ]
    }
}

Naming conventions of fragments

Fragments use a naming convention to avoid conflicts between different parties supplying fragment information, similar to Java or other programming languages.

In the example above, c8y_Position is a combination of “c8y” (a shorthand for “Cumulocity”), an underscore and “Position”. Together they form a set of standard fragments. Fragment definitions can be found in the Sensor library and in the Device management library in the Reference guide.

Important
Names used for fragments must not contain whitespaces nor the special characters . , * [ ] ( ) @ $ / '.

Note that Cumulocity IoT follows a document-oriented approach for storing data. All characteristics of an object can be inferred from the document with the object data itself. There is no explicit separate metadata model that needs to be configured and managed. However, applications can add own metadata and store values in the inventory additionally. For example, a vending application can maintain metadata about slot configurations of the diverse vending machine types in the inventory.

Object identification

Each managed object in the inventory has an own, unique and global identifier that is automatically generated by Cumulocity IoT when the object is created.

This identifier will always stay with the object regardless of network restructures or different hardware parts.

Identity service

To shield applications from these numbers of identifiers, Cumulocity IoT includes an identity service that registers all identifiers for one asset that are used outside of Cumulocity IoT and map these to a single global identifier that is used by applications.

This service is used by agents (to register external identifiers) and by business processes involving reorganisations and changes of devices (to modify maps of external identifiers to global identifiers).

As an example, assume that a smart meter would be faulty and a new meter with another meter number and asset tag needs to be installed in a household. The routine business process for replacing faulty hardware can now just update the asset tag and meter ID associated with a customer in the identity service. Afterwards, both previously collected and new meter readings are related to the correct customer.

More information can be found in Identity in the Cumulocity IoT OpenAPI Specification.

Object hierarchies

The inventory model supports two default hierarchies of objects: A communication hierarchy (“childDevices”) and an asset hierarchy (“childAssets”).

The communication hierarchy tracks how devices are linked to the IoT platform from a communication point of view. Agents connect the sensor network to Cumulocity IoT. They often communicate through gateway devices or modems with the sensor network. The gateways, in reverse, connect to devices in the sensor network, which contain sensors and controls. This typical communication hierarchy is shown in the picture below.

Example communication hierarchy

The asset hierarchy structures the assets that are remotely supervised and controlled through the IoT devices.

An example asset hierarchy for building management could be buildings containing rooms. Buildings would be associated with gateways connecting the building to Cumulocity IoT, while rooms would be associated with sensors and controls. This example hierarchy is shown in the picture below.

Example asset hierarchy

Child objects in hierarchies

The two hierarchies above are explicitly supported by the inventory interface and client libraries, that provide methods for adding and removing children in hierarchies. The hierarchies themselves are constructed by client applications. The communication hierarchy is constructed by agents, the asset hierarchy is added by applications on top.

Note that the object hierarchies do not necessarily need to form a tree, the same asset can be a child of multiple parent assets. This enables applications to create additional, user-defined groups of objects such as working sets or virtual networks. Applications can, in addition, use fragments to define arbitrary alternative hierarchies.

Object lifecycle

The previously described identification and hierarchy mechanisms form a very flexible device lifecycle approach that can be adapted to most business processes. Initially, when a device is powered on for the first time, it is neither connected to the system nor linked to an asset. Linking a device to an agent in the communication hierarchy (possibly indirectly through a gateway) signals that the device is connected. Only connected devices can be remotely controlled. Linking a device to an asset using the asset hierarchy can be used to signal that the device has been physically installed.

Disconnecting and uninstalling a device does not necessarily indicate that the device was discarded or deactivated and should be deleted from the system. It can indicate instead that the device was returned to the warehouse and will be installed elsewhere later on. It depends on the particular business process whether data for the device should be kept or not. Physically deleting a device from the inventory implies that all data collected for that device is lost – this is probably desired only when completely cleaning up old data. To keep data for a device that has been discarded, identifier mappings can be removed from the identity service. Should a new device be installed in the same place as the old device, a new global identifier will be generated.

Addressing the device lifecycle properly is important when designing agents. An agent connecting to devices should not assume automatically that devices can be deleted from the inventory when they cannot be connected to. In the same way, an agent interfacing a CRM system should not assume that a device can be deleted when it has been removed from the CRM system.

Further information

More detailed information for working with the inventory can be found in the Inventory API in the Cumulocity IoT OpenAPI Specification.

Events

Events are used to pass real-time information through Cumulocity IoT.

Events come in three types:

An event has one specific type (as specified in its naming convention), a time when the event occurred and a text to describe the event. An event refers to a source managed object in the inventory. This is an example of an event representation:

{
    "type": "c8y_LocationUpdate",
    "time": "2010-11-13T18:28:36.000Z",
    "text": "Location updated",
    "source": {
        "id": "47634"
    },
    "c8y_Position": {
        "alt": 67,
        "lng": 6.15173,
        "lat": 51.211977
    }
}

Any event can be extended in the same way as described for managed objects above. In this example, we not only signal that an object moved, we also include the new position of the object in the form of a c8y_Position fragment.

An audit log extends an event through:

This is an example of an audit record structure:

{
    "type": "c8y_SecurityEvent",
    "time": "2010-11-13T18:28:36.000Z",
    "text": "Gateway login failed",
    "source": {
        "id": "47633"
    },
    "user": "skywalker",
    "application": "Resort energy management",
    "activity": "login",
    "severity": "MINOR"
}

An alarm extends events through:

This is an example of an alarm that has been cleared:

{
    "count": 1,
    "creationTime": "2020-03-19T12:16:31.586Z",
    "id": "20200301",
    "severity": "MAJOR",
    "source": {
        "id": "251982",
        "name": "My tracking device"
    },
    "status": "CLEARED",
    "text": "No data received from the device within the required interval.",
    "time": "2020-03-19T00:00:00.000Z",
    "type": "c8y_UnavailabilityAlarm"
}

More detailed information can be found in Events, Alarms and Audits in the Cumulocity IoT OpenAPI Specification.

Measurements

Measurements represent regularly acquired readings and statistics from sensors.

Measurements consist of a time when the measurement was taken, the unique identifiers of the source of the measurement, and a list of fragments. Here is an example of a measurement:

{
    "time": "2011-01-02T03:04:00.000Z",
    "source": {
        "id": "1235"
    },
    "c8y_ThreePhaseElectricityMeasurement": {
        "A+": { "value": 435, "unit": "kWh" },
        "A-": { "value": 23, "unit": "kWh" },
        "P+": { "value": 657, "unit": "W" },
        "P-": { "value": 0, "unit": "W" },
        "A+:1": { "value": 123, "unit": "kWh" },
        "A-:1": { "value": 2, "unit": "kWh" },
    }
}

Similar to the inventory model, fragments are used to identify characteristics of particular devices. In the above example, a three-phase electricity meter sends readings for the different electrical phases. In the example above, such a fragment maps the names of the individual readings (for example, “A+” or “A-") to the actual numeric value and unit of the measurement.

Readings can hold various additional information that applications may require.

More detailed information can be found in Measurements in the Cumulocity IoT OpenAPI Specification.

Operations

Devices can be remote-controlled and managed in Cumulocity IoT.

Examples:

In Cumulocity IoT, these use cases are implemented by sending operations to a device.

The following snippet shows an operation for setting the state of the relay with the ID “42” to “OPEN”:

{
    "deviceId": "42",
    "c8y_Relay": {
        "state": "OPEN"
    }
}

Just like other types of data, operations are also standardized through the sensor library to simplify application development (see below). For example, setting a switch should be the same for all switches regardless of their make.

Operations are modeled just like fragments in the inventory model (see above). The same extensibility concept applies. Random vendor-proprietary extensions to the standard operations are possible. These are not denied or modified by Cumulocity IoT.

Sending operations to devices

Cumulocity IoT delivers operations to devices over any network using a reliable queueing routine. This queueing routine respects the limitations and security requirements of IoT networks:

To pass an operation from an application to a device, a process of several steps is required as illustrated in the image below. Assume that the user issues a remote control operation for a device (such as a device restart) from an application. The application creates the operation in Cumulocity IoT (Step “1”). Cumulocity IoT will queue the operation for execution and return control back to the application immediately.

At some point in time, the agent responsible for the device will request operations that are queued for the devices that it manages (“Step 2”). This will happen immediately through Cumulocity IoT’s push mechanism or at a regular or scheduled interval.

The agent will execute the operations on the devices that it manages (Step “3”), and will update Cumulocity IoT with the results of the execution (Step “4”). The devices that the agent manages are direct or indirect children (“childDevices”) of the agent.

Finally, the application can query the results of the operation (Step “5”). Audit records are generated both for the original request to run the device control operation and for the acknowledgement that the operation was actually run.

Device control architecture

If there are communication issues while delivering an operation to a device, an alarm should be raised by the agent.

Sometimes there are delays between sending an operation to a device and retrieving a response. The system assumes a delivery unless an error is reported to maintain functionality.

Designing operations for reliability

Operations should always be idempotent. Idempotent means that no matter how often you run the operation, the outcome is always the same.

For example, an operation to set a switch to a certain state is idempotent. No matter how often the switch is set to “on”, it will be “on” afterwards. An operation to toggle a switch is not idempotent - the result depends on whether the operation was run an odd or an even number of times.

More details can be found in Device control in the Cumulocity IoT OpenAPI Specification.

The sensor library

Cumulocity IoT includes a sensor library to model specific sensing and controlling skills across device products. A single device can have many sensor and control characteristics. The sensor library enables applications to answer questions such as:

It covers basic sensors and controls, and it is supported by the Cumulocity IoT client libraries. It also enables writing powerful generic IoT software plugins.

Technically, the sensor library defines standard fragments for inventory, measurements, events and device control, following the naming convention (see Inventory). The example below shows two fragments used for an electricity meter:

{
    "id" : "121",
    "type" : "com_kamstrup_382",
    "c8y_SinglePhaseElectricityMeasurement": {},
    "c8y_Relay": {
        "state": "OPEN"
    }
}

More examples and details can be found in Sensor library in the Reference guide.

The Cumulocity team welcomes contributions to the sensor library. If you integrate any devices, controls, sensors or other objects and find that your model fragments have a more general usability beyond your own case or your device, we encourage you to contribute them for inclusion into Cumulocity IoT by contacting our product support.

Summary

Cumulocity IoT provides a reference model for managing and controlling IoT systems, covering

This model is intended to be horizontal across device vendors. In addition it is also extensible to cover any needs of special features of various devices and applications.