Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/flavio-fernandes/mqtt2cmd

Command dispatcher based on mqtt topic/payloads
https://github.com/flavio-fernandes/mqtt2cmd

Last synced: 4 days ago
JSON representation

Command dispatcher based on mqtt topic/payloads

Awesome Lists containing this project

README 

        
# 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](https://nodered.org/), 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](https://github.com/flavio-fernandes/trelliswifi)

and turn on the [sprinklers](https://opensprinkler.com/product/opensprinkler-pi/)

via a [curl](https://www.codepedia.org/ama/how-to-test-a-rest-api-from-command-line-with-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](http://flaviof.com/blog/hacks/office-clock-part2.html)

via rest;

- React when the lights in the basement are on and have an indicator of that

on my [bedclock](http://www.flaviof.com/blog2/post/hacks/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](https://github.com/flavio-fernandes/mqtt2cmd/blob/main/mqtt2cmd/bin/create-env.sh)

to create an environment with all the

[dependencies](https://github.com/flavio-fernandes/mqtt2cmd/blob/main/requirements.txt)

- Start environment you just created

- Create/change a config yaml (see examples [here](https://github.com/flavio-fernandes/mqtt2cmd/tree/main/data)) 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:

```bash

$ 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/`



```bash

$ 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](https://github.com/flavio-fernandes/mqtt2cmd/blob/main/Vagrantfile).

Once you have [Vagrant](https://www.vagrantup.com/) installed, these steps will get you going:



```bash

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:



```bash

# 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](https://github.com/flavio-fernandes/mqtt2cmd/tree/main/data/config.yaml.vagrant):

```bash

$ 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](https://github.com/flavio-fernandes/mqtt2cmd/blob/main/mqtt2cmd/tests/basic_test.sh.vagrant),

together with the

[config yaml files](https://github.com/flavio-fernandes/mqtt2cmd/tree/main/data)

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](https://flaviof.com),

submit PRs or help out by improving this doc!