@riddix/hamh 2.1.0-alpha.367
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/LICENSE +202 -0
- package/README.md +479 -0
- package/dist/backend/bootstrap.js +6 -0
- package/dist/backend/cli.js +177923 -0
- package/dist/backend/cli.js.map +7 -0
- package/dist/frontend/assets/index-BNdBOwwe.css +1 -0
- package/dist/frontend/assets/index-Dbk2gs1T.js +483 -0
- package/dist/frontend/assets/javascript-ySlJ1b_l.js +1 -0
- package/dist/frontend/assets/roboto-cyrillic-300-normal-BoeCr7ev.woff2 +0 -0
- package/dist/frontend/assets/roboto-cyrillic-300-normal-D568C3aM.woff +0 -0
- package/dist/frontend/assets/roboto-cyrillic-400-normal-DAIM1_dR.woff2 +0 -0
- package/dist/frontend/assets/roboto-cyrillic-400-normal-DZJji7Rx.woff +0 -0
- package/dist/frontend/assets/roboto-cyrillic-500-normal-BI4HuXre.woff +0 -0
- package/dist/frontend/assets/roboto-cyrillic-500-normal-hCeO1jFL.woff2 +0 -0
- package/dist/frontend/assets/roboto-cyrillic-700-normal-BiSG5NnW.woff2 +0 -0
- package/dist/frontend/assets/roboto-cyrillic-700-normal-KqaQ5bNp.woff +0 -0
- package/dist/frontend/assets/roboto-cyrillic-ext-300-normal-CUPJdUZp.woff2 +0 -0
- package/dist/frontend/assets/roboto-cyrillic-ext-300-normal-DQdcc27I.woff +0 -0
- package/dist/frontend/assets/roboto-cyrillic-ext-400-normal-DtZHuW6i.woff +0 -0
- package/dist/frontend/assets/roboto-cyrillic-ext-400-normal-DzMWdK87.woff2 +0 -0
- package/dist/frontend/assets/roboto-cyrillic-ext-500-normal-B7rQpwPu.woff2 +0 -0
- package/dist/frontend/assets/roboto-cyrillic-ext-500-normal-C927yMrb.woff +0 -0
- package/dist/frontend/assets/roboto-cyrillic-ext-700-normal-BuQgZIrO.woff +0 -0
- package/dist/frontend/assets/roboto-cyrillic-ext-700-normal-UFn0vR9r.woff2 +0 -0
- package/dist/frontend/assets/roboto-greek-300-normal-CTj2MfNN.woff +0 -0
- package/dist/frontend/assets/roboto-greek-300-normal-Cnub06j7.woff2 +0 -0
- package/dist/frontend/assets/roboto-greek-400-normal-CcizSnRP.woff +0 -0
- package/dist/frontend/assets/roboto-greek-400-normal-jFM2czAU.woff2 +0 -0
- package/dist/frontend/assets/roboto-greek-500-normal-BJMS0heP.woff2 +0 -0
- package/dist/frontend/assets/roboto-greek-500-normal-BLLWU9W-.woff +0 -0
- package/dist/frontend/assets/roboto-greek-700-normal-BcGn9doz.woff2 +0 -0
- package/dist/frontend/assets/roboto-greek-700-normal-D3kmAf0K.woff +0 -0
- package/dist/frontend/assets/roboto-latin-300-normal-CztWkFGs.woff2 +0 -0
- package/dist/frontend/assets/roboto-latin-300-normal-KByCBsad.woff +0 -0
- package/dist/frontend/assets/roboto-latin-400-normal-068yxgMN.woff +0 -0
- package/dist/frontend/assets/roboto-latin-400-normal-CNwBRw8h.woff2 +0 -0
- package/dist/frontend/assets/roboto-latin-500-normal-CC5nhZkh.woff +0 -0
- package/dist/frontend/assets/roboto-latin-500-normal-CkrA1NAy.woff2 +0 -0
- package/dist/frontend/assets/roboto-latin-700-normal-CXeAXeti.woff2 +0 -0
- package/dist/frontend/assets/roboto-latin-700-normal-DUekQERp.woff +0 -0
- package/dist/frontend/assets/roboto-latin-ext-300-normal-BOz0oSmX.woff2 +0 -0
- package/dist/frontend/assets/roboto-latin-ext-300-normal-Tcf9y2tg.woff +0 -0
- package/dist/frontend/assets/roboto-latin-ext-400-normal-ZYmyxeOy.woff2 +0 -0
- package/dist/frontend/assets/roboto-latin-ext-400-normal-eTRLN0Nt.woff +0 -0
- package/dist/frontend/assets/roboto-latin-ext-500-normal-C_ARlJGk.woff2 +0 -0
- package/dist/frontend/assets/roboto-latin-ext-500-normal-FFcS8vBN.woff +0 -0
- package/dist/frontend/assets/roboto-latin-ext-700-normal-70GS1MYH.woff2 +0 -0
- package/dist/frontend/assets/roboto-latin-ext-700-normal-BS1OuQqR.woff +0 -0
- package/dist/frontend/assets/roboto-math-300-normal-BMxwzQmU.woff2 +0 -0
- package/dist/frontend/assets/roboto-math-300-normal-BU9CUCyj.woff +0 -0
- package/dist/frontend/assets/roboto-math-400-normal-B3wgz80t.woff2 +0 -0
- package/dist/frontend/assets/roboto-math-400-normal-rzxYvyVt.woff +0 -0
- package/dist/frontend/assets/roboto-math-500-normal-CFNaIMFC.woff2 +0 -0
- package/dist/frontend/assets/roboto-math-500-normal-DaFX-ZC8.woff +0 -0
- package/dist/frontend/assets/roboto-math-700-normal-VUAI6Bz2.woff2 +0 -0
- package/dist/frontend/assets/roboto-math-700-normal-pYD1nhov.woff +0 -0
- package/dist/frontend/assets/roboto-symbols-300-normal-BtHl5mYl.woff2 +0 -0
- package/dist/frontend/assets/roboto-symbols-300-normal-kyoSXp-d.woff +0 -0
- package/dist/frontend/assets/roboto-symbols-400-normal-Tzuungub.woff +0 -0
- package/dist/frontend/assets/roboto-symbols-400-normal-fF1SLJBj.woff2 +0 -0
- package/dist/frontend/assets/roboto-symbols-500-normal-BXFTxrNR.woff2 +0 -0
- package/dist/frontend/assets/roboto-symbols-500-normal-CAhAe-ik.woff +0 -0
- package/dist/frontend/assets/roboto-symbols-700-normal-CuuvBBxy.woff +0 -0
- package/dist/frontend/assets/roboto-symbols-700-normal-rJi6RjIy.woff2 +0 -0
- package/dist/frontend/assets/roboto-vietnamese-300-normal-CNeuLW5X.woff2 +0 -0
- package/dist/frontend/assets/roboto-vietnamese-300-normal-DXBG9gdz.woff +0 -0
- package/dist/frontend/assets/roboto-vietnamese-400-normal-CDDxGrUb.woff2 +0 -0
- package/dist/frontend/assets/roboto-vietnamese-400-normal-DmXaN3yE.woff +0 -0
- package/dist/frontend/assets/roboto-vietnamese-500-normal-DW96CsrR.woff +0 -0
- package/dist/frontend/assets/roboto-vietnamese-500-normal-HYpufUYk.woff2 +0 -0
- package/dist/frontend/assets/roboto-vietnamese-700-normal-Dz0HwF-w.woff +0 -0
- package/dist/frontend/assets/roboto-vietnamese-700-normal-iKxYNAzq.woff2 +0 -0
- package/dist/frontend/assets/vitesse-dark-D0r3Knsf.js +1 -0
- package/dist/frontend/assets/vitesse-light-CVO1_9PV.js +1 -0
- package/dist/frontend/hamh-logo.svg +12 -0
- package/dist/frontend/index.html +17 -0
- package/package.json +105 -0
package/README.md
ADDED
|
@@ -0,0 +1,479 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# Home-Assistant-Matter-Hub
|
|
4
|
+
|
|
5
|
+

|
|
6
|
+
|
|
7
|
+
**Expose your Home Assistant devices to Matter controllers like Apple Home, Google Home, and Alexa**
|
|
8
|
+
|
|
9
|
+
[](https://github.com/RiDDiX/home-assistant-matter-hub/releases)
|
|
10
|
+
[](https://github.com/RiDDiX/home-assistant-matter-hub/releases)
|
|
11
|
+
[](https://github.com/RiDDiX/home-assistant-matter-hub/issues)
|
|
12
|
+
[](https://github.com/RiDDiX/home-assistant-matter-hub/stargazers)
|
|
13
|
+
[](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.26 | 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.26)</strong> - Click to expand</summary>
|
|
56
|
+
|
|
57
|
+
**New in v2.0.26:**
|
|
58
|
+
|
|
59
|
+
| Feature | Description |
|
|
60
|
+
|---------|-------------|
|
|
61
|
+
| **🔐 Authentication UI** | Configure authentication credentials directly from the web UI Settings page ([#197](https://github.com/RiDDiX/home-assistant-matter-hub/issues/197)) |
|
|
62
|
+
| **� Select Entity Support** | `select` and `input_select` entities now mapped to Matter ModeSelectDevice — each option becomes a selectable mode in your controller |
|
|
63
|
+
| **🔗 Webhook Event Bridge** | HAMH fires `hamh_action` events on the HA event bus when controllers interact with exposed devices — enables HA automations from controller commands |
|
|
64
|
+
| **🔍 Cluster Diagnostics** | Expandable per-cluster state inspection on device cards — see all cluster attribute values without parsing logs |
|
|
65
|
+
| **⚠️ Compatibility Warnings** | Bridge editor shows dynamic warnings for conflicting feature flags (e.g., Server Mode + Vacuum OnOff) |
|
|
66
|
+
| **🤖 Vacuum Cleaning Mode Fallback** | "Vacuum Then Mop" (mode 7) now falls back to "Vacuum & Mop" when the cleaning mode entity doesn't have a dedicated option ([#189](https://github.com/RiDDiX/home-assistant-matter-hub/issues/189)) |
|
|
67
|
+
| **🤖 Vacuum Entity Filter Fix** | Changing the entity filter on an existing server-mode bridge now correctly updates the endpoint ([#202](https://github.com/RiDDiX/home-assistant-matter-hub/issues/202)) |
|
|
68
|
+
| **🤖 Vacuum PowerSource Fix** | Restored PowerSource device type on vacuum endpoints for Alexa compatibility ([#183](https://github.com/RiDDiX/home-assistant-matter-hub/issues/183)) |
|
|
69
|
+
| **🤖 RVC Spec Compliance** | Mode validation in `changeToMode` overrides prevents silent failures with Alexa |
|
|
70
|
+
| **� Matter.js 0.16.10** | Updated from 0.16.8 to 0.16.10 for stability and spec compliance improvements |
|
|
71
|
+
| **� Docker Node 22** | Pinned Docker runtime to Node 22 to fix `ERR_INVALID_PACKAGE_CONFIG` on some platforms ([#200](https://github.com/RiDDiX/home-assistant-matter-hub/issues/200)) |
|
|
72
|
+
| **� Cover Inversion Fix** | `coverSwapOpenClose` now also inverts position reporting |
|
|
73
|
+
| **� Media Player Keypad** | Implemented KeypadInputServer for BasicVideoPlayer media endpoints |
|
|
74
|
+
| **🤖 Vacuum OnOff Fix** | `turnOff` now sends `return_to_base` instead of `stop` |
|
|
75
|
+
| **🏥 Session Logging** | Non-destructive session lifecycle logging for diagnostic visibility ([#105](https://github.com/RiDDiX/home-assistant-matter-hub/issues/105)) |
|
|
76
|
+
|
|
77
|
+
**Previously in v2.0.25:**
|
|
78
|
+
|
|
79
|
+
| Feature | Description |
|
|
80
|
+
|---------|-------------|
|
|
81
|
+
| **🤖 Vacuum Mop Intensity** | `mopIntensityEntity` mapping adds mop intensity modes to Apple Home's extra features panel |
|
|
82
|
+
| **🤖 Vacuum Auto-Detection** | Cleaning mode, suction level, and mop intensity entities auto-detected for Dreame, Roborock, Ecovacs |
|
|
83
|
+
| **🤖 Roborock Room Auto-Detect** | Rooms resolved via `roborock.get_maps` — no manual button mapping needed |
|
|
84
|
+
| **� Live Entity Mapping** | Device type changes take effect automatically without bridge restart ([#192](https://github.com/RiDDiX/home-assistant-matter-hub/issues/192)) |
|
|
85
|
+
| **💾 Dynamic Heap Sizing** | Node.js heap calculated from system RAM (25%, 256–1024 MB) ([#190](https://github.com/RiDDiX/home-assistant-matter-hub/issues/190)) |
|
|
86
|
+
|
|
87
|
+
</details>
|
|
88
|
+
|
|
89
|
+
<details>
|
|
90
|
+
<summary><strong>🧪 Alpha Features (v2.1.0-alpha.x)</strong> - Click to expand</summary>
|
|
91
|
+
|
|
92
|
+
**Alpha is currently in sync with Stable (v2.0.26).** All alpha features have been promoted to stable. New alpha features will appear here as development continues.
|
|
93
|
+
|
|
94
|
+
</details>
|
|
95
|
+
|
|
96
|
+
<details>
|
|
97
|
+
<summary><strong>⚠️ Testing Features (v4.1.0-testing)</strong> - Click to expand</summary>
|
|
98
|
+
|
|
99
|
+
> [!CAUTION]
|
|
100
|
+
> Testing versions are **highly unstable** and intended for developers only!
|
|
101
|
+
|
|
102
|
+
**🏗️ Vision 1: Callback-based Architecture**
|
|
103
|
+
|
|
104
|
+
| Old (Legacy) | New (Vision 1) |
|
|
105
|
+
|--------------|----------------|
|
|
106
|
+
| Behaviors update themselves | Endpoint updates behaviors via `setStateOf()` |
|
|
107
|
+
| Behaviors call HA actions directly | Behaviors notify via `notifyEndpoint()` |
|
|
108
|
+
|
|
109
|
+
**New Callback-Behaviors:** OnOff, LevelControl, Lock, Cover, Fan, ColorControl, VacuumRunMode, VacuumOperationalState
|
|
110
|
+
|
|
111
|
+
**Updated Endpoints:** Switch, Lock, Cover, Vacuum, Button, Valve, Scene, Humidifier, Light, Fan
|
|
112
|
+
|
|
113
|
+
</details>
|
|
114
|
+
|
|
115
|
+
<details>
|
|
116
|
+
<summary><strong>📜 Previous Stable Versions</strong> - Click to expand</summary>
|
|
117
|
+
|
|
118
|
+
### v2.0.25
|
|
119
|
+
Vacuum mop intensity, vacuum auto-detection, Roborock room auto-detect, live entity mapping, dynamic heap sizing, multi-fabric commissioning, fan speed label fix
|
|
120
|
+
|
|
121
|
+
### v2.0.24
|
|
122
|
+
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
|
|
123
|
+
|
|
124
|
+
### v2.0.19–v2.0.23
|
|
125
|
+
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)
|
|
126
|
+
|
|
127
|
+
### v2.0.17 / v2.0.18
|
|
128
|
+
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
|
|
129
|
+
|
|
130
|
+
### v2.0.16
|
|
131
|
+
Force Sync, Lock PIN, Cover/Blinds improvements, Roborock Rooms, Auto Entity Grouping, Water Heater, Vacuum Server Mode, OOM fix
|
|
132
|
+
|
|
133
|
+
### v1.10.4
|
|
134
|
+
Climate/Thermostat fixes, Cover position fix, Vacuum battery, Humidifier improvements, Entity Mapping, Alexa brightness preserve
|
|
135
|
+
|
|
136
|
+
### v1.9.0
|
|
137
|
+
Custom bridge icons, Basic Video Player (TV), Alexa deduplication, Auto-only thermostat, Health Check API, WebSocket, Full backup/restore
|
|
138
|
+
|
|
139
|
+
### v1.8.x
|
|
140
|
+
Graceful crash handler, PM2.5/PM10 sensors, Water Valve, Smoke/CO Detector, Pressure/Flow sensors, Air Purifier, Pump device
|
|
141
|
+
|
|
142
|
+
### v1.7.x
|
|
143
|
+
Dark Mode toggle, Device list sorting
|
|
144
|
+
|
|
145
|
+
### v1.5.x
|
|
146
|
+
Matter Bridge, Multi-Fabric support, Health Monitoring, Bridge Wizard, AirQuality sensors, Fan control, Media playback
|
|
147
|
+
|
|
148
|
+
</details>
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
152
|
+
## Supported Device Types
|
|
153
|
+
|
|
154
|
+
| Home Assistant Domain | Matter Device Type | Feature Flags |
|
|
155
|
+
|-----------------------|-------------------|---------------|
|
|
156
|
+
| `light` | On/Off, Dimmable, Color Temp, Extended Color | `powerEntity`, `energyEntity` |
|
|
157
|
+
| `switch`, `input_boolean` | On/Off Plug-in Unit | `powerEntity`, `energyEntity` |
|
|
158
|
+
| `lock` | Door Lock | PIN Credentials, Unlatch/Unbolt |
|
|
159
|
+
| `cover` | Window Covering | `coverSwapOpenClose` |
|
|
160
|
+
| `climate` | Thermostat | Battery via `batteryEntity` |
|
|
161
|
+
| `fan` | Fan, Air Purifier | Oscillation, Wind Modes |
|
|
162
|
+
| `binary_sensor` | Contact, OnOff, Occupancy, Smoke/CO, Water Leak, Water Freeze | |
|
|
163
|
+
| `sensor` | Temperature, Humidity, Pressure, Flow, Light, AirQuality | `batteryEntity`, `humidityEntity`, `pressureEntity` |
|
|
164
|
+
| `event` | Generic Switch (Doorbell, Button Events) | |
|
|
165
|
+
| `button`, `input_button` | Generic Switch | |
|
|
166
|
+
| `media_player` | Speaker, Basic Video Player (TV) | |
|
|
167
|
+
| `valve` | Water Valve, Pump | |
|
|
168
|
+
| `select`, `input_select` | Mode Select | |
|
|
169
|
+
| `vacuum` | Robot Vacuum Cleaner | `serverMode`, `roomEntities`, `batteryEntity`, `cleaningModeEntity`, `suctionLevelEntity`, `mopIntensityEntity` |
|
|
170
|
+
| `humidifier` | Humidifier/Dehumidifier | |
|
|
171
|
+
| `water_heater` | Thermostat (Heating) | |
|
|
172
|
+
| `automation`, `script`, `scene` | On/Off Switch | |
|
|
173
|
+
|
|
174
|
+
> 📖 See [Supported Device Types Documentation](https://riddix.github.io/home-assistant-matter-hub/Supported%20Device%20Types/) for details
|
|
175
|
+
|
|
176
|
+
---
|
|
177
|
+
|
|
178
|
+
## 🤖 Robot Vacuum Server Mode
|
|
179
|
+
|
|
180
|
+
<details>
|
|
181
|
+
<summary><strong>⚠️ Important: Apple Home & Alexa require Server Mode for Robot Vacuums</strong> (click to expand)</summary>
|
|
182
|
+
|
|
183
|
+
### The Problem
|
|
184
|
+
|
|
185
|
+
Apple Home and Alexa **do not properly support bridged robot vacuums**. When your vacuum is exposed through a standard Matter bridge, you may experience:
|
|
186
|
+
|
|
187
|
+
- **Apple Home**: "Updating" status, Siri commands don't work, room selection fails
|
|
188
|
+
- **Alexa**: Vacuum is not discovered at all
|
|
189
|
+
|
|
190
|
+
This is because these platforms expect robot vacuums to be **standalone Matter devices**, not bridged devices.
|
|
191
|
+
|
|
192
|
+
### The Solution: Server Mode
|
|
193
|
+
|
|
194
|
+
**Server Mode** exposes your vacuum as a standalone Matter device without the bridge wrapper. This makes it fully compatible with Apple Home and Alexa.
|
|
195
|
+
|
|
196
|
+
### Setup Instructions
|
|
197
|
+
|
|
198
|
+
1. **Create a new bridge** in the Matter Hub web interface
|
|
199
|
+
2. **Enable "Server Mode"** checkbox in the bridge creation wizard
|
|
200
|
+
3. Add **only your vacuum** to this bridge
|
|
201
|
+
4. **Pair the new Server Mode bridge** with Apple Home or Alexa
|
|
202
|
+
5. Your other devices stay on your regular bridge(s)
|
|
203
|
+
|
|
204
|
+
### Important Notes
|
|
205
|
+
|
|
206
|
+
- Server Mode bridges support **exactly one device**
|
|
207
|
+
- Your vacuum needs its own dedicated Server Mode bridge
|
|
208
|
+
- Other device types (lights, switches, sensors) work fine on regular bridges
|
|
209
|
+
- After switching to Server Mode, Siri commands like "Hey Siri, start the vacuum" will work
|
|
210
|
+
|
|
211
|
+
### Documentation
|
|
212
|
+
|
|
213
|
+
For more details, see the [Robot Vacuum Documentation](https://riddix.github.io/home-assistant-matter-hub/Devices/Robot%20Vacuum/).
|
|
214
|
+
|
|
215
|
+
</details>
|
|
216
|
+
|
|
217
|
+
---
|
|
218
|
+
|
|
219
|
+
## Installation
|
|
220
|
+
|
|
221
|
+
### Home Assistant Add-on (Recommended)
|
|
222
|
+
|
|
223
|
+
Add this repository to your Add-on Store:
|
|
224
|
+
|
|
225
|
+
```
|
|
226
|
+
https://github.com/RiDDiX/home-assistant-addons
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
Two add-ons are available:
|
|
230
|
+
- **Home-Assistant-Matter-Hub** - Stable release
|
|
231
|
+
- **Home-Assistant-Matter-Hub (Alpha)** - Pre-release for testing
|
|
232
|
+
|
|
233
|
+
### Docker
|
|
234
|
+
|
|
235
|
+
```bash
|
|
236
|
+
docker run -d \
|
|
237
|
+
--name home-assistant-matter-hub \
|
|
238
|
+
--network host \
|
|
239
|
+
-v /path/to/data:/data \
|
|
240
|
+
-e HAMH_HOME_ASSISTANT_URL=http://192.168.178.123:8123 \
|
|
241
|
+
-e HAMH_HOME_ASSISTANT_ACCESS_TOKEN=your_long_lived_access_token \
|
|
242
|
+
ghcr.io/riddix/home-assistant-matter-hub:latest
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
> **Note:** All environment variables require the `HAMH_` prefix.
|
|
246
|
+
> See the [Installation Guide](docs/Getting%20Started/Installation.md) for all available options.
|
|
247
|
+
|
|
248
|
+
For alpha versions, use tag `alpha` instead of `latest`.
|
|
249
|
+
|
|
250
|
+
---
|
|
251
|
+
|
|
252
|
+
## Documentation
|
|
253
|
+
|
|
254
|
+
Please see the [documentation](https://riddix.github.io/home-assistant-matter-hub) for detailed installation instructions,
|
|
255
|
+
configuration options, known issues, limitations and guides.
|
|
256
|
+
|
|
257
|
+
---
|
|
258
|
+
|
|
259
|
+
## 🔧 Network Troubleshooting
|
|
260
|
+
|
|
261
|
+
<details>
|
|
262
|
+
<summary><strong>⚠️ "No Response" / Connection Drops — Common Network Causes</strong> (click to expand)</summary>
|
|
263
|
+
|
|
264
|
+
### The Problem
|
|
265
|
+
|
|
266
|
+
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.
|
|
267
|
+
|
|
268
|
+
### Root Cause: Network Equipment Blocking mDNS/Multicast
|
|
269
|
+
|
|
270
|
+
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.
|
|
271
|
+
|
|
272
|
+
> **💡 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.
|
|
273
|
+
|
|
274
|
+
### What to Check on Your Network Equipment
|
|
275
|
+
|
|
276
|
+
1. **IGMP Snooping** — Disable or configure it to allow mDNS (`224.0.0.251` / `ff02::fb`)
|
|
277
|
+
2. **Multicast Optimization / Multicast Enhancement** — Disable (often called "Airtime Fairness" or "Multicast to Unicast")
|
|
278
|
+
3. **AP Isolation / Client Isolation** — Must be **disabled** so devices on the same network can communicate
|
|
279
|
+
4. **mDNS / Bonjour Forwarding** — Enable if available (some enterprise APs have this)
|
|
280
|
+
5. **DHCP Server on secondary devices** — Disable DHCP on access points / switches that are NOT your main router (multiple DHCP servers cause IP conflicts)
|
|
281
|
+
6. **Firmware Updates** — Update your router/AP firmware, as multicast handling is frequently improved
|
|
282
|
+
|
|
283
|
+
### Affected Equipment (Known Cases)
|
|
284
|
+
|
|
285
|
+
| Device | Issue | Fix |
|
|
286
|
+
|--------|-------|-----|
|
|
287
|
+
| **TP-Link Archer AX50** (AP mode) | mDNS traffic blocked/limited over time | Firmware update + disable DHCP on the AP |
|
|
288
|
+
| **Ubiquiti UniFi APs** | IGMP Snooping can filter mDNS | Disable IGMP Snooping or enable mDNS Reflector |
|
|
289
|
+
| **Managed Switches** (various) | Multicast filtering enabled by default | Allow mDNS multicast groups |
|
|
290
|
+
|
|
291
|
+
### Quick Diagnostic Steps
|
|
292
|
+
|
|
293
|
+
1. **Does Alexa still work when Apple Home shows "No Response"?**
|
|
294
|
+
- **Yes** → Bridge is online, the issue is network path / mDNS related
|
|
295
|
+
- **No** → Bridge may actually be down, check HAMH logs
|
|
296
|
+
|
|
297
|
+
2. **Does removing a Home Hub (HomePod/Apple TV) fix it?**
|
|
298
|
+
- **Yes** → The hub's network path is affected (AP/switch between hub and bridge)
|
|
299
|
+
- **No** → May be a different issue
|
|
300
|
+
|
|
301
|
+
3. **Try binding mDNS to a specific interface:**
|
|
302
|
+
```
|
|
303
|
+
--mdns-network-interface eth0
|
|
304
|
+
```
|
|
305
|
+
(or `end0`, `enp0s18`, etc. — check your system)
|
|
306
|
+
|
|
307
|
+
### Network Topology Tips
|
|
308
|
+
|
|
309
|
+
- **Keep the path simple**: Avoid placing access points or managed switches between your Matter bridge (Home Assistant) and your Home Hub (HomePod/Apple TV)
|
|
310
|
+
- **Use wired connections** where possible for Home Hubs and the Home Assistant host
|
|
311
|
+
- **Same subnet**: All Matter devices, controllers, and the bridge must be on the same Layer 2 network / subnet
|
|
312
|
+
- **IPv6**: Matter uses IPv6 link-local addresses — make sure IPv6 is not disabled on your network
|
|
313
|
+
|
|
314
|
+
</details>
|
|
315
|
+
|
|
316
|
+
---
|
|
317
|
+
|
|
318
|
+
## Migration from t0bst4r
|
|
319
|
+
|
|
320
|
+
Migrating from the original `t0bst4r/home-assistant-matter-hub` is straightforward. **Your Matter fabric connections and paired devices will be preserved!**
|
|
321
|
+
|
|
322
|
+
### Home Assistant Add-on
|
|
323
|
+
|
|
324
|
+
1. **Backup your data:**
|
|
325
|
+
```bash
|
|
326
|
+
cp -r /addon_configs/*_hamh /config/hamh-backup
|
|
327
|
+
# Verify the backup was copied correctly
|
|
328
|
+
ls /config/hamh-backup
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
2. **Uninstall the old add-on** (Settings → Add-ons → Uninstall) and make sure the old folder is removed:
|
|
332
|
+
```bash
|
|
333
|
+
rm -rf /addon_configs/*_hamh
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
3. **Add the new repository:**
|
|
337
|
+
```
|
|
338
|
+
https://github.com/RiDDiX/home-assistant-addons
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
4. **Install and start the new add-on once** (creates the data folder), then **stop it**
|
|
342
|
+
|
|
343
|
+
5. **Clear the new folder and restore your backup:**
|
|
344
|
+
```bash
|
|
345
|
+
rm -rf /addon_configs/*_hamh/*
|
|
346
|
+
cp -r /config/hamh-backup/* /addon_configs/*_hamh/
|
|
347
|
+
```
|
|
348
|
+
|
|
349
|
+
6. **Start the add-on again** - your devices should reconnect automatically
|
|
350
|
+
|
|
351
|
+
### Docker / Docker Compose
|
|
352
|
+
|
|
353
|
+
Simply change the image from:
|
|
354
|
+
```
|
|
355
|
+
ghcr.io/t0bst4r/home-assistant-matter-hub:latest
|
|
356
|
+
```
|
|
357
|
+
to:
|
|
358
|
+
```
|
|
359
|
+
ghcr.io/riddix/home-assistant-matter-hub:latest
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
Your volume mounts stay the same - no data migration needed.
|
|
363
|
+
|
|
364
|
+
> For detailed instructions, see the [full Migration Guide](https://riddix.github.io/home-assistant-matter-hub/migration-from-t0bst4r/).
|
|
365
|
+
|
|
366
|
+
---
|
|
367
|
+
|
|
368
|
+
## 🙏 Contributors & Acknowledgments
|
|
369
|
+
|
|
370
|
+
This project thrives thanks to the amazing community! Special thanks to everyone who contributes by reporting bugs, suggesting features, and helping others.
|
|
371
|
+
|
|
372
|
+
### 🏆 Top Contributors
|
|
373
|
+
|
|
374
|
+
| Contributor | Contributions |
|
|
375
|
+
|-------------|---------------|
|
|
376
|
+
| [@codyc1515](https://github.com/codyc1515) | 🥇 **Top Reporter** - Climate/thermostat bugs (#52, #24, #21, #20), extensive testing feedback |
|
|
377
|
+
| [@Hatton920](https://github.com/Hatton920) | 🤖 **Vacuum Expert** - Intensive testing of Robot Vacuum Server Mode, Apple Home & Siri validation |
|
|
378
|
+
| [@Chrulf](https://github.com/Chrulf) | 🔍 Google Home brightness debugging (#41), detailed logs & testing |
|
|
379
|
+
| [@SH1FT-W](https://github.com/SH1FT-W) | 💎 **Sponsor** + Vacuum room selection feature request (#49) |
|
|
380
|
+
| [@depahk](https://github.com/depahk) | 📝 Migration documentation fix ([#32](https://github.com/RiDDiX/home-assistant-matter-hub/pull/32)) |
|
|
381
|
+
| [@Fettkeewl](https://github.com/Fettkeewl) | 🐛 Script import bug (#26), Alias feature request (#25) |
|
|
382
|
+
| [@razzietheman](https://github.com/razzietheman) | 🥈 **Active Tester** - Bridge icons (#101), sorting (#80), feature requests (#31, #30), extensive UI/UX feedback |
|
|
383
|
+
| [@markgaze](https://github.com/markgaze) | 🤖 **Code Contributor** - Ecovacs Deebot room support ([#118](https://github.com/RiDDiX/home-assistant-matter-hub/pull/118)) |
|
|
384
|
+
| [@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)) |
|
|
385
|
+
|
|
386
|
+
<details>
|
|
387
|
+
<summary><strong>📋 Issue Tracker - All Contributors</strong> (click to expand)</summary>
|
|
388
|
+
|
|
389
|
+
Thank you to everyone who helps improve this project by reporting issues!
|
|
390
|
+
|
|
391
|
+
| User | Issues |
|
|
392
|
+
|------|--------|
|
|
393
|
+
| [@omerfaruk-aran](https://github.com/omerfaruk-aran) | #129 |
|
|
394
|
+
| [@markgaze](https://github.com/markgaze) | #118 |
|
|
395
|
+
| [@BlairC1](https://github.com/BlairC1) | #117 |
|
|
396
|
+
| [@Giamp96](https://github.com/Giamp96) | #116 |
|
|
397
|
+
| [@NdR91](https://github.com/NdR91) | #115 #106 |
|
|
398
|
+
| [@Fry7](https://github.com/Fry7) | #114 |
|
|
399
|
+
| [@siobhanellis](https://github.com/siobhanellis) | #112 |
|
|
400
|
+
| [@Hatton920](https://github.com/Hatton920) | #110 |
|
|
401
|
+
| [@gette](https://github.com/gette) | #95 |
|
|
402
|
+
| [@400HPMustang](https://github.com/400HPMustang) | #103 |
|
|
403
|
+
| [@vandir](https://github.com/vandir) | #102 |
|
|
404
|
+
| [@razzietheman](https://github.com/razzietheman) | #101 #100 #80 #31 #30 |
|
|
405
|
+
| [@seitenprofi](https://github.com/seitenprofi) | #176 |
|
|
406
|
+
| [@semonR](https://github.com/semonR) | #99 #58 |
|
|
407
|
+
| [@italoc](https://github.com/italoc) | #78 |
|
|
408
|
+
| [@marksev1](https://github.com/marksev1) | #62 |
|
|
409
|
+
| [@smacpi](https://github.com/smacpi) | #60 |
|
|
410
|
+
| [@mrbluebrett](https://github.com/mrbluebrett) | #53 |
|
|
411
|
+
| [@anpak](https://github.com/anpak) | #45 |
|
|
412
|
+
| [@alondin](https://github.com/alondin) | #43 |
|
|
413
|
+
| [@Chrulf](https://github.com/Chrulf) | #41 |
|
|
414
|
+
| [@Weske90](https://github.com/Weske90) | #40 |
|
|
415
|
+
| [@didiht](https://github.com/didiht) | #37 |
|
|
416
|
+
| [@Dixiland20](https://github.com/Dixiland20) | #34 |
|
|
417
|
+
| [@chromaxx7](https://github.com/chromaxx7) | #29 |
|
|
418
|
+
| [@Tomyk9991](https://github.com/Tomyk9991) | #28 |
|
|
419
|
+
| [@datvista](https://github.com/datvista) | #27 |
|
|
420
|
+
| [@bwynants](https://github.com/bwynants) | #23 |
|
|
421
|
+
| [@Pozzi831](https://github.com/Pozzi831) | #22 |
|
|
422
|
+
| [@codyc1515](https://github.com/codyc1515) | #52 #24 #21 #20 |
|
|
423
|
+
|
|
424
|
+
</details>
|
|
425
|
+
|
|
426
|
+
### 💖 Sponsors
|
|
427
|
+
|
|
428
|
+
> **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. ❤️
|
|
429
|
+
|
|
430
|
+
| Sponsor | |
|
|
431
|
+
|---------|---|
|
|
432
|
+
| [@thorsten-gehrig](https://github.com/thorsten-gehrig) | 🥇 **First Sponsor!** Thank you for believing in this project! |
|
|
433
|
+
| [@SH1FT-W](https://github.com/SH1FT-W) | 💎 Thank you for your generous support! |
|
|
434
|
+
| [@ilGaspa](https://github.com/ilGaspa) | 💎 Thank you for your generous support! |
|
|
435
|
+
| [@linux4life798](https://github.com/linux4life798) | 💎 Thank you for your generous support! |
|
|
436
|
+
| [@torandreroland](https://github.com/torandreroland) | 💎 Thank you for your generous support! |
|
|
437
|
+
| [@ralondo](https://github.com/ralondo) | 💎 Thank you for your generous support! |
|
|
438
|
+
| [@bexxter85-ux](https://github.com/bexxter85-ux) | 💎 Thank you for your generous support! |
|
|
439
|
+
| [@dinariox](https://github.com/dinariox) | 💎 Thank you for your generous support! |
|
|
440
|
+
| StefanS | 💎 Thank you for your generous support! |
|
|
441
|
+
| Manny B. | 💎 Thank you for your generous support! |
|
|
442
|
+
| [@JRCondat](https://github.com/JRCondat) | 💎 Thank you for your generous support! |
|
|
443
|
+
| Bonjon | 💎 Thank you for your generous support! |
|
|
444
|
+
| TobiR | 💎 Thank you for your generous support! |
|
|
445
|
+
| *Anonymous supporters* | 🙏 Thank you to those who prefer not to be named - your support is equally appreciated! |
|
|
446
|
+
|
|
447
|
+
### 🌟 Original Author
|
|
448
|
+
|
|
449
|
+
- **[@t0bst4r](https://github.com/t0bst4r)** - Creator of the original Home-Assistant-Matter-Hub project
|
|
450
|
+
|
|
451
|
+
---
|
|
452
|
+
|
|
453
|
+
## ☕ Support the Project
|
|
454
|
+
|
|
455
|
+
> [!NOTE]
|
|
456
|
+
> **Completely optional!** This project will continue regardless of donations.
|
|
457
|
+
> I maintain this in my free time because I believe in open source.
|
|
458
|
+
|
|
459
|
+
If you find this project useful, consider supporting its development:
|
|
460
|
+
|
|
461
|
+
[](https://www.paypal.me/RiDDiX93)
|
|
462
|
+
|
|
463
|
+
Your support helps cover hosting costs and motivates continued development. Thank you! ❤️
|
|
464
|
+
|
|
465
|
+
---
|
|
466
|
+
|
|
467
|
+
## 📊 Project Stats
|
|
468
|
+
|
|
469
|
+
<div align="center">
|
|
470
|
+
|
|
471
|
+

|
|
472
|
+

|
|
473
|
+

|
|
474
|
+

|
|
475
|
+

|
|
476
|
+
|
|
477
|
+
</div>
|
|
478
|
+
|
|
479
|
+
---
|