Getting Started with Cumulocity IoT Device Management
Tags: iot, cumulocity, deviceconnectivity
Published: 2022-05-09 10:41:39

---
title: Getting Started with Cumulocity IoT Device Management
published: true
date: 2022-04-21 13:35:26 UTC
tags: IoT, Cumulocity, DeviceConnectivity
canonical_url: https://tech.forums.softwareag.com/t/getting-started-with-cumulocity-iot-device-management/256401
---

## Introduction

Cumulocity IoT offers comprehensive device management (DM) which includes features like software/firmware/configuration management, connection monitoring, cloud remote access and [much more](https://cumulocity.com/guides/users-guide/device-management/) to cover the whole device lifecycle.

[![image](https://aws1.discourse-cdn.com/techcommunity/optimized/3X/2/e/2e31342557532f3b7d7bd4ad1fe83f0c036b7fa9_2_690x386.png)](https://aws1.discourse-cdn.com/techcommunity/original/3X/2/e/2e31342557532f3b7d7bd4ad1fe83f0c036b7fa9.png "image")

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

[![](https://aws1.discourse-cdn.com/techcommunity/original/3X/b/8/b8f6913505ff8549e7f7324bc29689db98dc8cca.png)](https://cumulocity.com/guides/images/concepts-guide/agents.png)

### 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](https://github.com/SoftwareAG/cumulocity-devicemanagement-agent#quick-start)

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](http://thin-edge.io)

The [thin-edge.io](http://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.

[![image](https://aws1.discourse-cdn.com/techcommunity/optimized/3X/0/6/062ba3b1d4c3da28e250e7cf38bc09ed08cb52a9_2_690x327.png)](https://aws1.discourse-cdn.com/techcommunity/original/3X/0/6/062ba3b1d4c3da28e250e7cf38bc09ed08cb52a9.png "image")

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](https://medium.com/thin-edge-io/enhanced-device-management-with-thin-edge-io-0-5-4994683bba36) and can be used.

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

The [thin-edge.io](http://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](http://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](https://www.docker.com/) must be installed
- [Git](https://git-scm.com/) or any other git client of your choice
- A Cumulocity [(Trial)](https://signup.softwareag.cloud/#/basic?product=cumulocity&utm_referrer=TechCommunity) 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](http://eu-latest.cumulocity.com) you can continue with [Step 3](https://tech.forums.softwareag.com#3-start-the-agent) 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](http://mqtt.us.cumulocity.com)** instead of **[mqtt.eu-latest.cumulocity.com](http://mqtt.eu-latest.cumulocity.com)**

[![image](https://aws1.discourse-cdn.com/techcommunity/original/3X/8/b/8b31c19a10acb115e64b555f010e38b7be74b1f3.png)](https://aws1.discourse-cdn.com/techcommunity/original/3X/8/b/8b31c19a10acb115e64b555f010e38b7be74b1f3.png "image")

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

```

[![image](https://aws1.discourse-cdn.com/techcommunity/original/3X/0/8/087335cd95f3fa60361e63631c1b3322bc6bad46.png)](https://aws1.discourse-cdn.com/techcommunity/original/3X/0/8/087335cd95f3fa60361e63631c1b3322bc6bad46.png "image")
  
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.  
 ![image](https://aws1.discourse-cdn.com/techcommunity/original/3X/3/b/3b1dc4b75240f9b6be7b19239673eeb1cef0162a.png)

In the device management navigate to **“Devices”** → **"Registration"**  
Click on **Register Device** and paste the copied container ID to the cevice ID Input Field

[![image](https://aws1.discourse-cdn.com/techcommunity/optimized/3X/9/b/9baca2bd07fea281a874ef30b5da0b1357008037_2_370x500.png)](https://aws1.discourse-cdn.com/techcommunity/original/3X/9/b/9baca2bd07fea281a874ef30b5da0b1357008037.png "image")

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](https://aws1.discourse-cdn.com/techcommunity/original/3X/1/b/1b3b2c59f9be0d3a4fea2dd23a0dd984eab4c15b.png)

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

[![image](https://aws1.discourse-cdn.com/techcommunity/optimized/3X/3/2/3251a354daeb675728feccbaab53927d2130d11d_2_690x202.png)](https://aws1.discourse-cdn.com/techcommunity/original/3X/3/2/3251a354daeb675728feccbaab53927d2130d11d.png "image")

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

[![image](https://aws1.discourse-cdn.com/techcommunity/optimized/3X/3/c/3c51d33fe5ac233390506aaf238ab273c40b9d59_2_689x243.png)](https://aws1.discourse-cdn.com/techcommunity/original/3X/3/c/3c51d33fe5ac233390506aaf238ab273c40b9d59.png "image")

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.

[![image](https://aws1.discourse-cdn.com/techcommunity/optimized/3X/d/a/da852eceaa4fe877c9ff211417c01c3e0e117bbb_2_690x341.png)](https://aws1.discourse-cdn.com/techcommunity/original/3X/d/a/da852eceaa4fe877c9ff211417c01c3e0e117bbb.png "image")

## 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](https://www.youtube.com/embed/rEqdyQSsuPY?autoplay=1&feature=oembed&wmode=opaque)

Alternatively you’ll find the full documentation here: [Device Management - Cumulocity IoT Guides](https://cumulocity.com/guides/users-guide/device-management/).  
Another good starting point for an implementation of a new agent could be the [Device management library - Cumulocity IoT Guides](https://cumulocity.com/guides/reference/device-management-library/)

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

- [GitHub - SoftwareAG/cumulocity-devicemanagement-agent: Cumulocity Reference Agent written in Python to demonstrate most of the Device Management Capabilities of Cumulocity IoT](https://github.com/SoftwareAG/cumulocity-devicemanagement-agent)
- [https://thin-edge.io/](https://thin-edge.io/)
- [Remote Connect to your devices](https://tech.forums.softwareag.com/t/remote-connect-to-your-devices/239639)
- [Vendor Requirements for Device Certification](https://github.com/SoftwareAG/cumulocity-self-service-certification/blob/main/docs/vendor-requirements.md)
- [Device Management - Cumulocity IoT Guides](https://cumulocity.com/guides/users-guide/device-management/)
- [Device management library - Cumulocity IoT Guides](https://cumulocity.com/guides/reference/device-management-library/)
- [Cumulocity IoT Device Management - YouTube](https://www.youtube.com/watch?v=rEqdyQSsuPY)

## 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](http://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](https://info.softwareag.com/TechCommunity-Subscription-Page.html) to receive our quarterly updates or read the [latest issue](https://softwareag-usa.s3.amazonaws.com/FTP/public/techniques/2022/techniques_2022-02.html).

[Visit the original post](https://tech.forums.softwareag.com/t/getting-started-with-cumulocity-iot-device-management/256401)