docs: add README

1 files changed, 49 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e933f1a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,49 @@
+# mmx150d
+
+Connection monitoring for the beyerdynamic MMX 150 wireless headset dongle.
+
+The daemon watches the headset link state over the dongle's vendor HID
+interface and runs shell commands when the headset connects or disconnects.
+Typical use: switch the default audio sink between the headset and monitor
+speakers as the headset powers on and off.
+
+## Usage
+
+    mmx150 status
+
+Prints `connected` or `disconnected`. Exit codes: 0 connected, 1
+disconnected, 2 dongle missing or error.
+
+    mmx150 daemon [--on-connect CMD] [--on-disconnect CMD] [--interval SECS] [--no-initial]
+
+Hooks run via `sh -c` with output discarded. At startup the daemon fires the
+hook matching the current state, unless `--no-initial` is given.
+
+Example, switching the default sink with PipeWire:
+
+    mmx150 daemon \
+      --on-connect 'wpctl set-default <mmx150-sink-id>' \
+      --on-disconnect 'wpctl set-default <speakers-sink-id>'
+
+Find sink ids with `wpctl status`.
+
+## How it works
+
+The dongle exposes a vendor HID interface (`2e50:0035`). Writing the 61-byte
+output report `0x3a` (payload prefix `09 22 01`) makes the dongle answer with
+an input report `0x3c`, but only when the headset is linked. A query with no
+response within 400 ms therefore means the headset is off or out of range.
+
+The daemon polls this once per interval (default 2 s). A disconnect needs two
+consecutive missed polls, so a single dropped radio packet does not cause a
+bogus state change.
+
+## Building
+
+Development uses devenv:
+
+    devenv shell cargo build
+    devenv shell cargo test
+
+The binaries land at `target/debug/mmx150` (status and daemon) and
+`target/debug/mmx150-probe` (protocol reverse-engineering tool).