New 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.3

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)
• 🧩 JSON editor de-duplicates @codemirror/state (#345)
• 🌍 Polish translation update, credited to @MStankiewiczOfficial (#329)
• ✅ Added regression test coverage for the session-max-age parser (#287)
• ⬆️ Dependency hygiene: transitive deps flagged by Dependabot patched, serialize-javascript bumped to 7.0.5 in docs-site

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:

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:

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:

Alpha is currently level with Stable (v2.0.49). All alpha work up to the latest pre-release has been promoted into v2.0.49. New alpha work continues from the next pre-release tag onward and will appear here as development progresses.

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

🏗️ Vision 1: Callback-based Architecture

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

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

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

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 a device as a standalone (non-bridged) Matter endpoint without the bridge wrapper. It works for any device type, not just vacuums, and a bridge can host standalone devices. For a robot vacuum 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

• A Server Mode node exposes each device as a standalone endpoint, up to 10 per node; extra entities are skipped
• For best results give a robot vacuum its own dedicated Server Mode bridge
• Other device types (lights, switches, sensors) also work 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.

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)

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 requires IPv6, do not disable it. For VLAN setups, configure ULA addresses (fd00::/8), not just link-local (fe80::). See Troubleshooting and Discussion #39

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