Tech Community for Software AG Tech Community

Posted on May 9, 2022 • Originally published at tech.forums.softwareag.com on Apr 21, 2022

Getting Started with Cumulocity IoT Device Management

#iot #cumulocity #deviceconnectivity

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 to 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 & reliable 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:

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

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 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!

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 & log management are already available and can be used.

https://github.com/thin-edge/thin-edge.io

The thin-edge.io is not in 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.

Pre-requisite

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 an 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 login to our Cumulocity IoT tenant using your provided credentials.

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

In the device management navigate to “Devices” → "Registration"

Click on Register Device and paste the copied container ID to the cevice 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.

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:

https://www.youtube.com/embed/rEqdyQSsuPY

Alternatively you’ll find the 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 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.

Visit the original post

DEV Community