mqtt2matter 0.3.1 → 0.3.2

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.
Files changed (51) hide show
  1. package/CHANGELOG.md +54 -0
  2. package/README.md +1 -0
  3. package/dist/config/schema.d.ts +2 -0
  4. package/dist/families/cover.js +52 -26
  5. package/dist/families/cover.js.map +1 -1
  6. package/dist/families/fan.d.ts +2 -0
  7. package/dist/families/fan.js +17 -0
  8. package/dist/families/fan.js.map +1 -1
  9. package/dist/families/index.d.ts +2 -0
  10. package/dist/families/index.js +2 -1
  11. package/dist/families/index.js.map +1 -1
  12. package/dist/importers/ha/generate.d.ts +13 -1
  13. package/dist/importers/ha/generate.js +47 -4
  14. package/dist/importers/ha/generate.js.map +1 -1
  15. package/dist/importers/ha/sync.d.ts +11 -1
  16. package/dist/importers/ha/sync.js +88 -26
  17. package/dist/importers/ha/sync.js.map +1 -1
  18. package/dist/importers/sync.d.ts +18 -1
  19. package/dist/importers/sync.js +35 -6
  20. package/dist/importers/sync.js.map +1 -1
  21. package/dist/importers/z2m/generate.js +1 -1
  22. package/dist/importers/z2m/generate.js.map +1 -1
  23. package/dist/matter/bridge.js +1 -1
  24. package/dist/matter/bridge.js.map +1 -1
  25. package/dist/matter/ids.d.ts +1 -1
  26. package/dist/matter/ids.js +2 -2
  27. package/dist/matter/ids.js.map +1 -1
  28. package/dist/model/options.d.ts +2 -0
  29. package/dist/model/options.js +8 -3
  30. package/dist/model/options.js.map +1 -1
  31. package/dist/model/schema.d.ts +13 -1
  32. package/dist/model/schema.js +16 -4
  33. package/dist/model/schema.js.map +1 -1
  34. package/dist/server/config-store.js +2 -2
  35. package/dist/server/config-store.js.map +1 -1
  36. package/dist/server/importers.d.ts +4 -2
  37. package/dist/server/importers.js.map +1 -1
  38. package/dist/server/server.d.ts +5 -0
  39. package/dist/server/server.js +42 -1
  40. package/dist/server/server.js.map +1 -1
  41. package/docs/api.md +5 -5
  42. package/docs/architecture.md +1 -1
  43. package/docs/config.md +25 -19
  44. package/docs/importers.md +41 -15
  45. package/package.json +2 -1
  46. package/ui/dist/assets/index-Bl_bpL_0.js +10 -0
  47. package/ui/dist/assets/index-DsAb-xhK.css +1 -0
  48. package/ui/dist/index.html +2 -2
  49. package/ui/dist/licenses.json +1 -1
  50. package/ui/dist/assets/index-1HdbTkGD.css +0 -1
  51. package/ui/dist/assets/index-CoG5Wu5Q.js +0 -10
package/docs/config.md CHANGED
@@ -121,18 +121,21 @@ there for a new one.
121
121
  }
122
122
  ```
123
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>`) |
124
+ The **device key** (`living-room-lamp`) is the Matter endpoint id: 1–64 characters of `A–Z a–z 0–9 : _ -`,
125
+ starting with a letter or digit. **No `.`**: matter.js uses it as the separator of its endpoint id paths and
126
+ refuses an endpoint id that contains one, so a file with such a key (or endpoint `id`) fails to load with a
127
+ validation error that names it. It keeps the device's endpoint number stable; rename through `name`, never
128
+ through the key.
129
+
130
+ | Key | Default | Meaning |
131
+ | --------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
132
+ | `name` | required | the label controllers show (≤ 32) |
133
+ | `vendor`, `model`, `serial` | — | `BridgedDeviceBasicInformation`; the serial defaults to the key |
134
+ | `enabled` | `true` | a disabled device is not built |
135
+ | `bridge` | assigned | the bridge id; default: assigned once and remembered in `shards.json` |
136
+ | `source` | `{"kind": "manual"}` | where the device came from: `manual`, `z2m`, `ha-discovery`, `preset`; `key`, `version`, `raw`, `baseline`, `orphaned` are the importer's ([importers.md](importers.md)) |
137
+ | `availability` | — | one availability topic (short form) or `{topics: [...], mode}` → `reachable`, see below |
138
+ | `endpoints` | required | at least one; the first is the bridged node, the others are its child endpoints (ids `<key>~<id>`) |
136
139
 
