The following image shows the relevant aspects of devices and assets in the Internet of Things:
The inventory stores all master data related to devices, their configuration and their connections. It also contains all related assets (like vehicles, machines, buildings) and their structure.
Measurements contain numerical data produced by sensors (like temperature readings) or calculated data based on information from devices (service availability of a device).
Events contain other real-time information from the sensor network, such as the triggering of a door sensor. Events can also be alarms.The user or operator of the system must take action to resolve the alarm (like a power outage). In addition, security-related events are shown as audit logs.
Operations relate to data that is sent to devices for execution or processing, such as switching a relay in a power meter or sending a credit to a vending machine.
One of the great innovations in Cumulocity is its standardized representation of common devices and sensors as well as concepts for flexibly extending and modifying this representation. By default, Cumulocity 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’s REST APIs as format. To use them with different programming languages, refer to the specified samples in the Cumulocity 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.
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).
Fragments with specific meanings, for example, c8y_IsDevice.
Any additional custom fragments.
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:
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 Fragment library.
Info
While designing the data model for the inventory managed object consider the following:
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.
When designing asset hierarchies, use small groups with less than 1000 subassets. Each subitem in the asset hierarchy creates a reference record in the parent item. Therefore keep in mind the first recommendation regarding the JSON document size.
When you include arrays of elements within fragments, keep the length of such collections below 1k elements.
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:
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 fragment library.
Important
Names used for fragments must not contain whitespaces nor the special characters . , * [ ] ( ) @ $ / '.
Note that Cumulocity 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 must 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 when the object is created.
This identifier will always stay with the object regardless of network restructures or different hardware parts.
To shield applications from these numbers of identifiers, Cumulocity includes an identity service that registers all identifiers for one asset that are used outside of Cumulocity 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 must 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 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. 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.
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, while rooms would be associated with sensors and controls. This example hierarchy is shown in the picture below.
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 OpenAPI Specification.
Events
Events are used to pass real-time information through Cumulocity.
Events come in three types:
A base event signals when something happens. An event can be triggered when a switch is switched on or off.
An alarm signals an event that requires manual action, for example, when a meter has been tampered with or the temperature of a fridge increases above a particular threshold.
An audit log stores events that are security-relevant and should be stored for auditing. For example, an audit log should be generated when a user logs into a gateway.
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:
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:
A username of the user that carried out the activity.
An application that was used to carry out the activity.
A status showing whether the alarm is active or cleared.
A time stamp when the alarm was last updated.
A classification such as critical, major, minor, warning.
A history of changes to the event in form of audit logs.
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 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:
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 OpenAPI Specification.
Operations
Devices can be remote-controlled and managed in Cumulocity.
Examples:
Device control: Setting a switch which controls temperature.
Device configuration: Setting up a charge table in a smart meter.
Device maintenance: Requesting a gateway to download and install a new firmware.
In Cumulocity, 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”:
Just like other types of data, operations are also standardized 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.
Sending operations to devices
Cumulocity delivers operations to devices over any network using a reliable queueing routine. This queueing routine respects the limitations and security requirements of IoT networks:
Devices are often connected over unreliable, low-bandwidth links that may only occasionally be available. Devices may, for example, only dial up once in a day to the network to fetch commands for execution. Therefore Cumulocity communicates asynchronously with devices.
Device protocols are often not designed for secure online communication. They may not pass NAT networks, firewalls and web proxies. They may not be secure enough for public exposure on the Internet. Cumulocity offers the possibility to connect these devices as HTTPS clients.
It may not even be possible to reach a mobile device over the internet. Cumulocity uses push technology to send operations to devices.
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 (Step “1”). Cumulocity 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’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 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.
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 OpenAPI Specification.
Summary
Cumulocity provides a reference model for managing and controlling IoT systems, covering
Central representation of IoT devices, networks and assets in the inventory.
Configuration of devices.
Reading of sensors.
Manipulation of controls.
Handling of real-time events.
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.
