Getting Started with Cumulocity IoT Device Management

Introduction

Cumulocity IoT offers comprehensive device management (DM), which includes features like software/firmware/configuration management, connection monitoring, cloud remote access and much more to cover the whole device lifecycle.

If you want to try out these features, you either need a physical device using a full implemented agent for Cumulocity IoT or an agent that simulates a physical device.

As it is kind of difficult to get a physical device at hand, this guide will help you quickly start using an agent that runs in a container so you can easily explore the device management capabilities of Cumulocity IoT.

Cumulocity agent concept

An agent can be defined as a software artifact that…

  • Connects to device specific protocols
  • Maps the data of devices’ specific protocols to the Cumulocity domain model
  • Transports the data securely and reliably into Cumulocity IoT

DM-Agent

In this guide, we make use of a provided agent with most of the Cumulocity IoT DM Features already implemented:

Feature Supported
Device Certificates Yes
Device Bootstrapping & Registration Yes
Software Updates (apt) Yes
Firmware Updates Yes
Configuration Updates text-based Yes
Configuration Snapshots Yes
Device Profiles Yes
Network Yes
Device Metrics (CPU, Memory etc.) Yes
Remote Logfile Requests Yes
Location Updates Yes
Remote Shell Yes
Remote Access (SSH, VNC, Passthrough) Yes
Hardware Metering (CPU, Memory, HDD) Yes
Raspberry PI SenseHAT Yes
Docker Management Yes

The device management agent can be considered as an example agent to demonstrate device management capabilities of Cumulocity IoT. It is implemented in Python3 and provided as open-source with a Apache v2 license. It can be also used as reference to discover how specific device management capabilities can be implemented on the agent-side.

The agent can be executed either natively or in a docker container. In this guide, we will use the container version (as not everybody has a device at hand). If you are interested in running it natively e.g. on a Raspberry Pi, please follow the guide here.

The agent follows a modular concept so it can be easily extended with additional custom logic like docker container management or integrating to device protocols.

NOTE: The DM-Agent should be considered as an example only and should not be used in production!

Cumulocity Device Certification: The DM-Agent is a good starting point for getting a specific device certified in the Device Partner Portal. It implements most of the features required to get certified.

thin-edge.io

The thin-edge.io is an open-source project initiated by Software AG and partners to provide a cloud-agnostic edge framework. It is much more generic than the device management agent, so it can connect to multiple IoT Platforms, and it allows flexible logic executed on the device. It is optimized for a very small footprint and high performance.

Plugins are used to extend the thin-edge to also support device management features of Cumulocity IoT. Currently not all features are fully implemented, but the major blocks like software management, connectivity management and log management are already available and can be used.

The thin-edge.io is not the focus of THIS guide but should be considered as a productive and easily extendable framework.
In another upcoming “Getting Started Guide,” I will describe how to use the thin-edge.io to explore the (already supported) DM-Capabilities of Cumulocity IoT.

Prerequisite

To follow this guide, you only need the following:

  • Docker must be installed
  • Git or any other git client of your choice
  • A Cumulocity (Trial) tenant

Steps to follow

1. Clone the repo of the DM Reference Agent

Open a shell of your choice, navigate to any folder and clone the repo of the Cumulocity DM Reference Agent.

git clone https://github.com/SoftwareAG/cumulocity-devicemanagement-agent.git

2. Check the config

Depending on which instance of Cumulocity IoT you’re using, you have to change the configuration of the agent.
If you have a trial on eu-latest.cumulocity.com, you can continue with Step 3 as this is already preconfigured.

If you want to use any other instance, please edit the agent.ini and change the property “mqtt.url” to the instance you want to use.

nano cumulocity-devicemanagement-agent/config/agent.ini

In the example below, we change the URL to use mqtt.us.cumulocity.com instead of mqtt.eu-latest.cumulocity.com

3. Start the agent

On a Linux operating system, run:

cd cumulocity-devicemanagement-agent &&
chmod +x start.sh &&
./start.sh

On a Windows operating system, run:

cd cumulocity-devicemanagement-agent
./start.bat

It will take some time until the docker image is built and the container is started.
If you don’t encounter any errors in the end, one instance of the agent should be up and running.

4. Register the device in Cumulocity Tenant

4.1 DM-Agent Unique ID

Registration in Cumulocity IoT is based on a unique ID. The DM-Agent uses the container ID for that.
First we need to discover the container ID of the agent

docker ps


Make sure you copy that container ID so we can use it later on.

4.2 Register device

Now open the browser and log in to our Cumulocity IoT tenant using your provided credentials.

Use the application switcher on top to navigate to the device management.
image

In the device management, navigate to “Devices”“Registration”.
Click on Register Device and paste the copied container ID to the device ID Input Field.

Click “Next”“Complete”.

4.3 Approve device

After some time, you should see an “Accept” Button. Use that button to approve the device to have access to this tenant.
image

Congratulations, your DM-Agent is now successfully connected to your tenant!

5. Explore the device in Cumulocity IoT

Now that the agent is connected, you can use the device in Cumulocity IoT to explore the device management capabilities.
To find your device, you can enter the copied container ID in the search field on top right.

Alternatively you can click on “All Devices” and filter the list of available devices.

Now click on the device name to navigate to the device. You should see a list of tabs you can use to navigate through the DM features.

Next steps

Now that you have connected your device you can start exploring the device management features in Cumulocity IoT.
To get a full overview I recommend watching the following video:

Alternatively you’ll find full documentation here: Device Management - Cumulocity IoT Guides.
Another good starting point for an implementation of a new agent could be the Device management library - Cumulocity IoT Guides.

Multiple instances of DM-Agent

If you want to try out some mass features like bulk operations in Cumulocity, you can create multiple instances of this agent very easily.
Instead of ./start.sh just run

./mass_start.sh 5

to start 5 instances of the Agent.

Contribution

Do you have feedback or a great idea to extend the DM-Agent? I’m looking forward to receiving your feedback or PR!

Useful links | Relevant resources

Outlook

In my next articles, I will focus on some device management specific features and explain how you can make use of cloud remote access to tunnel any TCP-Protocol through Cumulocity.

Also I will focus a little bit more on the current status of the thin-edge.io and how you can use, extend it to your needs.


This article is part of the TECHniques newsletter blog - technical tips and tricks for the Software AG community. Subscribe to receive our quarterly updates or read the latest issue.

3 Likes