@riddix/hamh 2.0.27

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 (77) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +491 -0
  3. package/dist/backend/bootstrap.js +6 -0
  4. package/dist/backend/cli.js +178783 -0
  5. package/dist/backend/cli.js.map +7 -0
  6. package/dist/frontend/assets/index-BNdBOwwe.css +1 -0
  7. package/dist/frontend/assets/index-D-gJdVIp.js +499 -0
  8. package/dist/frontend/assets/javascript-ySlJ1b_l.js +1 -0
  9. package/dist/frontend/assets/roboto-cyrillic-300-normal-BoeCr7ev.woff2 +0 -0
  10. package/dist/frontend/assets/roboto-cyrillic-300-normal-D568C3aM.woff +0 -0
  11. package/dist/frontend/assets/roboto-cyrillic-400-normal-DAIM1_dR.woff2 +0 -0
  12. package/dist/frontend/assets/roboto-cyrillic-400-normal-DZJji7Rx.woff +0 -0
  13. package/dist/frontend/assets/roboto-cyrillic-500-normal-BI4HuXre.woff +0 -0
  14. package/dist/frontend/assets/roboto-cyrillic-500-normal-hCeO1jFL.woff2 +0 -0
  15. package/dist/frontend/assets/roboto-cyrillic-700-normal-BiSG5NnW.woff2 +0 -0
  16. package/dist/frontend/assets/roboto-cyrillic-700-normal-KqaQ5bNp.woff +0 -0
  17. package/dist/frontend/assets/roboto-cyrillic-ext-300-normal-CUPJdUZp.woff2 +0 -0
  18. package/dist/frontend/assets/roboto-cyrillic-ext-300-normal-DQdcc27I.woff +0 -0
  19. package/dist/frontend/assets/roboto-cyrillic-ext-400-normal-DtZHuW6i.woff +0 -0
  20. package/dist/frontend/assets/roboto-cyrillic-ext-400-normal-DzMWdK87.woff2 +0 -0
  21. package/dist/frontend/assets/roboto-cyrillic-ext-500-normal-B7rQpwPu.woff2 +0 -0
  22. package/dist/frontend/assets/roboto-cyrillic-ext-500-normal-C927yMrb.woff +0 -0
  23. package/dist/frontend/assets/roboto-cyrillic-ext-700-normal-BuQgZIrO.woff +0 -0
  24. package/dist/frontend/assets/roboto-cyrillic-ext-700-normal-UFn0vR9r.woff2 +0 -0
  25. package/dist/frontend/assets/roboto-greek-300-normal-CTj2MfNN.woff +0 -0
  26. package/dist/frontend/assets/roboto-greek-300-normal-Cnub06j7.woff2 +0 -0
  27. package/dist/frontend/assets/roboto-greek-400-normal-CcizSnRP.woff +0 -0
  28. package/dist/frontend/assets/roboto-greek-400-normal-jFM2czAU.woff2 +0 -0
  29. package/dist/frontend/assets/roboto-greek-500-normal-BJMS0heP.woff2 +0 -0
  30. package/dist/frontend/assets/roboto-greek-500-normal-BLLWU9W-.woff +0 -0
  31. package/dist/frontend/assets/roboto-greek-700-normal-BcGn9doz.woff2 +0 -0
  32. package/dist/frontend/assets/roboto-greek-700-normal-D3kmAf0K.woff +0 -0
  33. package/dist/frontend/assets/roboto-latin-300-normal-CztWkFGs.woff2 +0 -0
  34. package/dist/frontend/assets/roboto-latin-300-normal-KByCBsad.woff +0 -0
  35. package/dist/frontend/assets/roboto-latin-400-normal-068yxgMN.woff +0 -0
  36. package/dist/frontend/assets/roboto-latin-400-normal-CNwBRw8h.woff2 +0 -0
  37. package/dist/frontend/assets/roboto-latin-500-normal-CC5nhZkh.woff +0 -0
  38. package/dist/frontend/assets/roboto-latin-500-normal-CkrA1NAy.woff2 +0 -0
  39. package/dist/frontend/assets/roboto-latin-700-normal-CXeAXeti.woff2 +0 -0
  40. package/dist/frontend/assets/roboto-latin-700-normal-DUekQERp.woff +0 -0
  41. package/dist/frontend/assets/roboto-latin-ext-300-normal-BOz0oSmX.woff2 +0 -0
  42. package/dist/frontend/assets/roboto-latin-ext-300-normal-Tcf9y2tg.woff +0 -0
  43. package/dist/frontend/assets/roboto-latin-ext-400-normal-ZYmyxeOy.woff2 +0 -0
  44. package/dist/frontend/assets/roboto-latin-ext-400-normal-eTRLN0Nt.woff +0 -0
  45. package/dist/frontend/assets/roboto-latin-ext-500-normal-C_ARlJGk.woff2 +0 -0
  46. package/dist/frontend/assets/roboto-latin-ext-500-normal-FFcS8vBN.woff +0 -0
  47. package/dist/frontend/assets/roboto-latin-ext-700-normal-70GS1MYH.woff2 +0 -0
  48. package/dist/frontend/assets/roboto-latin-ext-700-normal-BS1OuQqR.woff +0 -0
  49. package/dist/frontend/assets/roboto-math-300-normal-BMxwzQmU.woff2 +0 -0
  50. package/dist/frontend/assets/roboto-math-300-normal-BU9CUCyj.woff +0 -0
  51. package/dist/frontend/assets/roboto-math-400-normal-B3wgz80t.woff2 +0 -0
  52. package/dist/frontend/assets/roboto-math-400-normal-rzxYvyVt.woff +0 -0
  53. package/dist/frontend/assets/roboto-math-500-normal-CFNaIMFC.woff2 +0 -0
  54. package/dist/frontend/assets/roboto-math-500-normal-DaFX-ZC8.woff +0 -0
  55. package/dist/frontend/assets/roboto-math-700-normal-VUAI6Bz2.woff2 +0 -0
  56. package/dist/frontend/assets/roboto-math-700-normal-pYD1nhov.woff +0 -0
  57. package/dist/frontend/assets/roboto-symbols-300-normal-BtHl5mYl.woff2 +0 -0
  58. package/dist/frontend/assets/roboto-symbols-300-normal-kyoSXp-d.woff +0 -0
  59. package/dist/frontend/assets/roboto-symbols-400-normal-Tzuungub.woff +0 -0
  60. package/dist/frontend/assets/roboto-symbols-400-normal-fF1SLJBj.woff2 +0 -0
  61. package/dist/frontend/assets/roboto-symbols-500-normal-BXFTxrNR.woff2 +0 -0
  62. package/dist/frontend/assets/roboto-symbols-500-normal-CAhAe-ik.woff +0 -0
  63. package/dist/frontend/assets/roboto-symbols-700-normal-CuuvBBxy.woff +0 -0
  64. package/dist/frontend/assets/roboto-symbols-700-normal-rJi6RjIy.woff2 +0 -0
  65. package/dist/frontend/assets/roboto-vietnamese-300-normal-CNeuLW5X.woff2 +0 -0
  66. package/dist/frontend/assets/roboto-vietnamese-300-normal-DXBG9gdz.woff +0 -0
  67. package/dist/frontend/assets/roboto-vietnamese-400-normal-CDDxGrUb.woff2 +0 -0
  68. package/dist/frontend/assets/roboto-vietnamese-400-normal-DmXaN3yE.woff +0 -0
  69. package/dist/frontend/assets/roboto-vietnamese-500-normal-DW96CsrR.woff +0 -0
  70. package/dist/frontend/assets/roboto-vietnamese-500-normal-HYpufUYk.woff2 +0 -0
  71. package/dist/frontend/assets/roboto-vietnamese-700-normal-Dz0HwF-w.woff +0 -0
  72. package/dist/frontend/assets/roboto-vietnamese-700-normal-iKxYNAzq.woff2 +0 -0
  73. package/dist/frontend/assets/vitesse-dark-D0r3Knsf.js +1 -0
  74. package/dist/frontend/assets/vitesse-light-CVO1_9PV.js +1 -0
  75. package/dist/frontend/hamh-logo.svg +12 -0
  76. package/dist/frontend/index.html +17 -0
  77. package/package.json +105 -0
