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-pip 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

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 is mqtt2cmd is up to:
sudo systemctl status mqtt2cmd
sudo systemctl cat mqtt2cmd
/home/vagrant/tail_log.sh

# On systems like RPI, you can also:
sudo tail -F /var/log/syslog | grep mqtt2cmd

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!