Cumulocity Device Management (DM) Reference Agent written in Python3 to demonstrate most of the Device Management Capabilities of Cumulocity IoT

To quickly run the agent just make sure that Docker is installed on your computer an run

./start.sh

in a console of your choice. The script will build a docker image and starting one instance afterwards. Per default bootstrapping is used an no other information is necessary. In this case the docker container Id is the device Id which should be entered when registering a device in cumulocity.

If you want to use device certificates or override bootstrapping parameters use the following env variables:

C8YDM_MQTT_URL=<tenant domain> \
C8YDM_SECRET_C8Y__BOOTSTRAP__TENANT=<tenant ID> \
C8YDM_SECRET_C8Y__BOOTSTRAP__USER=<username used for bootstrapping> \
C8YDM_SECRET_C8Y__BOOTSTRAP__PASSWORD=<password used for bootstrapping> \
./start.sh

If you want to use Cloud Remote Access with a VNC server, you can install the server and a desktop environment:

INSTALL_VNC=1 ./start.sh

By default, the docker container runs in background. If you want to run it interactively:

INTERACTIVE=1 ./start.sh

If you don't want to run within docker follow the steps below.

The agent can be configured via the agent.ini which must be placed in

{userFolder}/.cumulocity

When running in docker container the agent.ini can be mounted to the /root/.cumulocity/agent.ini

Below a reference agent.ini is proviced:

[mqtt]
url = mqtt.eu-latest.cumulocity.com
port = 8883
tls = true
cert_auth = false
client_cert = s7y_pi.crt
client_key = s7y_pi.key
cacert = /etc/ssl/certs/ca-certificates.crt
ping.interval.seconds = 60

[agent]
name = dm-example-device
type = c8y_dm_example_device
main.loop.interval.seconds = 10
requiredinterval = 10
loglevel = INFO

The environment variables which with C8YDM_ prefix are mapped to configuration files. Mapping rules:

• Prefix C8YDM__ means what section the option belongs to
• Upper case letters are mapped to lower case letters
• Double underscore __ is mapped to .

The agent can be build in multiple ways.

To build the agent via pip just run

pip install -r requirements.txt

to install dependencies and afterwards

pip install .

to build the agent itself. Please note that in debian/ubuntu you need additionally install

apt install python-apt

via apt.

In order to build the .deb yourself first install python-stdeb via apt.

apt install python-stdeb

Afterwards run

python setup.py --command-packages=stdeb.command bdist_deb

on the level of the setup.py.

In oder to install the debian package locally run

apt install ./deb_dist/python-c8ydm_0.1-1_all.deb 

To build a docker image you can make use of the provided Dockerfile.

Example:

docker build -t dm-image -f docker/Dockerfile .

Before running the agent some manual steps need to be taken

1. Manually put the config file into /root/.cumulocity

You can run the agent by executing

sudo c8ydm.start

in your console when you used Building via pip to build and install the agent.

Before running the agent some manual steps need to be taken

1. Manually put the config file into /root/.cumulocity

You can run the agent by executing

sudo c8ydm.start

in your console when you used Building via deb to build and install the agent.

You can run the agent by executing

docker run -d -v /var/run/docker.sock:/var/run/docker.sock dm-image

in your console when you used Building Docker Image to build and install the agent.

The config can be mounted the container. Otherwise the default config will be used.

The project comes with VS Code devcontainer support. Make sure you use Visual Studio Code in combination with docker. Just open the project in VS Code and click on "Reopen in Dev Container".

In the background the Agent will be build and started. Also a debug/run configuration is provided so you can easilly start/debug the agent within VS Code.

You can generate certificates necessary to certficate authentication, and you can upload the generated root certificate o your tenant's trusted certificate list by executing the scripts like below:

./scripts/generate_cert.sh \
--serial pyagent0001 \
--root-name iot-ca \
--cert-dir /root/.cumulocity/certs \
--cert-name device-cert

./scripts/upload_cert.sh \
--tenant-domain <tenant domain> \
--tenant-id <tenant ID> \
--username <username for the tenant> \
--password <password for the tenant> \
--cert-path /root/.cumulocity/certs/iot-ca.pem \
--cert-name <(arbitrary) displayed name of the root certificate>

After this, you can connect the agent to your tenant using cert authentication (with the serial pyagent0001 in this case).

With the agent running in the container, execute

./test.sh \
--url <tenant domain> \
--tenant <tenant ID> \
--username <username for the tenant> \
--password <password for the tenant>

to run pytest.

The agent knows three types of classes that it will automatically load and include from the "agentmodules" directory.

1. Sensors

    class Sensor:
      __metaclass__ = ABCMeta
   
      def __init__(self, serial):
        self.serial = serial
   
      '''
      Returns a list of SmartREST messages. Will be called every iteration of the main loop.
      '''
      @abstractmethod
      def getSensorMessages(self): pass
   

   Sensors are periodically polled by the main loop and published.

2. Listeners

    class Listener:
      __metaclass__ = ABCMeta
   
      def __init__(self, serial, agent):
        self.serial = serial
        self.agent = agent
   
      '''
      Callback that is executed for any operation received
      '''
      @abstractmethod
      def handleOperation(self, message): pass
   
      '''
      Returns a list of supported operations
      '''
      @abstractmethod
      def getSupportedOperations(self): pass
   
      '''
      Returns a list of supported SmartREST templates (X-Ids)
      '''
      @abstractmethod
      def getSupportedTemplates(self): pass
   

   Listeners are called whenever there is a message received on a subscribed topic.

3. Initializers

    class Initializer:
      __metaclass__ = ABCMeta
   
      def __init__(self, serial):
        self.serial = serial
   
      '''
      Returns a list of SmartREST messages. Will be called at the start of the agent
      '''
      @abstractmethod
      def getMessages(self): pass
   

   Initializers are only called once at the start of the agent.

You can take a look at the two example modules for how it can be used.

The logfile and configuration can be found in the following directory.

/root/.cumulocity

These tools are provided as-is and without warranty or support. They do not constitute part of the Software AG product suite. Users are free to use, fork and modify them, subject to the license agreement. While Software AG welcomes contributions, we cannot guarantee to include every contribution in the master project.

For more information you can Ask a Question in the Tech Community Forums.