Add a readme

1 files changed, 74 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1377bab
--- /dev/null
+++ b/README.md
@@ -0,0 +1,74 @@
+# 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`:
+
+```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:
+
+```shell
+$ 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.
+
+```shell
+$ 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.
+
+## 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))