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.
Files changed (279) hide show
  1. package/CHANGELOG.md +76 -0
  2. package/LICENSE +202 -0
  3. package/NOTICE +23 -0
  4. package/README.md +172 -2
  5. package/dist/app.d.ts +34 -0
  6. package/dist/app.js +157 -0
  7. package/dist/app.js.map +1 -0
  8. package/dist/commands/import-z2m.d.ts +20 -0
  9. package/dist/commands/import-z2m.js +173 -0
  10. package/dist/commands/import-z2m.js.map +1 -0
  11. package/dist/commands/install.d.ts +41 -0
  12. package/dist/commands/install.js +250 -0
  13. package/dist/commands/install.js.map +1 -0
  14. package/dist/commands/update.d.ts +14 -0
  15. package/dist/commands/update.js +109 -0
  16. package/dist/commands/update.js.map +1 -0
  17. package/dist/config/index.d.ts +2 -0
  18. package/dist/config/index.js +3 -0
  19. package/dist/config/index.js.map +1 -0
  20. package/dist/config/load.d.ts +57 -0
  21. package/dist/config/load.js +137 -0
  22. package/dist/config/load.js.map +1 -0
  23. package/dist/config/schema.d.ts +496 -0
  24. package/dist/config/schema.js +115 -0
  25. package/dist/config/schema.js.map +1 -0
  26. package/dist/engine/payload.d.ts +94 -0
  27. package/dist/engine/payload.js +515 -0
  28. package/dist/engine/payload.js.map +1 -0
  29. package/dist/engine/runtime.d.ts +79 -0
  30. package/dist/engine/runtime.js +438 -0
  31. package/dist/engine/runtime.js.map +1 -0
  32. package/dist/engine/template.d.ts +20 -0
  33. package/dist/engine/template.js +264 -0
  34. package/dist/engine/template.js.map +1 -0
  35. package/dist/engine/units.d.ts +9 -0
  36. package/dist/engine/units.js +42 -0
  37. package/dist/engine/units.js.map +1 -0
  38. package/dist/families/climate.d.ts +11 -0
  39. package/dist/families/climate.js +68 -0
  40. package/dist/families/climate.js.map +1 -0
  41. package/dist/families/color.d.ts +30 -0
  42. package/dist/families/color.js +152 -0
  43. package/dist/families/color.js.map +1 -0
  44. package/dist/families/cover.d.ts +17 -0
  45. package/dist/families/cover.js +308 -0
  46. package/dist/families/cover.js.map +1 -0
  47. package/dist/families/fan.d.ts +16 -0
  48. package/dist/families/fan.js +154 -0
  49. package/dist/families/fan.js.map +1 -0
  50. package/dist/families/index.d.ts +32 -0
  51. package/dist/families/index.js +162 -0
  52. package/dist/families/index.js.map +1 -0
  53. package/dist/families/light.d.ts +36 -0
  54. package/dist/families/light.js +258 -0
  55. package/dist/families/light.js.map +1 -0
  56. package/dist/families/lock.d.ts +10 -0
  57. package/dist/families/lock.js +31 -0
  58. package/dist/families/lock.js.map +1 -0
  59. package/dist/families/on-off.d.ts +7 -0
  60. package/dist/families/on-off.js +56 -0
  61. package/dist/families/on-off.js.map +1 -0
  62. package/dist/families/power-source.d.ts +12 -0
  63. package/dist/families/power-source.js +60 -0
  64. package/dist/families/power-source.js.map +1 -0
  65. package/dist/families/registry.d.ts +40 -0
  66. package/dist/families/registry.js +72 -0
  67. package/dist/families/registry.js.map +1 -0
  68. package/dist/families/rvc.d.ts +40 -0
  69. package/dist/families/rvc.js +83 -0
  70. package/dist/families/rvc.js.map +1 -0
  71. package/dist/families/switch.d.ts +19 -0
  72. package/dist/families/switch.js +94 -0
  73. package/dist/families/switch.js.map +1 -0
  74. package/dist/importers/actions.d.ts +19 -0
  75. package/dist/importers/actions.js +98 -0
  76. package/dist/importers/actions.js.map +1 -0
  77. package/dist/importers/ha/areas.d.ts +6 -0
  78. package/dist/importers/ha/areas.js +279 -0
  79. package/dist/importers/ha/areas.js.map +1 -0
  80. package/dist/importers/ha/generate.d.ts +51 -0
  81. package/dist/importers/ha/generate.js +1376 -0
  82. package/dist/importers/ha/generate.js.map +1 -0
  83. package/dist/importers/ha/index.d.ts +6 -0
  84. package/dist/importers/ha/index.js +7 -0
  85. package/dist/importers/ha/index.js.map +1 -0
  86. package/dist/importers/ha/source.d.ts +36 -0
  87. package/dist/importers/ha/source.js +95 -0
  88. package/dist/importers/ha/source.js.map +1 -0
  89. package/dist/importers/ha/sync.d.ts +29 -0
  90. package/dist/importers/ha/sync.js +132 -0
  91. package/dist/importers/ha/sync.js.map +1 -0
  92. package/dist/importers/ha/templates.d.ts +18 -0
  93. package/dist/importers/ha/templates.js +285 -0
  94. package/dist/importers/ha/templates.js.map +1 -0
  95. package/dist/importers/ha/types.d.ts +78 -0
  96. package/dist/importers/ha/types.js +479 -0
  97. package/dist/importers/ha/types.js.map +1 -0
  98. package/dist/importers/index.d.ts +5 -0
  99. package/dist/importers/index.js +8 -0
  100. package/dist/importers/index.js.map +1 -0
  101. package/dist/importers/patch.d.ts +50 -0
  102. package/dist/importers/patch.js +224 -0
  103. package/dist/importers/patch.js.map +1 -0
  104. package/dist/importers/sync.d.ts +112 -0
  105. package/dist/importers/sync.js +220 -0
  106. package/dist/importers/sync.js.map +1 -0
  107. package/dist/importers/twins.d.ts +10 -0
  108. package/dist/importers/twins.js +34 -0
  109. package/dist/importers/twins.js.map +1 -0
  110. package/dist/importers/z2m/generate.d.ts +81 -0
  111. package/dist/importers/z2m/generate.js +1171 -0
  112. package/dist/importers/z2m/generate.js.map +1 -0
  113. package/dist/importers/z2m/index.d.ts +5 -0
  114. package/dist/importers/z2m/index.js +6 -0
  115. package/dist/importers/z2m/index.js.map +1 -0
  116. package/dist/importers/z2m/source.d.ts +18 -0
  117. package/dist/importers/z2m/source.js +46 -0
  118. package/dist/importers/z2m/source.js.map +1 -0
  119. package/dist/importers/z2m/sync.d.ts +29 -0
  120. package/dist/importers/z2m/sync.js +92 -0
  121. package/dist/importers/z2m/sync.js.map +1 -0
  122. package/dist/importers/z2m/types.d.ts +72 -0
  123. package/dist/importers/z2m/types.js +46 -0
  124. package/dist/importers/z2m/types.js.map +1 -0
  125. package/dist/index.d.ts +5 -0
  126. package/dist/index.js +7 -0
  127. package/dist/index.js.map +1 -0
  128. package/dist/log.d.ts +17 -0
  129. package/dist/log.js +54 -0
  130. package/dist/log.js.map +1 -0
  131. package/dist/main.d.ts +2 -0
  132. package/dist/main.js +202 -0
  133. package/dist/main.js.map +1 -0
  134. package/dist/matter/bridge.d.ts +113 -0
  135. package/dist/matter/bridge.js +467 -0
  136. package/dist/matter/bridge.js.map +1 -0
  137. package/dist/matter/check.d.ts +11 -0
  138. package/dist/matter/check.js +116 -0
  139. package/dist/matter/check.js.map +1 -0
  140. package/dist/matter/cluster-defaults.d.ts +6 -0
  141. package/dist/matter/cluster-defaults.js +63 -0
  142. package/dist/matter/cluster-defaults.js.map +1 -0
  143. package/dist/matter/commissioning.d.ts +21 -0
  144. package/dist/matter/commissioning.js +88 -0
  145. package/dist/matter/commissioning.js.map +1 -0
  146. package/dist/matter/device-types.d.ts +44 -0
  147. package/dist/matter/device-types.js +230 -0
  148. package/dist/matter/device-types.js.map +1 -0
  149. package/dist/matter/ids.d.ts +31 -0
  150. package/dist/matter/ids.js +83 -0
  151. package/dist/matter/ids.js.map +1 -0
  152. package/dist/matter/index.d.ts +7 -0
  153. package/dist/matter/index.js +8 -0
  154. package/dist/matter/index.js.map +1 -0
  155. package/dist/matter/node-manager.d.ts +39 -0
  156. package/dist/matter/node-manager.js +161 -0
  157. package/dist/matter/node-manager.js.map +1 -0
  158. package/dist/matter/shards.d.ts +26 -0
  159. package/dist/matter/shards.js +93 -0
  160. package/dist/matter/shards.js.map +1 -0
  161. package/dist/model/attribute.d.ts +18 -0
  162. package/dist/model/attribute.js +28 -0
  163. package/dist/model/attribute.js.map +1 -0
  164. package/dist/model/catalog.d.ts +79 -0
  165. package/dist/model/catalog.js +223 -0
  166. package/dist/model/catalog.js.map +1 -0
  167. package/dist/model/index.d.ts +7 -0
  168. package/dist/model/index.js +8 -0
  169. package/dist/model/index.js.map +1 -0
  170. package/dist/model/migrate.d.ts +4 -0
  171. package/dist/model/migrate.js +39 -0
  172. package/dist/model/migrate.js.map +1 -0
  173. package/dist/model/options.d.ts +102 -0
  174. package/dist/model/options.js +88 -0
  175. package/dist/model/options.js.map +1 -0
  176. package/dist/model/presets.d.ts +37 -0
  177. package/dist/model/presets.js +105 -0
  178. package/dist/model/presets.js.map +1 -0
  179. package/dist/model/schema.d.ts +1747 -0
  180. package/dist/model/schema.js +243 -0
  181. package/dist/model/schema.js.map +1 -0
  182. package/dist/model/validate.d.ts +21 -0
  183. package/dist/model/validate.js +484 -0
  184. package/dist/model/validate.js.map +1 -0
  185. package/dist/mqtt/client.d.ts +38 -0
  186. package/dist/mqtt/client.js +94 -0
  187. package/dist/mqtt/client.js.map +1 -0
  188. package/dist/mqtt/index.d.ts +2 -0
  189. package/dist/mqtt/index.js +3 -0
  190. package/dist/mqtt/index.js.map +1 -0
  191. package/dist/mqtt/topic-cache.d.ts +20 -0
  192. package/dist/mqtt/topic-cache.js +58 -0
  193. package/dist/mqtt/topic-cache.js.map +1 -0
  194. package/dist/server/auth.d.ts +59 -0
  195. package/dist/server/auth.js +185 -0
  196. package/dist/server/auth.js.map +1 -0
  197. package/dist/server/catalog.d.ts +52 -0
  198. package/dist/server/catalog.js +96 -0
  199. package/dist/server/catalog.js.map +1 -0
  200. package/dist/server/compact.d.ts +3 -0
  201. package/dist/server/compact.js +105 -0
  202. package/dist/server/compact.js.map +1 -0
  203. package/dist/server/config-store.d.ts +36 -0
  204. package/dist/server/config-store.js +155 -0
  205. package/dist/server/config-store.js.map +1 -0
  206. package/dist/server/events.d.ts +50 -0
  207. package/dist/server/events.js +71 -0
  208. package/dist/server/events.js.map +1 -0
  209. package/dist/server/http.d.ts +27 -0
  210. package/dist/server/http.js +168 -0
  211. package/dist/server/http.js.map +1 -0
  212. package/dist/server/importers.d.ts +40 -0
  213. package/dist/server/importers.js +75 -0
  214. package/dist/server/importers.js.map +1 -0
  215. package/dist/server/index.d.ts +6 -0
  216. package/dist/server/index.js +8 -0
  217. package/dist/server/index.js.map +1 -0
  218. package/dist/server/log-buffer.d.ts +22 -0
  219. package/dist/server/log-buffer.js +55 -0
  220. package/dist/server/log-buffer.js.map +1 -0
  221. package/dist/server/presets.d.ts +17 -0
  222. package/dist/server/presets.js +55 -0
  223. package/dist/server/presets.js.map +1 -0
  224. package/dist/server/preview.d.ts +19 -0
  225. package/dist/server/preview.js +121 -0
  226. package/dist/server/preview.js.map +1 -0
  227. package/dist/server/server.d.ts +107 -0
  228. package/dist/server/server.js +810 -0
  229. package/dist/server/server.js.map +1 -0
  230. package/dist/server/update.d.ts +60 -0
  231. package/dist/server/update.js +191 -0
  232. package/dist/server/update.js.map +1 -0
  233. package/docs/api.md +128 -0
  234. package/docs/architecture.md +121 -0
  235. package/docs/config.md +538 -0
  236. package/docs/importers.md +241 -0
  237. package/example/mqtt2matter.json +276 -0
  238. package/package.json +90 -4
  239. package/presets/mqtt-smarthome/button.json +47 -0
  240. package/presets/mqtt-smarthome/contact.json +37 -0
  241. package/presets/mqtt-smarthome/cover.json +50 -0
  242. package/presets/mqtt-smarthome/dimmer.json +57 -0
  243. package/presets/mqtt-smarthome/humidity.json +38 -0
  244. package/presets/mqtt-smarthome/light.json +47 -0
  245. package/presets/mqtt-smarthome/occupancy.json +46 -0
  246. package/presets/mqtt-smarthome/switch.json +47 -0
  247. package/presets/mqtt-smarthome/temperature.json +38 -0
  248. package/presets/openbeken/color-light.json +64 -0
  249. package/presets/openbeken/ct-light.json +51 -0
  250. package/presets/openbeken/dimmer.json +47 -0
  251. package/presets/openbeken/humidity.json +37 -0
  252. package/presets/openbeken/relay.json +40 -0
  253. package/presets/openbeken/temperature.json +41 -0
  254. package/presets/shelly-gen1/dimmer.json +48 -0
  255. package/presets/shelly-gen1/door-window.json +43 -0
  256. package/presets/shelly-gen1/ht.json +43 -0
  257. package/presets/shelly-gen1/relay-pm.json +60 -0
  258. package/presets/shelly-gen1/relay.json +36 -0
  259. package/presets/shelly-gen1/roller.json +52 -0
  260. package/presets/shelly-gen2/cover.json +68 -0
  261. package/presets/shelly-gen2/dimmer.json +61 -0
  262. package/presets/shelly-gen2/ht.json +47 -0
  263. package/presets/shelly-gen2/i4.json +82 -0
  264. package/presets/shelly-gen2/switch-pm.json +101 -0
  265. package/presets/shelly-gen2/switch.json +47 -0
  266. package/presets/tasmota/climate.json +52 -0
  267. package/presets/tasmota/color-light.json +63 -0
  268. package/presets/tasmota/ct-light.json +50 -0
  269. package/presets/tasmota/dimmer.json +45 -0
  270. package/presets/tasmota/relay.json +39 -0
  271. package/presets/tasmota/shutter.json +46 -0
  272. package/presets/tasmota/temperature-humidity.json +42 -0
  273. package/presets/tasmota/temperature.json +32 -0
  274. package/presets/valetudo/vacuum.json +103 -0
  275. package/presets/wled/dimmer.json +46 -0
  276. package/presets/wled/light.json +59 -0
  277. package/ui/dist/assets/index-BDtT6bdH.js +10 -0
  278. package/ui/dist/assets/index-CHiG-aoU.css +1 -0
  279. package/ui/dist/index.html +18 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,76 @@
1
+ # Changelog
2
+
3
+ ## 0.2.0
4
+
5
+ - **Presets for the mqtt-smarthome convention**: switch, light, dimmer, cover, contact, occupancy,
6
+ temperature, humidity and button for any adapter that publishes `<name>/status/<item>` (plain values and
7
+ `{val, ts, lc}` alike), takes `<name>/set/<item>` and reports `<name>/connected`.
8
+ - **Presets for WLED**: a colour light (brightness, RGB colour, colour temperature to the main segment) and a
9
+ dimmer for single-colour strips, over WLED's own MQTT topics with its `status` topic as availability.
10
+ - **Presets for Shelly Gen2/Gen3** (Plus, Pro, Gen3): switch, switch with power metering (an electrical
11
+ sensor with active power, voltage and current), cover, dimmer, Plus H&T and Plus i4 — the component status
12
+ from the "Generic status update" topics, commands as RPC, the status requested at start.
13
+ - **Presets for first-generation Shelly devices**: relay, relay with power, roller (2.5), Dimmer 1/2, H&T and
14
+ Door/Window, over the `shellies/<id>/…` topics; mains-powered ones ask for their state at start.
15
+ - **More Tasmota presets**: dimmer, CT light, colour light (RGB/RGBW/RGBCCT with the colour mode from the
16
+ channels), shutter, and temperature, temperature/humidity and climate (with pressure) sensors from
17
+ `tele/<topic>/SENSOR`. `tasmota/relay` takes an optional relay index for `POWER1`…`POWERn` and asks for the
18
+ state at start.
19
+ - **Robot vacuums**: a `RoboticVacuumCleaner` family — run mode Idle/Cleaning, operational state, pause,
20
+ resume and go home routed to mappings — and a **Valetudo preset** over Valetudo's own MQTT topics with the
21
+ battery. Bridged, it shows in Google Home and Home Assistant; Apple Home and Alexa want a vacuum as a Matter
22
+ node of its own, which mqtt2matter does not offer yet.
23
+ - The model knows a derived cluster's own enum values and the commands it takes over from its base
24
+ (`RvcOperationalState`: `Docked`, `SeekingCharger`, `pause`, `resume`), and a rechargeable battery gets its
25
+ mandatory charge state by default.
26
+ - **Presets for OpenBeken** (Tuya/BK7231 and similar): relay channel, dimmer, CT and colour light, temperature and
27
+ humidity channels with their divisor.
28
+ - Templates: `int` takes Home Assistant's default and base, `'ff' | int(0, 16)` reads hexadecimal.
29
+ - A status value that a message does not carry (an extract path that is missing, a template that renders
30
+ nothing) is logged at debug instead of as a warning: topics several mappings share — Tasmota's `RESULT`, a
31
+ partial JSON report — carry only some of the values at a time.
32
+ - **Fans with an auto mode** (IKEA STARKVIND through Zigbee2MQTT or Home Assistant discovery): `auto` is
33
+ Matter's Auto fan mode — both importers now set the `Auto` feature, so it is no longer refused — and the
34
+ percent setting is `null` while in auto instead of a warning per message. A status `map` or `default` may be
35
+ `null` for a nullable attribute, a template's `None` is read as `null`, and a `null` for an attribute that
36
+ cannot be null is skipped quietly. Adopted fans show as updated on the next sync.
37
+ - Every shipped preset is tested: applied, validated, through the strict dry run, and against an in-process
38
+ broker with its documented status and command messages.
39
+
40
+ ## 0.1.0
41
+
42
+ The first release: a generic MQTT → Matter bridge on matter.js 0.18.
43
+
44
+ - **The model.** Devices composed from every device type matter.js ships (plus `PowerSource`), several per
45
+ endpoint, child endpoints, cluster features and attribute defaults from the Matter data model — no
46
+ hand-kept table of device types. A **mapping** joins a Matter attribute, command (`invoke`) or event with
47
+ MQTT: a status half (device → Matter) and a command half (Matter → device). The configuration schema
48
+ (`docs/config.md`) is frozen; later versions migrate files on load.
49
+ - **The payload engine**, in both directions: extract (JSON paths), Jinja templates in Home Assistant's dialect
50
+ (through `@huggingface/jinja`, with the Home Assistant filters it lacks added), map, explicit types, units,
51
+ scale, offset, invert, round, wrap, format, fixed payloads, `coalesce` per endpoint, `get` at start,
52
+ `expire`, and a `codec` escape hatch.
53
+ - **The families**: light (level with on-command ordering, colour temperature, xy, hue/saturation, RGB-only
54
+ devices, colour mode arbitration), cover (a position state machine with report timeout, external moves and
55
+ an echo filter; state-only covers; tilt), climate, lock, fan, buttons (GenericSwitch events), momentary
56
+ outlets (`options.onOff.momentary`), sensors, power source, availability (`all` / `any` / `latest`) →
57
+ reachable.
58
+ - **Validation**: static checks against the Matter data model, and `mqtt2matter --check`, a strict dry run
59
+ that builds every device in a throw-away matter.js node.
60
+ - **Zigbee2MQTT importer**: `bridge/devices` and `bridge/groups` become ordinary devices — exposes to device
61
+ types and mappings per endpoint, `action` enums to buttons, battery to a power source, groups as the union
62
+ of their members, scenes as momentary outlets. A re-sync carries your edits over, reports conflicts instead
63
+ of resolving them, and marks devices that left Zigbee2MQTT as orphaned without removing them. From the UI
64
+ or `mqtt2matter --import-z2m`.
65
+ - **Home Assistant MQTT discovery importer**: the per-entity and the device-based form, abbreviations, `~`,
66
+ availability modes; one Matter device per Home Assistant device; templates where the engine can run them,
67
+ listed where it cannot; `suggested_area` as a Matter Common Area tag; what has no Matter equivalent is
68
+ listed, not dropped. A device that Zigbee2MQTT also describes natively is a duplicate and adopted once.
69
+ - **The web UI** (port 8282): devices, the mapping editor with a live preview of every step and a topic picker
70
+ over the live topic tree, presets, the Adopt page, bridges with QR code, pairing code and fabrics, the live
71
+ MQTT view, the log, the dry run, import/export, settings. English and German, light and dark. A login
72
+ (`server.auth`: a password, or a reverse proxy's user header); **the default is no login** — keep the port
73
+ on a trusted network or set one.
74
+ - **Running as a service**: `mqtt2matter --install` sets up a systemd service under a user of its own
75
+ (configuration in `/etc/mqtt2matter`, the Matter storage in `/var/lib/mqtt2matter`), `--uninstall` removes
76
+ it and keeps both. Restart and update from the UI. The pairing code stays the same across restarts.
package/LICENSE ADDED
@@ -0,0 +1,202 @@
1
+
2
+ Apache License
3
+ Version 2.0, January 2004
4
+ http://www.apache.org/licenses/
5
+
6
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
7
+
8
+ 1. Definitions.
9
+
10
+ "License" shall mean the terms and conditions for use, reproduction,
11
+ and distribution as defined by Sections 1 through 9 of this document.
12
+
13
+ "Licensor" shall mean the copyright owner or entity authorized by
14
+ the copyright owner that is granting the License.
15
+
16
+ "Legal Entity" shall mean the union of the acting entity and all
17
+ other entities that control, are controlled by, or are under common
18
+ control with that entity. For the purposes of this definition,
19
+ "control" means (i) the power, direct or indirect, to cause the
20
+ direction or management of such entity, whether by contract or
21
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
22
+ outstanding shares, or (iii) beneficial ownership of such entity.
23
+
24
+ "You" (or "Your") shall mean an individual or Legal Entity
25
+ exercising permissions granted by this License.
26
+
27
+ "Source" form shall mean the preferred form for making modifications,
28
+ including but not limited to software source code, documentation
29
+ source, and configuration files.
30
+
31
+ "Object" form shall mean any form resulting from mechanical
32
+ transformation or translation of a Source form, including but
33
+ not limited to compiled object code, generated documentation,
34
+ and conversions to other media types.
35
+
36
+ "Work" shall mean the work of authorship, whether in Source or
37
+ Object form, made available under the License, as indicated by a
38
+ copyright notice that is included in or attached to the work
39
+ (an example is provided in the Appendix below).
40
+
41
+ "Derivative Works" shall mean any work, whether in Source or Object
42
+ form, that is based on (or derived from) the Work and for which the
43
+ editorial revisions, annotations, elaborations, or other modifications
44
+ represent, as a whole, an original work of authorship. For the purposes
45
+ of this License, Derivative Works shall not include works that remain
46
+ separable from, or merely link (or bind by name) to the interfaces of,
47
+ the Work and Derivative Works thereof.
48
+
49
+ "Contribution" shall mean any work of authorship, including
50
+ the original version of the Work and any modifications or additions
51
+ to that Work or Derivative Works thereof, that is intentionally
52
+ submitted to Licensor for inclusion in the Work by the copyright owner
53
+ or by an individual or Legal Entity authorized to submit on behalf of
54
+ the copyright owner. For the purposes of this definition, "submitted"
55
+ means any form of electronic, verbal, or written communication sent
56
+ to the Licensor or its representatives, including but not limited to
57
+ communication on electronic mailing lists, source code control systems,
58
+ and issue tracking systems that are managed by, or on behalf of, the
59
+ Licensor for the purpose of discussing and improving the Work, but
60
+ excluding communication that is conspicuously marked or otherwise
61
+ designated in writing by the copyright owner as "Not a Contribution."
62
+
63
+ "Contributor" shall mean Licensor and any individual or Legal Entity
64
+ on behalf of whom a Contribution has been received by Licensor and
65
+ subsequently incorporated within the Work.
66
+
67
+ 2. Grant of Copyright License. Subject to the terms and conditions of
68
+ this License, each Contributor hereby grants to You a perpetual,
69
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
70
+ copyright license to reproduce, prepare Derivative Works of,
71
+ publicly display, publicly perform, sublicense, and distribute the
72
+ Work and such Derivative Works in Source or Object form.
73
+
74
+ 3. Grant of Patent License. Subject to the terms and conditions of
75
+ this License, each Contributor hereby grants to You a perpetual,
76
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
77
+ (except as stated in this section) patent license to make, have made,
78
+ use, offer to sell, sell, import, and otherwise transfer the Work,
79
+ where such license applies only to those patent claims licensable
80
+ by such Contributor that are necessarily infringed by their
81
+ Contribution(s) alone or by combination of their Contribution(s)
82
+ with the Work to which such Contribution(s) was submitted. If You
83
+ institute patent litigation against any entity (including a
84
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
85
+ or a Contribution incorporated within the Work constitutes direct
86
+ or contributory patent infringement, then any patent licenses
87
+ granted to You under this License for that Work shall terminate
88
+ as of the date such litigation is filed.
89
+
90
+ 4. Redistribution. You may reproduce and distribute copies of the
91
+ Work or Derivative Works thereof in any medium, with or without
92
+ modifications, and in Source or Object form, provided that You
93
+ meet the following conditions:
94
+
95
+ (a) You must give any other recipients of the Work or
96
+ Derivative Works a copy of this License; and
97
+
98
+ (b) You must cause any modified files to carry prominent notices
99
+ stating that You changed the files; and
100
+
101
+ (c) You must retain, in the Source form of any Derivative Works
102
+ that You distribute, all copyright, patent, trademark, and
103
+ attribution notices from the Source form of the Work,
104
+ excluding those notices that do not pertain to any part of
105
+ the Derivative Works; and
106
+
107
+ (d) If the Work includes a "NOTICE" text file as part of its
108
+ distribution, then any Derivative Works that You distribute must
109
+ include a readable copy of the attribution notices contained
110
+ within such NOTICE file, excluding those notices that do not
111
+ pertain to any part of the Derivative Works, in at least one
112
+ of the following places: within a NOTICE text file distributed
113
+ as part of the Derivative Works; within the Source form or
114
+ documentation, if provided along with the Derivative Works; or,
115
+ within a display generated by the Derivative Works, if and
116
+ wherever such third-party notices normally appear. The contents
117
+ of the NOTICE file are for informational purposes only and
118
+ do not modify the License. You may add Your own attribution
119
+ notices within Derivative Works that You distribute, alongside
120
+ or as an addendum to the NOTICE text from the Work, provided
121
+ that such additional attribution notices cannot be construed
122
+ as modifying the License.
123
+
124
+ You may add Your own copyright statement to Your modifications and
125
+ may provide additional or different license terms and conditions
126
+ for use, reproduction, or distribution of Your modifications, or
127
+ for any such Derivative Works as a whole, provided Your use,
128
+ reproduction, and distribution of the Work otherwise complies with
129
+ the conditions stated in this License.
130
+
131
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
132
+ any Contribution intentionally submitted for inclusion in the Work
133
+ by You to the Licensor shall be under the terms and conditions of
134
+ this License, without any additional terms or conditions.
135
+ Notwithstanding the above, nothing herein shall supersede or modify
136
+ the terms of any separate license agreement you may have executed
137
+ with Licensor regarding such Contributions.
138
+
139
+ 6. Trademarks. This License does not grant permission to use the trade
140
+ names, trademarks, service marks, or product names of the Licensor,
141
+ except as required for reasonable and customary use in describing the
142
+ origin of the Work and reproducing the content of the NOTICE file.
143
+
144
+ 7. Disclaimer of Warranty. Unless required by applicable law or
145
+ agreed to in writing, Licensor provides the Work (and each
146
+ Contributor provides its Contributions) on an "AS IS" BASIS,
147
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148
+ implied, including, without limitation, any warranties or conditions
149
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150
+ PARTICULAR PURPOSE. You are solely responsible for determining the
151
+ appropriateness of using or redistributing the Work and assume any
152
+ risks associated with Your exercise of permissions under this License.
153
+
154
+ 8. Limitation of Liability. In no event and under no legal theory,
155
+ whether in tort (including negligence), contract, or otherwise,
156
+ unless required by applicable law (such as deliberate and grossly
157
+ negligent acts) or agreed to in writing, shall any Contributor be
158
+ liable to You for damages, including any direct, indirect, special,
159
+ incidental, or consequential damages of any character arising as a
160
+ result of this License or out of the use or inability to use the
161
+ Work (including but not limited to damages for loss of goodwill,
162
+ work stoppage, computer failure or malfunction, or any and all
163
+ other commercial damages or losses), even if such Contributor
164
+ has been advised of the possibility of such damages.
165
+
166
+ 9. Accepting Warranty or Additional Liability. While redistributing
167
+ the Work or Derivative Works thereof, You may choose to offer,
168
+ and charge a fee for, acceptance of support, warranty, indemnity,
169
+ or other liability obligations and/or rights consistent with this
170
+ License. However, in accepting such obligations, You may act only
171
+ on Your own behalf and on Your sole responsibility, not on behalf
172
+ of any other Contributor, and only if You agree to indemnify,
173
+ defend, and hold each Contributor harmless for any liability
174
+ incurred by, or claims asserted against, such Contributor by reason
175
+ of your accepting any such warranty or additional liability.
176
+
177
+ END OF TERMS AND CONDITIONS
178
+
179
+ APPENDIX: How to apply the Apache License to your work.
180
+
181
+ To apply the Apache License to your work, attach the following
182
+ boilerplate notice, with the fields enclosed by brackets "[]"
183
+ replaced with your own identifying information. (Don't include
184
+ the brackets!) The text should be enclosed in the appropriate
185
+ comment syntax for the file format. We also recommend that a
186
+ file or class name and description of purpose be included on the
187
+ same "printed page" as the copyright notice for easier
188
+ identification within third-party archives.
189
+
190
+ Copyright [yyyy] [name of copyright owner]
191
+
192
+ Licensed under the Apache License, Version 2.0 (the "License");
193
+ you may not use this file except in compliance with the License.
194
+ You may obtain a copy of the License at
195
+
196
+ http://www.apache.org/licenses/LICENSE-2.0
197
+
198
+ Unless required by applicable law or agreed to in writing, software
199
+ distributed under the License is distributed on an "AS IS" BASIS,
200
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201
+ See the License for the specific language governing permissions and
202
+ limitations under the License.
package/NOTICE ADDED
@@ -0,0 +1,23 @@
1
+ mqtt2matter
2
+ Copyright 2026 Sebastian Raff
3
+
4
+ Licensed under the Apache License, Version 2.0 (see LICENSE).
5
+
6
+ This product builds on matter.js (https://github.com/matter-js/matter.js, Apache-2.0) and
7
+ MQTT.js (https://github.com/mqttjs/MQTT.js, MIT) as dependencies; it contains no copied code
8
+ from either, nor from matterbridge or its plugins.
9
+
10
+ The test fixtures test/fixtures/z2m/bridge-devices.json and bridge-groups.json are copied
11
+ unchanged from matterbridge-zigbee2mqtt (https://github.com/Luligu/matterbridge-zigbee2mqtt,
12
+ src/mock/, commit c72dd312d0899e930aec220e67b8959f10221eb0), Copyright 2023-2025 Luca Liguori,
13
+ licensed under the Apache License, Version 2.0. They are used as a test corpus only.
14
+ test/fixtures/z2m/starkvind.json is written by hand: an air purifier with numbered fan speeds in the
15
+ shape zigbee2mqtt's bridge/devices documents, its values as the maintainer's own device reports them
16
+ (see test/fixtures/ha/zigbee2mqtt.json); nothing is copied.
17
+
18
+ The Home Assistant MQTT discovery test corpus in test/fixtures/ha/ is documented in
19
+ test/fixtures/ha/README.md: captures of the maintainer's own devices (ESPHome, zigbee2mqtt's own
20
+ discovery, his MQTT adapters), anonymised, and payloads written by hand in the shape the documentation
21
+ of Tasmota, Shelly, Z-Wave JS UI and OpenMQTTGateway describes; nothing is copied from those projects.
22
+ The abbreviation tables in src/importers/ha/types.ts list the key names of Home Assistant's MQTT
23
+ integration (https://github.com/home-assistant/core, Apache-2.0), which are the protocol, not code.
package/README.md CHANGED
@@ -1,3 +1,173 @@
1
- # Temporary Holding Version
1
+ # mqtt2matter
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ A generic MQTT → Matter bridge. Compose Matter devices by hand — device types, endpoints, clusters,
4
+ attributes — and map them onto MQTT topics with configurable payloads: JSON paths, value maps, scaling,
5
+ templates. Importers add devices with one click: Zigbee2MQTT natively (`bridge/devices`) and anything that
6
+ announces itself through Home Assistant MQTT discovery (ESPHome, Tasmota, Shelly, Zwave-JS-UI, …). Built on
7
+ [matter.js](https://github.com/matter-js/matter.js) and [MQTT.js](https://github.com/mqttjs/MQTT.js).
8
+
9
+ **Status: early (0.x).** The configuration schema is frozen and the core is covered by tests — the model, the
10
+ payload engine, the families, both importers, the UI with its API, end-to-end tests against a real matter.js
11
+ node — but it has seen few real controllers yet. Bug reports and payloads that do not map are welcome as
12
+ [issues](https://github.com/hobbyquaker/mqtt2matter/issues).
13
+
14
+ What it does:
15
+
16
+ - **Compose devices by hand** from every device type matter.js ships — child endpoints, cluster features,
17
+ attribute defaults straight from the Matter data model — and map each attribute, command or event onto MQTT
18
+ with a payload engine that works in both directions: JSON paths, value maps, units, scaling, rounding,
19
+ Jinja templates in Home Assistant's dialect.
20
+ - **Families with real behaviour**: lights (level, colour temperature, xy, hue/saturation, RGB), covers
21
+ (position state machine, state-only covers, tilt), thermostats, locks, fans, buttons (GenericSwitch events),
22
+ sensors, battery, availability → reachable.
23
+ - **Import** from Zigbee2MQTT's own `bridge/devices` and from Home Assistant MQTT discovery, review on the
24
+ Adopt page, re-sync without losing your edits; a device seen by both is adopted once.
25
+ - **A web UI** for all of it, with a live preview of every conversion step and the live MQTT traffic.
26
+ - `mqtt2matter --check` validates a configuration against the model and matter.js in strict mode.
27
+
28
+ ## Install
29
+
30
+ Node ≥ 22.13.
31
+
32
+ ```sh
33
+ npm install -g mqtt2matter
34
+ sudo mqtt2matter --install --mqtt-url mqtt://broker:1883 # a systemd service, see below
35
+ journalctl -u mqtt2matter -f # the pairing code and QR payload
36
+ ```
37
+
38
+ Then open `http://<host>:8282`, adopt devices or create them, and pair the bridge from Apple Home, Home
39
+ Assistant, Google Home or Alexa like any Matter bridge; the devices appear as bridged endpoints.
40
+
41
+ Without the service: `mqtt2matter mqtt2matter.json` runs in the foreground with the configuration file given
42
+ (start from [example/mqtt2matter.json](example/mqtt2matter.json)), `mqtt2matter --check mqtt2matter.json`
43
+ checks the devices without starting the bridge, `mqtt2matter --help` lists the options.
44
+
45
+ ### From source
46
+
47
+ ```sh
48
+ npm ci
49
+ npm run build
50
+ node dist/main.js example/mqtt2matter.json
51
+ ```
52
+
53
+ ### The web UI
54
+
55
+ The bridge serves its UI on port 8282 (`server.port`): the device list, an editor for devices and their
56
+ mappings with a live preview of every conversion step in both directions and a topic picker over the broker's
57
+ live topic tree, presets, the adopt page for devices Zigbee2MQTT describes, the bridges with their QR code
58
+ and pairing code, the live MQTT traffic, the log, the strict dry run, import and export. German and English,
59
+ light and dark. `server.enabled: false` turns it off; [docs/api.md](docs/api.md) is the API it uses.
60
+
61
+ > **The UI has no login by default** (`server.auth.mode: "none"`), so an existing installation keeps working as it
62
+ > is: whoever reaches port 8282 can change the bridge. Set a password on the Configuration page (Access), or let a
63
+ > reverse proxy authenticate (`proxy` mode, the user in a header such as `X-Remote-User`) —
64
+ > [docs/config.md](docs/config.md#access).
65
+
66
+ ### Presets
67
+
68
+ A preset turns a kind of device into a device entry from a few values (a topic, a name): the device editor
69
+ offers them. Shipped: devices following the mqtt-smarthome convention (switch, light, dimmer, cover, contact,
70
+ occupancy, temperature, humidity, button), WLED (colour light, dimmer), Shelly Gen2/Gen3 (switch with and without power metering, cover, dimmer, Plus H&T, Plus i4), Shelly Gen1 (relay with and without power, roller, dimmer, H&T, Door/Window) Tasmota (relay, dimmer, CT and colour lights, shutter, temperature, humidity and pressure sensors) a Valetudo robot vacuum and OpenBeken (relay, dimmer, CT and colour lights, temperature and humidity channels) — the list with what each needs on the device
71
+ side is in [docs/config.md](docs/config.md#shipped-presets). Your own presets are JSON files in a directory
72
+ named in `presets`.
73
+
74
+ ### Zigbee2MQTT
75
+
76
+ ```sh
77
+ mqtt2matter --import-z2m mqtt2matter.json # reads zigbee2mqtt/bridge/devices and /groups
78
+ mqtt2matter --import-z2m mqtt2matter.json --dry-run # shows what it would do
79
+ mqtt2matter mqtt2matter.json # starts the bridge, logs the pairing code
80
+ ```
81
+
82
+ `--import-z2m` connects to the broker of the configuration (or `MQTT2MATTER_MQTT_URL`), reads the retained
83
+ `bridge/devices` and `bridge/groups` (`--base-topic` for another base topic), writes every supported device
84
+ and group into the file as ordinary devices — lights, switches, covers, locks, thermostats, fans, sensors,
85
+ buttons as GenericSwitch endpoints, battery, availability — and prints one line per device with what it could
86
+ not map. Edit the result like any other device; running the import again carries your edits over, lists
87
+ conflicts instead of resolving them, and marks devices that left zigbee2mqtt as orphaned without removing
88
+ them. [docs/importers.md](docs/importers.md) has the mapping and the API.
89
+
90
+ ### Home Assistant MQTT discovery
91
+
92
+ Anything that announces itself under `homeassistant/#` — ESPHome, Tasmota, Shelly, Z-Wave JS UI,
93
+ OpenMQTTGateway, the device-based form with components — appears on the Adopt page while the bridge runs
94
+ (`importers.ha` in the configuration): one Matter device per Home Assistant device, the primary entity on
95
+ its own endpoint, the other entities as children, a suggested area as a Matter area tag, templates through
96
+ the payload engine where it can run them and listed with the template where it cannot. What has no Matter
97
+ equivalent (`number`, `select`, `button`, settings and diagnostics) is listed, not dropped. A device that
98
+ zigbee2mqtt announces itself is marked as a duplicate of its native description, which is the better one: the
99
+ bridge adopts one device twice only when you confirm it.
100
+
101
+ [docs/config.md](docs/config.md) describes the configuration, [docs/architecture.md](docs/architecture.md)
102
+ the module layout and its rules.
103
+
104
+ ## Install on a Linux host
105
+
106
+ mqtt2matter runs as the systemd service `mqtt2matter.service` under a system user of its own:
107
+
108
+ | What | Where |
109
+ | ------------------ | ------------------------------------------------------------------------------------- |
110
+ | the package | `/usr/local/lib/node_modules/mqtt2matter`, the command `/usr/local/bin/mqtt2matter` |
111
+ | the configuration | `/etc/mqtt2matter/mqtt2matter.json` (the UI edits it) |
112
+ | the Matter storage | `/var/lib/mqtt2matter` — the pairings; keep it, or every controller has to pair again |
113
+ | the log | `journalctl -u mqtt2matter -f` — the pairing code and QR payload are there |
114
+
115
+ From a checkout, `deploy.sh` does all of it over ssh: lint, typecheck and tests (`SKIP_TESTS=1` skips them),
116
+ build, `npm pack`, copy the tarball and the lock file, install with `npm install --omit=dev`, link the
117
+ command, and run `--install` again on a host that has the service (the units follow the version, the service
118
+ restarts). It checks the host's Node against `engines` before anything is copied.
119
+
120
+ ```sh
121
+ INSTALL=1 MQTT_URL=mqtt://broker:1883 npm run deploy -- root@my-host # the first time: also installs the service
122
+ npm run deploy -- root@my-host # later: update and restart
123
+ ```
124
+
125
+ The host defaults to `mqtt2matter` (an ssh host name or a `Host` alias in `~/.ssh/config`). By hand, on the
126
+ host: `npm install -g ./mqtt2matter-<version>.tgz`, then `sudo mqtt2matter --install --mqtt-url
127
+ mqtt://broker:1883`. `--install` creates the user and the directories, writes the configuration only when there
128
+ is none, writes the unit and enables and starts it; running it again rewrites the unit (after a Node update,
129
+ say, or after an update that needs a new unit). `--install --dry-run` shows what it would write.
130
+ `mqtt2matter --uninstall` removes the service and keeps the configuration and the storage.
131
+
132
+ **Restart and update from the UI** (Configuration → Version) work under this service. A restart exits with code
133
+ 75, which the unit restarts on (`RestartForceExitStatus=75`) and counts as a clean stop
134
+ (`SuccessExitStatus=75`). An update installs the registry's latest `mqtt2matter` the way it was installed,
135
+ globally with npm — which the service user may not do: the UI only writes
136
+ the version into `/var/lib/mqtt2matter/update/request`, and `--install` sets up `mqtt2matter-update.path`, which
137
+ starts the root oneshot `mqtt2matter-update.service` (`mqtt2matter --apply-update`): it installs exactly
138
+ `mqtt2matter@<that version>`, logs to `/var/lib/mqtt2matter/update/update.log` (shown in the UI) and restarts
139
+ the service. No sudo rule, no polkit. Outside the service (by hand, Docker) the UI offers neither and says why.
140
+
141
+ **The host needs:**
142
+
143
+ - Node ≥ 22.13 with npm, installed system-wide (`/usr/bin` or `/usr/local/bin` — the unit runs with
144
+ `ProtectHome`, so a Node under `/root` or `/home`, as nvm installs it, does not start), systemd, and ssh as
145
+ root or with sudo for `deploy.sh`.
146
+ - **The same layer-2 network as the Matter controllers**: Matter finds the bridge through mDNS (UDP 5353,
147
+ multicast `224.0.0.251` and `ff02::fb`) and talks to it over IPv6. In a container, that means a bridged
148
+ network interface (not NAT) with IPv6 enabled — link-local addresses at least, SLAAC when the network has
149
+ it — and multicast passed through.
150
+ - No firewall on UDP 5353 (mDNS), UDP 5540 (`bridges.<id>.port`, one port per bridge) and TCP 8282 (the UI,
151
+ `server.port`), or rules that let them in.
152
+
153
+ ## Looking for the other direction?
154
+
155
+ To bridge real Matter devices to MQTT, use [she](https://github.com/hobbyquaker/she) (smart home engine): it
156
+ has a built-in Matter controller and MQTT.
157
+
158
+ ## Develop
159
+
160
+ ```sh
161
+ npm run lint # eslint + prettier
162
+ npm run typecheck
163
+ npm test # vitest: unit tests, the strict dry run, and end-to-end tests with an in-process broker and matter.js node
164
+ npm run test:e2e # Playwright: the UI against the real stack on ephemeral ports (Chromium in CI, Firefox elsewhere; PW_BROWSER overrides)
165
+ npm run dev:ui # Vite with hot reload, the API proxied to a running mqtt2matter on 127.0.0.1:8282 (UI_API overrides)
166
+ ```
167
+
168
+ `node ui/test/serve.ts` starts a throw-away stack — broker, bridge, UI, zigbee2mqtt's test corpus — on an
169
+ ephemeral port it prints, for a look at the UI without a configuration of your own.
170
+
171
+ ## License
172
+
173
+ Apache-2.0, see [LICENSE](LICENSE) and [NOTICE](NOTICE).
package/dist/app.d.ts ADDED
@@ -0,0 +1,34 @@
1
+ import type { Config } from './config/schema.ts';
2
+ import { MappingRuntime, type Codec } from './engine/runtime.ts';
3
+ import { type Logger } from './log.ts';
4
+ import type { DeviceHandle } from './matter/bridge.ts';
5
+ import { NodeManager } from './matter/node-manager.ts';
6
+ import type { DeviceConfig } from './model/schema.ts';
7
+ import { MqttClient } from './mqtt/client.ts';
8
+ export declare const VERSION: string;
9
+ export interface AppOptions {
10
+ log?: Logger;
11
+ /** ms to wait for the first MQTT connection; default 30 s */
12
+ mqttConnectTimeout?: number;
13
+ /** the codec modules the config names, loaded by `loadCodecs` */
14
+ codecs?: ReadonlyMap<string, Codec>;
15
+ }
16
+ export declare class App {
17
+ readonly log: Logger;
18
+ readonly mqtt: MqttClient;
19
+ readonly nodes: NodeManager;
20
+ readonly runtime: MappingRuntime;
21
+ readonly config: Config;
22
+ private started;
23
+ constructor(config: Config, options?: AppOptions);
24
+ start(): Promise<void>;
25
+ get running(): boolean;
26
+ /**
27
+ * Add or replace a device while running: its old endpoint and mappings go, the new entry is validated,
28
+ * built in its bridge and wired. A device with errors is kept in the configuration but not built.
29
+ */
30
+ applyDevice(key: string, device: DeviceConfig): Promise<DeviceHandle | undefined>;
31
+ /** remove a device while running */
32
+ removeDevice(key: string): Promise<void>;
33
+ stop(): Promise<void>;
34
+ }