137
140
  ### Availability
138
141
 
@@ -157,7 +160,7 @@ device is unreachable when availability says so or any expired topic has not rep
157
160
 
158
161
  | Key | Default | Meaning |
159
162
  | ------------- | -------- | ---------------------------------------------------------------------------------------------------- |
160
- | `id` | `main` | the endpoint within the device; unique per device |
163
+ | `id` | `main` | the endpoint within the device; unique per device; the device key's characters (no `.`) |
161
164
  | `deviceTypes` | required | matter.js device type names; the first is the endpoint's type, the others are added (`PowerSource`) |
162
165
  | `features` | — | cluster features on top of what the device types require, e.g. `{"PowerSource": ["Battery"]}` |
163
166
  | `attributes` | — | fixed attribute values and defaults, e.g. `{"PowerSource": {"description": "2×AA"}}` |
@@ -313,16 +316,19 @@ A controller's `moveToLevelWithOnOff` publishes the level and, per `onCommandTyp
313
316
  uses `scale: {"from": [0, 100], "to": [10000, 0]}` — or `motion` plus `invoke` mappings for `upOrOpen`,
314
317
  `downOrClose`, `stopMotion` for a state-only one; tilt uses the `…Tilt…` attributes.
315
318
 
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 |
319
+ | Option | Default | Meaning |
320
+ | --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
321
+ | `echoFilter` | `false` | hold back what the bridge publishes right after a command before the cover moves: the old position repeated (until a second report or `reportTimeout`) and the commanded target echoed (until the travel is reported; applied after `reportGap` when nothing follows) — zigbee2mqtt with IKEA FYRTUR/KADRILJ |
322
+ | `reportTimeout` | `30` | seconds a command waits for the first position report (and a stop for the final one) before the movement counts as ended (target snaps to current) |
323
+ | `reportGap` | `3` | seconds after the last position report of a running movement before it counts as ended; a cover with `motion` reports keeps `reportTimeout` here |
324
+ | `tolerance` | `100` | percent100ths within which current and target count as equal |
321
325
 
322
326
  A command sets the target and publishes it; reports drive the current position; `operationalStatus` follows
