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.
- package/CHANGELOG.md +54 -0
- package/README.md +1 -0
- package/dist/config/schema.d.ts +2 -0
- package/dist/families/cover.js +52 -26
- package/dist/families/cover.js.map +1 -1
- package/dist/families/fan.d.ts +2 -0
- package/dist/families/fan.js +17 -0
- package/dist/families/fan.js.map +1 -1
- package/dist/families/index.d.ts +2 -0
- package/dist/families/index.js +2 -1
- package/dist/families/index.js.map +1 -1
- package/dist/importers/ha/generate.d.ts +13 -1
- package/dist/importers/ha/generate.js +47 -4
- package/dist/importers/ha/generate.js.map +1 -1
- package/dist/importers/ha/sync.d.ts +11 -1
- package/dist/importers/ha/sync.js +88 -26
- package/dist/importers/ha/sync.js.map +1 -1
- package/dist/importers/sync.d.ts +18 -1
- package/dist/importers/sync.js +35 -6
- package/dist/importers/sync.js.map +1 -1
- package/dist/importers/z2m/generate.js +1 -1
- package/dist/importers/z2m/generate.js.map +1 -1
- package/dist/matter/bridge.js +1 -1
- package/dist/matter/bridge.js.map +1 -1
- package/dist/matter/ids.d.ts +1 -1
- package/dist/matter/ids.js +2 -2
- package/dist/matter/ids.js.map +1 -1
- package/dist/model/options.d.ts +2 -0
- package/dist/model/options.js +8 -3
- package/dist/model/options.js.map +1 -1
- package/dist/model/schema.d.ts +13 -1
- package/dist/model/schema.js +16 -4
- package/dist/model/schema.js.map +1 -1
- package/dist/server/config-store.js +2 -2
- package/dist/server/config-store.js.map +1 -1
- package/dist/server/importers.d.ts +4 -2
- package/dist/server/importers.js.map +1 -1
- package/dist/server/server.d.ts +5 -0
- package/dist/server/server.js +42 -1
- package/dist/server/server.js.map +1 -1
- package/docs/api.md +5 -5
- package/docs/architecture.md +1 -1
- package/docs/config.md +25 -19
- package/docs/importers.md +41 -15
- package/package.json +2 -1
- package/ui/dist/assets/index-Bl_bpL_0.js +10 -0
- package/ui/dist/assets/index-DsAb-xhK.css +1 -0
- package/ui/dist/index.html +2 -2
- package/ui/dist/licenses.json +1 -1
- package/ui/dist/assets/index-1HdbTkGD.css +0 -1
- 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
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
|
131
|
-
|
|
|
132
|
-
| `
|
|
133
|
-
| `
|
|
134
|
-
| `
|
|
135
|
-
| `
|
|
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
|
|
319
|
-
| `reportTimeout` | `30` | seconds
|
|
320
|
-
| `
|
|
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
|
|
5
|
-
other device. The imported **baseline** and the user's **edits** are kept apart:
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
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
|
|
91
|
-
|
|
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
|
|
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
|
-
|
|
229
|
-
const
|
|
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.
|
|
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",
|