From 3f0c85c41b35e88d143d667a67f6dbc6288c7cd9 Mon Sep 17 00:00:00 2001
From: David Gwilliam <dhgwilliam@gmail.com>
Date: Wed, 1 Jul 2026 01:35:04 -0700
Subject: [PATCH] zigbee2mqtt: add per-device pairing notes (3RSB22BZ button
 modes)

Document the ThirdReality Smart Button (3RSB22BZ) pairing mode quirk
that bit us today: the button has Standard ZigBee (blue only) and
Echo ZigBee (blue + red) modes, and only the former works with
zigbee2mqtt. Switching requires 5 quick presses of the back reset
button (firmware >= 1.00.22), NOT holding the front button.

Also document the Smart Plug Zigbee PROD pairing procedure and the
BLE->ZigBee mode switch.
---
 infra/zigbee2mqtt/DEVICES.md | 42 ++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)
 create mode 100644 infra/zigbee2mqtt/DEVICES.md

diff --git a/infra/zigbee2mqtt/DEVICES.md b/infra/zigbee2mqtt/DEVICES.md
new file mode 100644
index 0000000..4aefd49
--- /dev/null
+++ b/infra/zigbee2mqtt/DEVICES.md
@@ -0,0 +1,42 @@
+# Zigbee device notes
+
+Per-device quirks discovered during setup. Keep this file in sync as we
+encounter new devices.
+
+## ThirdReality Smart Button (3RSB22BZ) — Door Button
+
+**Has two pairing modes** — the button will only work with zigbee2mqtt
+in **Standard ZigBee mode**.
+
+| Mode | LED indicator | zigbee2mqtt compatible? |
+|---|---|---|
+| Standard ZigBee | blinks **blue only** | yes |
+| Echo ZigBee | blinks **blue + red alternating** | no |
+
+Switching modes depends on firmware version:
+
+- **Firmware ≥ 1.00.22** (most common): press the **back reset button**
+  (pinhole) **5 times within 5 seconds**.
+- **Firmware < 1.00.22**: hold the **front button + back reset button**
+  simultaneously for 5 seconds.
+
+The front button does NOT trigger a reset — only the back pinhole does.
+Holding the front button for any length of time only emits Zigbee
+`action` events (`single`, `hold`, `release`).
+
+If the button joins but zigbee2mqtt can't interview it correctly,
+check the LED — it's almost certainly in Echo mode.
+
+## ThirdReality Smart Plug Zigbee PROD (3RSP02028BZ / similar)
+
+Factory reset / pairing mode: **press and hold the side button for
+>10 seconds** until the LED flashes (red = ZigBee mode, green = BLE mode).
+
+Most plugs ship in **BLE mode** out of the box. To switch to ZigBee:
+hold button + insert into outlet + hold 10s + release + press button
+**twice immediately**. LED should flash **red** (ZigBee).
+
+To re-join an existing ZigBee network (e.g. after the dongle was
+swapped), **power-cycle** is usually sufficient — no reset needed. The
+plug retains the network_key and rejoins automatically when permit_join
+is open on the coordinator.