323
327
  from target vs current; a report while no command is in flight is an external move whose predicted target (the
324
328
  direction's extreme) is written before the current position; after a stop the next report is the final
325
- position.
329
+ position. A cover that reports its travel (about once a second for zigbee2mqtt) stops reporting when it stops:
330
+ `reportGap` ends the movement there, so a move stopped at the cover shows as stopped within seconds; raise it
331
+ for a cover that reports its travel less often.
326
332
 
327
333
  **climate** (`Thermostat`): temperatures in Matter's 0.01 °C (`unit: celsius`). Features follow the mappings:
328
334
  `Heating` with `occupiedHeatingSetpoint`, `Cooling` with `occupiedCoolingSetpoint`, `AutoMode` with both and
package/docs/importers.md CHANGED
@@ -1,11 +1,13 @@
1
1
  # Importers
2
2
 
3
3
  An importer turns a foreign description into ordinary `devices` entries of the manual model
4
- ([config.md](config.md)) with `source: {kind, key, version, raw}`, so the user can edit the result like any
5
- other device. The imported **baseline** and the user's **edits** are kept apart: on a re-sync the baseline is
6
- regenerated from the new description, the edits are reapplied, and an edit on a path the new baseline changed
7
- too is a **conflict** — reported, never silently resolved (the edit wins; the report says what the importer
8
- would have written). A device whose description disappears is marked **orphaned** (`source.orphaned: true`) and
4
+ ([config.md](config.md)) with `source: {kind, key, version, raw, baseline}`, so the user can edit the result like
5
+ any other device. The imported **baseline** and the user's **edits** are kept apart: the baseline the device was
6
+ adopted or last re-synced from is stored with it (`source.baseline`), the edits are the difference between it and
7
+ the device. On a re-sync the baseline is generated anew — from the new description and with the current
8
+ generator, so an improvement of the importer reaches adopted devices like a change of the description — the
9
+ edits are reapplied, and an edit on a path the new baseline changed too is a **conflict** — reported, never
10
+ silently resolved (the edit wins; the report says what the importer would have written). A device whose description disappears is marked **orphaned** (`source.orphaned: true`) and
9
11
  never removed by the importer; removal is the user's click.
10
12
 
11
13
  Importers depend on `model/` and `mqtt/` only ([architecture.md](architecture.md)); the runtime does not know
@@ -33,6 +35,13 @@ subtrees, deletes of removed ones. `applyOps(edits, oldBaseline, newBaseline)` r
33
35
  `resync(oldBaseline, current, newBaseline)` does the whole round and returns the device, the edits and the
34
36
  conflicts; endpoints and mappings keep the new baseline's order, the user's additions follow.
35
37
 
38
+ The old baseline is `source.baseline`: the generated device without its own `source`, stored when the device is
39
+ adopted and replaced by the new baseline on every re-sync (also when nothing changed). A device stored without
40
+ one — adopted by a version before 0.3.2 — has its old baseline regenerated from `source.raw` with the current
41
+ generator instead; what an older generator produced differently then cannot be told from an edit (it counts as
42
+ one and is kept), and the device gets `source.baseline` at its next re-sync. Such a device takes a generator
43
+ improvement made before that only when it is re-adopted (removed and adopted again) or edited by hand.
44
+
36
45
  ## Zigbee2MQTT (`src/importers/z2m/`)
37
46
 
38
47
  Reads the retained `<base>/bridge/devices` and `<base>/bridge/groups` (zigbee2mqtt 1.x and 2.x). Keys:
@@ -87,8 +96,9 @@ of the common controllers is known to offer them for a bridged device.
87
96
  ```
88
97
 
89
98
  `raw` is the description trimmed to what regenerates the baseline (a group's `raw` carries the computed
90
- union instead of the members' descriptions); `version` is `<generator version>.<hash of raw>`. A device
91
- without a usable `raw` is kept as it is on a re-sync and only its `source` refreshed.
99
+ union instead of the members' descriptions); `version` is `<generator version>.<hash of raw>`; `baseline` is
100
+ the device as generated then (see above, left out of the example). A device without a usable `raw` and without a
101
+ `baseline` is kept as it is on a re-sync and only its `source` refreshed.
92
102
 
93
103
  ### The API (`src/importers/z2m/sync.ts`, `source.ts`)
94
104
 
@@ -107,7 +117,7 @@ const {devices, report} = z2m.adopt(config.devices, discovery, {keys?, resync?,
107
117
  // covered?: the key that covers a `covered` entry; twins?: configured devices for the same physical device
108
118
  // adopt(devices, discovery, {keys?, resync?, orphan?, force?, replace?}) — `force` takes the covered ones in `keys`
109
119
  z2m.orphaned(devices); // the keys marked orphaned
110
- z2m.edits(device); // the user's edits against the baseline
120
+ z2m.edits(device); // the user's edits against the stored baseline
111
121
  z2m.generate(raw); // the baseline for a stored `source.raw`
112
122
  ```
113
123
 
@@ -180,7 +190,7 @@ identifiers (`0x…`). The shared sync makes it a rule for both importers, the A
180
190
  | `lock` (`payload_lock/unlock`, `state_locked/unlocked/jammed`) | `DoorLock.lockState` (`Locked`, `Unlocked`, `NotFullyLocked`) |
181
191
  | `fan` (`percentage_*`, `speed_range_max`, `preset_modes`) | `Fan`: `OnOff.onOff`, `percentSetting` `scale [0, speed_range_max] → [0, 100]`, `fanMode` from the preset modes named `off` / `low` / `medium` / `high` / `auto` (`auto` adds the `Auto` feature; the percentage's `None` is `null` while in auto); oscillation and direction listed; `coalesce: 50` |
182
192
  | `valve` (`state_open/opening/closed/closing`, `payload_open/close`) | `WaterValve`: `ValveConfigurationAndControl.currentState`, `open` / `close` |
183
- | `binary_sensor` by `device_class` | door / window / opening / garage_door → `ContactSensor` (inverted: Home Assistant's on is the open contact); motion / occupancy / presence / moving → `OccupancySensor`; moisture → `WaterLeakDetector`; cold → `WaterFreezeDetector`; smoke, carbon_monoxide → `SmokeCoAlarm`; battery → `PowerSource.batChargeLevel`, battery_charging → `batChargeState` (the `Rechargeable` feature); every other class and no class: listed |
193
+ | `binary_sensor` by `device_class` | door / window / opening / garage_door → `ContactSensor` (inverted: Home Assistant's on is the open contact); motion / occupancy / presence / moving → `OccupancySensor`; moisture → `WaterLeakDetector`; cold → `WaterFreezeDetector`; smoke, carbon_monoxide → `SmokeCoAlarm`; battery → `PowerSource.batChargeLevel`, battery_charging → `batChargeState` (the `Rechargeable` feature); every other class: listed; no class: listed until the user chooses one (below) |
184
194
  | `sensor` by `device_class` and `unit_of_measurement` | temperature (°C, °F) → `TemperatureSensor`; humidity → `HumiditySensor`; pressure / atmospheric_pressure (hPa, mbar, kPa, Pa, bar, psi, inHg, mmHg) → `PressureSensor`; illuminance (lx) → `LightSensor`; battery (%) → `PowerSource.batPercentRemaining`; carbon_dioxide, carbon_monoxide (ppm), pm1 / pm25 / pm10 (µg/m³), volatile_organic_compounds(_parts), nitrogen_dioxide, ozone, formaldehyde (ppb; ppm × 1000) → `AirQualitySensor`; aqi → `AirQuality.airQuality` through the US bands; volume_flow_rate (m³/h) → `FlowSensor`; °C / °F / lx without a class count as temperature / illuminance; everything else listed (the electrical classes until electrical measurement exists) |
185
195
  | `event` (`event_types`, payload `{"event_type": …}`) | one `GenericSwitch` per button the event types name (`single` / `double` / `long` / `single_push` / `double_press` …, the shared press-kind table), `extract: event_type` unless a `value_template` renders it |
186
196
  | `device_trigger` / `device_automation` (`topic`, `type`, `subtype`, `payload`) | accumulated per device: one button per `subtype` (Tasmota's `button_1`), the kind from the `type` (`button_short_press`, `button_double_press`, `button_long_press`, …) or, for zigbee2mqtt's `type: action`, from the subtype as the zigbee2mqtt importer reads actions; continuous actions listed |
@@ -206,6 +216,16 @@ switch, the mode string for a climate or a fan, `LOCK` / `UNLOCK` for a lock; `p
206
216
  are the open-percentage for a cover. A `value_template` on a `light` is read as its `state_value_template`
207
217
  (what Tasmota sends).
208
218
 
219
+ **A binary sensor without a `device_class`** has no Matter type of its own: Home Assistant shows it as plain
220
+ on/off, and the importer does not guess one from its name. The Adopt page lists such entities with the entry
221
+ (`unclassed`) and lets the user choose, per entity, one of the classes the table above maps — motion /
222
+ occupancy, opening (contact), moisture, cold, smoke, carbon monoxide, battery, battery charging — or leave it
223
+ unmapped. The entity is then generated as if it had announced that class, and a device that was `unsupported`
224
+ only because of such entities becomes adoptable. The choice is stored in `source.raw.classes` (entity id →
225
+ class); a re-sync reads it from there, so it survives a new announcement and the user's edits are carried over
226
+ as usual. A choice for an entity that disappears or starts announcing a class of its own is dropped. Entities
227
+ with an `entity_category` or `enabled_by_default: false` are not offered.
228
+
209
229
  ### `source`
210
230
 
211
231
  ```json
@@ -213,7 +233,10 @@ are the open-percentage for a cover. A `value_template` on a `light` is read as
213
233
  ```
214
234
 
215
235
  `raw` holds the expanded configs trimmed of what the generator does not read (`icon`, `entity_picture`,
216
- `json_attributes_*`, `configuration_url`, …), in a stable order; `version` is `<generator version>.<hash of raw>`.
236
+ `json_attributes_*`, `configuration_url`, …), in a stable order; `version` is `<generator version>.<hash of raw>`; `baseline` is the device as generated when
237
+ it was adopted or last re-synced (as for zigbee2mqtt, left out of the example).
238
+ `classes` (optional) holds the classes the user chose for binary sensors announced without one, by entity id
239
+ (`{"MotionSensor": "motion"}`).
217
240
 
218
241
  ### The API (`src/importers/ha/sync.ts`, `source.ts`)
219
242
 
@@ -222,11 +245,14 @@ import {ha} from 'mqtt2matter';
222
245
 
223
246
  const source = new ha.HaSource('homeassistant'); // .topics = ['homeassistant/#']; .handle(topic, payload); .load(cache)
224
247
  const discovery = source.discover(); // or ha.discover({entities, prefix, seen})
225
- // Discovery {prefix, items: Discovered[], seen}
226
- // Discovered {key, kind: 'device', name, vendor?, model?, area?, native?, supported, reason?, baseline?, unmapped}
227
-
228
- const report = ha.diff(discovery, config.devices); // SyncEntry[] as the zigbee2mqtt importer's, plus `area` and `native`
229
- const {devices, report} = ha.adopt(config.devices, discovery, {keys?, resync?, orphan?});
248
+ // Discovery {prefix, items: Discovered[], seen, raws?}
249
+ // Discovered {key, kind: 'device', name, vendor?, model?, area?, native?, unclassed?, supported, reason?, baseline?, unmapped}
250
+ // unclassed: [{id, name, class?}] — binary sensors without a device_class, with the class chosen for each
251
+
252
+ const report = ha.diff(discovery, config.devices); // SyncEntry[] as the zigbee2mqtt importer's, plus `area`, `native`, `unclassed`
253
+ const {devices, report} = ha.adopt(config.devices, discovery, {keys?, resync?, orphan?, classes?});
254
+ // classes: {[device key]: {[entity id]: class | null}} — a choice for a binary sensor without a class; null clears it
255
+ ha.BINARY_SENSOR_CLASSES; // {motion: 'OccupancySensor', opening: 'ContactSensor', …}: the classes that can be chosen
230
256
  ha.orphaned(devices);
231
257
  ha.edits(device);
232
258
  ha.generate(raw);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mqtt2matter",
3
- "version": "0.3.1",
3
+ "version": "0.3.2",
4
4
  "description": "Generic MQTT to Matter bridge: compose Matter devices by hand and map them onto MQTT topics with configurable payloads; importers for Zigbee2MQTT and Home Assistant MQTT discovery",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",
@@ -56,6 +56,7 @@
56
56
  "lint": "eslint . && prettier --check .",
57
57
  "lint:fix": "eslint . --fix && prettier --write .",
58
58
  "test": "vitest run",
59
+ "test:ui": "vitest run --config ui/vitest.config.ts",
59
60
  "test:e2e": "playwright test --config ui/playwright.config.ts",
60
61
  "start": "node dist/main.js",
61
62
  "prepack": "npm run build",