Interfacing devices

Overview

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:

• Cumulocity IoT´s domain model in the Concepts guide, for understanding the data structures exchanged between agents and the Cumulocity IoT core.
• Device integration for understanding in detail how to develop agent software using the REST or MQTT protocols.
• REST implementation in the Cumulocity IoT OpenAPI Specification, for a detailed specification of the interfaces between agents and the Cumulocity IoT core.

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:

• It translates the device-specific interface protocol into a single reference protocol.
• It translates the specific domain model of the device into a reference domain model.
• It enables secure remote communication in various network architectures.

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.

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:

• The device is “closed”, that means, it is not programmable and supports only one particular, pre-defined protocol to communicate with the outside world.
• The protocol on the device is secure and internet-enabled, that is, the device connects to the cloud and not vice-versa.

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.

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:

• A regular inventory upload, which runs first when the agent is started and will be repeated periodically.
• A propagation of individual changes occurring while the agent runs.

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:

• Measurements are produced by reading sensor values. In some cases, this data is read in static intervals and sent to the platform (for example temperature sensors or electrical meters). In other cases, the data is read on demand or at irregular intervals (for example health devices such as weight scales). Regardless what kind of protocol the device supports, the agent is responsible for converting it into a “push” protocol by uploading data to Cumulocity IoT.
• Events that must be processed in realtime by IoT applications, for example, notifications from a motion detector or transactions from a vending machine.
• Alarms are events that require human intervention, for example, tamper events sent by an electrical meter.
• Audit logs are events that are recorded for risk management purposes, for example, login failures.

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:

• Asset management systems that provide additional information about the available devices and their location.
• Customer relationship management systems that provide information about the customer as device owner.
• Workforce management systems that provide information on the maintenance status of devices.

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:

• There are a number of full-featured open source agents and drivers in Cumulocity’s github.com and mbed.org repositories. More information can be found in the “Devices” section of this documentation.
• Client libraries for major runtime environments such as C/C++, Java and Lua, again as open source in github.com.
• Technology-neutral REST APIs for other runtime environments.