Intro
If you haven’t heard of it: thin-edge.io makes connectivity to Cumulocity IoT a matter of configuration. Developing your own device agent becomes just so much nicer if you don’t have to take care of basic aspects over and over again. With thin-edge.io’s out-of-the-box plugins you get a lot of functionality for Cumulocity IoT for free. And if you have to write some code (and chances are you have to for your devices) you are free to pick any language you like. In fact, one of the strengths of thin-edge.io is how easy you can hook into its environment and extend it with custom code.
For a customer project, we were looking at integrating a bunch of Modbus devices to Cumulocity IoT. Note that there are some alternatives for that: you can for example choose the Linux Agent with its Modbus plugin or just install collectd and configure it – but while these options do work, they are not flexible enough and too limiting. For that reason, we choose thin-edge.io as our base platform and decided to write a small mapper plugin on our own.
And here it is: the first public version of our small Modbus plugin available on the thin-edge.io github [0]
Get it and Installation
The official releases are available via GitHub release tags. Just pick the latest version [1] and download the *.deb file.
The Debian package can be installed on all architectures by simply copying the package to your device and doing a
sudo dpkg -i te-modbus-plugin_<version>_all.deb
The package does assume thin-edge.io as dependency 
In case you need something else than a Debian package (or you want to extend the plugin code) you can also build the plugin on your own. Just follow the readme [2] to package the python module to whatever you need.
Using it
There are two configuration files you need to edit for your use case. Any changes to the files will restart the polling of your Modbus servers automatically, so you don’t have to worry about restarting any services. You can find them after the installation under /etc/tedge/plugins/modbus/
modbus.toml
This includes the basic configuration for the plugin such as poll rate and the connection to thin-edge (the MQTT broker needs to match the one of tedge and is probably the default localhost:1883).
devices.toml
This file includes the information for the connection(s) to the Modbus server(s) and how the Modbus Registers and Coils map to thin-edge’s Measurements, Events and Alarms.
The plugin config aims to be compliant to Cumulocity’s Cloud Fieldbus protocol [3]. If you had a chance to use that, you probably feel familiar with the devices.toml. The plugin comes with an example config [4] with comments to get you started. Adding multiple servers should also be as simple as adding additional [[device]] sections for each IP address you want to poll.
Other integration
As said, one of the reason we picked thin-edge.io is the fact that it comes with a bunch of stuff out of the box. So this adds nicely to the plugin:
Software Management
You can use the Software Repository of Cumulocity IoT and thin-edge.io Software Management plugin to install the deb remotely:
Upload the deb package to the Cumulocity IoT Software Repository. The name must be te-modbus-plugin and the version must match the version in the deb package name plus ::apt (e.g. 0.4.0::apt). The rest of the fields can be set as necessary. Go to the Software tab of the target device and select the package for installation. After the operation is successful the plugin will start automatically on the device.
Log file access
For integration with the C8Y log plugin add the following line to the /etc/tedge/c8y/c8y-log-plugin.toml. You might have to restart the c8y-log-plugin service after that.
{ type = "modbus", path = "/var/log/te-modbus-plugin/modbus.log" }
After that the agent logs will appear in the Cumulocity UI:
Configuration management
Editing config files on a device is not comfortable (and sometimes not possible). But luckily thin-edge.io comes with a plugin for remote config.
Add the following lines to the c8y-configuration-plugin.toml to be able to access them from the Cumulocity Configuration UI:
{path = '/etc/tedge/plugins/modbus/modbus.toml', type='modbus'},
{path = '/etc/tedge/plugins/modbus/devices.toml', type='modbus-devices'}
With this you can see the Configuration files on your device. Even better, you can also use Cumulocity‘s configuration repository to store configs and upload them to your device.
To replace the files with a version from the C8Y Configuration Repository you have to download a copy, edit it and upload it to the repository. The device type must be set to thin-edge.io and the config type must match the definition in your c8y-configuration-plugin.toml. I.e either modbus (for modbus.toml) or modbus-devices for (devices.toml)
Afterwards these configs should appear in the Configuration section of your thin-edge device and be uploaded to the agent.
TODO
This plugin has been part of a PoC and for sure needs some more production usage to become really stable. Usage is therefore on your own risk but please give it a chance and let us know what is missing. There are some know limitations rights now:
-
The plugin focuses on reading values, so writing back to your registers and coils is not available (yet).
-
Right now configuration is based on the *.toml files. We might later add support for Cumulocitys Cloud Fieldbus protocol to make it even more easy to change configurations.
Summary
Check out our new Modbus plugin for thin-edge.io in case you are looking for connectivity with a Modbus device! And in case you are looking for using thin-edge.io it might also help in building your own mapper.
Please feel also free to provide feedback and improvements suggestions in the issue tracker [5]
Thanks go out to Rina Fujino and Reuben Miller from the thin-edge.io team and Jan Humble, Murat Bayram from SAG for supporting this.
[0] GitHub - thin-edge/modbus-plugin: Community developed modbus plugin for thin-edge.io
[1] Releases · thin-edge/modbus-plugin · GitHub
[2] GitHub - thin-edge/modbus-plugin: Community developed modbus plugin for thin-edge.io
[3] Cloud Fieldbus - Cumulocity IoT Guides
[4] modbus-plugin/devices.toml at main · thin-edge/modbus-plugin · GitHub
[5] Issues · thin-edge/modbus-plugin · GitHub