Self-host HomeBridge

Changes

• fix: guard child bridge shutdown before bridgeService is assigned (#3999) (@SAY-5)
• perf: reduce plugin discovery filesystem calls (#4000) (@n0rt0nthec4t)
• perf: index accessory operations (#4003) (@n0rt0nthec4t)
• perf: remove shell from npm prefix lookup (#4004) (@n0rt0nthec4t)
• test: restore and enforce type checking (#4005) (@n0rt0nthec4t)
• feat: expose RVC direct mode change capability (#4001) (@jbwhy)
• fix: validate stored Matter credentials (#4006) (@n0rt0nthec4t)
• perf: cache Homebridge package metadata (#4007) (@n0rt0nthec4t)
• fix: coalesce child bridge port requests (#4008) (@n0rt0nthec4t)
• fix(matter): report a plugin's manufacturer and model on an external matter accessory
• fix(matter): keep a restored accessory's owner, so the cache stops losing it on alternate restarts
• fix(matter): re-arm state monitoring on child bridge start, so the ui keeps showing changes (#3993)
• chore(deps): dependency updates
• fix(matter): keep the cluster features a plugin chose when homebridge attaches its handlers
• fix(matter): restore a cached accessory with the cluster features the plugin composed
• fix(matter): show a thermostat's temperature when it registers after the bridge is online
• feat(matter): turn on fan auto mode when a fan declares a sequence that offers it
• feat(matter): add auto mode to a room air conditioner that starts in auto or declares a deadband
• feat(matter): let an air quality sensor report every level, not only good and poor
• feat(matter): add the water heater device type, with mode and boost handlers
• fix(matter): keep a light's lighting feature on its on/off cluster when handlers are attached
• docs(matter): say which clusters the media player device type actually carries
• fix(matter): pass accessory information to the UI (#4019) (@thecloudseeker)
• fix(matter): keep uniqueId when re-registering a restored accessory (#4020) (@thecloudseeker)
• fix: read matter.js native fabric storage to report commissioned state (#4021) (@AxelDreemurr)
• fix(matter): preserve accessory cache on read errors (#4023) (@ethanjnrg)
• fix(matter): skip malformed accessory cache entries (#4024) (@ethanjnrg)
• fix(matter): report cache save failures without blocking shutdown (#4025) (@ethanjnrg)
• fix(matter): fall back to matter.js when a ColorControl handler is missing (#4028) (@cestercian)
• fix(matter): stop the ui's light commands failing when sent together or without options (#4029)
• fix(matter): show a newly registered accessory in the ui without a restart (#4013)
• docs(matter): say a restored accessory needs registering again, and keeps its cached state (#4015)
• fix(matter): shorten an accessory's over-long name, model or serial and say which (#4016)
• chore(deps): update matter.js to v0.18.0, with the changes its new checks need
• feat(api): expose bridge HAP enablement to plugins (#4037) (@n0rt0nthec4t)
• feat(api): add isMatterExternalsOnly to match isHapExternalsOnly
• fix(matter): only enable matter for main bridge plugins when the main bridge uses it
• fix: keep external accessory ports off the ports bridges are configured to use (#4035)
• fix(matter): resolve register and unregister once the bridge has finished (#4033)
• fix(matter): give a power source with no battery the wired feature, so it registers
• fix(matter): build a composed accessory together with its parts
• feat(matter): add solar, battery, ev charger, meter and tariff device types (#4034)
• fix: accept a config.json that starts with a UTF-8 BOM (#4039) (@b84330808)
• chore(docs): regenerate docs for v2.5.0

Homebridge Dependencies

• @homebridge/hap-nodejs @ v2.3.0

Matter Dependencies

• @matter/main @ v0.18.0

Changes

• chore(deps): dependency updates
• fix(matter): echo the control correlationId so the ui stops retrying successful commands
• refactor(matter): collapse the three identical rvc operational command handlers into one
• fix(matter): keep a restored colour light's colour features, so it stops failing on every restart
• fix(matter): only warn about a cluster the plugin actually supplies handlers for
• feat(matter): expose the device type requirements, so a plugin can choose its own cluster features
• feat(matter): send each cluster's feature map to the ui, so it can offer only the controls a device has
• fix(matter): send the feature map for accessory parts too, not just the accessory
• fix(matter): keep a whole matter message in the debug log, so a report's value is not cut off (#3958)
• fix(matter): stop a brightness command failing on a dimmable light by writing the on/off state twice (#3993)
• fix(matter): keep an accessory's endpoint when a plugin updates it, so state updates keep working

Homebridge Dependencies

• @homebridge/hap-nodejs @ v2.2.2

Matter Dependencies

• @matter/main @ v0.17.9

Changes

• fix(matter): stop rejecting the bridge's own storage path on windows (#3987)

Homebridge Dependencies

• @homebridge/hap-nodejs @ v2.2.0

Matter Dependencies

• @matter/main @ v0.17.9

⚠️ HAP-NodeJS Changes

Homebridge v2.3.0 ships HAP-NodeJS v2.2.0, which replaces the unmaintained node-persist with a small built-in file storage.

For Homebridge Users:

• Your saved data is not touched — the on-disk format is identical, and nothing is migrated or rewritten.
• There is a small chance that a plugin uses one of the storage methods that has been removed, in which case that plugin will stop working on this version. This should be rare, but it is possible. If a plugin starts misbehaving after updating, you can safely go back to Homebridge v2.2.1 while it is fixed — because the file format has not changed, nothing is lost by downgrading, and your pairings and accessories come back exactly as they were.

For Plugin Developers:

• If your plugin calls HAPStorage.storage(), it can now only do four things. HAPStorage is exported from homebridge, so some plugins reach for it to store their own data. The object it returns now supports initSync, getItem, setItemSync and removeItemSync. Every other method from the old API throws an error that names the method and explains why.
• Three smaller changes on those four:
  • Keys must be plain file names — no / in them, and no leading dot. A key like my-plugin/device-1 has to become something like my-plugin-device-1.
  • initSync({ dir }) needs an absolute path. A relative one used to be quietly resolved inside node_modules, where the data was lost at the next install.
  • getItem(key, callback) throws. Use await getItem(key).

Everything else is unchanged. api.user.storagePath() and api.user.persistPath() behave exactly as before, and a plugin running its own node-persist instance against the storage directory keeps working, because the file format has not changed.

Changes

• feat: make identifying material in bonjour configurable (#3965) (@naterator)
• fix(matter): compose PowerSource for all device types (#3968) (@zbuc)
• fix(matter): restore cached accessories into the bridge before going online (#3969) (@keremerkan)
• feat(matter): expose matter status errors on api.matter.status
• feat(matter): detect thermostat features from the declared setpoints
• fix(matter): read cluster features from the behavior, not the cluster
• fix(matter): retry Matter server start on transient storage-lock contention
• fix(matter): retry parts-list notification on synchronous lock contention
• fix(matter): reject bridged registrations that arrive before the server is running
• test(matter): cover cache-restore attach-in-place and pre-online ordering
• fix(matter): defer bridge online until registrations settle (#3973) (@keremerkan)
• fix(matter): add FixedLabel and PowerSource to composed parents (#3972) (@keremerkan)
• feat(matter): expose commissioned fabrics in the child bridge status (#3974)
• fix(matter): read the fabric vendor id from cluster-shaped fabric entries (#3974)
• fix(matter): declare ac/dc feature on power measurement (#3977) (@keremerkan)
• feat(matter): populate bridged accessory firmware version from firmwareRevision (#3976) (@keremerkan)
• chore(deps): dependency updates
• chore(deps): bump @matter/main to the released v0.17.7
• feat: Support for NodeJS 26
• feat(matter): warn when a thermostat's setpoint limits cannot satisfy its auto-mode deadband
• fix(matter): advertise the power source device type on endpoints with a battery, per the Matter spec
• fix(matter): seed a battery's unknown charge state, so a late first report is not rejected (#3982)
• chore(deps): updated @matter/main from v0.17.6 to v0.17.9
  • see changelog →
• feat(matter): expose the closure, media player and speaker device types to plugins
• fix(matter): expose the clusters and enums the new device types need, so plugins are not left with magic numbers
• fix(matter): route closure, media playback and keypad commands to plugin handlers
• fix(matter): give composed parts the same preparation as their parent accessory
• fix(matter): measure thermostat setpoint limits against the declared absolute limits
• fix(matter): report zero commissioned fabrics as not commissioned (#3974)

Homebridge Dependencies

• @homebridge/hap-nodejs @ v2.2.0

Matter Dependencies

• @matter/main @ v0.17.9

Changes

• fix(matter): add electrical clusters to public cluster name map
• chore(deps): dependency updates
• docs(matter): document update cadence for electrical measurement clusters
• docs: regenerate docs for v2.2.1

Homebridge Dependencies

• @homebridge/hap-nodejs @ v2.1.9

Matter Dependencies

• @matter/main @ v0.17.6