Home-Assistant-Matter-Hub

Expose your Home Assistant devices to Matter controllers like Apple Home, Google Home, and Alexa

📖 Documentation • � Discord • �🐛 Report Bug • 💡 Request Feature

---

Note

🔀 Community Fork - This is a fork of the original 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 for the original work! ❤️

📦 Migrating? See Migration Guide - your paired devices will continue to work!

---

📝 About

This project simulates bridges to publish your entities from Home Assistant to any Matter-compatible controller like Alexa, Apple Home or Google Home. Using Matter, those can be connected easily using local communication without the need of port forwarding etc.

---

📦 Releases & Branches

Channel	Branch	Current Version	Description
Stable	main	v2.0.x	Production-ready, recommended for most users
Alpha	alpha	v2.1.0-alpha.x	Pre-release with new features, for early adopters
Testing	testing	v4.1.0-testing.x	⚠️ Highly unstable! Experimental features, may break

Which version should I use?

• Most users: Use Stable (main branch) - thoroughly tested
• Early adopters: Use Alpha (alpha branch) - new features, occasional bugs
• Developers/Testers: Use Testing (testing branch) - bleeding edge, expect breakage

---

🎉 What's New

📦 Stable Features (v2.0.x) - Click to expand

Feature	Description
🌬️ Fan Oscillation	Rocking/oscillation via Matter (#108)
🌬️ Wind Modes	Natural Wind, Sleep Wind preset modes
🔋 PowerSource	Battery support for Climate, Fan, Temperature sensors
🔒 Lock PIN	PBKDF2 hashed PINs, lock without PIN, per-lock disable option (#95)
🚪 Cover/Blinds	coverSwapOpenClose flag for Alexa (#117)
🔋 Battery Entity	batteryEntity mapping for Roomba/Deebot/Climate/Fan (#112)
🤖 Vacuum Rooms	Ecovacs Deebot, Roborock, Dreame room support (#118, #106)
🤖 Vacuum Cleaning Modes	Dreame cleaning mode entity mapping (#110)
� Force Sync	Push device states to controllers, auto-sync every 5min
�🔋 Auto Entity Grouping	Auto Battery/Humidity mapping feature flags
🏷️ Labels API	/api/matter/labels for label-based filtering
🌡️ Thermostat	Heat/Cool mode fix, AutoMode support
💡 Lights	ColorTemp + HueSat fix, boundary order fix
🌡️ Sensors	PM2.5/PM10/CO2/TVOC fixes, Apple Home defaults
🌬️ Air Purifier	HEPA Filter Life Monitoring
📋 Copy to Clipboard	Copy endpoint data button in UI (#121)
🐛 Bug Fixes	Lock initialization fix (#122), vacuum log spam fix (#123)

🧪 Alpha Features (v2.1.0-alpha.x) - Click to expand

[!NOTE] Alpha and Stable are currently synchronized. New alpha features will appear here.

Currently all features are in stable. Check back for upcoming features!

⚠️ Testing Features (v4.1.0-testing) - Click to expand

[!CAUTION] Testing versions are highly unstable and intended for developers only!

🏗️ Vision 1: Callback-based Architecture

Old (Legacy)	New (Vision 1)
Behaviors update themselves	Endpoint updates behaviors via setStateOf()
Behaviors call HA actions directly	Behaviors notify via notifyEndpoint()

New Callback-Behaviors: OnOff, LevelControl, Lock, Cover, Fan, ColorControl, VacuumRunMode, VacuumOperationalState

Updated Endpoints: Switch, Lock, Cover, Vacuum, Button, Valve, Scene, Humidifier, Light, Fan

📜 Previous Stable Versions - Click to expand

v2.0.x

Force Sync, Lock PIN, Cover/Blinds improvements, Roborock Rooms, Auto Entity Grouping, Water Heater, Vacuum Server Mode

v1.10.4

Climate/Thermostat fixes, Cover position fix, Vacuum battery, Humidifier improvements, Entity Mapping, Alexa brightness preserve

v1.9.0

Custom bridge icons, Basic Video Player (TV), Alexa deduplication, Auto-only thermostat, Health Check API, WebSocket, Full backup/restore

v1.8.x

Graceful crash handler, PM2.5/PM10 sensors, Water Valve, Smoke/CO Detector, Pressure/Flow sensors, Air Purifier, Pump device

v1.7.x

Dark Mode toggle, Device list sorting

v1.5.x

Matter Bridge, Multi-Fabric support, Health Monitoring, Bridge Wizard, AirQuality sensors, Fan control, Media playback

---

Supported Device Types

Home Assistant Domain	Matter Device Type	Feature Flags
light	On/Off, Dimmable, Color Temp, Extended Color
switch, input_boolean	On/Off Plug-in Unit
lock	Door Lock	PIN Credentials
cover	Window Covering	coverSwapOpenClose
climate	Thermostat	Battery via batteryEntity
fan	Fan, Air Purifier	Oscillation, Wind Modes
binary_sensor	Contact, Occupancy, Smoke/CO, Water Leak
sensor	Temperature, Humidity, Pressure, Flow, Light, AirQuality	batteryEntity, humidityEntity
button, input_button	Generic Switch
media_player	Speaker, Basic Video Player (TV)
valve	Water Valve, Pump
vacuum	Robot Vacuum Cleaner	serverMode, roomEntities, batteryEntity
humidifier	Humidifier/Dehumidifier
water_heater	Thermostat (Heating)
automation, script, scene	On/Off Switch

📖 See Supported Device Types Documentation for details

---

🤖 Robot Vacuum Server Mode

⚠️ Important: Apple Home & Alexa require Server Mode for Robot Vacuums (click to expand)

The Problem

Apple Home and Alexa do not properly support bridged robot vacuums. When your vacuum is exposed through a standard Matter bridge, you may experience:

• Apple Home: "Updating" status, Siri commands don't work, room selection fails
• Alexa: Vacuum is not discovered at all

This is because these platforms expect robot vacuums to be standalone Matter devices, not bridged devices.

The Solution: Server Mode

Server Mode exposes your vacuum as a standalone Matter device without the bridge wrapper. This makes it fully compatible with Apple Home and Alexa.

Setup Instructions

1. Create a new bridge in the Matter Hub web interface
2. Enable "Server Mode" checkbox in the bridge creation wizard
3. Add only your vacuum to this bridge
4. Pair the new Server Mode bridge with Apple Home or Alexa
5. Your other devices stay on your regular bridge(s)

Important Notes

• Server Mode bridges support exactly one device
• Your vacuum needs its own dedicated Server Mode bridge
• Other device types (lights, switches, sensors) work fine on regular bridges
• After switching to Server Mode, Siri commands like "Hey Siri, start the vacuum" will work

Documentation

For more details, see the Robot Vacuum Documentation.

---

Installation

Home Assistant Add-on (Recommended)

Add this repository to your Add-on Store:

https://github.com/RiDDiX/home-assistant-addons

Two add-ons are available:

• Home-Assistant-Matter-Hub - Stable release
• Home-Assistant-Matter-Hub (Alpha) - Pre-release for testing

Docker

docker run -d \
  --name home-assistant-matter-hub \
  --network host \
  -v /path/to/data:/data \
  -e HAMH_HOME_ASSISTANT_URL=http://192.168.178.123:8123 \
  -e HAMH_HOME_ASSISTANT_ACCESS_TOKEN=your_long_lived_access_token \
  ghcr.io/riddix/home-assistant-matter-hub:latest

Note: All environment variables require the HAMH_ prefix. See the Installation Guide for all available options.

For alpha versions, use tag alpha instead of latest.

---

Documentation

Please see the documentation for detailed installation instructions, configuration options, known issues, limitations and guides.

---

🔧 Network Troubleshooting

⚠️ "No Response" / Connection Drops — Common Network Causes (click to expand)

The Problem

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.

Root Cause: Network Equipment Blocking mDNS/Multicast

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.

💡 This was confirmed and documented thanks to the excellent systematic testing by @omerfaruk-aran in #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.

What to Check on Your Network Equipment

1. IGMP Snooping — Disable or configure it to allow mDNS (224.0.0.251 / ff02::fb)
2. Multicast Optimization / Multicast Enhancement — Disable (often called "Airtime Fairness" or "Multicast to Unicast")
3. AP Isolation / Client Isolation — Must be disabled so devices on the same network can communicate
4. mDNS / Bonjour Forwarding — Enable if available (some enterprise APs have this)
5. DHCP Server on secondary devices — Disable DHCP on access points / switches that are NOT your main router (multiple DHCP servers cause IP conflicts)
6. Firmware Updates — Update your router/AP firmware, as multicast handling is frequently improved

Affected Equipment (Known Cases)

Device	Issue	Fix
TP-Link Archer AX50 (AP mode)	mDNS traffic blocked/limited over time	Firmware update + disable DHCP on the AP
Ubiquiti UniFi APs	IGMP Snooping can filter mDNS	Disable IGMP Snooping or enable mDNS Reflector
Managed Switches (various)	Multicast filtering enabled by default	Allow mDNS multicast groups

Quick Diagnostic Steps

1. Does Alexa still work when Apple Home shows "No Response"?

   • Yes → Bridge is online, the issue is network path / mDNS related
   • No → Bridge may actually be down, check HAMH logs

2. Does removing a Home Hub (HomePod/Apple TV) fix it?

   • Yes → The hub's network path is affected (AP/switch between hub and bridge)
   • No → May be a different issue

3. Try binding mDNS to a specific interface:

   --mdns-network-interface eth0
   

   (or end0, enp0s18, etc. — check your system)

Network Topology Tips

• Keep the path simple: Avoid placing access points or managed switches between your Matter bridge (Home Assistant) and your Home Hub (HomePod/Apple TV)
• Use wired connections where possible for Home Hubs and the Home Assistant host
• Same subnet: All Matter devices, controllers, and the bridge must be on the same Layer 2 network / subnet
• IPv6: Matter uses IPv6 link-local addresses — make sure IPv6 is not disabled on your network

---

Migration from t0bst4r

Migrating from the original t0bst4r/home-assistant-matter-hub is straightforward. Your Matter fabric connections and paired devices will be preserved!

Home Assistant Add-on

1. Backup your data:

   # SSH into Home Assistant and find your add-on folder
   ls /addon_configs/
   # Look for folder ending with _hamh (e.g., a0c_hamh)
   
   cp -r /addon_configs/*_hamh /config/hamh-backup

2. Uninstall the old add-on (Settings → Add-ons → Uninstall)

3. Add the new repository:

   https://github.com/RiDDiX/home-assistant-addons
   

4. Install and start the new add-on, then check the new _hamh folder:

   ls /addon_configs/

5. Stop the add-on and restore your backup:

   cp -r /config/hamh-backup/* /addon_configs/*_hamh/

6. Start the add-on again - your devices should reconnect automatically

Docker / Docker Compose

Simply change the image from:

ghcr.io/t0bst4r/home-assistant-matter-hub:latest

to:

ghcr.io/riddix/home-assistant-matter-hub:latest

Your volume mounts stay the same - no data migration needed.

For detailed instructions, see the full Migration Guide.

---

🙏 Contributors & Acknowledgments

This project thrives thanks to the amazing community! Special thanks to everyone who contributes by reporting bugs, suggesting features, and helping others.

🏆 Top Contributors

Contributor	Contributions
@codyc1515	🥇 Top Reporter - Climate/thermostat bugs (#52, #24, #21, #20), extensive testing feedback
@Hatton920	🤖 Vacuum Expert - Intensive testing of Robot Vacuum Server Mode, Apple Home & Siri validation
@Chrulf	🔍 Google Home brightness debugging (#41), detailed logs & testing
@SH1FT-W	💎 Sponsor + Vacuum room selection feature request (#49)
@depahk	📝 Migration documentation fix (#32)
@Fettkeewl	🐛 Script import bug (#26), Alias feature request (#25)
@razzietheman	🥈 Active Tester - Bridge icons (#101), sorting (#80), feature requests (#31, #30), extensive UI/UX feedback
@markgaze	🤖 Code Contributor - Ecovacs Deebot room support (#118)
@omerfaruk-aran	🔧 Network Debugging Expert - Systematic mDNS/multicast root cause analysis for "No Response" issues (#129)

📋 Issue Tracker - All Contributors (click to expand)

Thank you to everyone who helps improve this project by reporting issues!

User	Issues
@omerfaruk-aran	#129
@markgaze	#118
@BlairC1	#117
@Giamp96	#116
@NdR91	#115 #106
@Fry7	#114
@siobhanellis	#112
@Hatton920	#110
@gette	#95
@400HPMustang	#103
@vandir	#102
@razzietheman	#101 #100 #80 #31 #30
@semonR	#99 #58
@italoc	#78
@marksev1	#62
@smacpi	#60
@mrbluebrett	#53
@anpak	#45
@alondin	#43
@Chrulf	#41
@Weske90	#40
@didiht	#37
@Dixiland20	#34
@chromaxx7	#29
@Tomyk9991	#28
@datvista	#27
@bwynants	#23
@Pozzi831	#22
@codyc1515	#52 #24 #21 #20

💖 Sponsors

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. ❤️

Sponsor
@thorsten-gehrig	🥇 First Sponsor! Thank you for believing in this project!
@SH1FT-W	💎 Thank you for your generous support!
@ilGaspa	💎 Thank you for your generous support!
@linux4life798	💎 Thank you for your generous support!
@torandreroland	💎 Thank you for your generous support!
Anonymous supporters	🙏 Thank you to those who prefer not to be named - your support is equally appreciated!

🌟 Original Author

• @t0bst4r - Creator of the original Home-Assistant-Matter-Hub project

---

☕ Support the Project

Note

Completely optional! This project will continue regardless of donations. I maintain this in my free time because I believe in open source.

If you find this project useful, consider supporting its development:

Your support helps cover hosting costs and motivates continued development. Thank you! ❤️

---

📊 Project Stats

---