Home-Assistant-Matter-Hub

---

Community Fork - This is the actively maintained fork and successor of t0bst4r/home-assistant-matter-hub, which was discontinued in January 2026 and has since been archived. We continue active development with bug fixes, new features, and community support. The Home Assistant add-on slugs are hamh (stable), hamh-alpha and hamh-testing.

We actively work on fixing old issues from the original project and welcome new feature requests. This is a living project maintained by the community! Coming from the original? See the fork comparison and the migration guide.

---

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.

---

Known issues and limitations

Device Type Support

This project does not yet support all available device types in the matter specification. In addition, controllers like Alexa or Google Home do not support all device types, too.

To check which types are supported, please review the list of supported device types.

Alexa

• Alexa cannot pair with a bridge which has too many devices attached. It seems to have a limit of about 80-100 devices
• Alexa needs at least one Amazon device which supports Matter to pair with a Matter device. If you only have a third party smart speaker which supports Alexa, this isn't enough.

Google Home

• Google Home needs an actual Google Hub to connect a Matter device. Just using the GH app isn't enough.
• Google Home can deny the Matter device under certain conditions because it is not a certified Matter device. You need to follow this guide to register your hub.

Network setup

The Matter protocol is designed to work best with UDP and IPv6 within your local network. At the moment some manufacturers built their controllers to be compatible with IPv4, too, but this can break at any time with any update.

Many users report connection issues when using VLANs or firewalls, where HAMH and the assistant devices (Alexa, Google Home, ...) are not placed in the same network segment. Please make sure to review the common connectivity issues.

What's New

📦 Stable (v2.0.58) - Current

New in v2.0.58:

