Initial commit

1 files changed, 82 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c376268
--- /dev/null
+++ b/README.md
@@ -0,0 +1,82 @@
+<!--
+SPDX-FileCopyrightText: 2025 Tomasz Kramkowski <tomasz@kramkow.ski>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# MQTTR
+
+MQTTR (named for "MQTT Router") is a MQTT router (duh) which lets you subscribe
+to MQTT topics and execute arbitrary programs when a message matching that topic
+arrives.
+
+It is the successor of [MQTTT](https://the-tk.com/cgit/mqttt/about/) which was
+the result of realising that using a filesystem hierarchy to represent the
+configuration did not appear to have any particular benefits over just storing
+the information in the already existing config file.
+
+## Building and Installation
+
+Use `cargo build` as normal.
+
+The `SYSCONFDIR` environment variable controls the location of where `mqttr.toml` is searched. The default is `/usr/local/etc`.
+
+Once built, the `mqttr` program (found in `target/{debug,release}/mqttr`) should
+be located in some sensible place (e.g. `/usr/local/bin/mqttr`) and configured
+as a system service.
+
+`mqttr` does not have a way to double-fork, if you need this behaviour, use
+`daemon` or some equivalent utility.
+
+## Configuration
+
+Create a `mqttr.toml` in the appropriate location. The file should contain at
+minimum a set of routes. The following is the default configuration:
+
+```toml
+host = "localhost"      # MQTT server host
+port = 1883             # MQTT server port
+# [credentials]         # Uncomment to specify MQTT connection credentials
+# username = "username"
+# password = "password"
+id = "mqttr"            # MQTT client identifier
+```
+
+The routes follow the following format:
+
+```toml
+[routes]
+"zigbee2mqtt/+/light" = [
+    ["/path/to/program"],
+    ["/path/to/another/program", "with", "args"],
+]
+"foo/bar/baz" = [ ... ]
+```
+
+On startup, `mqttr` will read the config file and subscribe to all the topics.
+When a message is received, `mqttr` will match the message topic against the
+routes and execute every program which is part of a matching route. Each program
+will have the message topic appended as an additional argument and will receive
+the message on stdin.
+
+An example program is this script:
+
+```bash
+#!/usr/bin/env bash
+topic=$1
+action=$(jq --raw-output .action)
+[[ $action == "toggle" ]] || exit 0
+mosquitto_pub --topic "zigbee2mqtt/light/set" --message '{"state":"TOGGLE"}'
+```
+
+This can be bound to a topic such as `zigbee2mqtt/light` which would result in
+it being ran every time a new MQTT message is published to this topic.
+
+## Missing Features
+
+* Asynchronous program execution
+* Timeouts (existent, configurable, per process configurable)
+* Permission checks on `mqttr.toml` if it contains a password (to ensure the
+  password isn't being exposed)
+* Configurable QoS for each subscription (default is 0 (at most once))
+* Pass message metadata via the environment (QoS, retain, dup)
+* Configurable logging