package/README.md ADDED
@@ -0,0 +1,491 @@
1
+ <div align="center">
2
+
3
+ # Home-Assistant-Matter-Hub
4
+
5
+ !["Home-Assistant-Matter-Hub"](./docs/assets/hamh-logo-small.png)
6
+
7
+ **Expose your Home Assistant devices to Matter controllers like Apple Home, Google Home, and Alexa**
8
+
9
+ [![GitHub Release](https://img.shields.io/github/v/release/RiDDiX/home-assistant-matter-hub?label=stable&color=green)](https://github.com/RiDDiX/home-assistant-matter-hub/releases)
10
+ [![GitHub Pre-Release](https://img.shields.io/github/v/release/RiDDiX/home-assistant-matter-hub?include_prereleases&label=alpha&color=orange)](https://github.com/RiDDiX/home-assistant-matter-hub/releases)
11
+ [![GitHub Issues](https://img.shields.io/github/issues/RiDDiX/home-assistant-matter-hub)](https://github.com/RiDDiX/home-assistant-matter-hub/issues)
12
+ [![GitHub Stars](https://img.shields.io/github/stars/RiDDiX/home-assistant-matter-hub)](https://github.com/RiDDiX/home-assistant-matter-hub/stargazers)
13
+ [![License](https://img.shields.io/github/license/RiDDiX/home-assistant-matter-hub)](LICENSE)
14
+
15
+ [📖 Documentation](https://riddix.github.io/home-assistant-matter-hub) • [� Discord](https://discord.gg/Kubv7sSGyW) • [�🐛 Report Bug](https://github.com/RiDDiX/home-assistant-matter-hub/issues/new?labels=bug) • [💡 Request Feature](https://github.com/RiDDiX/home-assistant-matter-hub/issues/new?labels=enhancement)
16
+
17
+ </div>
18
+
19
+ ---
20
+
21
+ > [!NOTE]
22
+ > 🔀 **Community Fork** - This is a fork of the original [t0bst4r/home-assistant-matter-hub](https://github.com/t0bst4r/home-assistant-matter-hub), which was discontinued in January 2026. We continue active development with bug fixes, new features, and community support. Thank you **[@t0bst4r](https://github.com/t0bst4r)** for the original work! ❤️
23
+ >
24
+ > **📦 Migrating?** See [Migration Guide](#migration-from-t0bst4r) - your paired devices will continue to work!
25
+
26
+ ---
27
+
28
+ ## 📝 About
29
+
30
+ This project simulates bridges to publish your entities from Home Assistant to any Matter-compatible controller like
31
+ Alexa, Apple Home or Google Home. Using Matter, those can be connected easily using local communication without the need
32
+ of port forwarding etc.
33
+
34
+ ---
35
+
36
+ ## 📦 Releases & Branches
37
+
38
+ | Channel | Branch | Current Version | Description |
39
+ |---------|--------|-----------------|-------------|
40
+ | **Stable** | `main` | v2.0.27 | Production-ready, recommended for most users |
41
+ | **Alpha** | `alpha` | v2.1.0-alpha.x | Pre-release with new features, for early adopters |
42
+ | **Testing** | `testing` | v4.1.0-testing.x | ⚠️ **Highly unstable!** Experimental features, may break |
43
+
44
+ ### Which version should I use?
45
+
46
+ - **Most users**: Use **Stable** (`main` branch) - thoroughly tested
47
+ - **Early adopters**: Use **Alpha** (`alpha` branch) - new features, occasional bugs
48
+ - **Developers/Testers**: Use **Testing** (`testing` branch) - bleeding edge, expect breakage
49
+
50
+ ---
51
+
52
+ ## 🎉 What's New
53
+
54
+ <details>
55
+ <summary><strong>📦 Stable Features (v2.0.27)</strong> - Click to expand</summary>
56
+
57
+ **New in v2.0.27:**
58
+
59
+ | Feature | Description |
60
+ |---------|-------------|
61
+ | **🤖 Native Valetudo Support** | Auto-detect Valetudo select entities, map segments, use `segment_cleanup` via MQTT for room cleaning ([#205](https://github.com/RiDDiX/home-assistant-matter-hub/issues/205)) |
62
+ | **🤖 Custom Service Areas** | Define custom room/zone names for generic zone-based robots without native room support ([#177](https://github.com/RiDDiX/home-assistant-matter-hub/issues/177)) |
63
+ | **🤖 ServiceArea Maps** | Multi-floor vacuum support — rooms grouped by floor map in Apple Home |
64
+ | **🤖 Vacuum Identify → Locate** | "Play Sound" in Apple Home triggers `vacuum.locate` to find your robot ([#189](https://github.com/RiDDiX/home-assistant-matter-hub/issues/189)) |
65
+ | **🤖 Vacuum Charging State** | Reports `IsCharging` when docked — Apple Home shows correct charging indicator ([#206](https://github.com/RiDDiX/home-assistant-matter-hub/issues/206)) |
66
+ | **🤖 Vacuum Minimal Clusters** | `vacuumMinimalClusters` feature flag strips non-essential clusters for Alexa compatibility ([#183](https://github.com/RiDDiX/home-assistant-matter-hub/issues/183)) |
67
+ | **🌡️ Composed Air Purifier** | Air purifiers with thermostat/humidity sensors create real Matter Composed Devices (spec 9.4.4) |
68
+ | **🚨 Alarm Control Panel** | `alarm_control_panel` entities exposed as Matter ModeSelect — arm/disarm modes available in controllers ([#209](https://github.com/RiDDiX/home-assistant-matter-hub/issues/209)) |
69
+ | **🖥️ Dashboard Controls** | Bridge Start/Stop/Restart All buttons in header, Settings nav entry |
70
+ | **🖥️ Process Memory Display** | RSS + heap usage shown in System Information page |
71
+ | **🖥️ Compact Include/Exclude Editor** | Collapsible entity filter editor with search |
72
+ | **🖥️ Improved Bridge Config UI** | Better layout and usability for bridge settings editor |
73
+ | **🏢 Vendor Brand Icons** | 20+ new manufacturer icons (Razer, Roborock, iRobot, Signify, and more) |
74
+ | **🐳 linux/arm/v7 Docker** | Added ARM v7 platform for standalone Docker image |
75
+ | **📦 npm Package** | Published as `@riddix/hamh` on npm for standalone installations |
76
+ | **🌡️ Thermostat #207 Fix** | heat_cool-only HVAC zones now dynamically report CoolingOnly/HeatingOnly based on hvac_action |
77
+ | **🌡️ Thermostat #28 Fix** | Devices with auto+cool but no explicit heat (e.g. SmartIR ACs) no longer crash with conformance error |
78
+ | **🤖 Vacuum Alexa Fixes** | Multiple fixes for OnOff, PowerSource, mode IDs, room sorting ([#183](https://github.com/RiDDiX/home-assistant-matter-hub/issues/183), [#185](https://github.com/RiDDiX/home-assistant-matter-hub/issues/185)) |
79
+ | **🔧 Air Purifier Fix** | Added Rocking (oscillation) and Wind feature support, removed incorrect Lighting feature |
80
+ | **🔧 Composed Sensor Fix** | Temperature not updating in composed sensors, missing device types in flat endpoints ([#214](https://github.com/RiDDiX/home-assistant-matter-hub/issues/214)) |
81
+ | **⚡ Performance** | Fingerprint-based registry change detection, reduced refresh overhead |
82
+
83
+ **Previously in v2.0.26:**
84
+
85
+ | Feature | Description |
86
+ |---------|-------------|
87
+ | **🔐 Authentication UI** | Configure authentication credentials directly from the web UI Settings page ([#197](https://github.com/RiDDiX/home-assistant-matter-hub/issues/197)) |
88
+ | **🔌 Select Entity Support** | `select` and `input_select` entities now mapped to Matter ModeSelectDevice |
89
+ | **🔗 Webhook Event Bridge** | HAMH fires `hamh_action` events on the HA event bus for controller command automations |
90
+ | **🔍 Cluster Diagnostics** | Expandable per-cluster state inspection on device cards |
91
+ | **⚙ Matter.js 0.16.10** | Updated from 0.16.8 to 0.16.10 for stability and spec compliance |
92
+ | **� Docker Node 22** | Pinned Docker runtime to Node 22 ([#200](https://github.com/RiDDiX/home-assistant-matter-hub/issues/200)) |
93
+
94
+ </details>
95
+
96
+ <details>
97
+ <summary><strong>🧪 Alpha Features (v2.1.0-alpha.x)</strong> - Click to expand</summary>
98
+
99
+ **Alpha is currently in sync with Stable (v2.0.27).** All alpha features have been promoted to stable. New alpha features will appear here as development continues.
100
+
101
+ </details>
102
+
103
+ <details>
104
+ <summary><strong>⚠️ Testing Features (v4.1.0-testing)</strong> - Click to expand</summary>
105
+
106
+ > [!CAUTION]
107
+ > Testing versions are **highly unstable** and intended for developers only!
108
+
109
+ **🏗️ Vision 1: Callback-based Architecture**
110
+
111
+ | Old (Legacy) | New (Vision 1) |
112
+ |--------------|----------------|
113
+ | Behaviors update themselves | Endpoint updates behaviors via `setStateOf()` |
114
+ | Behaviors call HA actions directly | Behaviors notify via `notifyEndpoint()` |
115
+
116
+ **New Callback-Behaviors:** OnOff, LevelControl, Lock, Cover, Fan, ColorControl, VacuumRunMode, VacuumOperationalState
117
+
118
+ **Updated Endpoints:** Switch, Lock, Cover, Vacuum, Button, Valve, Scene, Humidifier, Light, Fan
119
+
120
+ </details>
121
+
122
+ <details>
123
+ <summary><strong>📜 Previous Stable Versions</strong> - Click to expand</summary>
124
+
125
+ ### v2.0.26
126
+ Authentication UI, Select entity support, Webhook event bridge, Cluster diagnostics, Matter.js 0.16.10, Docker Node 22, vacuum cleaning mode fallback, vacuum entity filter fix
127
+
128
+ ### v2.0.25
129
+ Vacuum mop intensity, vacuum auto-detection, Roborock room auto-detect, live entity mapping, dynamic heap sizing, multi-fabric commissioning, fan speed label fix
130
+
131
+ ### v2.0.24
132
+ Dashboard landing page, composed devices, bridge wizard feature flags, entity autocomplete, light transitions, live diagnostics, vacuum suction level, thermostat auto-resume, vacuum docked state, memory leak fix
133
+
134
+ ### v2.0.19–v2.0.23
135
+ Bridge templates, live filter preview, entity diagnostics, multi-bridge bulk operations, entity health indicators, diagnostic export, EntityLabel/DeviceLabel filters, Power & Energy Measurement, Event domain (GenericSwitch)
136
+
137
+ ### v2.0.17 / v2.0.18
138
+ Room Label (FixedLabel), thermostat overhaul, lock unlatch/unbolt, binary sensor fix, auto pressure mapping, vacuum fixes, dead session recovery, network map, mobile UI, Labels & Areas page, crash resilience, memory limit
139
+
140
+ ### v2.0.16
141
+ Force Sync, Lock PIN, Cover/Blinds improvements, Roborock Rooms, Auto Entity Grouping, Water Heater, Vacuum Server Mode, OOM fix
142
+
143
+ ### v1.10.4
144
+ Climate/Thermostat fixes, Cover position fix, Vacuum battery, Humidifier improvements, Entity Mapping, Alexa brightness preserve
145
+
146
+ ### v1.9.0
147
+ Custom bridge icons, Basic Video Player (TV), Alexa deduplication, Auto-only thermostat, Health Check API, WebSocket, Full backup/restore
148
+
149
+ ### v1.8.x
150
+ Graceful crash handler, PM2.5/PM10 sensors, Water Valve, Smoke/CO Detector, Pressure/Flow sensors, Air Purifier, Pump device
151
+
152
+ ### v1.7.x
153
+ Dark Mode toggle, Device list sorting
154
+
155
+ ### v1.5.x
156
+ Matter Bridge, Multi-Fabric support, Health Monitoring, Bridge Wizard, AirQuality sensors, Fan control, Media playback
157
+
158
+ </details>
159
+
160
+ ---
161
+
162
+ ## Supported Device Types
163
+
164
+ | Home Assistant Domain | Matter Device Type | Feature Flags |
165
+ |-----------------------|-------------------|---------------|
166
+ | `light` | On/Off, Dimmable, Color Temp, Extended Color | `powerEntity`, `energyEntity` |
167
+ | `switch`, `input_boolean` | On/Off Plug-in Unit | `powerEntity`, `energyEntity` |
168
+ | `lock` | Door Lock | PIN Credentials, Unlatch/Unbolt |
169
+ | `cover` | Window Covering | `coverSwapOpenClose` |
170
+ | `climate` | Thermostat | Battery via `batteryEntity` |
171
+ | `fan` | Fan, Air Purifier | Oscillation, Wind Modes, `filterLifeEntity` |
172
+ | `alarm_control_panel` | Mode Select | Arm/Disarm modes |
173
+ | `binary_sensor` | Contact, OnOff, Occupancy, Smoke/CO, Water Leak, Water Freeze | |
174
+ | `sensor` | Temperature, Humidity, Pressure, Flow, Light, AirQuality | `batteryEntity`, `humidityEntity`, `pressureEntity` |
175
+ | `event` | Generic Switch (Doorbell, Button Events) | |
176
+ | `button`, `input_button` | Generic Switch | |
177
+ | `media_player` | Speaker, Basic Video Player (TV) | |
178
+ | `valve` | Water Valve, Pump | |
179
+ | `select`, `input_select` | Mode Select | |
180
+ | `vacuum` | Robot Vacuum Cleaner | `serverMode`, `roomEntities`, `batteryEntity`, `cleaningModeEntity`, `suctionLevelEntity`, `mopIntensityEntity`, `customServiceAreas`, `vacuumMinimalClusters` |
181
+ | `humidifier` | Humidifier/Dehumidifier | |
182
+ | `water_heater` | Thermostat (Heating) | |
183
+ | `automation`, `script`, `scene` | On/Off Switch | |
184
+
185
+ > 📖 See [Supported Device Types Documentation](https://riddix.github.io/home-assistant-matter-hub/Supported%20Device%20Types/) for details
186
+
187
+ ---
188
+
189
+ ## 🤖 Robot Vacuum Server Mode
190
+
191
+ <details>
192
+ <summary><strong>⚠️ Important: Apple Home & Alexa require Server Mode for Robot Vacuums</strong> (click to expand)</summary>
193
+
194
+ ### The Problem
195
+
196
+ Apple Home and Alexa **do not properly support bridged robot vacuums**. When your vacuum is exposed through a standard Matter bridge, you may experience:
197
+
198
+ - **Apple Home**: "Updating" status, Siri commands don't work, room selection fails
199
+ - **Alexa**: Vacuum is not discovered at all
200
+
201
+ This is because these platforms expect robot vacuums to be **standalone Matter devices**, not bridged devices.
202
+
203
+ ### The Solution: Server Mode
204
+
205
+ **Server Mode** exposes your vacuum as a standalone Matter device without the bridge wrapper. This makes it fully compatible with Apple Home and Alexa.
206
+
207
+ ### Setup Instructions
208
+
209
+ 1. **Create a new bridge** in the Matter Hub web interface
210
+ 2. **Enable "Server Mode"** checkbox in the bridge creation wizard
211
+ 3. Add **only your vacuum** to this bridge
212
+ 4. **Pair the new Server Mode bridge** with Apple Home or Alexa
213
+ 5. Your other devices stay on your regular bridge(s)
214
+
215
+ ### Important Notes
216
+
217
+ - Server Mode bridges support **exactly one device**
218
+ - Your vacuum needs its own dedicated Server Mode bridge
219
+ - Other device types (lights, switches, sensors) work fine on regular bridges
220
+ - After switching to Server Mode, Siri commands like "Hey Siri, start the vacuum" will work
221
+
222
+ ### Documentation
223
+
224
+ For more details, see the [Robot Vacuum Documentation](https://riddix.github.io/home-assistant-matter-hub/Devices/Robot%20Vacuum/).
225
+
226
+ </details>
227
+
228
+ ---
229
+
230
+ ## Installation
231
+
232
+ ### Home Assistant Add-on (Recommended)
233
+
234
+ Add this repository to your Add-on Store:
235
+
236
+ ```
237
+ https://github.com/RiDDiX/home-assistant-addons
238
+ ```
239
+
240
+ Two add-ons are available:
241
+ - **Home-Assistant-Matter-Hub** - Stable release
242
+ - **Home-Assistant-Matter-Hub (Alpha)** - Pre-release for testing
243
+
244
+ ### Docker
245
+
246
+ ```bash
247
+ docker run -d \
248
+ --name home-assistant-matter-hub \
249
+ --network host \
250
+ -v /path/to/data:/data \
251
+ -e HAMH_HOME_ASSISTANT_URL=http://192.168.178.123:8123 \
252
+ -e HAMH_HOME_ASSISTANT_ACCESS_TOKEN=your_long_lived_access_token \
253
+ ghcr.io/riddix/home-assistant-matter-hub:latest
254
+ ```
255
+
256
+ > **Note:** All environment variables require the `HAMH_` prefix.
257
+ > See the [Installation Guide](docs/Getting%20Started/Installation.md) for all available options.
258
+
259
+ For alpha versions, use tag `alpha` instead of `latest`.
260
+
261
+ ---
262
+
263
+ ## Documentation
264
+
265
+ Please see the [documentation](https://riddix.github.io/home-assistant-matter-hub) for detailed installation instructions,
266
+ configuration options, known issues, limitations and guides.
267
+
268
+ ---
269
+
270
+ ## 🔧 Network Troubleshooting
271
+
272
+ <details>
273
+ <summary><strong>⚠️ "No Response" / Connection Drops — Common Network Causes</strong> (click to expand)</summary>
274
+
275
+ ### The Problem
276
+
277
+ Your Matter devices suddenly show **"No Response"** (Apple Home), **"Unavailable"** (Google Home), or become **unresponsive** after some time — even though the bridge is still running and other controllers (e.g., Alexa) continue to work fine.
278
+
279
+ ### Root Cause: Network Equipment Blocking mDNS/Multicast
280
+
281
+ Matter relies heavily on **mDNS (multicast DNS)** for device discovery and reachability. Many routers, access points, and managed switches have features that **filter, throttle, or block multicast traffic** — which breaks Matter communication silently.
282
+
283
+ > **💡 This was confirmed and documented thanks to the excellent systematic testing by [@omerfaruk-aran](https://github.com/omerfaruk-aran) in [#129](https://github.com/RiDDiX/home-assistant-matter-hub/issues/129).** The issue was traced to a TP-Link Archer AX50 (in AP mode) sitting between the Apple TV and the network — its default settings were blocking/limiting mDNS/Bonjour traffic over time.
284
+
285
+ ### What to Check on Your Network Equipment
286
+
287
+ 1. **IGMP Snooping** — Disable or configure it to allow mDNS (`224.0.0.251` / `ff02::fb`)
288
+ 2. **Multicast Optimization / Multicast Enhancement** — Disable (often called "Airtime Fairness" or "Multicast to Unicast")
289
+ 3. **AP Isolation / Client Isolation** — Must be **disabled** so devices on the same network can communicate
290
+ 4. **mDNS / Bonjour Forwarding** — Enable if available (some enterprise APs have this)
291
+ 5. **DHCP Server on secondary devices** — Disable DHCP on access points / switches that are NOT your main router (multiple DHCP servers cause IP conflicts)
292
+ 6. **Firmware Updates** — Update your router/AP firmware, as multicast handling is frequently improved
293
+
294
+ ### Affected Equipment (Known Cases)
295
+
296
+ | Device | Issue | Fix |
297
+ |--------|-------|-----|
298
+ | **TP-Link Archer AX50** (AP mode) | mDNS traffic blocked/limited over time | Firmware update + disable DHCP on the AP |
299
+ | **Ubiquiti UniFi APs** | IGMP Snooping can filter mDNS | Disable IGMP Snooping or enable mDNS Reflector |
300
+ | **Managed Switches** (various) | Multicast filtering enabled by default | Allow mDNS multicast groups |
301
+
302
+ ### Quick Diagnostic Steps
303
+
304
+ 1. **Does Alexa still work when Apple Home shows "No Response"?**
305
+ - **Yes** → Bridge is online, the issue is network path / mDNS related
306
+ - **No** → Bridge may actually be down, check HAMH logs
307
+
308
+ 2. **Does removing a Home Hub (HomePod/Apple TV) fix it?**
309
+ - **Yes** → The hub's network path is affected (AP/switch between hub and bridge)
310
+ - **No** → May be a different issue
311
+
312
+ 3. **Try binding mDNS to a specific interface:**
313
+ ```
314
+ --mdns-network-interface eth0
315
+ ```
316
+ (or `end0`, `enp0s18`, etc. — check your system)
317
+
318
+ ### Network Topology Tips
319
+
320
+ - **Keep the path simple**: Avoid placing access points or managed switches between your Matter bridge (Home Assistant) and your Home Hub (HomePod/Apple TV)
321
+ - **Use wired connections** where possible for Home Hubs and the Home Assistant host
322
+ - **Same subnet**: All Matter devices, controllers, and the bridge must be on the same Layer 2 network / subnet
323
+ - **IPv6**: Matter uses IPv6 link-local addresses — make sure IPv6 is not disabled on your network
324
+
325
+ </details>
326
+
327
+ ---
328
+
329
+ ## Migration from t0bst4r
330
+
331
+ Migrating from the original `t0bst4r/home-assistant-matter-hub` is straightforward. **Your Matter fabric connections and paired devices will be preserved!**
332
+
333
+ ### Home Assistant Add-on
334
+
335
+ 1. **Backup your data:**
336
+ ```bash
337
+ cp -r /addon_configs/*_hamh /config/hamh-backup
338
+ # Verify the backup was copied correctly
339
+ ls /config/hamh-backup
340
+ ```
341
+
342
+ 2. **Uninstall the old add-on** (Settings → Add-ons → Uninstall) and make sure the old folder is removed:
343
+ ```bash
344
+ rm -rf /addon_configs/*_hamh
345
+ ```
346
+
347
+ 3. **Add the new repository:**
348
+ ```
349
+ https://github.com/RiDDiX/home-assistant-addons
350
+ ```
351
+
352
+ 4. **Install and start the new add-on once** (creates the data folder), then **stop it**
353
+
354
+ 5. **Clear the new folder and restore your backup:**
355
+ ```bash
356
+ rm -rf /addon_configs/*_hamh/*
357
+ cp -r /config/hamh-backup/* /addon_configs/*_hamh/
358
+ ```
359
+
360
+ 6. **Start the add-on again** - your devices should reconnect automatically
361
+
362
+ ### Docker / Docker Compose
363
+
364
+ Simply change the image from:
365
+ ```
366
+ ghcr.io/t0bst4r/home-assistant-matter-hub:latest
367
+ ```
368
+ to:
369
+ ```
370
+ ghcr.io/riddix/home-assistant-matter-hub:latest
371
+ ```
372
+
373
+ Your volume mounts stay the same - no data migration needed.
374
+
375
+ > For detailed instructions, see the [full Migration Guide](https://riddix.github.io/home-assistant-matter-hub/migration-from-t0bst4r/).
376
+
377
+ ---
378
+
379
+ ## 🙏 Contributors & Acknowledgments
380
+
381
+ This project thrives thanks to the amazing community! Special thanks to everyone who contributes by reporting bugs, suggesting features, and helping others.
382
+
383
+ ### 🏆 Top Contributors
384
+
385
+ | Contributor | Contributions |
386
+ |-------------|---------------|
387
+ | [@codyc1515](https://github.com/codyc1515) | 🥇 **Top Reporter** - Climate/thermostat bugs (#52, #24, #21, #20), extensive testing feedback |
388
+ | [@Hatton920](https://github.com/Hatton920) | 🤖 **Vacuum Expert** - Intensive testing of Robot Vacuum Server Mode, Apple Home & Siri validation |
389
+ | [@Chrulf](https://github.com/Chrulf) | 🔍 Google Home brightness debugging (#41), detailed logs & testing |
390
+ | [@SH1FT-W](https://github.com/SH1FT-W) | 💎 **Sponsor** + Vacuum room selection feature request (#49) |
391
+ | [@depahk](https://github.com/depahk) | 📝 Migration documentation fix ([#32](https://github.com/RiDDiX/home-assistant-matter-hub/pull/32)) |
392
+ | [@Fettkeewl](https://github.com/Fettkeewl) | 🐛 Script import bug (#26), Alias feature request (#25) |
393
+ | [@razzietheman](https://github.com/razzietheman) | 🥈 **Active Tester** - Bridge icons (#101), sorting (#80), feature requests (#31, #30), extensive UI/UX feedback |
394
+ | [@markgaze](https://github.com/markgaze) | 🤖 **Code Contributor** - Ecovacs Deebot room support ([#118](https://github.com/RiDDiX/home-assistant-matter-hub/pull/118)) |
395
+ | [@omerfaruk-aran](https://github.com/omerfaruk-aran) | 🔧 **Network Debugging Expert** - Systematic mDNS/multicast root cause analysis for "No Response" issues ([#129](https://github.com/RiDDiX/home-assistant-matter-hub/issues/129)) |
396
+ | [@gustavakerstrom](https://github.com/gustavakerstrom) | 🤖 **Code Contributor** - Template description display fix ([#215](https://github.com/RiDDiX/home-assistant-matter-hub/pull/215)) |
397
+
398
+ <details>
399
+ <summary><strong>📋 Issue Tracker - All Contributors</strong> (click to expand)</summary>
400
+
401
+ Thank you to everyone who helps improve this project by reporting issues!
402
+
403
+ | User | Issues |
404
+ |------|--------|
405
+ | [@omerfaruk-aran](https://github.com/omerfaruk-aran) | #129 |
406
+ | [@markgaze](https://github.com/markgaze) | #118 |
407
+ | [@BlairC1](https://github.com/BlairC1) | #117 |
408
+ | [@Giamp96](https://github.com/Giamp96) | #116 |
409
+ | [@NdR91](https://github.com/NdR91) | #115 #106 |
410
+ | [@Fry7](https://github.com/Fry7) | #114 |
411
+ | [@siobhanellis](https://github.com/siobhanellis) | #112 |
412
+ | [@Hatton920](https://github.com/Hatton920) | #110 |
413
+ | [@gette](https://github.com/gette) | #95 |
414
+ | [@400HPMustang](https://github.com/400HPMustang) | #103 |
415
+ | [@vandir](https://github.com/vandir) | #102 |
416
+ | [@razzietheman](https://github.com/razzietheman) | #101 #100 #80 #31 #30 |
417
+ | [@seitenprofi](https://github.com/seitenprofi) | #176 |
418
+ | [@semonR](https://github.com/semonR) | #99 #58 |
419
+ | [@italoc](https://github.com/italoc) | #78 |
420
+ | [@marksev1](https://github.com/marksev1) | #62 |
421
+ | [@smacpi](https://github.com/smacpi) | #60 |
422
+ | [@mrbluebrett](https://github.com/mrbluebrett) | #53 |
423
+ | [@anpak](https://github.com/anpak) | #45 |
424
+ | [@alondin](https://github.com/alondin) | #43 |
425
+ | [@Chrulf](https://github.com/Chrulf) | #41 |
426
+ | [@Weske90](https://github.com/Weske90) | #40 |
427
+ | [@didiht](https://github.com/didiht) | #37 |
428
+ | [@Dixiland20](https://github.com/Dixiland20) | #34 |
429
+ | [@chromaxx7](https://github.com/chromaxx7) | #29 |
430
+ | [@Tomyk9991](https://github.com/Tomyk9991) | #28 |
431
+ | [@datvista](https://github.com/datvista) | #27 |
432
+ | [@bwynants](https://github.com/bwynants) | #23 |
433
+ | [@Pozzi831](https://github.com/Pozzi831) | #22 |
434
+ | [@codyc1515](https://github.com/codyc1515) | #52 #24 #21 #20 |
435
+
436
+ </details>
437
+
438
+ ### 💖 Sponsors
439
+
440
+ > **Donations are completely voluntary!** I'm incredibly grateful to everyone who has supported this project - it wasn't necessary, but it truly means a lot. This project exists because of passion for open source, not money. ❤️
441
+
442
+ | Sponsor | |
443
+ |---------|---|
444
+ | [@thorsten-gehrig](https://github.com/thorsten-gehrig) | 🥇 **First Sponsor!** Thank you for believing in this project! |
445
+ | [@SH1FT-W](https://github.com/SH1FT-W) | 💎 Thank you for your generous support! |
446
+ | [@ilGaspa](https://github.com/ilGaspa) | 💎 Thank you for your generous support! |
447
+ | [@linux4life798](https://github.com/linux4life798) | 💎 Thank you for your generous support! |
448
+ | [@torandreroland](https://github.com/torandreroland) | 💎 Thank you for your generous support! |
449
+ | [@ralondo](https://github.com/ralondo) | 💎 Thank you for your generous support! |
450
+ | [@bexxter85-ux](https://github.com/bexxter85-ux) | 💎 Thank you for your generous support! |
451
+ | [@dinariox](https://github.com/dinariox) | 💎 Thank you for your generous support! |
452
+ | StefanS | 💎 Thank you for your generous support! |
453
+ | Manny B. | 💎 Thank you for your generous support! |
454
+ | [@JRCondat](https://github.com/JRCondat) | 💎 Thank you for your generous support! |
455
+ | Bonjon | 💎 Thank you for your generous support! |
456
+ | TobiR | 💎 Thank you for your generous support! |
457
+ | *Anonymous supporters* | 🙏 Thank you to those who prefer not to be named - your support is equally appreciated! |
458
+
459
+ ### 🌟 Original Author
460
+
461
+ - **[@t0bst4r](https://github.com/t0bst4r)** - Creator of the original Home-Assistant-Matter-Hub project
462
+
463
+ ---
464
+
465
+ ## ☕ Support the Project
466
+
467
+ > [!NOTE]
468
+ > **Completely optional!** This project will continue regardless of donations.
469
+ > I maintain this in my free time because I believe in open source.
470
+
471
+ If you find this project useful, consider supporting its development:
472
+
473
+ [![PayPal](https://img.shields.io/badge/PayPal-Donate-blue?logo=paypal&style=for-the-badge)](https://www.paypal.me/RiDDiX93)
474
+
475
+ Your support helps cover hosting costs and motivates continued development. Thank you! ❤️
476
+
477
+ ---
478
+
479
+ ## 📊 Project Stats
480
+
481
+ <div align="center">
482
+
483
+ ![GitHub commit activity](https://img.shields.io/github/commit-activity/m/RiDDiX/home-assistant-matter-hub)
484
+ ![GitHub last commit](https://img.shields.io/github/last-commit/RiDDiX/home-assistant-matter-hub)
485
+ ![GitHub issues](https://img.shields.io/github/issues/RiDDiX/home-assistant-matter-hub)
486
+ ![GitHub closed issues](https://img.shields.io/github/issues-closed/RiDDiX/home-assistant-matter-hub)
487
+ ![GitHub pull requests](https://img.shields.io/github/issues-pr/RiDDiX/home-assistant-matter-hub)
488
+
489
+ </div>
490
+
491
+ ---
@@ -0,0 +1,6 @@
1
+ import { config } from "@matter/nodejs/config";
2
+ config.trapProcessSignals = true;
3
+ config.setProcessExitCodeOnError = true;
4
+ config.loadConfigFile = false;
5
+ config.loadProcessArgv = false;
6
+ config.loadProcessEnv = false;