mqtt2matter 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +76 -0
- package/LICENSE +202 -0
- package/NOTICE +23 -0
- package/README.md +172 -2
- package/dist/app.d.ts +34 -0
- package/dist/app.js +157 -0
- package/dist/app.js.map +1 -0
- package/dist/commands/import-z2m.d.ts +20 -0
- package/dist/commands/import-z2m.js +173 -0
- package/dist/commands/import-z2m.js.map +1 -0
- package/dist/commands/install.d.ts +41 -0
- package/dist/commands/install.js +250 -0
- package/dist/commands/install.js.map +1 -0
- package/dist/commands/update.d.ts +14 -0
- package/dist/commands/update.js +109 -0
- package/dist/commands/update.js.map +1 -0
- package/dist/config/index.d.ts +2 -0
- package/dist/config/index.js +3 -0
- package/dist/config/index.js.map +1 -0
- package/dist/config/load.d.ts +57 -0
- package/dist/config/load.js +137 -0
- package/dist/config/load.js.map +1 -0
- package/dist/config/schema.d.ts +496 -0
- package/dist/config/schema.js +115 -0
- package/dist/config/schema.js.map +1 -0
- package/dist/engine/payload.d.ts +94 -0
- package/dist/engine/payload.js +515 -0
- package/dist/engine/payload.js.map +1 -0
- package/dist/engine/runtime.d.ts +79 -0
- package/dist/engine/runtime.js +438 -0
- package/dist/engine/runtime.js.map +1 -0
- package/dist/engine/template.d.ts +20 -0
- package/dist/engine/template.js +264 -0
- package/dist/engine/template.js.map +1 -0
- package/dist/engine/units.d.ts +9 -0
- package/dist/engine/units.js +42 -0
- package/dist/engine/units.js.map +1 -0
- package/dist/families/climate.d.ts +11 -0
- package/dist/families/climate.js +68 -0
- package/dist/families/climate.js.map +1 -0
- package/dist/families/color.d.ts +30 -0
- package/dist/families/color.js +152 -0
- package/dist/families/color.js.map +1 -0
- package/dist/families/cover.d.ts +17 -0
- package/dist/families/cover.js +308 -0
- package/dist/families/cover.js.map +1 -0
- package/dist/families/fan.d.ts +16 -0
- package/dist/families/fan.js +154 -0
- package/dist/families/fan.js.map +1 -0
- package/dist/families/index.d.ts +32 -0
- package/dist/families/index.js +162 -0
- package/dist/families/index.js.map +1 -0
- package/dist/families/light.d.ts +36 -0
- package/dist/families/light.js +258 -0
- package/dist/families/light.js.map +1 -0
- package/dist/families/lock.d.ts +10 -0
- package/dist/families/lock.js +31 -0
- package/dist/families/lock.js.map +1 -0
- package/dist/families/on-off.d.ts +7 -0
- package/dist/families/on-off.js +56 -0
- package/dist/families/on-off.js.map +1 -0
- package/dist/families/power-source.d.ts +12 -0
- package/dist/families/power-source.js +60 -0
- package/dist/families/power-source.js.map +1 -0
- package/dist/families/registry.d.ts +40 -0
- package/dist/families/registry.js +72 -0
- package/dist/families/registry.js.map +1 -0
- package/dist/families/rvc.d.ts +40 -0
- package/dist/families/rvc.js +83 -0
- package/dist/families/rvc.js.map +1 -0
- package/dist/families/switch.d.ts +19 -0
- package/dist/families/switch.js +94 -0
- package/dist/families/switch.js.map +1 -0
- package/dist/importers/actions.d.ts +19 -0
- package/dist/importers/actions.js +98 -0
- package/dist/importers/actions.js.map +1 -0
- package/dist/importers/ha/areas.d.ts +6 -0
- package/dist/importers/ha/areas.js +279 -0
- package/dist/importers/ha/areas.js.map +1 -0
- package/dist/importers/ha/generate.d.ts +51 -0
- package/dist/importers/ha/generate.js +1376 -0
- package/dist/importers/ha/generate.js.map +1 -0
- package/dist/importers/ha/index.d.ts +6 -0
- package/dist/importers/ha/index.js +7 -0
- package/dist/importers/ha/index.js.map +1 -0
- package/dist/importers/ha/source.d.ts +36 -0
- package/dist/importers/ha/source.js +95 -0
- package/dist/importers/ha/source.js.map +1 -0
- package/dist/importers/ha/sync.d.ts +29 -0
- package/dist/importers/ha/sync.js +132 -0
- package/dist/importers/ha/sync.js.map +1 -0
- package/dist/importers/ha/templates.d.ts +18 -0
- package/dist/importers/ha/templates.js +285 -0
- package/dist/importers/ha/templates.js.map +1 -0
- package/dist/importers/ha/types.d.ts +78 -0
- package/dist/importers/ha/types.js +479 -0
- package/dist/importers/ha/types.js.map +1 -0
- package/dist/importers/index.d.ts +5 -0
- package/dist/importers/index.js +8 -0
- package/dist/importers/index.js.map +1 -0
- package/dist/importers/patch.d.ts +50 -0
- package/dist/importers/patch.js +224 -0
- package/dist/importers/patch.js.map +1 -0
- package/dist/importers/sync.d.ts +112 -0
- package/dist/importers/sync.js +220 -0
- package/dist/importers/sync.js.map +1 -0
- package/dist/importers/twins.d.ts +10 -0
- package/dist/importers/twins.js +34 -0
- package/dist/importers/twins.js.map +1 -0
- package/dist/importers/z2m/generate.d.ts +81 -0
- package/dist/importers/z2m/generate.js +1171 -0
- package/dist/importers/z2m/generate.js.map +1 -0
- package/dist/importers/z2m/index.d.ts +5 -0
- package/dist/importers/z2m/index.js +6 -0
- package/dist/importers/z2m/index.js.map +1 -0
- package/dist/importers/z2m/source.d.ts +18 -0
- package/dist/importers/z2m/source.js +46 -0
- package/dist/importers/z2m/source.js.map +1 -0
- package/dist/importers/z2m/sync.d.ts +29 -0
- package/dist/importers/z2m/sync.js +92 -0
- package/dist/importers/z2m/sync.js.map +1 -0
- package/dist/importers/z2m/types.d.ts +72 -0
- package/dist/importers/z2m/types.js +46 -0
- package/dist/importers/z2m/types.js.map +1 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.js +7 -0
- package/dist/index.js.map +1 -0
- package/dist/log.d.ts +17 -0
- package/dist/log.js +54 -0
- package/dist/log.js.map +1 -0
- package/dist/main.d.ts +2 -0
- package/dist/main.js +202 -0
- package/dist/main.js.map +1 -0
- package/dist/matter/bridge.d.ts +113 -0
- package/dist/matter/bridge.js +467 -0
- package/dist/matter/bridge.js.map +1 -0
- package/dist/matter/check.d.ts +11 -0
- package/dist/matter/check.js +116 -0
- package/dist/matter/check.js.map +1 -0
- package/dist/matter/cluster-defaults.d.ts +6 -0
- package/dist/matter/cluster-defaults.js +63 -0
- package/dist/matter/cluster-defaults.js.map +1 -0
- package/dist/matter/commissioning.d.ts +21 -0
- package/dist/matter/commissioning.js +88 -0
- package/dist/matter/commissioning.js.map +1 -0
- package/dist/matter/device-types.d.ts +44 -0
- package/dist/matter/device-types.js +230 -0
- package/dist/matter/device-types.js.map +1 -0
- package/dist/matter/ids.d.ts +31 -0
- package/dist/matter/ids.js +83 -0
- package/dist/matter/ids.js.map +1 -0
- package/dist/matter/index.d.ts +7 -0
- package/dist/matter/index.js +8 -0
- package/dist/matter/index.js.map +1 -0
- package/dist/matter/node-manager.d.ts +39 -0
- package/dist/matter/node-manager.js +161 -0
- package/dist/matter/node-manager.js.map +1 -0
- package/dist/matter/shards.d.ts +26 -0
- package/dist/matter/shards.js +93 -0
- package/dist/matter/shards.js.map +1 -0
- package/dist/model/attribute.d.ts +18 -0
- package/dist/model/attribute.js +28 -0
- package/dist/model/attribute.js.map +1 -0
- package/dist/model/catalog.d.ts +79 -0
- package/dist/model/catalog.js +223 -0
- package/dist/model/catalog.js.map +1 -0
- package/dist/model/index.d.ts +7 -0
- package/dist/model/index.js +8 -0
- package/dist/model/index.js.map +1 -0
- package/dist/model/migrate.d.ts +4 -0
- package/dist/model/migrate.js +39 -0
- package/dist/model/migrate.js.map +1 -0
- package/dist/model/options.d.ts +102 -0
- package/dist/model/options.js +88 -0
- package/dist/model/options.js.map +1 -0
- package/dist/model/presets.d.ts +37 -0
- package/dist/model/presets.js +105 -0
- package/dist/model/presets.js.map +1 -0
- package/dist/model/schema.d.ts +1747 -0
- package/dist/model/schema.js +243 -0
- package/dist/model/schema.js.map +1 -0
- package/dist/model/validate.d.ts +21 -0
- package/dist/model/validate.js +484 -0
- package/dist/model/validate.js.map +1 -0
- package/dist/mqtt/client.d.ts +38 -0
- package/dist/mqtt/client.js +94 -0
- package/dist/mqtt/client.js.map +1 -0
- package/dist/mqtt/index.d.ts +2 -0
- package/dist/mqtt/index.js +3 -0
- package/dist/mqtt/index.js.map +1 -0
- package/dist/mqtt/topic-cache.d.ts +20 -0
- package/dist/mqtt/topic-cache.js +58 -0
- package/dist/mqtt/topic-cache.js.map +1 -0
- package/dist/server/auth.d.ts +59 -0
- package/dist/server/auth.js +185 -0
- package/dist/server/auth.js.map +1 -0
- package/dist/server/catalog.d.ts +52 -0
- package/dist/server/catalog.js +96 -0
- package/dist/server/catalog.js.map +1 -0
- package/dist/server/compact.d.ts +3 -0
- package/dist/server/compact.js +105 -0
- package/dist/server/compact.js.map +1 -0
- package/dist/server/config-store.d.ts +36 -0
- package/dist/server/config-store.js +155 -0
- package/dist/server/config-store.js.map +1 -0
- package/dist/server/events.d.ts +50 -0
- package/dist/server/events.js +71 -0
- package/dist/server/events.js.map +1 -0
- package/dist/server/http.d.ts +27 -0
- package/dist/server/http.js +168 -0
- package/dist/server/http.js.map +1 -0
- package/dist/server/importers.d.ts +40 -0
- package/dist/server/importers.js +75 -0
- package/dist/server/importers.js.map +1 -0
- package/dist/server/index.d.ts +6 -0
- package/dist/server/index.js +8 -0
- package/dist/server/index.js.map +1 -0
- package/dist/server/log-buffer.d.ts +22 -0
- package/dist/server/log-buffer.js +55 -0
- package/dist/server/log-buffer.js.map +1 -0
- package/dist/server/presets.d.ts +17 -0
- package/dist/server/presets.js +55 -0
- package/dist/server/presets.js.map +1 -0
- package/dist/server/preview.d.ts +19 -0
- package/dist/server/preview.js +121 -0
- package/dist/server/preview.js.map +1 -0
- package/dist/server/server.d.ts +107 -0
- package/dist/server/server.js +810 -0
- package/dist/server/server.js.map +1 -0
- package/dist/server/update.d.ts +60 -0
- package/dist/server/update.js +191 -0
- package/dist/server/update.js.map +1 -0
- package/docs/api.md +128 -0
- package/docs/architecture.md +121 -0
- package/docs/config.md +538 -0
- package/docs/importers.md +241 -0
- package/example/mqtt2matter.json +276 -0
- package/package.json +90 -4
- package/presets/mqtt-smarthome/button.json +47 -0
- package/presets/mqtt-smarthome/contact.json +37 -0
- package/presets/mqtt-smarthome/cover.json +50 -0
- package/presets/mqtt-smarthome/dimmer.json +57 -0
- package/presets/mqtt-smarthome/humidity.json +38 -0
- package/presets/mqtt-smarthome/light.json +47 -0
- package/presets/mqtt-smarthome/occupancy.json +46 -0
- package/presets/mqtt-smarthome/switch.json +47 -0
- package/presets/mqtt-smarthome/temperature.json +38 -0
- package/presets/openbeken/color-light.json +64 -0
- package/presets/openbeken/ct-light.json +51 -0
- package/presets/openbeken/dimmer.json +47 -0
- package/presets/openbeken/humidity.json +37 -0
- package/presets/openbeken/relay.json +40 -0
- package/presets/openbeken/temperature.json +41 -0
- package/presets/shelly-gen1/dimmer.json +48 -0
- package/presets/shelly-gen1/door-window.json +43 -0
- package/presets/shelly-gen1/ht.json +43 -0
- package/presets/shelly-gen1/relay-pm.json +60 -0
- package/presets/shelly-gen1/relay.json +36 -0
- package/presets/shelly-gen1/roller.json +52 -0
- package/presets/shelly-gen2/cover.json +68 -0
- package/presets/shelly-gen2/dimmer.json +61 -0
- package/presets/shelly-gen2/ht.json +47 -0
- package/presets/shelly-gen2/i4.json +82 -0
- package/presets/shelly-gen2/switch-pm.json +101 -0
- package/presets/shelly-gen2/switch.json +47 -0
- package/presets/tasmota/climate.json +52 -0
- package/presets/tasmota/color-light.json +63 -0
- package/presets/tasmota/ct-light.json +50 -0
- package/presets/tasmota/dimmer.json +45 -0
- package/presets/tasmota/relay.json +39 -0
- package/presets/tasmota/shutter.json +46 -0
- package/presets/tasmota/temperature-humidity.json +42 -0
- package/presets/tasmota/temperature.json +32 -0
- package/presets/valetudo/vacuum.json +103 -0
- package/presets/wled/dimmer.json +46 -0
- package/presets/wled/light.json +59 -0
- package/ui/dist/assets/index-BDtT6bdH.js +10 -0
- package/ui/dist/assets/index-CHiG-aoU.css +1 -0
- package/ui/dist/index.html +18 -0
package/docs/config.md
ADDED
|
@@ -0,0 +1,538 @@
|
|
|
1
|
+
# Configuration
|
|
2
|
+
|
|
3
|
+
A JSON file — `mqtt2matter [config.json]`, else `$MQTT2MATTER_CONFIG`, else `./mqtt2matter.json` — with
|
|
4
|
+
the environment on top. Every object is strict: an unknown key is an error. Every field has a default; an
|
|
5
|
+
empty file (or none) starts a bridge on port 5540 with no devices. `example/mqtt2matter.json` is a complete
|
|
6
|
+
example; `mqtt2matter --check [config.json]` validates a file against the Matter data model and matter.js
|
|
7
|
+
in strict mode without touching the network.
|
|
8
|
+
|
|
9
|
+
**This schema is frozen** (format 1): importers write it, the UI edits it, and a later version that has to
|
|
10
|
+
change it migrates files on load. Additions are allowed; renames and removals are not. The one rename so far,
|
|
11
|
+
before the first release: an endpoint's `bindings` are `mappings` (Matter's own Binding cluster means
|
|
12
|
+
something else); a file with `bindings` is read as `mappings`, a warning is logged once at start, and the file is
|
|
13
|
+
written in the new form at the next save from the UI (`POST /api/import` takes the old form too).
|
|
14
|
+
|
|
15
|
+
## Environment
|
|
16
|
+
|
|
17
|
+
| Variable | Overrides |
|
|
18
|
+
| ----------------------------------- | ----------------------------------------------------------------------------- |
|
|
19
|
+
| `MQTT2MATTER_CONFIG` | the file path |
|
|
20
|
+
| `MQTT2MATTER_MQTT_URL` | `mqtt.url` |
|
|
21
|
+
| `MQTT2MATTER_MQTT_USERNAME` | `mqtt.username` |
|
|
22
|
+
| `MQTT2MATTER_MQTT_PASSWORD` | `mqtt.password` |
|
|
23
|
+
| `MQTT2MATTER_MQTT_CLIENT_ID` | `mqtt.clientId` |
|
|
24
|
+
| `MQTT2MATTER_STORAGE` | `storage` |
|
|
25
|
+
| `MQTT2MATTER_LOG_LEVEL` | `log.level` |
|
|
26
|
+
| `MQTT2MATTER_MATTER_LOG_LEVEL` | `log.matter` |
|
|
27
|
+
| `MQTT2MATTER_SERVER_HOST` | `server.host` |
|
|
28
|
+
| `MQTT2MATTER_SERVER_PORT` | `server.port` |
|
|
29
|
+
| `MQTT2MATTER_AUTH` | `server.auth.mode` |
|
|
30
|
+
| `MQTT2MATTER_AUTH_PASSWORD` | `server.auth.password` (a hash, or the plain password: it is hashed at start) |
|
|
31
|
+
| `MQTT2MATTER_AUTH_PROXY_HEADER` | `server.auth.proxyHeader` |
|
|
32
|
+
| `MQTT2MATTER_AUTH_PROXY_LOGOUT_URL` | `server.auth.proxyLogoutUrl` |
|
|
33
|
+
|
|
34
|
+
## Top level
|
|
35
|
+
|
|
36
|
+
| Key | Default | Meaning |
|
|
37
|
+
| ------------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------- |
|
|
38
|
+
| `mqtt.url` | `mqtt://localhost:1883` | `mqtt://`, `mqtts://`, `ws://`, `wss://` as mqtt.js takes it |
|
|
39
|
+
| `mqtt.username`, `mqtt.password`, `mqtt.clientId` | — | credentials; a random client id when unset |
|
|
40
|
+
| `storage` | `./data` | matter.js storage (fabrics, endpoint numbers), `shards.json` and `commissioning.json` |
|
|
41
|
+
| `log.level` | `info` | `debug`, `info`, `warn`, `error` |
|
|
42
|
+
| `log.matter` | `warn` | matter.js' own log level |
|
|
43
|
+
| `vendorId` | `0xFFF1` | the Matter test vendor id |
|
|
44
|
+
| `productId` | `0x8000` | bridge n gets `productId + n` |
|
|
45
|
+
| `bridges` | `{"default": {}}` | one entry per Matter bridge, see below; at least one |
|
|
46
|
+
| `devices` | `{}` | one entry per device, keyed by the **device key** |
|
|
47
|
+
| `server.enabled` | `true` | the web UI and its API (`docs/api.md`); `false` for headless |
|
|
48
|
+
| `server.host`, `server.port` | `0.0.0.0`, `8282` | where the UI listens |
|
|
49
|
+
| `server.topics` | `["#"]` | MQTT subscriptions for the UI's topic tree and live view, on top of the mappings' topics |
|
|
50
|
+
| `server.auth.mode` | `none` | who may use the UI and the API: `none` (everyone who reaches the port), `password`, `proxy` — see below |
|
|
51
|
+
| `server.auth.password` | — | `password` mode: the password's hash (`mqtt2matter --hash-password`, or set on the UI's Configuration page) |
|
|
52
|
+
| `server.auth.proxyHeader` | `X-Remote-User` | `proxy` mode: the header the reverse proxy sets to the authenticated user |
|
|
53
|
+
| `server.auth.proxyLogoutUrl` | — | `proxy` mode: where the UI's "Log out" goes (the proxy's sign-out) |
|
|
54
|
+
| `server.auth.sessionHours` | `168` | `password` mode: how long a login lasts |
|
|
55
|
+
| `presets` | `[]` | directories with the user's preset files (`*.json`), on top of the shipped ones |
|
|
56
|
+
| `importers.z2m.enabled` | `true` | watch zigbee2mqtt's `bridge/devices` and `bridge/groups` for the UI's adopt page ([importers.md](importers.md)) |
|
|
57
|
+
| `importers.z2m.baseTopic` | `zigbee2mqtt` | zigbee2mqtt's base topic |
|
|
58
|
+
| `importers.ha.enabled` | `true` | watch Home Assistant MQTT discovery (`<prefix>/#`) for the UI's adopt page ([importers.md](importers.md)) |
|
|
59
|
+
| `importers.ha.prefix` | `homeassistant` | the discovery prefix |
|
|
60
|
+
|
|
61
|
+
## Access
|
|
62
|
+
|
|
63
|
+
**The default is `none`: no login.** Whoever reaches `server.port` can edit the devices, publish to the broker
|
|
64
|
+
and open commissioning windows — keep the port on a trusted network, or choose a mode:
|
|
65
|
+
|
|
66
|
+
- `password`: one password. The UI shows a login; a login is a session cookie (HttpOnly, SameSite=Strict, `Secure`
|
|
67
|
+
behind a proxy that sends `X-Forwarded-Proto: https`) that lasts `sessionHours` or until the logout or the next
|
|
68
|
+
start. The file holds an scrypt hash, written by the UI's Configuration page (Access) or printed by
|
|
69
|
+
`mqtt2matter --hash-password` (it reads the password from stdin); a plain password in the file or in
|
|
70
|
+
`MQTT2MATTER_AUTH_PASSWORD` works too and is hashed at start. Ten failed logins from one address within
|
|
71
|
+
15 minutes are refused for the rest of that window.
|
|
72
|
+
- `proxy`: a reverse proxy (nginx with authentik, Authelia, oauth2-proxy, …) authenticates and sets
|
|
73
|
+
`proxyHeader` to the user; a request without it is refused, the user is shown in the UI. **Only the proxy may
|
|
74
|
+
reach the port** — set `server.host` to `127.0.0.1` (or firewall the port) — or anyone can send the header.
|
|
75
|
+
The UI switches to proxy mode only through a request that already carries the header.
|
|
76
|
+
|
|
77
|
+
The Configuration page's Access section changes the mode at once, without a restart; the other settings apply at
|
|
78
|
+
the next start. A mode the environment sets is not editable there.
|
|
79
|
+
|
|
80
|
+
## Bridges
|
|
81
|
+
|
|
82
|
+
```json
|
|
83
|
+
"bridges": {"default": {"name": "mqtt2matter", "port": 5540, "passcode": 20202021, "discriminator": 3840, "maxDevices": 0}}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
| Key | Default | Meaning |
|
|
87
|
+
| --------------- | ------------------ | ------------------------------------------------------------------------- |
|
|
88
|
+
| `name` | `mqtt2matter <id>` | what controllers show (≤ 32 characters) |
|
|
89
|
+
| `port` | `5540` | the UDP port; several bridges need distinct ports |
|
|
90
|
+
| `passcode` | random, persisted | 1–99999998, not one of the forbidden values |
|
|
91
|
+
| `discriminator` | random, persisted | 0–4095 |
|
|
92
|
+
| `maxDevices` | `0` (unlimited) | devices this bridge takes before the next one is used (multi-bridge, 1.1) |
|
|
93
|
+
|
|
94
|
+
The bridge id (`default`) is the matter.js node id and its storage directory: 1–32 characters of
|
|
95
|
+
`A–Z a–z 0–9 _ -`. Pairing codes are logged at start while the bridge is not commissioned. A passcode or
|
|
96
|
+
discriminator that is not configured is generated at the bridge's first start and kept in
|
|
97
|
+
`<storage>/commissioning.json`, so the pairing code stays the same across restarts; delete the bridge's entry
|
|
98
|
+
there for a new one.
|
|
99
|
+
|
|
100
|
+
## Devices
|
|
101
|
+
|
|
102
|
+
```json
|
|
103
|
+
"living-room-lamp": {
|
|
104
|
+
"name": "Living room lamp", "vendor": "Tasmota", "model": "Sonoff B1",
|
|
105
|
+
"availability": {"topic": "tele/b1/LWT", "online": "Online", "offline": "Offline"},
|
|
106
|
+
"endpoints": [{
|
|
107
|
+
"deviceTypes": ["ColorTemperatureLight"],
|
|
108
|
+
"options": {"light": {"onCommandType": "last"}},
|
|
109
|
+
"mappings": [
|
|
110
|
+
{"attribute": "OnOff.onOff",
|
|
111
|
+
"status": {"topic": "stat/b1/RESULT", "extract": "$.POWER", "map": {"ON": true, "OFF": false}},
|
|
112
|
+
"command": {"topic": "cmnd/b1/POWER", "format": {"true": "ON", "false": "OFF"}}},
|
|
113
|
+
{"attribute": "LevelControl.currentLevel",
|
|
114
|
+
"status": {"topic": "stat/b1/RESULT", "extract": "$.Dimmer", "unit": "percentLevel"},
|
|
115
|
+
"command": {"topic": "cmnd/b1/Dimmer", "unit": "percentLevel", "round": 0}},
|
|
116
|
+
{"attribute": "ColorControl.colorTemperatureMireds",
|
|
117
|
+
"status": {"topic": "stat/b1/RESULT", "extract": "$.CT"},
|
|
118
|
+
"command": {"topic": "cmnd/b1/CT"}}
|
|
119
|
+
]
|
|
120
|
+
}]
|
|
121
|
+
}
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
The **device key** (`living-room-lamp`) is the Matter endpoint id: 1–64 characters of `A–Z a–z 0–9 : . _ -`.
|
|
125
|
+
It keeps the device's endpoint number stable; rename through `name`, never through the key.
|
|
126
|
+
|
|
127
|
+
| Key | Default | Meaning |
|
|
128
|
+
| --------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
129
|
+
| `name` | required | the label controllers show (≤ 32) |
|
|
130
|
+
| `vendor`, `model`, `serial` | — | `BridgedDeviceBasicInformation`; the serial defaults to the key |
|
|
131
|
+
| `enabled` | `true` | a disabled device is not built |
|
|
132
|
+
| `bridge` | assigned | the bridge id; default: assigned once and remembered in `shards.json` |
|
|
133
|
+
| `source` | `{"kind": "manual"}` | where the device came from: `manual`, `z2m`, `ha-discovery`, `preset`; `key`, `version`, `raw`, `orphaned` are the importer's ([importers.md](importers.md)) |
|
|
134
|
+
| `availability` | — | one availability topic (short form) or `{topics: [...], mode}` → `reachable`, see below |
|
|
135
|
+
| `endpoints` | required | at least one; the first is the bridged node, the others are its child endpoints (ids `<key>~<id>`) |
|
|
136
|
+
|
|
137
|
+
### Availability
|
|
138
|
+
|
|
139
|
+
```json
|
|
140
|
+
"availability": {"topic": "zigbee2mqtt/lamp/availability", "extract": "state", "online": "online", "offline": "offline"}
|
|
141
|
+
"availability": {"mode": "all", "topics": [{"topic": "tele/a/LWT", "online": "Online", "offline": "Offline"}, {"topic": "tele/b/LWT", "online": "Online", "offline": "Offline"}]}
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
| Key | Default | Meaning |
|
|
145
|
+
| ------------------- | --------- | -------------------------------------------------------------------------------- |
|
|
146
|
+
| `topics[].topic` | required | the topic |
|
|
147
|
+
| `topics[].extract` | — | a JSON path into the payload |
|
|
148
|
+
| `topics[].template` | — | a Jinja template over `value` and `value_json`, like a status half's |
|
|
149
|
+
| `topics[].online` | `online` | the payload (after extract/template) that means reachable |
|
|
150
|
+
| `topics[].offline` | `offline` | the payload that means unreachable; other payloads are ignored |
|
|
151
|
+
| `mode` | `latest` | `all`: every topic online; `any`: one online; `latest`: the last message decides |
|
|
152
|
+
|
|
153
|
+
`reachable` on the bridged device follows availability and every `expire` of the device's status halves: a
|
|
154
|
+
device is unreachable when availability says so or any expired topic has not reported in time.
|
|
155
|
+
|
|
156
|
+
### Endpoints
|
|
157
|
+
|
|
158
|
+
| Key | Default | Meaning |
|
|
159
|
+
| ------------- | -------- | ---------------------------------------------------------------------------------------------------- |
|
|
160
|
+
| `id` | `main` | the endpoint within the device; unique per device |
|
|
161
|
+
| `deviceTypes` | required | matter.js device type names; the first is the endpoint's type, the others are added (`PowerSource`) |
|
|
162
|
+
| `features` | — | cluster features on top of what the device types require, e.g. `{"PowerSource": ["Battery"]}` |
|
|
163
|
+
| `attributes` | — | fixed attribute values and defaults, e.g. `{"PowerSource": {"description": "2×AA"}}` |
|
|
164
|
+
| `mappings` | `[]` | see below |
|
|
165
|
+
| `options` | defaults | the family options (light, cover, climate, fan, switch, powerSource), see below |
|
|
166
|
+
| `coalesce` | `0` | ms: JSON command payloads to one topic within this window are merged into one message (z2m's `/set`) |
|
|
167
|
+
|
|
168
|
+
**Device types** are matter.js' names: every `*Device` it ships (`OnOffLight`, `DimmableLight`,
|
|
169
|
+
`ColorTemperatureLight`, `ExtendedColorLight`, `OnOffPlugInUnit`, `DimmablePlugInUnit`, `WindowCovering`,
|
|
170
|
+
`Thermostat`, `DoorLock`, `Fan`, `GenericSwitch`, `ContactSensor`, `OccupancySensor`, `TemperatureSensor`,
|
|
171
|
+
`HumiditySensor`, `LightSensor`, `PressureSensor`, `FlowSensor`, `AirQualitySensor`, `WaterLeakDetector`,
|
|
172
|
+
`RainSensor`, `SmokeCoAlarm`, …) plus the utility `PowerSource`. The device type's mandatory clusters come
|
|
173
|
+
with it, its optional clusters and any other cluster are added when a mapping names them. Feature names are
|
|
174
|
+
matter.js' (`Lighting`, `ColorTemperature`, `HueSaturation`, `Xy`, `PositionAwareLift`, `Heating`, `Battery`,
|
|
175
|
+
…) or the specification's codes (`LT`, `CT`, `HS`, `XY`, `PA_LF`, `HEAT`, `BAT`). The families add the
|
|
176
|
+
features their mappings imply (a bound `occupiedHeatingSetpoint` → `Heating`; `colorHs` → `HueSaturation`).
|
|
177
|
+
|
|
178
|
+
### Mappings
|
|
179
|
+
|
|
180
|
+
A mapping joins one Matter attribute, command or event channel with MQTT in two independent halves —
|
|
181
|
+
`status` (device → Matter) and `command` (Matter → device); one may be absent.
|
|
182
|
+
|
|
183
|
+
| Key | Meaning |
|
|
184
|
+
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
|
185
|
+
| `attribute` | `Cluster.attribute` in matter.js' names: `OnOff.onOff`, `LevelControl.currentLevel`, `Thermostat.systemMode` |
|
|
186
|
+
| `invoke` | a command that is not an attribute write: `WindowCovering.stopMotion`, `WindowCovering.upOrOpen`, `Identify.identify`; command half only |
|
|
187
|
+
| `event` | a family's event channel: `Switch` — the status half yields a press kind, see _Switch_ |
|
|
188
|
+
| `comment` | free text |
|
|
189
|
+
|
|
190
|
+
Enum attributes are written by their member names in `map`, `default` and `format` (`"Heat"`, `"Locked"`,
|
|
191
|
+
`"Good"`; case does not matter); bitmap attributes by their field names, comma-separated (`"heat,fan"`,
|
|
192
|
+
`""` for none), or by a boolean for the first field (`OccupancySensing.occupancy`). Values a controller can
|
|
193
|
+
write — thermostat setpoints and `systemMode`, `FanControl.fanMode` and `percentSetting`, `WindowCovering.mode`
|
|
194
|
+
— are applied by matter.js before they are published, so their command halves are optimistic in any case.
|
|
195
|
+
|
|
196
|
+
**`status`** (device → Matter), in this order:
|
|
197
|
+
|
|
198
|
+
| Key | Meaning |
|
|
199
|
+
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
200
|
+
| `topic` | the topic to subscribe |
|
|
201
|
+
| `extract` | a JSON path into the payload: `$.POWER`, `state.on`, `$.a[0].b`; absent = the whole payload |
|
|
202
|
+
| `template` | a Jinja template over `value` (the extracted value or the payload text), `value_json` (the parsed payload) and `topic`; its text is the value; an empty result is ignored, `None` (Home Assistant's "no value") is `null` unless `map` names it |
|
|
203
|
+
| `map` | value (as text) → attribute value: `{"ON": true, "OFF": false}`, `{"heat": "Heat"}`; an unmapped value is ignored unless `default` is set; `null` clears a nullable attribute |
|
|
204
|
+
| `default` | the value for an unmapped key or a failed `type` (`null` as in `map`) |
|
|
205
|
+
| `type` | without a map: `boolean`, `number` or `string` — explicit, no guessing (`"ON"` is not a boolean) |
|
|
206
|
+
| `unit` | a named conversion into the attribute's unit, see _Units_ |
|
|
207
|
+
| `scale` | `{"from": [0, 100], "to": [1, 254], "clamp": true}`: linear, clamped into `from`; reversed `to` bounds invert (`[10000, 0]`) |
|
|
208
|
+
| `offset` | added after scaling |
|
|
209
|
+
| `invert` | booleans: not; numbers with a scale: mirrored within `scale.to` |
|
|
210
|
+
| `round` | decimals; integer attributes are rounded to whole numbers in any case |
|
|
211
|
+
| `expire` | seconds without a message on this topic after which the device is unreachable |
|
|
212
|
+
| `get` | `{"topic", "payload"}` published at start and after a reconnect so the device reports (z2m `…/get`) |
|
|
213
|
+
| `codec` | `{"module": "./my-codec.js", "options": …}`: `decode(payload, {topic, options})` replaces every step above |
|
|
214
|
+
|
|
215
|
+
Without `extract`, `map` and `type` a plain payload is taken as text and a JSON scalar as itself; a JSON
|
|
216
|
+
object or array is handed to the family (the colour composites).
|
|
217
|
+
|
|
218
|
+
A message that carries no value for a mapping — the `extract` path is missing, the template renders nothing,
|
|
219
|
+
the value is `null` for an attribute that cannot be null — is skipped and logged at debug: several mappings
|
|
220
|
+
often share a topic and each message carries only some of their values. Other failures are warnings.
|
|
221
|
+
|
|
222
|
+
**`command`** (Matter → device): a value a controller wrote becomes a payload on `topic`.
|
|
223
|
+
|
|
224
|
+
| Key | Default | Meaning |
|
|
225
|
+
| -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
226
|
+
| `topic` | required | the topic to publish to |
|
|
227
|
+
| `unit`, `scale`, `offset`, `invert`, `round` | — | the status steps inverted |
|
|
228
|
+
| `precision` | — | decimals the number is printed with |
|
|
229
|
+
| `format` | — | attribute value (as text, enum name, bitmap field list) → payload: `{"true": "ON", "false": "OFF"}`, `{"Locked": "LOCK"}` |
|
|
230
|
+
| `payload` | — | a fixed payload (for `invoke` mappings: `"STOP"`) |
|
|
231
|
+
| `template` | — | a Jinja template over `value`, `name` (an enum's member name), `topic` and the family's fields, see _Templates_ |
|
|
232
|
+
| `wrap` | — | a JSON path: the payload becomes `{"a": {"b": value}}` for `$.a.b`; merged by `coalesce` |
|
|
233
|
+
| `retain` | `false` | |
|
|
234
|
+
| `qos` | `0` | |
|
|
235
|
+
| `optimistic` | see → | apply the value locally right after publishing; default `true` without a status half (or a related one: a cover's target is confirmed by its position), `false` with one |
|
|
236
|
+
| `codec` | — | `encode(value, {topic, options, fields})` returns the payload (a string) or JSON |
|
|
237
|
+
|
|
238
|
+
Without `format`, `payload` and `template` the payload is the value as text (an object as JSON).
|
|
239
|
+
|
|
240
|
+
### Units
|
|
241
|
+
|
|
242
|
+
| `unit` | Device | Matter attribute |
|
|
243
|
+
| --------------- | ------- | ---------------------------------------------- |
|
|
244
|
+
| `celsius` | °C | 0.01 °C (`TemperatureMeasurement`, setpoints) |
|
|
245
|
+
| `fahrenheit` | °F | 0.01 °C |
|
|
246
|
+
| `kelvin` | K | mireds (`colorTemperatureMireds`) |
|
|
247
|
+
| `percent100ths` | 0–100 % | 0–10000 (humidity, cover positions) |
|
|
248
|
+
| `halfPercent` | 0–100 % | 0–200 (`batPercentRemaining`) |
|
|
249
|
+
| `percentLevel` | 0–100 % | level 1–254, 0 stays 0 (`currentLevel`) |
|
|
250
|
+
| `byteLevel` | 0–255 | level 1–254 (brightness as z2m and HA send it) |
|
|
251
|
+
| `lux` | lux | `IlluminanceMeasurement`: 10000·log10(lux) + 1 |
|
|
252
|
+
| `volt` | V | mV (`batVoltage`) |
|
|
253
|
+
| `degrees254` | 0–360° | hue 0–254 |
|
|
254
|
+
| `percent254` | 0–100 % | saturation 0–254 |
|
|
255
|
+
| `seconds10ths` | s | tenths of a second |
|
|
256
|
+
|
|
257
|
+
### Templates
|
|
258
|
+
|
|
259
|
+
Jinja through `@huggingface/jinja`, Home Assistant style. Available: expressions, `if … else …`, loops, the
|
|
260
|
+
filters `int` (Home Assistant's `int(default, base)`: `'ff' | int(0, 16)`), `float`, `string`, `bool`, `lower`, `upper`, `trim`, `abs`, `default`, `length`, `join`,
|
|
261
|
+
`replace`, `tojson`, `round(precision, method, default)`, `is_defined`, `iif`, `multiply`, `is_number`, `max`,
|
|
262
|
+
`min`; the tests `defined`, `none`, `number`, `string`; the functions `iif`, `float`, `int`, `max`, `min`.
|
|
263
|
+
Whole floats render as Python does (`3.0`). Not available: `states()`, `now()`, macros, `format`.
|
|
264
|
+
|
|
265
|
+
Status templates see `value`, `value_json`, `topic`. Command templates see `value`, `topic`, `name` (an
|
|
266
|
+
enum member's name) and the family's fields: lights add `level`, `brightness` (0–254), `percent`,
|
|
267
|
+
`transition` (seconds, when the controller gave one); colours add `hue` (0–360), `saturation` (0–100), `x`,
|
|
268
|
+
`y`, `red`, `green`, `blue` (and `h`, `s`, `r`, `g`, `b`), colour temperature `mireds`, `kelvin`; covers add
|
|
269
|
+
`position`, `percent` (0–100, 0 = open as Matter has it), `open` (100 − position), `percent100ths`; fans
|
|
270
|
+
`percent`, `mode`, `speed`; locks `action` (`locked`, `unlocked`, `unlatched`).
|
|
271
|
+
|
|
272
|
+
### Composite attributes
|
|
273
|
+
|
|
274
|
+
The light family owns three attribute names beyond the model; each value is an object (status: also an
|
|
275
|
+
array or `"a,b(,c)"`):
|
|
276
|
+
|
|
277
|
+
| Attribute | Fields | Feature it implies |
|
|
278
|
+
| ----------------------- | -------------------------------------------- | ---------------------------------------------- |
|
|
279
|
+
| `ColorControl.colorHs` | `hue` 0–360, `saturation` 0–100 (`h`, `s`) | `HueSaturation` |
|
|
280
|
+
| `ColorControl.colorXy` | `x`, `y` 0–1 | `Xy` |
|
|
281
|
+
| `ColorControl.colorRgb` | `r`, `g`, `b` 0–255 (`red`, `green`, `blue`) | — (converted to the features the endpoint has) |
|
|
282
|
+
|
|
283
|
+
A controller's colour command goes to whichever of these the endpoint binds (converted), else to the plain
|
|
284
|
+
`currentHue`/`currentSaturation` or `currentX`/`currentY` mappings. A status on any colour attribute sets every
|
|
285
|
+
representation the endpoint's features carry and `colorMode`/`enhancedColorMode` — unless `ColorControl.colorMode`
|
|
286
|
+
has a status mapping of its own (bind it for devices that report `color_mode`; a message carrying both a colour and
|
|
287
|
+
a colour temperature lets the last mapping win otherwise).
|
|
288
|
+
|
|
289
|
+
The cover family owns `WindowCovering.motion`: `opening`, `closing`, `stopped` (`stop`, `idle`), `open`,
|
|
290
|
+
`closed` — for state-only covers and for `moving`/`motor_state` reports.
|
|
291
|
+
|
|
292
|
+
### Families and their options
|
|
293
|
+
|
|
294
|
+
**onOff** (`OnOff`)
|
|
295
|
+
|
|
296
|
+
| Option | Default | Meaning |
|
|
297
|
+
| ----------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
298
|
+
| `momentary` | `0` | ms; a stateless trigger (a scene, a button behind an outlet): on publishes the command and the endpoint falls back to off after this long, off publishes nothing; `0` = plain on/off |
|
|
299
|
+
|
|
300
|
+
**light** (`OnOff`, `LevelControl`, `ColorControl`)
|
|
301
|
+
|
|
302
|
+
| Option | Default | Meaning |
|
|
303
|
+
| ------------------------ | ------------ | -------------------------------------------------------------------------------------------------------------------- |
|
|
304
|
+
| `onCommandType` | `last` | HA's `on_command_type`: `first` publishes on, then the level; `last` the level, then on; `brightness` only the level |
|
|
305
|
+
| `transition` | `true` | pass the controller's transition time to the templates as `transition` |
|
|
306
|
+
| `minMireds`, `maxMireds` | `153`, `500` | the colour temperature range |
|
|
307
|
+
|
|
308
|
+
A controller's `moveToLevelWithOnOff` publishes the level and, per `onCommandType`, the on/off; `move` and
|
|
309
|
+
`step` publish the resulting level. Values are applied locally only where the mapping is optimistic.
|
|
310
|
+
|
|
311
|
+
**cover** (`WindowCovering`): bind `currentPositionLiftPercent100ths` (status) and `targetPositionLiftPercent100ths`
|
|
312
|
+
(command) for a position-aware cover — Matter counts 0 = open, 100 % = closed; a device counting the other way
|
|
313
|
+
uses `scale: {"from": [0, 100], "to": [10000, 0]}` — or `motion` plus `invoke` mappings for `upOrOpen`,
|
|
314
|
+
`downOrClose`, `stopMotion` for a state-only one; tilt uses the `…Tilt…` attributes.
|
|
315
|
+
|
|
316
|
+
| Option | Default | Meaning |
|
|
317
|
+
| --------------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
|
|
318
|
+
| `echoFilter` | `false` | hold back a first report after a command that repeats the old position until a second report or the timeout (FYRTUR) |
|
|
319
|
+
| `reportTimeout` | `30` | seconds after the last report before a movement counts as ended (target snaps to current) |
|
|
320
|
+
| `tolerance` | `100` | percent100ths within which current and target count as equal |
|
|
321
|
+
|
|
322
|
+
A command sets the target and publishes it; reports drive the current position; `operationalStatus` follows
|
|
323
|
+
from target vs current; a report while no command is in flight is an external move whose predicted target (the
|
|
324
|
+
direction's extreme) is written before the current position; after a stop the next report is the final
|
|
325
|
+
position.
|
|
326
|
+
|
|
327
|
+
**climate** (`Thermostat`): temperatures in Matter's 0.01 °C (`unit: celsius`). Features follow the mappings:
|
|
328
|
+
`Heating` with `occupiedHeatingSetpoint`, `Cooling` with `occupiedCoolingSetpoint`, `AutoMode` with both and
|
|
329
|
+
`systemMode`. `thermostatRunningState` is a bitmap (`"heat"`, `"cool"`, `"fan"`, `""`).
|
|
330
|
+
|
|
331
|
+
| Option | Default | Meaning |
|
|
332
|
+
| ------------------------------------------ | --------------------- | ------------------------------------- |
|
|
333
|
+
| `minHeat`, `maxHeat`, `minCool`, `maxCool` | `7`, `30`, `16`, `32` | setpoint limits in °C |
|
|
334
|
+
| `deadband` | `2` | °C between the setpoints in auto mode |
|
|
335
|
+
|
|
336
|
+
**lock** (`DoorLock`): `lockState` with the names `Locked`, `Unlocked`, `NotFullyLocked` (jammed), `Unlatched`;
|
|
337
|
+
a controller's lock/unlock publishes the command half keyed by those names and waits for the report.
|
|
338
|
+
|
|
339
|
+
**fan** (`FanControl`): bind `percentSetting` (command) and `percentCurrent` or `percentSetting` (status), or
|
|
340
|
+
`fanMode` by name (`Off`, `Low`, `Medium`, `High`, `Auto`); the family keeps mode and percent consistent. `Auto`
|
|
341
|
+
needs the `Auto` feature (`"features": {"FanControl": ["Auto"]}`); in Auto Matter has no percent setting, so map
|
|
342
|
+
the device's auto value to `null` on `percentSetting` (`"map": {"auto": null, …}`). A percent report while the mode
|
|
343
|
+
is Auto leaves Auto.
|
|
344
|
+
|
|
345
|
+
| Option | Default | Meaning |
|
|
346
|
+
| --------------- | ---------- | -------------------------------------------------------------------- |
|
|
347
|
+
| `low`, `medium` | `33`, `66` | percent thresholds between the modes |
|
|
348
|
+
| `speedMax` | `0` | discrete speeds (the `MultiSpeed` feature, `speedSetting`); 0 = none |
|
|
349
|
+
|
|
350
|
+
**switch** (`GenericSwitch`, the `Switch` event channel): the status half's value is a press kind —
|
|
351
|
+
`single` (`click`), `double`, `triple`, a number of presses, `long` (`hold`), `press`, `release`,
|
|
352
|
+
`longRelease` — played into the switch's events (initialPress, shortRelease, multiPressOngoing/Complete,
|
|
353
|
+
longPress, longRelease) with the delays below; one `GenericSwitch` endpoint per button. A latching switch takes
|
|
354
|
+
the value as its position.
|
|
355
|
+
|
|
356
|
+
| Option | Default | Meaning |
|
|
357
|
+
| ------------------- | ----------- | ----------------------------------------------------- |
|
|
358
|
+
| `kind` | `momentary` | `momentary` or `latching` |
|
|
359
|
+
| `numberOfPositions` | `2` | |
|
|
360
|
+
| `multiPressMax` | `3` | presses in one sequence |
|
|
361
|
+
| `multiPressDelay` | `300` | ms after a release before a sequence completes |
|
|
362
|
+
| `longPressDelay` | `500` | ms a press lasts before it is long |
|
|
363
|
+
| `pressDuration` | `50` | ms between the press and the release the family plays |
|
|
364
|
+
|
|
365
|
+
**powerSource** (`PowerSource` on the same endpoint): `batPercentRemaining` (`unit: halfPercent`),
|
|
366
|
+
`batVoltage` (`unit: volt`), `batChargeLevel` (`Ok`, `Warning`, `Critical`); `Battery` is the default feature,
|
|
367
|
+
`Wired` when `wiredCurrentType` is bound.
|
|
368
|
+
|
|
369
|
+
| Option | Default | Meaning |
|
|
370
|
+
| --------------------- | ---------- | ------------------------------------------------------------------- |
|
|
371
|
+
| `warning`, `critical` | `20`, `10` | percent at or below which the charge level is derived, unless bound |
|
|
372
|
+
|
|
373
|
+
**robot vacuum** (`RvcRunMode`, `RvcOperationalState` of a `RoboticVacuumCleaner`): the run modes are `0` Idle
|
|
374
|
+
and `1` Cleaning — `RvcRunMode.currentMode` maps the device's state to them and its command half formats a
|
|
375
|
+
controller's mode change (`{"1": "START", "0": "HOME"}`); `RvcOperationalState.operationalState` by name
|
|
376
|
+
(`Stopped`, `Running`, `Paused`, `Error`, `SeekingCharger`, `Charging`, `Docked`); `invoke` mappings for
|
|
377
|
+
`RvcOperationalState.pause`, `resume` and `goHome` — a command without a mapping is refused as invalid in the
|
|
378
|
+
current state. No options.
|
|
379
|
+
|
|
380
|
+
**sensors** have no options: `TemperatureMeasurement`, `RelativeHumidityMeasurement`, `IlluminanceMeasurement`,
|
|
381
|
+
`PressureMeasurement`, `FlowMeasurement` (`measuredValue`), `BooleanState.stateValue` (contact, leak, rain,
|
|
382
|
+
freeze), `OccupancySensing.occupancy` (a boolean), `AirQuality.airQuality` (`Good` … `ExtremelyPoor`), the
|
|
383
|
+
concentration clusters' `measuredValue` (CO₂ and CO in ppm, NO₂, O₃, formaldehyde and VOC in ppb, PM1/2.5/10 in
|
|
384
|
+
µg/m³, radon in Bq/m³).
|
|
385
|
+
|
|
386
|
+
## Presets
|
|
387
|
+
|
|
388
|
+
A preset is a device template in a JSON file:
|
|
389
|
+
|
|
390
|
+
```json
|
|
391
|
+
{
|
|
392
|
+
"id": "tasmota/relay",
|
|
393
|
+
"name": "Tasmota relay",
|
|
394
|
+
"vendor": "Tasmota",
|
|
395
|
+
"format": 1,
|
|
396
|
+
"variables": {
|
|
397
|
+
"topic": {"label": "Tasmota topic"},
|
|
398
|
+
"name": {"label": "Name", "default": "Relay"}
|
|
399
|
+
},
|
|
400
|
+
"device": {
|
|
401
|
+
"name": "%name%",
|
|
402
|
+
"vendor": "Tasmota",
|
|
403
|
+
"availability": {"topic": "tele/%topic%/LWT", "online": "Online", "offline": "Offline"},
|
|
404
|
+
"endpoints": [
|
|
405
|
+
{
|
|
406
|
+
"deviceTypes": ["OnOffPlugInUnit"],
|
|
407
|
+
"mappings": [
|
|
408
|
+
{
|
|
409
|
+
"attribute": "OnOff.onOff",
|
|
410
|
+
"status": {"topic": "stat/%topic%/RESULT", "extract": "$.POWER", "map": {"ON": true, "OFF": false}},
|
|
411
|
+
"command": {"topic": "cmnd/%topic%/POWER", "format": {"true": "ON", "false": "OFF"}}
|
|
412
|
+
}
|
|
413
|
+
]
|
|
414
|
+
}
|
|
415
|
+
]
|
|
416
|
+
}
|
|
417
|
+
}
|
|
418
|
+
```
|
|
419
|
+
|
|
420
|
+
`%name%` placeholders stand anywhere in `device`; every one must be declared in `variables` (`label`,
|
|
421
|
+
`description`, `default`, `optional`). Applying a preset substitutes the values into the JSON text and
|
|
422
|
+
validates the result; the device gets `source: {"kind": "preset", "key": "<id>"}`. Users add their own files
|
|
423
|
+
(`presets` in the top level); an id that is taken already (a shipped one) is reported and skipped.
|
|
424
|
+
|
|
425
|
+
### Shipped presets
|
|
426
|
+
|
|
427
|
+
The UI's device editor offers them; `POST /api/presets/:id/apply` ([api.md](api.md)) does the same. Every
|
|
428
|
+
preset has a `name` variable (what controllers show) besides the ones listed here.
|
|
429
|
+
|
|
430
|
+
**mqtt-smarthome** — adapters that follow the [mqtt-smarthome convention](https://github.com/mqtt-smarthome/mqtt-smarthome/blob/master/SPEC.md)
|
|
431
|
+
(2.0): `<instance>/status/<item>` as a plain value or a `{val, ts, lc}` object (both are read),
|
|
432
|
+
`<instance>/set/<item>` with a plain value, `<instance>/connected` `2` = reachable (`0` and `1` unreachable).
|
|
433
|
+
Variables: `instance` (the adapter's `--name`), `item` (the item path, may have several levels).
|
|
434
|
+
|
|
435
|
+
| Id | Matter | Notes |
|
|
436
|
+
| ---------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------- |
|
|
437
|
+
| `mqtt-smarthome/switch` | OnOffPlugInUnit | `true`/`false` (also `1`/`0`, `on`/`off`, `yes`/`no`); sends `true`/`false` |
|
|
438
|
+
| `mqtt-smarthome/light` | OnOffLight | the same as a light |
|
|
439
|
+
| `mqtt-smarthome/dimmer` | DimmableLight | `max`: the value for 100 % (default `100`; `1` for 0…1 levels); on/off follows the level, off sends `0`, on `max` |
|
|
440
|
+
| `mqtt-smarthome/cover` | WindowCovering | `max` as above; the item counts 0 = closed … `max` = open; stop is not sent |
|
|
441
|
+
| `mqtt-smarthome/contact` | ContactSensor | `true`, `1`, `open` = open |
|
|
442
|
+
| `mqtt-smarthome/occupancy` | OccupancySensor | `true`/`false` |
|
|
443
|
+
| `mqtt-smarthome/temperature` | TemperatureSensor | °C |
|
|
444
|
+
| `mqtt-smarthome/humidity` | HumiditySensor | % |
|
|
445
|
+
| `mqtt-smarthome/button` | GenericSwitch | `true`, `1`, `single`, `short`, `click` = one press; `double`, `triple`; `long`, `hold` = a long press |
|
|
446
|
+
|
|
447
|
+
**WLED** — `topic`: the device topic (Config → Sync Interfaces → MQTT → Device Topic; default `wled/<MAC>`),
|
|
448
|
+
the whole of it. WLED publishes `<topic>/g` (brightness 0–255) and `<topic>/c` (`#RRGGBB`, `#WWRRGGBB` with
|
|
449
|
+
white) on every change and keeps `<topic>/status` (`online`/`offline`) retained; there is no request for the
|
|
450
|
+
state, so after a restart of mqtt2matter the light shows its state from the next change on (or at once where the
|
|
451
|
+
broker holds `/g` and `/c` retained).
|
|
452
|
+
|
|
453
|
+
| Id | Matter | Notes |
|
|
454
|
+
| ------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
455
|
+
| `wled/light` | ExtendedColorLight | brightness to `<topic>` (`ON`/`OFF`/0–255), the colour to `<topic>/col` as a decimal `0xRRGGBB`; colour temperature as `{"seg":{"cct":<K>}}` to `<topic>/api` (strips with white channels; not reported back) |
|
|
456
|
+
| `wled/dimmer` | DimmableLight | single-colour strips: on/off and brightness only |
|
|
457
|
+
|
|
458
|
+
**Shelly Gen2/Gen3** (Plus, Pro, Gen3, Gen4) — `prefix`: the MQTT prefix (Settings → MQTT; by default the device
|
|
459
|
+
id, `shellyplus1pm-a8032abe54dc`). **Switch on "Generic status update"** (`status_ntf`) in the device's MQTT
|
|
460
|
+
settings: the presets read the complete component status from `<prefix>/status/<component>:<id>`, which the
|
|
461
|
+
device publishes only with it. Commands go as RPC frames to `<prefix>/rpc` (`src` `mqtt2matter`, so the answers
|
|
462
|
+
land on `mqtt2matter/rpc`); at start each status is requested with `status_update` on
|
|
463
|
+
`<prefix>/command/<component>:<id>` (MQTT control, firmware 0.14 and later; 1.6 for lights). Availability is
|
|
464
|
+
`<prefix>/online` (`true`/`false`). `channel` is the component id: `0`, or `1` for the second relay of a 2PM.
|
|
465
|
+
|
|
466
|
+
| Id | Matter | Notes |
|
|
467
|
+
| ----------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
|
|
468
|
+
| `shelly-gen2/switch` | OnOffPlugInUnit | `switch:<channel>` `output`; `Switch.Set` |
|
|
469
|
+
| `shelly-gen2/switch-pm` | OnOffPlugInUnit, ElectricalSensor | as above plus `apower`, `voltage`, `current` → active power, voltage, current (1PM, 2PM, Plug S, Pro xPM) |
|
|
470
|
+
| `shelly-gen2/cover` | WindowCovering | `cover:<channel>` `current_pos` (100 = open); `Cover.GoToPosition`, `Open`, `Close`, `Stop`; calibrate first |
|
|
471
|
+
| `shelly-gen2/dimmer` | DimmableLight | `light:<channel>` `output`, `brightness`; `Light.Set` (a level switches on) |
|
|
472
|
+
| `shelly-gen2/ht` | TemperatureSensor, PowerSource | Plus H&T: `temperature:0`, `devicepower:0` battery; humidity (`humidity:0`) as a child; no availability (it sleeps) |
|
|
473
|
+
| `shelly-gen2/i4` | GenericSwitch ×4 | Plus i4: `NotifyEvent` on `<prefix>/events/rpc`, single/double/triple/long push per input; inputs of type Button |
|
|
474
|
+
|
|
475
|
+
One preset is one channel: a 2PM's two relays are two devices (`channel` `0` and `1`) — the preset format has no
|
|
476
|
+
repetition, and two devices let each relay have its own name and room.
|
|
477
|
+
|
|
478
|
+
**Shelly Gen1** (the first generation, topics under `shellies/`) — `device`: the id in the device's topics,
|
|
479
|
+
`<model>-<deviceid>` (`shelly1pm-B929CC`). At start each mains-powered preset sends `update` to
|
|
480
|
+
`shellies/<device>/command`, which makes the device publish its state; availability is `shellies/<device>/online`.
|
|
481
|
+
Battery devices sleep between reports and have no availability.
|
|
482
|
+
|
|
483
|
+
| Id | Matter | Notes |
|
|
484
|
+
| ------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
|
|
485
|
+
| `shelly-gen1/relay` | OnOffPlugInUnit | `relay/<channel>` (`on`/`off`/`overpower`) and `relay/<channel>/command` |
|
|
486
|
+
| `shelly-gen1/relay-pm` | OnOffPlugInUnit, ElectricalSensor | as above plus the active power from `relay/<channel>/power` (1PM, 2.5, Plug S) |
|
|
487
|
+
| `shelly-gen1/roller` | WindowCovering | Shelly 2.5 in roller mode: `roller/0/pos` (100 = open, `-1` uncalibrated is skipped), `roller/0/command/pos`, open/close/stop |
|
|
488
|
+
| `shelly-gen1/dimmer` | DimmableLight | Dimmer 1/2: `light/0/status` (`ison`, `brightness`), JSON to `light/0/set` |
|
|
489
|
+
| `shelly-gen1/ht` | TemperatureSensor, PowerSource | H&T: `sensor/temperature` (set the device to °C), `sensor/battery`; humidity as a child |
|
|
490
|
+
| `shelly-gen1/door-window` | ContactSensor, PowerSource | Door/Window 1/2: `sensor/state` `open`/`close`, `sensor/battery`; `sensor/lux` as a child |
|
|
491
|
+
|
|
492
|
+
**Valetudo** — `prefix` (default `valetudo`) and `identifier`: Valetudo's Connectivity → MQTT settings.
|
|
493
|
+
Valetudo's own topics (not its Home Assistant discovery): `StatusStateAttribute/status`, `BatteryStateAttribute/level`
|
|
494
|
+
and `/status`, `BasicControlCapability/operation/set`; availability from the Homie `$state` (`ready` = reachable).
|
|
495
|
+
|
|
496
|
+
| Id | Matter | Notes |
|
|
497
|
+
| ----------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
498
|
+
| `valetudo/vacuum` | RoboticVacuumCleaner, PowerSource | run mode Idle/Cleaning (Cleaning → `START`, Idle → `HOME`), operational state (cleaning, paused, returning → seeking charger, docked, idle, error), pause/resume/go home, battery level and charging |
|
|
499
|
+
|
|
500
|
+
**A bridged vacuum shows in Google Home and Home Assistant.** Apple Home (iOS 18.4 and later) and Alexa expect a
|
|
501
|
+
robot vacuum as a Matter node of its own: behind a bridge Apple Home shows it at best as "Updating" (and other
|
|
502
|
+
bridges report the Home app failing with a vacuum among other bridged devices), Alexa does not discover it. Rooms
|
|
503
|
+
(Service Area) and cleaning modes (RvcCleanMode) are not mapped.
|
|
504
|
+
|
|
505
|
+
**OpenBeken** (BK7231, BL602, … — OpenBK7231T_App) — `client`: the client topic (Config → MQTT). Channels publish
|
|
506
|
+
`<client>/<channel>/get` and take `<client>/<channel>/set`; LED drivers publish `led_enableAll`, `led_dimmer` and
|
|
507
|
+
`led_basecolor_rgb` on `<client>/<variable>/get` and take the commands of the same names on
|
|
508
|
+
`cmnd/<client>/<command>`. Each status is asked for at start with an empty `…/get`. Availability is
|
|
509
|
+
`<client>/connected` (`online`; `offline` from the broker's last will).
|
|
510
|
+
|
|
511
|
+
| Id | Matter | Notes |
|
|
512
|
+
| ----------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
|
513
|
+
| `openbeken/relay` | OnOffPlugInUnit | a relay channel, `1`/`0` |
|
|
514
|
+
| `openbeken/dimmer` | DimmableLight | `led_enableAll`, `led_dimmer` 0–100 |
|
|
515
|
+
| `openbeken/ct-light` | ColorTemperatureLight | as the dimmer, plus `led_temperature` (154–500 mireds); its value is kept locally, the topic list names no report of it |
|
|
516
|
+
| `openbeken/color-light` | ExtendedColorLight | as the dimmer, the colour as hex in `led_basecolor_rgb`, `led_temperature` as above |
|
|
517
|
+
| `openbeken/temperature` | TemperatureSensor | a channel of type `Temperature`, `Temperature_div10` or `_div100`: `divisor` `1`, `10` (default) or `100` |
|
|
518
|
+
| `openbeken/humidity` | HumiditySensor | `Humidity` or `Humidity_div10`: `divisor` `1` (default) or `10` |
|
|
519
|
+
|
|
520
|
+
**Tasmota** — `topic`: the device's MQTT topic (Configuration → MQTT → Topic); the default FullTopic
|
|
521
|
+
`%prefix%/%topic%/`. Actuators read `stat/<topic>/RESULT` and ask for their state at start with an empty
|
|
522
|
+
`cmnd/<topic>/<Command>`; sensors read `tele/<topic>/SENSOR`, sent every `TelePeriod` (300 s by default), with
|
|
523
|
+
`TempUnit` C and `PressureUnit` hPa. Availability is `tele/<topic>/LWT` (`Online`/`Offline`).
|
|
524
|
+
|
|
525
|
+
| Id | Matter | Notes |
|
|
526
|
+
| ------------------------------ | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
|
|
527
|
+
| `tasmota/relay` | OnOffPlugInUnit | `POWER`; `index` empty for one relay, `1`, `2`, … for `POWER1`, `POWER2` of a multi-relay device |
|
|
528
|
+
| `tasmota/dimmer` | DimmableLight | `POWER`, `Dimmer` 0–100 |
|
|
529
|
+
| `tasmota/ct-light` | ColorTemperatureLight | `POWER`, `Dimmer`, `CT` 153–500 |
|
|
530
|
+
| `tasmota/color-light` | ExtendedColorLight | RGB, RGBW, RGBCCT: the colour from `HSBColor`, sent as `Color2 r,g,b` (keeps the dimmer); `CT`; the colour mode from `Channel` |
|
|
531
|
+
| `tasmota/shutter` | WindowCovering | `Shutter<index>.Position` (100 = open), `ShutterPosition<index>`, `ShutterOpen`, `ShutterClose`, `ShutterStop` |
|
|
532
|
+
| `tasmota/temperature` | TemperatureSensor | `sensor`: the key in `SENSOR` (`DS18B20`, `DS18B20-1`, …) |
|
|
533
|
+
| `tasmota/temperature-humidity` | TemperatureSensor, HumiditySensor child | `SHT3X`, `AM2301`, `DHT11`, `SI7021`, … |
|
|
534
|
+
| `tasmota/climate` | TemperatureSensor, Humidity- and PressureSensor children | `BME280`, `BME680`, … |
|
|
535
|
+
|
|
536
|
+
A device with several relays is one `tasmota/relay` per relay (`index`), not one device with child endpoints:
|
|
537
|
+
the preset format has no repetition, and separate devices give each relay its own name and room in the
|
|
538
|
+
controllers — the way the relays are usually used.
|