MQTTT

MQTTT (named for "MQTT Tree") is a MQTT router which uses a the structure of a filesystem hierarchy to subscribe to MQTT topics and dispatch them to executables within this structure.

It is deprecated as there's no particular advantage to having a directory hierarchy as opposed to having a config file with routes mapped to program invocations.

Building

Use cargo build as normal.

The DEFAULT_ROOT environment variable controls the default root path which is normally /var/run/mqttt.

The SYSCONFDIR environment variable controls the location of where mqttt.toml is searched. The default is /usr/local/etc.

Installation and Configuration

Copy the mqttt binary to the path on the target system. The default configuration is equivalent to the following contents of mqttt.toml:

root = "/var/run/mqttt" # Path to MQTTT root
host = "localhost"      # MQTT server host
port = 1883             # MQTT server port
# [credentials]         # Uncomment to specify MQTT connection credentials
# username = "username"
# password = "password"
id = "mqttt"            # MQTT client identifier
}

Usage

Create a directory structure under the root directory which matches the MQTT topic you want to subscribe to. For example:

$ mkdir -p /var/run/mqttt/zigbee2mqtt/light_switch

Populate this directory with executables which you wish to run when a message matching that topic filter is received.

$ cat <<EOF >/var/run/mqttt/zigbee2mqtt/light_switch/toggle_light
#!/usr/bin/env bash
topic=$1
action=$(jq --raw-output .action)
[[ $action == "toggle" ]] || exit 0
mosquitto_pub --topic "zigbee2mqtt/light/set" --message '{"state":"TOGGLE"}'
EOF
$ chmod +x /var/run/mqttt/zigbee2mqtt/light_switch/toggle_light

Start the mqttt program. It cannot be forked to background so it is expected to be ran under a daemontools style supervisor, the daemon utility or with something like systemd.

It's a good idea to run mqttt as its own dedicated user.

The special + and # wildcards can be used as path components. Additonally #empty path component can be used to represent a topic such as foo//bar as the filesystem path foo/#empty/bar.

Known bugs

Executables are run sequentially
No timeout
Can't map to a topic with a single or double dot as a path component
No permission checks on mqttt.toml if it contains a password (to ensure the password isn't being exposed)
No way to specify the subscription QOS for a route (default is 0 (at most once))