This section explains concepts relevant for interfacing IoT devices and other IoT-related data sources with Cumulocity IoT.

To interface these systems with Cumulocity IoT, a driver software called agent is required. We first describe the main tasks of an agent and discuss the structural options for agents later. We will walk step by step through the tasks of an agent. Finally, we discuss the usage of agents for acquiring data from other data sources such as a tenant’s IT system.

Related topics can be found in the following sections:

What is an agent?

Internet of Things (IoT) devices come with a wide variety of protocols, parameters and network connectivity options. Protocols of devices range from low-level serial links to full-blown IT protocols such as web services. Today’s IoT standards rarely define exactly how to access particular readings of particular sensors or manipulate particular controls. Devices can be connected through mobile networks and gateways.

To shield machine-to-machine applications from this numbers of access options, Cumulocity IoT uses agents. An agent is a function that complies with three duties for a specific vendor and type of devices:

Agent architecture

Protocol translation

The configuration of parameters, readings, events and other information is either send to an agent (“push”) or queried by an agent (“pull”) through a device-specific protocol on one side. The agent will convert these messages into the protocol that Cumulocity IoT requires. It will also receive device control commands from Cumulocity IoT (“switch off that relay”) and translate these into a kind of protocol the device requires.

Cumulocity IoT uses a simple and secure reference protocol based on REST (that is, HTTPS) and JSON, which can be used for a wide variety of programming environments down to small embedded systems. To support real-time scenarios, the protocol is designed around a “push” model, that is, data is sent as soon as it is available.

Model transformation

The configuration parameters, readings, events, they all have their device-specific name (and possibly units). An agent for a particular device will transform this device-specific model to the Cumulocity IoT reference model. For example, an electricity meter provides the main reading as a parameter “Received Wh”, so the agent will transform this reading into a reference “Total active energy” in kWh.

Secure remote communication

Devices can provide a protocol that is unsuitable for secure remote communication, in particular in public cloud environments. The protocol only supports local networking and does not pass through firewalls and proxies and it can contain sensitive data in clear text form. To avoid security issues like these, an agent can be co-located to the device and provide a secure, internet-enabled link to the remote device via Cumulocity IoT.

To summarize the benefits of the agent concept: Agents enable IoT applications to securely interface with any type of remote IoT device and without imposing any mandatory system requirement on the device itself. They drastically simplify developing IoT applications by shielding the applications from the variety of IoT devices and protocols.

What agent architecture is supported?

Agents can be deployed in various ways, as illustrated in the picture below. We distinguish two main variants: server-side agents and device-side agents.

Agent architectures

Server-side agents are run in a cloud, hosted on Cumulocity IoT as microservices or managed by yourself in your own cloud. Devices connect to server-side agents using their device-specific protocol. This option is mainly chosen when one or more of the following complies:

Device-side agents run on a device in the sensor network. These devices can be routers, mobile phones or modems. The agents perform in any kind of run-time environment the device supports, ranging from the very battery- and memory-consuming embedded microcontrollers to minicomputers running Embedded Linux. The agents will directly query connected sensors and manipulate connected controls. This usually results in a simpler architecture than server-side agents.

Agent life cycle

Starting the agent

Server-side agents run continuously in the cloud, accepting connections from the device types that they support. Device-side agents run on the device and are started along with other device software when the device is powered on.

Both types of agents are pre-configured with a fixed platform endpoint URL. Using this platform endpoint URL, credentials for each connected device are acquired. These credentials enable the device to connect to a tenant in Cumulocity IoT and to send data to the tenant as well as to accept operations from the tenant.

After starting, the agent will synchronize the inventory with the sensor subnetwork that the agent is responsible for.

Synchronizing inventory data

To understand inventory synchronization, remember the communication hierarchy described in Cumulocity IoT´s domain model. In the inventory, agents are located at the roots of the communication hierarchy. Below each agent, the topology of the subnetwork that the agent manages is reflected. This topology exists in the real network as well as in snapshot form in the inventory. It may change in the real network, and these changes must be reflected in the inventory.

Communication hierarchy

Inventory synchronization is a two step procedure: The first step is to query the agent’s entry from the inventory and to create it in the network. The second step is then to discover the subnetwork and synchronize it with the inventory based on the queried agent’s entry.

The first step provides the option to pass configuration information to an agent as part of the agent entry into the network. This configuration information is determined by the type of agent and the connected devices. It contains, for example, polling intervals for measurements. It can also assign subnetwork tasks to the agent in case the agent cannot automatically discover its associated network.

For example, an agent installed on a mobile phone can discover a connected bluetooth heart monitor without further configuration. An agent installed on a local IP network can run a discovery procedure on a local network. Unlike a Multispeak agent requires the URL of a Multispeak server and credentials to be able to discover connected smart meters.

To keep inventory information up-to-date and maintain a centralized view on devices, two mechanisms are used:

The need for a regular inventory upload depends on the particular device protocol, which possibly supports change notifications. Assume, for example, that a device is operated locally through controls on the device or using a local device manager software. If the device protocol does not propagate these changes, they can only be discovered by a regular query. Another example would be the assumption that new devices can only be discovered by scanning a network address range in the sensor network regularly. This must be executed by an agent.

It is important to know that the device agent is assuming data ownership of configuration properties or device topology data and therefore modifies or overwrites this data accordingly.

Receiving data and commands from applications

Now that the topology is established in the inventory, the devices are visible and operable from IoT applications. As described in the device control section of Cumulocity IoT´s domain model, IoT applications can send operations to devices, which are queued in the core. The agent must query the core for operations intended for its devices.

If an operation was sent to an agent’s device, the agent will translate the operation into the device-specific representation. For example, a Multispeak agent would translate an operation to set the state of a switch to a SOAP “initiateConnectDisconnect” request for an electricity meter. The translated operation is then sent to the device.

Finally, the agent acknowledges the execution of the operation and it would update the state of the switch in the inventory.

Sending sensor readings, events, alarms and audit logs

Besides remote control of devices, the other main task of agents is to transmit data from sensors. This data can vary as outlined in the domain model section:

Updating agent configuration

The agent configuration may need to be changed during run-time. For example, a new gateway to a sensor network is installed and the address and credentials for accessing that gateway must be sent to the agent. This is performed by sending a device control request targeted to the agent itself. After processing the configuration, the agent will publish changes within the device network.

Integrating of other data sources

System integration

Enterprises offering IoT-enabled services typically run other IT systems that supply important information on IoT assets and devices. Examples of those systems are:

Technically, developing and running an agent for system integration is not different from an agent for device integration. However, the subset of data owned by the systems is different. Agents for device integration own the device hierarchy and device configuration information. Agents for system integration provide additional information for devices and own parts of the asset hierarchy. Together, they contribute to the device information stored in the inventory to provide a centralized view on everything related to the assets and devices that are relevant for the IoT service.

How does the platform support developing agents?

Cumulocity IoT supports agent development on three different levels: