@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.
- package/LICENSE +202 -0
- package/README.md +491 -0
- package/dist/backend/bootstrap.js +6 -0
- package/dist/backend/cli.js +178783 -0
- package/dist/backend/cli.js.map +7 -0
- package/dist/frontend/assets/index-BNdBOwwe.css +1 -0
- package/dist/frontend/assets/index-D-gJdVIp.js +499 -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,491 @@
|
|
|
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.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
|
+
[](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
|
+

|
|
484
|
+

|
|
485
|
+

|
|
486
|
+

|
|
487
|
+

|
|
488
|
+
|
|
489
|
+
</div>
|
|
490
|
+
|
|
491
|
+
---
|