<!--
SPDX-FileCopyrightText: 2025 Tomasz Kramkowski <tomasz@kramkow.ski>
SPDX-License-Identifier: CC-BY-SA-4.0
-->

# 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.

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