Skip to content

fix(matter): use valid outlet and occupancy cluster shapes - #1467

Merged
donavanbecker merged 1 commit into
beta-5.4.2from
fix/matter-cluster-shapes
Nov 20, 2026
Merged

donavanbecker merged 1 commit into
beta-5.4.2from
fix/matter-cluster-shapes

Conversation

@donavanbecker

Copy link
Copy Markdown
Contributor

What changed

Two Matter cluster definitions didn't match Matter / matter.js, which Homebridge 2.5.1 (now in beta, 2.5.1-beta.6) starts warning about at registration (homebridge/homebridge commits 7872665 and c04c8ce: unknown cluster and unknown attribute warnings):

  • Plug: DEVICE_MATTER_CLUSTERS.plug declared electricalMeasurement, which is not a Matter cluster, so matter.js always dropped it. It is removed; the plug is { onOff }. electricalPowerMeasurement was deliberately not added: Homebridge would then expose power metering on every plug, and nothing in the plugin updates it yet, so every plug would show a stale empty reading.
  • Motion: occupancySensing.occupancy is a bitmap. It now starts as { occupied: false } (was 0), and the OccupancySensing read in genericDevice.ts returns { occupied } instead of 1/0.

Not changed: meter (TemperatureSensor) and humidifier (Fan) also declare relativeHumidityMeasurement, which matter.js doesn't allow on those device types, so it is dropped and 2.5.1 will warn. Fixing that needs a composed device or a different device type, which changes what users see; left for a separate decision.

No config migration needed. Not tied to a node-switchbot release.

Branch

No beta-* branch existed, so beta-5.4.2 was created from latest (patch, no issue labels) per the contributing guide.

Checks

npm run build, npm run test (244 passed, 1 skipped) and npm run lint pass. Tests and tsc --noEmit also pass with homebridge@beta installed. New tests: test/device/matter-cluster-shapes.spec.ts.

Side note: npm run lint passes src/**/*.ts unquoted, so the shell expands it one level deep and top-level files such as src/utils.ts are never linted. Not fixed here, because linting them produces large unrelated formatting changes.


Generated by Claude Code

Homebridge 2.5.1 warns at registration for clusters a device type does
not carry and for attribute names a cluster does not have.

- plug: drop the `electricalMeasurement` block. It is not a Matter
  cluster, so matter.js always discarded it and Homebridge now warns.
  Not replaced with electricalPowerMeasurement: nothing in the plugin
  updates power readings yet, so it would expose a permanent empty
  reading on every plug, metering or not.
- motion: OccupancySensing's Occupancy attribute is a bitmap, so the
  initial value is now `{ occupied: false }` instead of `0`, and the
  descriptor read in GenericDevice returns `{ occupied }` instead of 1/0.

meter and humidifier still declare relativeHumidityMeasurement on device
types (TemperatureSensor, Fan) that do not list it, even as optional, so
Homebridge will keep warning for them; fixing that needs a different
device composition and is left for a separate change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LzktUspaxcZ9Dh5WVEtf5W
@donavanbecker
donavanbecker merged commit 0e58288 into beta-5.4.2 Nov 20, 2026
3 checks passed
@donavanbecker
donavanbecker deleted the fix/matter-cluster-shapes branch November 20, 2026 18:54
@donavanbecker donavanbecker mentioned this pull request Nov 20, 2026
donavanbecker added a commit that referenced this pull request Nov 20, 2026
## homebridge-switchbot 5.5.0

Releases what was waiting on `beta-5.4.2` (published as `5.4.2-beta.0`).
5.4.2 was cut from `latest` before these landed.

- **New device types** (#1468): Curtain4 (Window Covering, like the
Curtain 3), Robot Vacuum Cleaner S30 (like the S20), Robot Vacuum
Cleaner K11 Plus Pro (like the K11+). They're resolved by node-switchbot
6.1.4, which the existing `^6.1.2` range allows.
- **Matter fix** (#1467): the plug no longer declares the invalid
`electricalMeasurement` cluster, and motion sensors report occupancy as
the `{ occupied }` bitmap. Homebridge 2.5.1 warns about both otherwise.

Labelled `minor` like v5.4.0, since it adds device types. No config
migration needed.

---
_Generated by [Claude Code](https://claude.ai/code)_

---------

Co-authored-by: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants