@riddix/hamh 2.0.46 → 2.0.48

package/README.md

@@ -37,41 +37,63 @@ of port forwarding etc.
 
 | Channel | Branch | Current Version | Description |
 |---------|--------|-----------------|-------------|
-| **Stable** | `main` | v2.0.46 | Production-ready, recommended for most users |
-| **Alpha** | `alpha` | v2.1.0-alpha.x | Pre-release with new features, for early adopters |
+| **Stable** | `main` | v2.0.47 | Production-ready, recommended for most users |
+| **Alpha** | `alpha` | v2.1.0-alpha.x (next) | Currently level with Stable; next pre-release lands here first |
 | **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
+- **Early adopters**: Use **Alpha** (`alpha` branch) - currently level with Stable until the next pre-release lands
 - **Developers/Testers**: Use **Testing** (`testing` branch) - bleeding edge, expect breakage
 
+### Upgrading from 2.0.46
+
+A few entities re-pair once on the first start after the update and lose their room assignment in the controller:
+
+- leak and freeze `binary_sensor`s (now Contact Sensors by default) and any entity using the **On/Off Switch** override
+- a light may drop its auto power/energy readout, re-add it by mapping the sensor by hand
+
+Re-assign the affected devices to their rooms after they reconnect. See the [docs](https://riddix.github.io/home-assistant-matter-hub/supported-device-types) for detail.
+
 ---
 
 ## 🎉 What's New
 
 <details>
-<summary><strong>📦 Stable Features (v2.0.46)</strong> - Click to expand</summary>
-
-**New 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](https://github.com/RiDDiX/home-assistant-matter-hub/issues/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](https://github.com/RiDDiX/home-assistant-matter-hub/issues/291))
-- 🔒 **Door Lock credential hardening** — safer access-code handling and fabric-index casting on the lock cluster ([#313](https://github.com/RiDDiX/home-assistant-matter-hub/issues/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](https://github.com/RiDDiX/home-assistant-matter-hub/issues/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](https://github.com/RiDDiX/home-assistant-matter-hub/issues/352))
+<summary><strong>📦 Stable Features (v2.0.47)</strong> - Click to expand</summary>
+
+**New in v2.0.47:**
+
+- 💧 Leak and freeze `binary_sensor`s 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](https://github.com/RiDDiX/home-assistant-matter-hub/issues/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](https://github.com/RiDDiX/home-assistant-matter-hub/issues/374))
+- 🔘 The **On/Off Switch** device-type override now exposes a real On/Off Light instead of a no-op plug ([#380](https://github.com/RiDDiX/home-assistant-matter-hub/issues/380))
+- 🔍 New **`manufacturer` entity-filter matcher** ([#382](https://github.com/RiDDiX/home-assistant-matter-hub/issues/382))
+- 🌀 Opt-in: turning the **companion fan** off now turns the AC off too ([#309](https://github.com/RiDDiX/home-assistant-matter-hub/issues/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](https://github.com/RiDDiX/home-assistant-matter-hub/issues/372)), per-entity **update throttle** ([#351](https://github.com/RiDDiX/home-assistant-matter-hub/issues/351)), **charging-state sensor** mapping ([#377](https://github.com/RiDDiX/home-assistant-matter-hub/issues/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](https://github.com/RiDDiX/home-assistant-matter-hub/issues/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](https://github.com/RiDDiX/home-assistant-matter-hub/issues/291))
+- 🔒 **Door Lock credential hardening**: safer access-code handling and fabric-index casting on the lock cluster ([#313](https://github.com/RiDDiX/home-assistant-matter-hub/issues/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](https://github.com/RiDDiX/home-assistant-matter-hub/issues/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](https://github.com/RiDDiX/home-assistant-matter-hub/issues/352))
 - 🔁 **RVC sessions refreshed safely** so vacuum reactors don't go stale ([#287](https://github.com/RiDDiX/home-assistant-matter-hub/issues/287))
 - 🪟 **Tilt-only covers** use the tilt channel for lift commands ([#350](https://github.com/RiDDiX/home-assistant-matter-hub/issues/350))
 - 🔋 **Battery auto-mapping narrowed** to avoid false matches, plus support for enum battery states ([#359](https://github.com/RiDDiX/home-assistant-matter-hub/issues/359))
-- 🔘 **`automation` entities are momentary** — turning one on triggers it and snaps back to off ([#364](https://github.com/RiDDiX/home-assistant-matter-hub/issues/364))
+- 🔘 **`automation` entities are momentary**: turning one on triggers it and snaps back to off ([#364](https://github.com/RiDDiX/home-assistant-matter-hub/issues/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](https://github.com/RiDDiX/home-assistant-matter-hub/issues/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](https://github.com/RiDDiX/home-assistant-matter-hub/issues/358))
+- 🚨 **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](https://github.com/RiDDiX/home-assistant-matter-hub/issues/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](https://github.com/RiDDiX/home-assistant-matter-hub/issues/358))
 - ⬆️ Dependency vulnerabilities resolved
-- 📝 Docs — `hvac_action` requirement for the Auto running-state display ([#309](https://github.com/RiDDiX/home-assistant-matter-hub/issues/309)), Google Home ModeSelect label gap ([#356](https://github.com/RiDDiX/home-assistant-matter-hub/issues/356)), Alexa cover-routine limitation ([#312](https://github.com/RiDDiX/home-assistant-matter-hub/issues/312)), and the new weather domain
+- 📝 Docs: `hvac_action` requirement for the Auto running-state display ([#309](https://github.com/RiDDiX/home-assistant-matter-hub/issues/309)), Google Home ModeSelect label gap ([#356](https://github.com/RiDDiX/home-assistant-matter-hub/issues/356)), Alexa cover-routine limitation ([#312](https://github.com/RiDDiX/home-assistant-matter-hub/issues/312)), and the new weather domain
 
 **Previously in v2.0.45 (hotfix release):**
 
@@ -79,12 +101,12 @@ of port forwarding etc.
 
 **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](https://github.com/RiDDiX/home-assistant-matter-hub/issues/328))
+- 🪟 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](https://github.com/RiDDiX/home-assistant-matter-hub/issues/328))
 - 🎚️ Per-bridge and per-entity cover slider debounce, window widened to 300 ms for smoother slider control ([#331](https://github.com/RiDDiX/home-assistant-matter-hub/issues/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](https://github.com/RiDDiX/home-assistant-matter-hub/issues/335))
 - 🔋 Docked vacuum stops reporting charging once the battery is full ([#334](https://github.com/RiDDiX/home-assistant-matter-hub/issues/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](https://github.com/RiDDiX/home-assistant-matter-hub/issues/340))
-- 🔁 Matter session rotation — opt-in per-bridge setting, aged sessions rotated, RVC clean-mode reactor goes offline correctly, `pushKeepalive` guarded on construction ([#287](https://github.com/RiDDiX/home-assistant-matter-hub/issues/287))
+- 🔁 Matter session rotation: opt-in per-bridge setting, aged sessions rotated, RVC clean-mode reactor goes offline correctly, `pushKeepalive` guarded on construction ([#287](https://github.com/RiDDiX/home-assistant-matter-hub/issues/287))
 - 🧠 Heap-headroom and force-sync pressure guard to reduce memory pressure ([#347](https://github.com/RiDDiX/home-assistant-matter-hub/issues/347))
 - 🏷️ Per-entity `customVendorId` with Home Assistant device-registry serial fallback ([#290](https://github.com/RiDDiX/home-assistant-matter-hub/issues/290))
 - 🔢 `serialNumberSuffix` now loads when editing a bridge and is preserved when the serial is trimmed to 32 characters ([#330](https://github.com/RiDDiX/home-assistant-matter-hub/issues/330))
@@ -97,7 +119,7 @@ of port forwarding etc.
 - 🧩 JSON editor de-duplicates `@codemirror/state` ([#345](https://github.com/RiDDiX/home-assistant-matter-hub/issues/345))
 - 🌍 Polish translation update, credited to [@MStankiewiczOfficial](https://github.com/MStankiewiczOfficial) ([#329](https://github.com/RiDDiX/home-assistant-matter-hub/pull/329))
 - ✅ Added regression test coverage for the session-max-age parser ([#287](https://github.com/RiDDiX/home-assistant-matter-hub/issues/287))
-- ⬆️ Dependency hygiene — transitive deps flagged by Dependabot patched, `serialize-javascript` bumped to 7.0.5 in docs-site
+- ⬆️ Dependency hygiene: transitive deps flagged by Dependabot patched, `serialize-javascript` bumped to 7.0.5 in docs-site
 
 **Previously in v2.0.43:**
 
@@ -296,27 +318,42 @@ Matter Bridge, Multi-Fabric support, Health Monitoring, Bridge Wizard, AirQualit
 
 | Home Assistant Domain | Matter Device Type | Feature Flags |
 |-----------------------|-------------------|---------------|
-| `light` | On/Off, Dimmable, Color Temp, Extended Color | `powerEntity`, `energyEntity` |
+| `light` | On/Off, Dimmable, Color Temp, Extended Color | `powerEntity`, `energyEntity` (no longer auto-mapped, set explicitly if a light's energy readout disappears, [#374](https://github.com/RiDDiX/home-assistant-matter-hub/issues/374)), `coverExposeAsDimmableLight` ([#372](https://github.com/RiDDiX/home-assistant-matter-hub/issues/372)) |
 | `switch`, `input_boolean` | On/Off Plug-in Unit | `powerEntity`, `energyEntity` |
 | `lock` | Door Lock | PIN Credentials, Unlatch/Unbolt |
 | `cover` | Window Covering | `coverSwapOpenClose` |
-| `climate` | Thermostat | Battery via `batteryEntity` |
+| `climate` | Thermostat | Battery via `batteryEntity`, `climateExposeFan` ([#309](https://github.com/RiDDiX/home-assistant-matter-hub/issues/309)) |
 | `fan` | Fan, Air Purifier | Oscillation, Wind Modes, `filterLifeEntity` |
 | `alarm_control_panel` | Mode Select | Arm/Disarm modes |
-| `binary_sensor` | Contact, OnOff, Occupancy, Smoke/CO, Water Leak, Water Freeze | |
+| `binary_sensor` | Contact, OnOff, Occupancy, Smoke/CO | Leak/freeze default to Contact Sensor (Alexa-safe); the Matter 1.4 Water Leak/Freeze and Rain detector types are per-entity overrides ([#365](https://github.com/RiDDiX/home-assistant-matter-hub/issues/365)) |
 | `sensor` | Temperature, Humidity, Pressure, Flow, Light, AirQuality | `batteryEntity`, `humidityEntity`, `pressureEntity` |
 | `event` | Generic Switch (Doorbell, Button Events) | |
 | `button`, `input_button` | Generic Switch | |
 | `media_player` | Speaker, Basic Video Player (TV) | |
 | `valve` | Water Valve, Pump | |
 | `select`, `input_select` | Mode Select | |
-| `vacuum` | Robot Vacuum Cleaner | `serverMode`, `roomEntities`, `batteryEntity`, `cleaningModeEntity`, `suctionLevelEntity`, `mopIntensityEntity`, `customServiceAreas`, `vacuumMinimalClusters` |
+| `vacuum` | Robot Vacuum Cleaner | `serverMode`, `roomEntities`, `batteryEntity`, `cleaningModeEntity`, `suctionLevelEntity`, `mopIntensityEntity`, `customServiceAreas`, `vacuumMinimalClusters`, `chargingStateEntity` ([#377](https://github.com/RiDDiX/home-assistant-matter-hub/issues/377)) |
+| `lawn_mower` | Robotic Lawn Mower (RVC-based) | reuses the robot-vacuum flags ([#301](https://github.com/RiDDiX/home-assistant-matter-hub/issues/301)) |
 | `humidifier` | Humidifier/Dehumidifier | |
 | `water_heater` | Thermostat (Heating) | |
-| `automation`, `script`, `scene` | On/Off Switch | |
+| `automation`, `script`, `scene` | On/Off Switch | The per-entity "On/Off Switch" override now produces a real `0x0100` On/Off Light (controllers render a switch), needs a one-time re-pair, and no longer carries power/energy fields ([#380](https://github.com/RiDDiX/home-assistant-matter-hub/issues/380)) |
 
 > 📖 See [Supported Device Types Documentation](https://riddix.github.io/home-assistant-matter-hub/supported-device-types) for details
 
+**Common per-entity flags:** `updateThrottleMs` rate-limits how often an entity pushes updates to controllers ([#351](https://github.com/RiDDiX/home-assistant-matter-hub/issues/351)), `coverExposeAsDimmableLight` exposes a cover as a dimmable light for Alexa routines ([#372](https://github.com/RiDDiX/home-assistant-matter-hub/issues/372)), `chargingStateEntity` maps a charging-state sensor ([#377](https://github.com/RiDDiX/home-assistant-matter-hub/issues/377)), `climateExposeFan` exposes a climate AC's fan as its own endpoint ([#309](https://github.com/RiDDiX/home-assistant-matter-hub/issues/309)).
+
+### Entity Filters
+
+Filter rules match on these matcher types: `pattern`, `regex`, `domain`, `platform`, `entity_label`, `device_label`, `entity_label_regex`, `device_label_regex`, `any_field_regex`, `area`, `entity_category`, `device_name`, `product_name`, `device_class`. The new **`manufacturer`** matcher matches the device manufacturer (or `default_manufacturer`) and supports `*` wildcards ([#382](https://github.com/RiDDiX/home-assistant-matter-hub/issues/382)).
+
+### Reliability & Health
+
+Configurable auto-recovery with failure timestamps in Settings, controller-compatibility warnings on each bridge page, per-entity device-health diagnostics on the health dashboard, and a warning when a bridge exposes device types its controller does not support.
+
+### Experimental: Camera Plugin
+
+A built-in plugin exposes Home Assistant cameras as Matter Cameras (`0x0142`). Experimental, SmartThings-only as of 2026, and the WebRTC media path is not verified end to end.
+
 ---
 
 ## 🤖 Robot Vacuum Server Mode
@@ -335,7 +372,7 @@ This is because these platforms expect robot vacuums to be **standalone Matter d
 
 ### 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.
+**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
 
@@ -347,9 +384,9 @@ This is because these platforms expect robot vacuums to be **standalone Matter d
 
 ### 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
+- 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
@@ -524,6 +561,7 @@ Newest first.
 
 | Contributor | Contributions |
 |-------------|---------------|
+| [@qbattersby](https://github.com/qbattersby) | 🤖 **Code Contributor** - LevelControl transitionTime patch for matter.js 0.17, so Google Home can dim already-on lights ([#383](https://github.com/RiDDiX/home-assistant-matter-hub/pull/383)) |
 | [@Yllelder](https://github.com/Yllelder) | 🌐 **Translator** - Spanish translation ([#314](https://github.com/RiDDiX/home-assistant-matter-hub/pull/314)) |
 | [@MStankiewiczOfficial](https://github.com/MStankiewiczOfficial) | 🌐 **Translator** - Polish translation ([#288](https://github.com/RiDDiX/home-assistant-matter-hub/pull/288), [#329](https://github.com/RiDDiX/home-assistant-matter-hub/pull/329)) |
 | [@aetasoul](https://github.com/aetasoul) | 🤖 **Code Contributor** - Immediate force sync on startup to beat stale Alexa queues ([#282](https://github.com/RiDDiX/home-assistant-matter-hub/pull/282)) |