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:
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.
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.
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
- GitHub - SoftwareAG/cumulocity-devicemanagement-agent: Cumulocity Reference Agent written in Python to demonstrate most of the Device Management Capabilities of Cumulocity IoT
- https://thin-edge.io/
- Remote connect to your devices
- Vendor Requirements for Device Certification
- Device management - Cumulocity IoT Guides
- Device management library - Cumulocity IoT Guides
- 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 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.