• 🗂️ Old backups get deleted again: the automatic backup only runs while HAMH shuts down, and the add-on gets a few seconds to stop, so the backup could be cut off before it reached the cleanup. Every restart left one more half-written backup in the list. Old backups are now also cleaned up at startup, and a backup keeps a temporary name until it is complete, so a cut-off one never shows up (#483)
• 🛡️ Backup settings are checked: the settings endpoint only takes a keep count from 1 to 100, and a failed write (a full disk, for example) fails that backup instead of crashing the app. The Turkish, Portuguese (Brazil) and Traditional Chinese texts no longer promise a scheduled backup
• 📖 Docs: the Alexa "never connects" entry drops the fresh bridge advice, a new bridge did not help in #478, and says how to tell from the log whether the Echo reached the bridge
• 🔌 Port 80 in the network check: freeing it helped two users pair Alexa, so the Health Dashboard shows when it's in use (#449, #478)
• 💡 Wattage for lights in Apple Home: a light can be set to On/Off Plug-in Unit, Apple only shows wattage on outlets (#484)
• 📖 Docs: Apple Home power readings since iOS 27, and the port 80 note for Alexa
• 🔌 Each outlet of a power strip reports its own power (#488, thanks @barnabasbusa)
• 🔁 A bridge that went quiet comes back on its own: a subscription that died while starting left every device offline until a restart (#487)
• 🧽 Dishwashers understand Home Connect and SmartThings states (#486)
• 🧹 Vacuum rooms reset when a clean finishes on its own: the next clean started from Home Assistant could only match the old rooms (#490)
• 💡 No flash when Alexa dims a light that is off: it now turns on straight at the new level instead of its old brightness first (#491)
• 🧽 Dishwashers on a power switch show their real state: the Home Connect or SmartThings state sensor is picked up automatically (#486)
• 🧺 Washers and dryers on a power switch show their real state: Laundry Washer and Laundry Dryer types pick up the state from Home Connect, SmartThings, Miele or LG
• ✅ Vacuums and appliances report a finished clean or cycle
• 🏠 Every paired controller shows on the bridge card: it only showed Google and Alexa, and 4448 now shows as Sengled
• 📖 Controller support: SmartThings added, Apple no longer warns about fans, air purifiers and air quality, and Google no longer warns about smoke alarms and dishwashers
• 🌀 Fans and air purifiers follow Home Assistant again: speed and mode changes from HA stopped reaching controllers in alpha.880 and 2.0.57, only on/off still followed (#494, thanks @bigmike613)
• 🧹 Apple Home drops the old rooms during a clean started elsewhere: after a three room Apple job, a one room clean from Home Assistant still showed "cleaning 3 rooms" (#492)
• 🧹 Apple Home stays on Vacuuming after a start: while the vacuum was still leaving the dock, Home flipped to "Ready, Resume Cleaning Later" for a few seconds (#496)
• 🪟 Dashboard cover chip shows how far it is open: a closed cover showed "100% open", controllers were never affected (#495)
• 🗺️ Vacuum rooms stay in the run mode list: Valetudo and auto-detected Roborock rooms fell out after the first Home Assistant update, CLEAN_AREA rooms right at startup, so controllers such as Alexa saw only Idle and Cleaning (#497)
• 🔋 Battery sensors stop showing up as their own device: a battery that was unavailable during a refresh got its own device next to the temperature sensor and stayed, and a temperature sensor built in that moment never picked its battery up (#498)
• 🧹 Vacuum current room and room names in Apple Home: the current room follows the robot through rooms outside the job, and a room renamed in Home Assistant reaches the room list without re-pairing (#501)
• ↩️ Failed Home Assistant calls no longer leave a stale state: when a call fails after the command was accepted, the device goes back to its Home Assistant state within a second instead of staying "opening" or "on" (#446)
• 🇳🇱 Dutch translation: new nl locale, thanks @toineenzo (#503)
• 🇫🇷 French translation completed: about 316 strings that fell back to English are translated now, thanks @iblur01 (#504)
• ☁️ VeSync plugin: Levoit, Cosori and Etekcity devices from your VeSync account mount when you switch them on, with no bridge restart. Cloud only, these devices have no local control. An air fryer cannot be started from a controller.
• ⚙️ Saving a disabled built-in no longer wipes its settings: a built-in plugin that has been disabled since the last restart keeps its stored settings when you save.

Previously in v2.0.57:

• 🧹 Air purifiers stop rebuilding themselves: a composed device never listed its battery entity, so the battery auto-map retry rebuilt the endpoint on every sensor update, burning CPU and raising unhandled rejections. A sensor without a device class now needs "batt" in its id to count as the battery, so a filter life or tank level percentage is no longer taken for one (#461)
• 🪟 Covers keep their position while a controller is talking to them: endpoint state writes are serialized per device, and an update that arrives while the endpoint is busy waits for it instead of being dropped with a warning (#464)
• 🔒 Lock PIN handling reworked: a PIN added or cleared through a controller takes effect immediately instead of on the next state change, empty and overlong PINs are rejected, Add, Modify and the creating fabric are enforced as the Matter rules require, a code the physical lock rejected is no longer reported as programmed, and hashing moved off the event loop so a PIN protected unlock stops freezing every bridge
• 🧠 Heap limit is configurable: the add-on takes a heap_size_mb option, the automatic sizing moved from a quarter to half of the available memory, and a NODE_OPTIONS you set yourself is honored instead of being silently overridden (#459)
• 🧩 Third-party plugins load again: an installed plugin package is imported through its manifest entry point instead of its directory, plugin devices report their own name to controllers, and adding or removing one tells commissioned controllers that the bridge composition changed; contributed by Patrick Gu (#458)
• 🚨 Security plugin can mirror an existing alarm panel: the new sourceAlarmPanel setting turns the four mode switches and the Alarm contact into a Matter view of an alarm_control_panel.* entity (Alarmo etc.), with arm and disarm flowing back to Home Assistant; contributed by Patrick Gu (#457). Panels that require an alarm code reject the bridge's arm/disarm calls, the switches then fall back to the panel's real state
• 🏷️ A device renamed in Home Assistant reaches the controller: the registry snapshot is pushed to the endpoints on every registry refresh, a rename counts as a registry change now so that refresh runs at all, and server mode pushes the renamed identity to its root node. Apple Home takes the accessory name when the device is added and keeps its own copy, so a rename shows up there only for accessories you add after it (#467)
• 🔍 Editing the entity filter takes effect right away: a removed entity rode the five minute outage protection meant for Home Assistant restarts. It is removed on the spot now, its endpoint number stays reserved so re-adding restores the device with its groups, and a filtered-out vacuum takes its room switches along and brings them back on their old numbers (#468)
• 🍳 An oven exposed as a climate entity mounts in a Fahrenheit install: registration multiplied the raw Fahrenheit number by 100 before the unit conversion had a chance to run, so a template climate with max_temp: 500 failed with "Value 50000 is above the int16 maximum". Registration values are clamped into the Matter range now and the thermostat converts them on its first update (#470)
• 💡 Siri "set to 100%" works next to Alexa: alexaPreserveBrightnessOnTurnOn now only suppresses the brightness reset for commands arriving over the Alexa fabric, before it swallowed the same command from Apple Home (#460)
• 🪟 Covers keep the same Matter fingerprint for life: a cover that had been moved used to come back from a restart advertising an extra attribute it never had when the controller paired it (#456)
• 🧩 New composedPrimaryOnParent bridge option, off by default: puts the primary entity of a self-grouped composed device on the parent endpoint, so Apple Home reads the accessory as a light instead of taking an icon from one of the grouped entities. Needs autoComposedDevices on as well. It changes the endpoint layout, so the device has to be removed and added again in the controller, and Apple Home has been seen to stop listing the grouped entities afterwards, so try it on one bridge first (#469)
• 📡 New omitEventsInPriming bridge option, off by default: for Google fabrics that acknowledge every chunk of the initial subscription report but never answer the final one, leaving the device permanently offline. With it on, the initial report carries attributes only, live events afterwards are unaffected (#424)
• ❄️ Per-entity climateForceTurnOn: sends climate.turn_on on every Matter On command, for IR controlled ACs where Home Assistant can report on while the device is off (#462)
• 🔐 A controller that refuses the bridge certificates says so in the log: pairing that stops right after the attestation step left only a bare "Failed" on the controller and nothing in the HAMH log. Controllers that only pair with CSA certified products, like the Ambiscape feature on Philips Ambilight TVs, cannot be used at all (#465)
• 🌡️ The HAMH device cards follow Home Assistant's temperature unit: a Fahrenheit install saw Celsius chips on every thermostat and temperature sensor, because the card printed the raw Matter value (Matter always carries 0.01 °C) with a hardcoded unit. The chips now read the unit out of the endpoint itself: thermostats and water heaters from their UI configuration cluster, sensors and weather from the entity's own unit_of_measurement. What the controllers show never changed, Apple Home and Alexa convert on their side (#472)
• 🔔 A controller that stops answering is logged as a warning: the three "Error sending subscription update message" lines that precede a dropped subscription were logged at INFO, so a dying controller link was invisible to anyone filtering for warnings. The first two retries stay at INFO, the third one and the "Giving up on subscription" line are warnings now (#471)
• 🌡️ A temperature sensor outside the usual range keeps updating: the sensor endpoint declared a -40 to 125 °C measurement window while writing anything int16 could hold, so an oven probe, a grill thermometer or a deep freezer was rejected by matter.js and the endpoint kept its last in-range reading forever. The declared window now covers everything the bridge can send
• 🔌 A docked vacuum stops claiming it is charging: with no charging signal of its own the bridge assumed a docked robot below 100% was charging, so Apple Home showed "Charging" for a robot that had long finished. If the vacuum's device has a charging sensor in Home Assistant (a battery_charging binary sensor, or a ..._charging_state sensor as Xiaomi exposes), it is mapped automatically now and drives both the battery charge state and the status line. Devices without one keep the old assumption, and a charging sensor picked up this way still stays available as its own device (#450)
• 🔌 EV charger mode works from SmartThings: SmartThings addresses EnergyEvseMode modes by list position, so the single Manual mode numbered 1 never showed and every mode change was refused. It is mode 0 now; a node that stored the old number still mounts. UserMaximumChargeCurrent is optional and read by no known controller, ModeSelect is not part of the EVSE device type, neither was added (#475)
• 🧩 Auto Composed Devices says what it does: the description claimed a master toggle merging power and energy; those never depended on it. It changes the shape of a temperature sensor with humidity/pressure sensors (one device with a sub-device per reading), forces battery, humidity and pressure auto-mapping on and unlocks Composed Sub-Entities. Stored key unchanged (#474)
• 🔋 Battery percentage goes out with the write: the percentage is a quieter Matter attribute, and matter.js reported its change ten seconds after the write, on its own. The charge state went with the write, the percentage late or, on Apple Home, never. Both go together now (#450)
• 🔋 A short outage no longer blanks the battery: a device marked unavailable for a moment (a missed Roborock poll, an HA restart) got a null percentage and a flipped charge state, then the old values back 15 s later. The bridge keeps what the controller has; only a battery never seen stays null (#450)
• 🧪 Loopback subscription test: a matter.js commissioner pairs with the vacuum node over loopback, subscribes, and checks that battery percentage and charge state arrive with the write. Off by default, HAMH_LOOPBACK=1 runs it. This settled the Apple Home battery question: the bridge sends the value, Apple's framework treats BatPercentRemaining as changes-omitted and keeps only the value from pairing or from a read (#450)
• 🔎 Diagnostic export shows the connection attempts: the export now keeps the PASE and CASE session setup lines and the failsafe expiry, lists every open session with its subscriptions, the host's network interfaces and mDNS settings (addresses replaced by their kind when anonymized), and the log levels it was taken at. A controller that never connects, or connects and never subscribes, is readable from the file instead of a debug log (#477, #478)
• 🧹 Factory reset goes through the stop path: the reset restarted the bridge without stopping it first, so the built-in plugins stayed registered and every reset logged "Plugin camera is already registered" (#477, #478)
• 💡 Cool white lights load again after a restart: a light that ran above 6800 K kept its color temperature in storage, and on the next start the bridge's default range no longer covered it, so matter.js refused the endpoint and the light was missing until the value changed. The range now widens around the stored value first (#477).
• 🔐 The devices API keeps the camera's Home Assistant token to itself: the WebRTC bridge lives in the camera endpoint's state, and the devices JSON behind the endpoint inspector printed its haUrl and haToken. The credentials are a private field now, and any key named token, secret or password is redacted in that output (#155, #373)
• 🏷️ Prefer Entity Registry Name applies in server mode: only bridged devices read the flag, a standalone device kept the friendly name (#276)
• 🚫 Water Leak Detector is marked unsupported on Alexa: the mapping dialog warns before you pick the type that took a whole Alexa bridge offline (#365)
• 🧹 A rebuilt composed device drops its pending update: after a mapping change the old endpoint was closed with a 50 ms update still queued, which then failed on the closed endpoint (#461)
• 🔇 Deleting a bridge no longer logs a mutex warning: the shutdown guard looked for a message matter.js never sends
• 📖 Docs: the vacuum "Updating" section describes the Wedge Watchdog and the 60 s report interval (#287), the Alexa section covers the 11-digit manual code, the Echo models that stop after the certification prompt and the Unique ID Suffix (#478, #449, #385), heap warnings name the add-on's heap_size_mb option (#459)
• 🧭 The interface warning names your LAN interface: on a Docker host the Network Diagnostics card and the startup log listed every interface, Docker bridges included, and left the choice to you. A compose bridge on a 172.x address no longer counts as a candidate, the suggestion reads "eth0 (192.168.5.161)", and the text says the warning only matters when a controller shows devices offline (#482)
• 📖 Docs: the Alexa "never connects" entry lists the checks that helped in #478 (firewall on UDP 5540, manual code, fresh bridge) instead of a theory

Previously in v2.0.56:

• 🔋 Vacuum battery after HA 2026.8: integrations that moved the battery to a separate sensor are picked up as the sensor appears, a missing percentage reports an unknown charge state instead of "charging forever", and terminal states like "not charging" stop counting as charging (#450)
• 💡 RGB-only lights pass controller conformance again: the Extended Color Light always advertises the full mandatory feature set, which brings WLED and similar lights back to Alexa (#452)
• 🌫️ PM2.5, PM10 and CO₂ sensor overrides: map a single-pollutant sensor to an Air Quality Sensor endpoint carrying just that concentration cluster via the Entity Mapping UI (Aqara renders them, Alexa partially)
• 🇰🇷 Korean translation by @hyeok-yoo (#455)
• 🔀 Debounced commands no longer swallow an explicit on/off that arrives next to a level or color change (#453)
• 🌡️ Thermostats write their absolute limits before the user limits, so a flat heat range can no longer trip the range check on bring-up (#454)
• 🪟 Cover end product type follows the feature map: a tilting curtain or shade reports the matching tilting product, a lift-only blind stops claiming InteriorBlind (follow-up to #304)
• 🔍 Three Alexa pairing diagnostics, off by default: advertiseSpecVersion151, supportTermsAndConditions and enableMatterTcp, for Echos that stop right after the attestation step (#449)
• 🧹 Session supervision and entity mapping sync now live in shared code instead of two near-identical copies per bridge flavour; no behavior change

Previously in v2.0.55:

• 🔗 Devices keep their Matter numbers when Home Assistant restarts, so controllers stop re-adding everything and losing groups and routines (#438)
• 🔌 One plugin device no longer stalls every state update on its bridge, and plugin devices stop vanishing a minute after a refresh (#445)
• 🚫 A command that cannot reach Home Assistant now fails instead of reporting success, so a cover no longer shows a position it never reached (#446)
• 💡 Identify presses the identify button of the device, on everything rather than vacuums alone (#447)
• 🌡️ Climate power-on reaches the device even when the cached state lags (#441)
• 🌀 Fan speed zero picks the slowest mode the entity really has, and fan sliders can be debounced so bridged air conditioners stop beeping (#442, #443)
• 🎚️ Number feature flags render as number inputs, so the cover and fan debounce settings are reachable in the UI at last
• 🤝 A controller that is still being interviewed is no longer disconnected halfway, which could abort commissioning
• 📷 Camera devices carry the bridged information every device under a bridge needs (#155)

Previously in v2.0.54 (hotfix release):

• 🔌 Plugin disable now sticks across restarts, for the security and camera plugins alike
• 👻 An unconfigured security plugin exposes no devices anymore; updating removes the ghost plugs
• 🔁 Disabling a plugin removes its devices immediately, re-enabling keeps their identity

Previously in v2.0.53:

• 🛡️ Security plugin (experimental): the bridge becomes a small alarm system with Home/Away/Night/Vacation switches you arm from any controller or by voice, entry/exit delays, trigger and alert lists; for setups without an alarm integration
• 🤖 Vacuum room switches: opt-in per-room switches that controller routines can flip, an opt-in ascending room order for batch cleaning, and auto-resolved rooms survive state updates (#355, #368)
• 🔌 Plugin settings dialog: configure plugins right on the Plugins page; config survives restarts, stored secret fields are redacted from the plugin listing, and the page explains server mode instead of failing (#432)
• 🔔 Doorbell and electrical utility meter overrides: opt-in Matter 1.4 device types for event entities and consumption sensors; SmartThings renders them, defaults stay unchanged
• 🚿 Water heater management: opt-in Matter 1.4 Water Heater with Boost/CancelBoost on top of the heating thermostat, for energy-management controllers (#437)
• 🌀 Fan modes follow the entity: controllers are only offered the speeds and modes the HA fan actually accepts, no more phantom Medium or Auto (#436)
• 🌡️ heat_cool thermostats no longer crash-loop the add-on: the auto deadband is zeroed, single-mode setpoints ignore the parked range, and an endpoint that still fails is contained instead of exiting (#435)
• 🔒 Lock stops re-adding itself: a stale flag written by v2.0.7-v2.0.16 failed lock init on every start, so the lock re-paired as a new device each boot; it is cleared on load (#433)
• 💡 Google room-off no longer relights dimmable lights: the level Google sends after "turn off" is stored for the next turn-on instead of being applied (#434)
• 🪟 Cover stuck-moving paths closed: the remaining cases that kept a cover reported as moving are fixed, and resolved cover flags are logged (#429)
• 🔌 Plugin devices receive controller writes again: a wiring gap dropped attribute writes on the way to plugin devices
• 🧵 matter.js 0.17.9
• 📊 Fork comparison page: the docs compare this fork with the archived t0bst4r upstream, feature by feature

Previously in v2.0.52 (hotfix release):

• 🔌 The plugins page no longer fails with a 500 when a server mode bridge exists (#430)

Previously in v2.0.51:

• 🐕 Opt-in wedge watchdog: rotates a controller session that keeps acking but stops talking at the interaction layer, the automated "Play Sound" fix for stuck Apple devices (#287, #428)
• 🧹 Clean up orphaned records: bridge menu action with a dry-run preview that removes identity and mapping leftovers of entities deleted from HA (7 day tombstone guards against false positives)
• 🚗 EV charger support: new EVSE device-type override with charging switch and current limit mapping, EnableCharging/Disable from the controller; Aqara and Home Assistant render it, keep it off Alexa bridges
• 🩺 Subscription scope on the health card: see whether each controller holds a whole-node wildcard or watches specific endpoints
• 📷 Camera live view signaling completed: the WebRTC answer now reaches the controller over the requestor cluster, plus full media path logging, HA signaling timeouts, trickle ICE and ICE server support (still experimental until verified on real hardware)
• 🪟 Cover stop detection in every position space: the v2.0.50 cover fix now also works with the Alexa percentage flag and the per-cover swap toggle, and swapped covers report the right direction (#429)
• 🤖 Vacuum on/off crash fixed: state updates no longer throw on vacuums with the on/off toggle (#428)
• 🌍 Brazilian Portuguese completed: 602 of 615 strings (#420)

Previously in v2.0.50:

• 🆔 Stable device identity (opt-in): endpoints keep their identity when an entity is renamed or re-registered, keyed on the HA registry unique id; enable the stableIdentity feature flag per bridge (#404, #407)
• ⚡ Energy suite stage 1: consumption sensors expose an Electrical Meter that Google Home and SmartThings render, home batteries become a Battery Storage device with signed charge/discharge power and lifetime energy, and voltage/current/energy sensors group onto one endpoint via new mapping fields
• 🪟 Covers report their own movement: controllers get the moving-to-stopped edge even when the integration never reports opening/closing, clears the stuck "Opening" on Echo Show (#429), and discrete commands cancel a pending slider action (#411)
• 🧙 Commissioning preflight in the wizard: port, mDNS and controller checks with fix-it buttons before the QR code, plus a label guard and an empty-filter block
• 🔋 Per-entity "Disable battery mapping" switch (#427)
• 🧩 Auto-grouped sensors read sub-entities past the bridge filter (#426)
• 📡 mDNS records refresh when interface addresses change, recovers Google Home after an IPv6 prefix change (#415), and mDNS IPv4 can be disabled (#417)
• 🖥 Server mode shares the dead-session timeout and session diagnostics (#428)
• 🔒 Per-lock PIN length overrides and an opt-in passthrough that programs the physical lock usercode (#418)
• 🔘 Opt-in to suppress the momentary on/off flip for scripts (#423)
• 🚨 Smoke alarms report battery, fault and expressed state (#408)
• 💡 Light level and color-temperature step control (#412)
• 📷 Camera bridges enable Matter-over-TCP for SmartThings live view, and camera endpoints set the mandatory AV stream attributes (#419)
• 🔧 Valve and cover overrides route On/Off to their services (#65)
• 🌍 Brazilian Portuguese added (#420)
• 🧵 matter.js 0.17.9
• ⬆️ Dependency vulnerabilities resolved (websocket-driver, react-router 8, fast-uri, js-yaml and friends)

Previously in v2.0.49:

• 🌀 Fan speed restore: speed is remembered across transactions and restarts, localized wind presets map through, Auto is gated on a real auto preset, and an opt-in restores speed on power-on (#387)
• 📡 Session recovery hardening: subscription jitter dropped, superseded sessions of a reconnecting peer swept, stale sessions closed only after a real quiet period, plus opt-in fast recovery (#386, #400, #398, #287)
• 🩺 Per-fabric controller health card on the bridge page
• 🔢 Endpoint number kept on mapping change so Alexa no longer re-adds the device (#404), plus a unique-id suffix to shed stale controller records (#385)
• 🔘 select as an On/Off Switch (#356), plus an experimental mounted On/Off control type (#380)
• 🪟 Tilt for set_tilt_position-only covers (#405), and tilt-only cover-as-light uses the tilt channel (#350)
• 🚨 Warns on a non-5540 Alexa bridge (#401) and on an OTBR Thread mDNS interface (#388)
• 📷 Camera plugin config scoped per bridge (#373)
• 🔌 Clashing bridge port reassigned on load (#378)
• 🧩 Composed sub-entities compose even outside the bridge filter (#408), and composed sensors list all device types (#214)
• 🔒 Unbolt maps to lock.unlock not open (#397), level-to-brightness uses one scale (#402), button drops the Lighting feature (#182), and stale cooling/auto state is cleared (#384)
• 🌍 Russian translations added (#409) and zh-TW completed

Previously in v2.0.48:

• 🌡️ Cooling-only thermostats no longer drop and re-pair after a switch to cool; a leftover Heat setpoint limit was crashing init (#381)
• 📝 The Settings update box now shows the full release notes instead of cutting them off

Previously in v2.0.47:

• 💧 Leak and freeze binary_sensors now default to a Matter 1.3 Contact Sensor so Alexa stays stable; the Matter 1.4 Water Leak, Water Freeze, and Rain detector types are selectable per entity through the device-type override (#365)
• 💡 Lights no longer auto-attach power/energy clusters; map a light's power or energy sensor explicitly with powerEntity/energyEntity if you want the readout (#374)
• 🔘 The On/Off Switch device-type override now exposes a real On/Off Light instead of a no-op plug (#380)
• 🔍 New manufacturer entity-filter matcher (#382)
• 🌀 Opt-in: turning the companion fan off now turns the AC off too (#309)
• 🩺 Reliability & health: configurable auto-recovery with failure timestamps, controller-compatibility warnings on each bridge page, and per-entity device-health on the dashboard
• 🖥️ Standalone (non-vacuum) devices in server mode, plus lawn_mower entities exposed as a robotic mower
• 🪟 Cover exposed as a dimmable light for Alexa routines (#372), per-entity update throttle (#351), charging-state sensor mapping (#377)
• 📷 Experimental built-in WebRTC camera plugin (SmartThings-only, media path not verified yet)
• 🧵 matter.js 0.17.9

Previously in v2.0.46:

• ❄️ Opt-in companion fan for climate ACs: a per-entity toggle exposes the AC's fan as its own Matter fan endpoint, the setting is persisted, and fan-speed presets are now ordered low→high (#309)
• 🌦️ Weather domain support: weather.* entities are exposed as a composed Temperature + Humidity + Pressure sensor read from the entity's attributes (pressure converted to hPa, shown on Google Home)
• 🤖 Vacuum service-area editing: edit area data inline in Entity Mapping and dispatch room cleaning in batches, plus a batch-room-data fix (#291)
• 🔒 Door Lock credential hardening: safer access-code handling and fabric-index casting on the lock cluster (#313)
• ⚡ Skip unchanged endpoints on HA updates: only endpoints whose entity or a mapped sub-entity actually changed are refreshed, so CPU no longer scales with entity count × event rate (#351)
• 🔌 Registry stays resilient when HA drops: an initial reload failure no longer puts the add-on in a restart loop on a flaky HA boot, and a mid-flight "Connection lost" retries once (#352)
• 🔁 RVC sessions refreshed safely so vacuum reactors don't go stale (#287)
• 🪟 Tilt-only covers use the tilt channel for lift commands (#350)
• 🔋 Battery auto-mapping narrowed to avoid false matches, plus support for enum battery states (#359)
• 🔘 automation entities are momentary: turning one on triggers it and snaps back to off (#364)
• 🌀 Climate swing-mode handling fix
• 🚨 Non-5540 Alexa bridge warning: a bridge on any other port now warns, since Alexa only pairs on port 5540
• 🧵 matter.js 0.17.0: upgraded from 0.16.11; the local LG-TV NOC-serial patch is dropped because upstream now tolerates 21-octet operational cert serials (#305)
• 🧰 Build/runtime fixes: bun:sqlite constants export stubbed so the esbuild bundle builds against matter.js 0.17.0, add-on heap flag preserved (#358)
• ⬆️ Dependency vulnerabilities resolved
• 📝 Docs: hvac_action requirement for the Auto running-state display (#309), Google Home ModeSelect label gap (#356), Alexa cover-routine limitation (#312), and the new weather domain

Previously in v2.0.45 (hotfix release):

• ⌨️ Typed text now binds in the entity-id autocomplete, so a partial entity id isn't dropped when you pick a suggestion (#348)

Previously in v2.0.44:

• 🪟 Cover reliability overhaul: Matter state/target/current reports split and correctly ordered, deferred target writes de-duplicated, legacy position attributes dropped from updates, cluster profile aligned with the certified Eve blind, current position held during external motion (#328)
• 🎚️ Per-bridge and per-entity cover slider debounce, window widened to 300 ms for smoother slider control (#331)
• 🤖 Vacuum service-area handling: customServiceAreas preserved in dynamic RvcRunMode supported modes, custom areas dispatched sequentially, currentArea cleared on dock return and no longer inherited stale across restarts, observedCleaning set on every cleaning event (#335)
• 🔋 Docked vacuum stops reporting charging once the battery is full (#334)
• ❄️ Per-entity climateKeepModeOnIdle for off+idle ACs; mode kept through a cool→off transition, freeze applied immediately on off and cleared on action=off (#340)
• 🔁 Matter session rotation: opt-in per-bridge setting, aged sessions rotated, RVC clean-mode reactor goes offline correctly, pushKeepalive guarded on construction (#287)
• 🧠 Heap-headroom and force-sync pressure guard to reduce memory pressure (#347)
• 🏷️ Per-entity customVendorId with Home Assistant device-registry serial fallback (#290)
• 🔢 serialNumberSuffix now loads when editing a bridge and is preserved when the serial is trimmed to 32 characters (#330)
• 🔍 Regex filters for entity and device labels, plus an any_field_regex matcher for grouped AND/OR filter rules (#337)
• ⌨️ Entity-id autocomplete in the filter-rule editor (#338)
• ⚡ Energy sensor endpoints default activePower to 0 and gain PowerTopology + cumulativeEnergyImported defaults (#343)
• ⏱️ Home Assistant WebSocket message timeout is now configurable, default raised to 60 s (#341)
• 🪟 device_class=window covers no longer emit EndProductType.Unknown (#312)
• 🖼️ Bridge-icon existence check now uses the /exists endpoint instead of a HEAD probe (#336)
• 🌍 Polish translation update, credited to @MStankiewiczOfficial (#329)

Previously in v2.0.43:

• 🤖 Vacuum currentArea updates when cleaning is started outside HAMH (#281)
• 📡 Sensor reactors mark themselves offline when HA disconnects, so updates reach controllers on reconnect (#327)
• 🪟 Lift+tilt window coverings pick a valid Matter Type (#323)
• 🪟 Cover device_class=window maps to Rollershade (#312)
• 🧹 UWANT and Xiaomi sweep/mop labels recognised, mop usage routed via mode.vacuum_mop (#322)
• 🤖 Vacuum identify falls back to a sibling identify button when vacuum.locate is unsupported (#320)
• ❄️ HA-auto AC systemMode stays put when hvac_action is idle, ha-auto-only ACs no longer expose Matter Auto (#309)
• 🌡️ Climate setpoints snap to the entity target_temp_step (#321)
• 🛰️ matter.js controller traffic captured in /api/logs
• 🇯🇵 Japanese translation by @kimera257 (#325)
• 📝 Docs note for the iPhone-only stuck-on-updating vacuum workaround (#287)

Previously in v2.0.42 (hotfix release):

• 🇯🇵 Aqara bridge registration no longer stalls, root softwareVersionString now matches the numeric softwareVersion (#316)
• ❄️ Climate auto mode is clamped to heat/cool on devices without an AutoMode base (#319)
• 🌀 Per-entity disableClimateFanControl mapping flag, falls back to ThermostatDevice when controllers like Aqara don't recognise RoomAirConditioner (0x0072) (#318)
• 🗺️ Vacuum service area selectedAreas is kept after dispatch instead of being cleared

Previously in v2.0.41:

Feature	Description
🌡️ Google Home AC offline fix	DeadFrontBehavior on climate OnOff cluster so RoomAirConditioner stops showing offline on Google Home (#302)
🪟 Cover device_class mapping	Map HA garage/gate/window/awning/etc. to the matching Matter WindowCovering type so voice commands hit the right device type (#304)
📺 LG TV commissioning patch	Local patch on matter.js 0.16.11 to accept long NOC operational cert serials (#305)
💡 Alexa brightness-reset behind flag	Old Alexa brightness-reset heuristic moved behind alexaPreserveBrightnessOnTurnOn, default off, Apple Home "set room to 100%" works again (#306)
🌀 Google Home fan speed	Uses fan.set_percentage so already-on fans pick up speed changes from Google Home (#308)
❄️ Climate auto mode	Expose Matter Auto mode when HA reports auto in hvac_modes (#309)
🆔 Server-mode root identity	Root identity now applies as a single transaction, so controllers don't drop devices mid-swap (#311)
🪟 Lift-only blinds	No more TiltBlindTiltOnly on covers without tilt, fixes Alexa routines for roller blinds (#312)
🏷️ Per-entity disableClimateOnOff	Turn off the OnOff cluster on climate endpoints per entity for controllers that prefer mode-only control
🔢 serialNumberSuffix per bridge	Append a suffix to every entity serial, useful if controllers like Aqara cache stale device data
📝 protocolLogLevel option	Quiet matter.js logs independently from the app log level
🖥️ Bridge HW/SW version strings	HA device-registry hw_version/sw_version now show up in Matter BasicInformation on server-mode endpoints
🎨 Extended color light: XY + enhancedColorMode	XY feature added as mandatory, enhancedColorMode mirrors colorMode
🎭 Groups + Scenes	Scenes and Groups clusters added on light, plug, and fan endpoints
💧 Boolean state configuration	Cluster added on leak, freeze, rain, and contact sensors
🌍 Spanish translation	New es locale (#314, thanks @Yllelder)
🧵 Matter.js 0.16.11 (pinned)	Kept pinned, local NOC serial patch applied
⬆️ Dep bumps	Vite 8, jsdom 29, MUI x-tree-view 9, i18next 26, react-i18next 17, TypeScript 6.0.3, biome pinned 2.4.3, pnpm overrides for transitive CVEs

Reliability & resilience: parallel bridge stop in stopAll/restartAll, parallel HA registry fetches, serialized bridge start/stop lifecycle, serialized updateStates with plugin listener detach, HA reconnect retry on transient network errors, 30s timeout on sendMessagePromise, port-conflict reject on web-api start, graceful shutdown on /api/backup/restart, AppEnvironment disposal on SIGINT, stale optimistic state sweep, pending debouncer clear, healthcheck 401 fix under basic auth, deep-equal entity attribute comparison, overlap guard for auto-refresh, safer mireds conversion, aligned colorMode publishing, surfaced bridge import errors, corrected thermostat running state for unknown modes + drying, unified Node version across Dockerfiles, sourcemaps excluded from npm tarball, unused deps dropped (rxjs, strip-color, lodash), unused config-validator utility removed.

Previously in v2.0.39 & v2.0.40 (hotfix releases):

• Fixed crash loop on startup caused by Node 22 native WebSocket dropping connections (#297, #299), affects both aarch64 (RPi) and amd64
• Fixed service initialization errors being silently swallowed, causing the process to hang instead of exiting
• Registry fetch now waits for WebSocket reconnect between retries and has increased retry tolerance
• Fixed select, input_select, siren domains showing as unsupported in filter preview (#298)

Previously in v2.0.38:

Feature	Description
🏷️ Per-Entity Identity Overrides	customProductName, customVendorName, customSerialNumber per entity mapping (#277, #290)
🪟 Garage & Gate Open/Close	Discrete Open/Close mode for garage and gate covers (#55)
🚿 Dishwasher Device Type	Dishwasher override for switch entities
🚨 Siren Support	Siren domain as OnOff Plug-in Unit
🏷️ productNameFromNodeLabel Flag	Report node label as Matter productName for Aqara controllers
🤖 Vacuum Room Progress	Dynamic room progress tracking via currentRoomEntity sensor
⚡ Startup Force Sync	Immediate force sync on startup to beat stale Alexa queues (#282)
🌐 Network Diagnostic API	mDNS/network diagnostic endpoint with dashboard card
🔌 Energy on Composed Devices	Energy/power measurement clusters on composed endpoints
🩺 Multi-Admin Fabric Diagnostics	Per-fabric session info in health API
🩺 Docker HEALTHCHECK	Native healthcheck in standalone and addon images
🔒 Admin Password Hashing	Admin password stored hashed, timingSafeEqual for lock PIN verification
🧵 Matter.js 0.16.11	Updated Matter stack
🌍 Polish + Traditional Chinese	New pl and zh-tw locales

Fix highlights: vacuum keepalive for Apple Home "Updating…" (#287), multi-phase clean progress (#281), GenericSwitch single/multi split for Apple Home buttons (#289), HA restart attribute guards (#286), fan speed restore on turn-on (#275), moisture sensor auto-map to HumiditySensor (#273), TV speaker override (#293), rain + radon sensor auto-mapping, composed sub-endpoint cleanup.

Previously in v2.0.36:

Feature	Description
🏗️ User-Defined Composed Devices	Create custom composed devices via composedEntities mapping (#220)
🔌 Plugin Domain Mappings	Domain mapping support in plugin API with cloud-mock example
🔋 Valve & Pump Battery	Battery support for valve and pump endpoints
🌐 German + Russian Translations	Complete German translation and new Russian language
📡 Session Recovery	Graceful session close, dead session cleanup, mDNS re-announcement (#266)
🔗 Quick Link to Failed Devices	Dashboard quick link to failed devices (#270)
🌡️ Thermostat Fix	Skip climate.turn_on when already on (#269)
🪟 Cover Fix	Correct stale targetPosition during external movement (#268)
🌬️ Air Purifier Fix	Sub-endpoints for composed air purifier, manual temp/humidity mapping (#265)
🔥 Cooling-Only Thermostat Fix	Prevent HeatingOnly on cooling-only thermostat (#264)
↔️ Per-Entity Cover Swap	Individual coverSwapOpenClose per cover (#263)

🧪 Alpha (v2.1.0-alpha.933)

v2.1.0-alpha.933:

• 🪟 Option to send cover open/close as a position: some cover integrations, like Cover Time Based, stop when they get open or close while the cover is moving, and only reverse on a position. Turn on Send open/close as position in the entity mapping and open and close go out as set_cover_position 100 and 0. Off by default, covers without a position keep open/close (#512)

v2.1.0-alpha.932:

• 🧹 Removed option cleaned from saved bridges: a bridge saved with the old "Omit events in priming" option still listed it on the Diagnostics page and in the export. It is now dropped from storage on start

v2.1.0-alpha.931:

• 🧵 No local matter.js patch any more: HAMH now runs matter.js 0.18 unchanged. The "Omit events in priming" bridge option is gone, it was never confirmed to help Google. The last failed subscription update and "Giving up on subscription" are logged at INFO again
• 🔁 Session rotation is opt-in in server mode too: server mode bridges no longer close controller sessions every 4 h. Set Session Rotation Max Age if you want it back. When HAMH closes a session itself, it closes its subscriptions first
• 🔌 EV chargers answer charging target commands: SetTargets, GetTargets and ClearTargets are accepted and stored, nothing is sent to Home Assistant

v2.1.0-alpha.930:

• 🧵 matter.js 0.18 RC (nightly 0.18.0-alpha.0-20261008): brings Matter 1.6.1. Controllers now see spec version 1.6.1, a Groupcast cluster on the bridge root and newer device type revisions. If something pairs or behaves differently than on alpha.929, please open an issue with the diagnostic export
• 🔇 matter.js device type checks stay off at runtime: 0.18 can check every endpoint against its device type and log a warning for each deviation at every start. HAMH turns that off, the endpoint shapes are covered by its tests

v2.1.0-alpha.929:

• 🧹 Vacuums with one cleaning mode get a second "Auto" mode: Matter needs at least two cleaning modes, and the coming matter.js 0.18 refuses a vacuum with only one. Picking "Auto" is refused and nothing is sent to Home Assistant. Apple Home shows it as "Automatic"
• 🔌 EV chargers list "Time of Use" next to Manual: same rule for the EVSE mode list. Picking it is refused, Manual stays selected
• 🪟 Shutters with tilt become exterior venetian blinds: Matter 1.6.1 allows the Shutter type only with lift or tilt, not both. A tilting shutter cover now reports TiltBlindLift with ExteriorVenetianBlind, so already paired ones may show a different blind type. Covers also set a valid product type before their first state arrives
• 🔒 Unlock with timeout reaches Home Assistant: the command used to flip the lock state in the controller without calling Home Assistant. It now unlocks through Home Assistant like a normal unlock and locks again when the timeout runs out
• 🔘 Long press events end released: a long_press without a following release sent the press twice and left the button held. It now sends press, long press and release once
• 📺 TVs without play or pause mount: they failed to start because the playback cluster was left out
• 💡 Color lights list RemainingTime and the pump mapping mounts, it never did before

v2.1.0-alpha.928:

• 🧹 Apple Home can clean all rooms of a CLEAN_AREA vacuum: Apple sends "all rooms" as an empty selection and then starts with one room's run mode, so only that room got cleaned. The "Don't expose rooms as per-room cleaning modes" option in the entity mapping now also covers CLEAN_AREA rooms and rooms from the vacuum attributes, not only custom areas. Turn it on when only Apple Home starts the vacuum; Alexa and Google Home still need the room modes (#511)

v2.1.0-alpha.927:

• 🌀 Fans and air purifiers keep their speed range while unavailable: Home Assistant drops the speed step while a fan is unavailable, so the bridge changed the fixed SpeedMax from 100 to 3 and back on every outage. It now keeps the last value (#505)

v2.1.0-alpha.926:

• 🎨 A color sent right after On is applied: Alexa sends the color a moment after On, while Home Assistant still reports the light off. The color was held back and applied on the next turn-on instead. It now goes out with this one, and a color right after Off no longer switches the light back on (#510)

v2.1.0-alpha.925:

• 🔒 Locks without a keypad can skip PIN codes: the new Lock has no keypad switch in a lock's entity mapping exposes it without PIN codes, so controllers offer no access code setup. Other locks keep their PIN support (#418)

v2.1.0-alpha.924:

• 📷 High resolution camera streams get through: a 1440p keyframe overflowed the bridge's UDP receive buffer, so the controller never got a whole picture. The bridge now asks for 4 MB, which HAOS allows (#373)

v2.1.0-alpha.923:

• 📷 Camera errors from Home Assistant are readable: when HA refuses a live view request the log shows its error instead of [object Object], and camera ids HA can't accept (like camera.rtsp-lq) are skipped at startup with a warning (#373)

v2.1.0-alpha.922:

• 📷 Camera live view can work with SmartThings: four bugs stopped it every time, SmartThings' stream setup was rejected, every offer failed, the bridge offered VP8 instead of H.264 and answered too late. Tested end to end with a simulated SmartThings controller, a test on real hardware is still missing (#373)

v2.1.0-alpha.921:

• 🗺️ Vacuum custom areas can carry a map and a floor: custom service areas of a vacuum can carry a map name and a floor number, areas sharing a map name show up as one Matter map, and the same room name can sit on two maps (#506)

v2.1.0-alpha.920:

• ⚙️ Device list changes are one log line: the log now has one line 'Device list changed: N removed, M added, K mounted' whenever a bridge changes its set of devices, with the added ones named and the bridge id in the logger name, so a log or diagnostic export shows whether the bridge itself changed what a controller sees (#505)
• ⚙️ Session cleanup no longer quotes a false 60s gap: the session cleanup lines no longer say 'no subscriptions for 60s', because that number was the check interval and not the time without subscriptions (#505)

v2.1.0-alpha.919:

• ⚙️ Failed label queries keep the last labels: a failed Home Assistant label query no longer empties the label list, and before that a bridge filtering by label name could unmount its devices until the next refresh (#500)
• 📡 False mDNS re-announcement log is gone: the log line "Triggered mDNS re-announcement after session cleanup" is gone, nothing was sent at that point (#500, #485)

v2.1.0-alpha.918:

• 📡 Clearer mDNS global IPv6 warning: the startup log now says you can ignore it when devices work, and names mdns_strip_global_ipv6 for the add-on and --mdns-strip-global-ipv6 for a container (#392)

📋 Previous Versions

v2.0.40

Filter preview domain fix, select, input_select, siren now show as supported (#298)

v2.0.39

Node 22 WebSocket crash loop fix (#297, #299), service init error surfacing, registry retry hardening, support link added

v2.0.37

Aqara productNameFromNodeLabel flag, Matter.js 0.16.11, Swedish locale update

v2.0.35

HA 2026.3 Clean Area Support, Valetudo Identifier Mapping, Plugin System Hardening, Registry Fingerprint Fix, Roomba Battery Fix, Contact Sensor Fix, Script Momentary Fix, Docusaurus Docs

v2.0.34

Automatic Backup, Vacuum Battery Auto-Map, Deprecated Feature Flags Fix

v2.0.33

Endpoint Number Preservation, Binary Sensor Battery Auto-Map

v2.0.32

Multi-Language Support, Plugin System, New Device Types (PIR, Rain, Electrical, AQ Sensors), Cluster Diagnostics, Dashboard Enhancements, Mapping Profile Export/Import, Fan & Air Purifier Fixes, Stale Session Cleanup, KNX Cover Fix

v2.0.31

Controller Profiles & Area Setup, Fan Speed/Preset Fix, Optimistic State Fix, Cover Target Fix, Humidity Auto-Mapping Default

v2.0.30

Mapped Entity Propagation Fix, API Error Surfacing

v2.0.29

Light currentLevel Fix, Bridge Config Save Fix, Fan Device Feature Fix, Humidity Auto-Mapping Fix

v2.0.28

Device Image Support, Custom Fan Speed Mapping, TV Source Selection, Reverse Proxy Base Path, On/Off-Only Fans, Light Brightness Fix, Fan Speed Fixes, Composed Air Purifier Fix, Dreame Multi-Floor Fix, Optimistic State Updates, Frontend Improvements

v2.0.27

Valetudo support, Custom Service Areas, ServiceArea Maps, Vacuum Identify/Locate/Charging, Alarm Control Panel, Composed Air Purifier, Dashboard Controls, Vendor Brand Icons, Thermostat fixes, Air Purifier oscillation/wind

v2.0.26

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

v2.0.25

Vacuum mop intensity, vacuum auto-detection, Roborock room auto-detect, live entity mapping, dynamic heap sizing, multi-fabric commissioning, fan speed label fix

v2.0.24

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

v2.0.19-v2.0.23

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)

v2.0.17 / v2.0.18

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

v2.0.16

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

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

Getting started

To get things up and running, please follow the installation guide.

Additional Resources

If you need more assistance on the topic, please have a look at the following external resources:

Videos

YouTube-Video on "HA Matter HUB/BRIDGE 😲 👉 Das ändert alles für ALEXA und GOOGLE Nutzer" (🇩🇪)

YouTube-Video on "Alexa et Google Home dans Home Assistant GRATUITEMENT grâce à Matter" (🇫🇷)

Support the Project

This is completely optional! The project will continue regardless of donations. I maintain this in my free time because I believe in open source and helping the community.

If you find this project useful and want to support its development, consider buying me a coffee! ☕

Maintaining this project takes time and effort - from fixing bugs, adding new features, to helping users in issues. Your support is appreciated but never expected. Thank you for using Home-Assistant-Matter-Hub! ❤️