mqtt2cmd

Python based project to translate mqtt events into shell commands

Goals

• Use a yaml file to keep all the config and handlers
• Take values from optional payload (json) and make them available to commands
• Use simple variables to allow reuse of commands
• Enforce timeouts on commands
• Allow multiple shell commands per handlers
• Run commands of a job in parallel or serially
• Add the ability for a job handler to invoke other handlers

Background

Based on multiple MQTT topic subscriptions, I needed the ability to run one or many shell commands, depending on the payload of the event. At first I considered using something like Node-RED, but then I realized that it was way too fancy. The end result is this project, which allows us to start mqtt2cmd manually or as a service. That makes it portable enough to be ran on anything that provides python; such as a Raspberry Pi. All easily done by changing a single yaml file. An example of how this can be useful would be:

• React to a specific button push from trelliswifi and turn on the sprinklers via a curl command;
• Aslo, as part of turning on the sprinklers on the same handler, make the RGB under the button in the trelliswifi turn green;
• React to an mqtt event generated when there is motion in my garage by displaying a message in my office display via rest;
• React when the lights in the basement are on and have an indicator of that on my bedclock;
• Map an mqtt event into with one or multiple mqtt/rest/bash actions.

Installation

Manually

• Clone this repo
• Make sure to have python3 and python3-venv installed
• Run script create-env.sh to create an environment with all the dependencies
• Start environment you just created
• Create/change a config yaml (see examples here) file to indicate:
  • the MQTT broker to be used
  • topics to be subscribed to
  • handlers to indicate what to do when events on the topics take place
• Invoke start_mqtt2cmd.sh

In other words:

$ git clone https://github.com/flavio-fernandes/mqtt2cmd.git && \
  cd mqtt2cmd && ./mqtt2cmd/bin/create-env.sh && \
  source ./env/bin/activate
$ vi ./data/config.yaml
$ ./mqtt2cmd/bin/start_mqtt2cmd.sh ${PWD}/data/config.yaml

If you are interested in starting mqtt2cmd as a systemd service, copy the service file to /lib/systemd/system/

$ sudo cp -v ./mqtt2cmd/bin/mqtt2cmd.service /lib/systemd/system/

$ # Make sure it is proper
$ sudo vi /lib/systemd/system/mqtt2cmd.service

$ sudo systemctl enable mqtt2cmd.service
$ sudo systemctl start mqtt2cmd.service

Follow the service logs through the systemd journal:

$ ./mqtt2cmd/bin/tail_log.sh

$ # Equivalent command:
$ sudo journalctl \
    --unit=mqtt2cmd.service \
    --lines=100 \
    --follow \
    --output=short-iso

The journal-based command works on current Debian and Raspberry Pi OS releases that do not create /var/log/syslog by default. Set MQTT2CMD_LOG_LINES to change the initial number of records displayed, for example:

$ MQTT2CMD_LOG_LINES=250 ./mqtt2cmd/bin/tail_log.sh

Installation via Vagrant

In order to easily have a VM running this project, take a look at the Vagrantfile. Once you have Vagrant installed, these steps will get you going:

git clone https://github.com/flavio-fernandes/mqtt2cmd.git && \
cd mqtt2cmd && vagrant up && vagrant ssh

# To see what mqtt2cmd is up to:
sudo systemctl status mqtt2cmd
sudo systemctl cat mqtt2cmd
~/tail_log.sh

Usage

Start an MQTT client to see events generated by mqtt2cmd jobs:

# Change this to use your MQTT broker. If you use Vagrantfile
# mentioned above, there will be a local broker installed and
# started with the ip address shown below
$ MQTT_BROKER='192.168.123.123'

# Start a subscriber to see notifications of executed commands.
# By default these will be on /mqtt2cmd/status, but you can change
# it to be whatever you like.
$ mosquitto_sub -h ${MQTT_BROKER} \
  -F '@Y-@m-@dT@H:@M:@S@z : %q : %t : %p' \
  -t /mqtt2cmd/status -t /mqtt2cmd/ping

From another shell session

Try publishing into these topic to see mqtt2cmd in action. These topics are used in the config example located in config.yaml.vagrant:

$ mosquitto_pub -h ${MQTT_BROKER} -t /foo/bar -m hello
$ mosquitto_pub -h ${MQTT_BROKER} -t /foo/foo -n

By looking at the test script file, together with the config yaml files you should be able to get a good idea on how to use this project to do whatever you are interested in. Otherwise, please reach out, submit PRs or help out by improving this doc!