MQTT stands for MQ Telemetry Transport. It is a publish/subscribe, extremely simple and lightweight messaging protocol, designed for constrained devices and low-bandwidth, high-latency or unreliable networks. The design principles are to minimize network bandwidth and device resource requirements whilst also attempting to ensure reliability and some degree of assurance of delivery. These principles also turn out to make the protocol ideal of the emerging “machine-to-machine” (M2M) or “Internet of Things” world of connected devices, and for mobile applications where bandwidth and battery power are at a premium.
Nowadays, there are many devices and IoT platforms using this protocol, like those developed by Libelium and Siemens, among others. Conscious of this situation, we are proud to announce the release of an adapter to interconnect those solutions with CitiSim.
Our new MQTT-to-CitiSim adapter is an application that connects to a provided MQTT server address, it subscribes to a list of topics and forwards received MQTT events to the CitiSim event distribution service. It parses received messages, extracting the data needed to publish new events to CitiSim making use of the libcitisim library.
To follow this recipe, apart from a working ZeroC ICE installation, you will need the libcitisim package, which can be installed from our Debian repository.
In Debian-based systems, this can be achieved by running
sudo apt-get install python3-zeroc-ice property-service-simple libcitisim
Paho-mqtt is also needed for the adapter to run, this can be installed with pip3:
sudo pip3 install paho- mqtt
Once installed, the repository must be cloned:
git clone git@bitbucket.org:arco_group/citisim-mqtt- adapter.git
Once the repository is cloned, in this directory you can find three main files:
- mqttAdapter.py: Service executable file.
- citisim.config: Contains the libcitisim broker configuration.
- mqtt.config: Contains the MQTT broker configuration and correspondences with CitiSim.
The following is a minimal example for citisim.config
Where Ice.Default.Locator is the endpoint of the CitiSim locator and TopicManagerProxy is the proxy for the Topic Manager that will be used by the libcitisim broker.
A small example for the mqtt.config file can be found below:
Where:
- client is the name of the client that will be used to connect to the MQTT broker.
- broker_addr is the address of the MQTT broker.
- topic_list is a list of MQTT topics that will be subscribed.
- sensor_ids is a correspondence between MQTT topics and the unique 16-byte identifier used in CitiSim. Check the ID specification (/specs/id_specification/) to learn how to set IDs for your devices. icestorm_topics is a correspondence between the “sensor” field in the MQTT messages and CitiSim defined topics. Check the topics specification (/specs/topics_specification/) to learn how to set your topics.
If a sensor ID is not defined in mqtt.config, events will still be published, but with source = “MISSING_ID:” instead of the 16-byte sensor ID.
Also, if a sensor is not defined in the icestorm_topics field in mqtt.config, events will still be published, but since the corresponding icestorm topic is not known, they will be published to a topic called “Unconfigured”.
Executing the service is really simple: once citisim.config and mqtt.config are properly configured, all that is needed to do is running mqttAdapter.py with both configuration files as arguments:
python3 mqttAdapter.py citisim.config mqtt.config
This will connect the service to the configured MQTT broker and wait for events to arrive, locking the console. For each message received, it will publish the corresponding event to CitiSim.
The source code of the MQTT adapter can be downloaded from here.
Author: Carlos Jimenez
Company: Abalia