matterbridge-homey 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-10-28
+
+### Changed
+
+- [platform]: The `newDevices` setting replaces `exposeNewDevices` of 0.3.0: new Homey devices can be added to the white list or the black list automatically, also the devices added while Matterbridge was stopped. The default applies the lists as they are and exposes new devices right away.
+- [build]: The plugin is published to npm by a GitHub workflow when a GitHub release is created.
+- [test]: The tests use the test utilities of Matterbridge 3.11 (`matterbridge/test-utils`).
+
+### Fixed
+
+- [devices]: Plugs have the Lighting feature of the OnOff cluster, and smoke and CO alarms without a battery have a wired power source, as Matter 1.4 requires. Matterbridge 3.11 warned about both.
+
 ## [0.3.0] - 2026-10-28
 
 ### Added

package/README.md

@@ -25,20 +25,20 @@ The key is shown only once, so copy it right away.
 
 ## Configuration
 
-| Setting                     | Description                                                                                                                                                 |
-| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `address`                   | Local address of the Homey, e.g. `http://192.168.1.50`. `https://192-168-1-50.homey.homeylocal.com` also works, unless your router blocks DNS rebinding.    |
-| `token`                     | The API key.                                                                                                                                                |
-| `whiteList`                 | Only these devices are exposed (names or Homey device IDs). Empty exposes all supported devices. The frontend offers a device picker after the first start. |
-| `blackList`                 | These devices are never exposed.                                                                                                                            |
-| `zoneWhiteList`             | Only devices in these Homey zones are exposed, including sub-zones. Empty exposes all zones.                                                                |
-| `lightList`                 | These devices are exposed as lights, whatever their Homey class.                                                                                            |
-| `outletList`                | These devices are exposed as plugs, whatever their Homey class.                                                                                             |
-| `capabilityBlackList`       | These Homey capabilities are never exposed, e.g. `meter_power`.                                                                                             |
-| `deviceCapabilityBlackList` | Capabilities not exposed for one device: the device name (or ID) and its list of capabilities, e.g. `{ "Multisensor": ["alarm_occupancy"] }`.               |
-| `exposeNewDevices`          | Expose devices added to Homey right away, without a restart (default on). The lists above still apply. When off, new devices are exposed after a restart.   |
-| `debug`                     | Log the homey-api debug output.                                                                                                                             |
-| `unregisterOnShutdown`      | Remove all devices from the controllers on shutdown. For development only.                                                                                  |
+| Setting                     | Description                                                                                                                                                                                                                  |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `address`                   | Local address of the Homey, e.g. `http://192.168.1.50`. `https://192-168-1-50.homey.homeylocal.com` also works, unless your router blocks DNS rebinding.                                                                     |
+| `token`                     | The API key.                                                                                                                                                                                                                 |
+| `whiteList`                 | Only these devices are exposed (names or Homey device IDs). Empty exposes all supported devices. The frontend offers a device picker after the first start.                                                                  |
+| `blackList`                 | These devices are never exposed.                                                                                                                                                                                             |
+| `zoneWhiteList`             | Only devices in these Homey zones are exposed, including sub-zones. Empty exposes all zones.                                                                                                                                 |
+| `lightList`                 | These devices are exposed as lights, whatever their Homey class.                                                                                                                                                             |
+| `outletList`                | These devices are exposed as plugs, whatever their Homey class.                                                                                                                                                              |
+| `capabilityBlackList`       | These Homey capabilities are never exposed, e.g. `meter_power`.                                                                                                                                                              |
+| `deviceCapabilityBlackList` | Capabilities not exposed for one device: the device name (or ID) and its list of capabilities, e.g. `{ "Multisensor": ["alarm_occupancy"] }`.                                                                                |
+| `newDevices`                | What happens to devices added to Homey, also while Matterbridge is stopped: `default` applies the lists as they are, `whiteList` adds them to the white list (when it isn't empty), `blackList` adds them to the black list. |
+| `debug`                     | Log the homey-api debug output.                                                                                                                                                                                              |
+| `unregisterOnShutdown`      | Remove all devices from the controllers on shutdown. For development only.                                                                                                                                                   |
 
 ## Supported devices
 
@@ -114,7 +114,7 @@ The white and black lists accept Homey device IDs as well as names. Entries by n
 
 ### Limitations
 
-- New Homey devices are exposed right away and deleted devices are removed right away. With `exposeNewDevices` off, new devices need a Matterbridge restart; the frontend asks for it. To keep new devices out entirely, use the white list.
+- New Homey devices are exposed right away, unless the lists or `newDevices` keep them out, and deleted devices are removed right away. `newDevices` adds a device to a list by its name: like the other entries by name, it stops matching when the device is renamed.
 - A new device is exposed with the capabilities Homey reports for it. Capabilities that its app adds later appear after a restart.
 - Devices with the same name get their zone appended, e.g. `Ceiling light Kitchen`.
 - Not supported yet: buttons and remotes, media players and TVs (only their `onoff`), window covering tilt, plant moisture, `level_aqi`.
@@ -139,7 +139,16 @@ Uploading a newer tarball replaces the installed version. Test builds are marked
 
 ## Development
 
-The plugin follows the [Matterbridge plugin template](https://github.com/Luligu/matterbridge-plugin-template). Matterbridge must never be a dependency of the plugin: link a global or locally built Matterbridge with `npm link matterbridge` (see the [development guide](https://matterbridge.io/README-DEV.html)).
+The plugin follows the [Matterbridge plugin template](https://github.com/Luligu/matterbridge-plugin-template). Matterbridge must never be a dependency of the plugin: clone and build Matterbridge next to the plugin and link it, like the CI does (see the [development guide](https://matterbridge.io/README-DEV.html)):
+
+```bash
+git clone --depth 1 --single-branch --no-tags https://github.com/Luligu/matterbridge.git ../matterbridge
+(cd ../matterbridge && npm install && npm run build && npm link)
+npm install
+npm run link
+```
+
+A Matterbridge installed with `npm install -g matterbridge` builds the plugin, but the tests and the typecheck fail: its test utilities need Vitest, which only a clone installs. Pull and rebuild the clone to update it. The tests need Matterbridge 3.11 or later.
 
 | Script                  | Purpose                         |
 | ----------------------- | ------------------------------- |
@@ -160,6 +169,16 @@ Source layout:
 
 The tests run the platform against a Matter server node with a fake Homey. `vitest/homey.real.test.ts` runs it against your own Homey, read-only (every write is refused): put `HOMEY_ADDRESS`, `HOMEY_TOKEN` and `HOMEY_REAL_TEST=1` in `.env` (ignored by git) and run `npm run test -- vitest/homey.real.test.ts`.
 
+### Publishing
+
+The [Publish to npm](.github/workflows/publish.yml) workflow publishes the plugin when a GitHub release is created: it builds Matterbridge, runs the build, typecheck, lint and tests, and publishes with [npm trusted publishing](https://docs.npmjs.com/trusted-publishers), so neither an npm login nor a local Matterbridge is needed.
+
+1. `npm version minor --no-git-tag-version --ignore-scripts` (or `patch`), and move the `[Unreleased]` changes in `CHANGELOG.md` under the new version and date.
+2. Commit and push.
+3. `node scripts/create-release.mjs`: creates the GitHub release from the changelog (needs the [GitHub CLI](https://cli.github.com)), which starts the workflow.
+
+Once, before the first release from the workflow: on npmjs.com, add the trusted publisher in the settings of the package (GitHub Actions, repository `stefan-schweiger/matterbridge-homey`, workflow `publish.yml`).
+
 ## License
 
 Apache-2.0

package/dist/features.js

@@ -1,4 +1,4 @@
-import { airQualitySensor, colorTemperatureLight, contactSensor, dimmableLight, dimmablePlugInUnit, doorLock, electricalSensor, extendedColorLight, fan, humiditySensor, lightSensor, occupancySensor, onOffLight, onOffPlugInUnit, pressureSensor, rainSensor, roboticVacuumCleaner, smokeCoAlarm, temperatureSensor, thermostat, waterLeakDetector, windowCovering, } from 'matterbridge';
+import { airQualitySensor, colorTemperatureLight, contactSensor, dimmableLight, dimmablePlugInUnit, doorLock, electricalSensor, extendedColorLight, fan, humiditySensor, lightSensor, occupancySensor, onOffLight, onOffPlugInUnit, powerSource, pressureSensor, rainSensor, roboticVacuumCleaner, smokeCoAlarm, temperatureSensor, thermostat, waterLeakDetector, windowCovering, } from 'matterbridge';
 import { MatterbridgeRvcCleanModeServer, MatterbridgeRvcOperationalStateServer, MatterbridgeRvcRunModeServer } from 'matterbridge/devices';
 import { AirQuality, BooleanState, CarbonDioxideConcentrationMeasurement, CarbonMonoxideConcentrationMeasurement, ColorControl, DoorLock, ElectricalEnergyMeasurement, ElectricalPowerMeasurement, FanControl, IlluminanceMeasurement, LevelControl, OccupancySensing, OnOff, Pm10ConcentrationMeasurement, Pm25ConcentrationMeasurement, PressureMeasurement, RelativeHumidityMeasurement, RvcCleanMode, RvcOperationalState, RvcRunMode, SmokeCoAlarm, TemperatureMeasurement, Thermostat, TotalVolatileOrganicCompoundsConcentrationMeasurement, WindowCovering, } from 'matterbridge/matter/clusters';
 import { kelvinToRGB, miredToKelvin, rgbColorToHslColor, xyToHsl } from 'matterbridge/utils';
@@ -119,7 +119,7 @@ function lightFeature(device) {
         deviceTypes: [deviceType],
         clusters,
         build: (context) => {
-            buildOnOff(context, 'onoff', true);
+            buildOnOff(context, 'onoff');
             if (clusters.includes('LevelControl'))
                 buildLevelControl(context);
             if (hasHueSaturation)
@@ -137,19 +137,16 @@ function plugFeature(device, capabilityId) {
         deviceTypes: [isDimmable ? dimmablePlugInUnit : onOffPlugInUnit],
         clusters: isDimmable ? ['OnOff', 'LevelControl'] : ['OnOff'],
         build: (context) => {
-            buildOnOff(context, capabilityId, isDimmable);
+            buildOnOff(context, capabilityId);
             if (isDimmable)
                 buildLevelControl(context);
         },
     };
 }
-function buildOnOff(context, capabilityId, isLighting) {
+function buildOnOff(context, capabilityId) {
     const { device, endpoint } = context;
     const isOn = context.value(capabilityId) === true;
-    if (isLighting)
-        endpoint.createDefaultOnOffClusterServer(isOn);
-    else
-        endpoint.createOnOffClusterServer(isOn);
+    endpoint.createDefaultOnOffClusterServer(isOn);
     if (hasCapability(device, capabilityId)) {
         endpoint.addCommandHandler('on', () => context.set(capabilityId, true));
         endpoint.addCommandHandler('off', () => context.set(capabilityId, false));
@@ -578,18 +575,17 @@ function vacuumFeature(device) {
                 else if (request.newMode === vacuumIdleMode)
                     stop('stopped', true);
             });
+            const isInState = (state, ...states) => states.includes(state);
             endpoint.addCommandHandler('RvcOperationalState.pause', ({ attributes }) => {
-                if (attributes.operationalState === OperationalState.Running || attributes.operationalState === OperationalState.SeekingCharger)
+                if (isInState(attributes.operationalState, OperationalState.Running, OperationalState.SeekingCharger))
                     stop('stopped', false);
             });
             endpoint.addCommandHandler('RvcOperationalState.resume', ({ attributes }) => {
-                if (attributes.operationalState === OperationalState.Paused)
+                if (isInState(attributes.operationalState, OperationalState.Paused))
                     start();
             });
             endpoint.addCommandHandler('RvcOperationalState.goHome', ({ attributes }) => {
-                if (attributes.operationalState === OperationalState.Stopped ||
-                    attributes.operationalState === OperationalState.Running ||
-                    attributes.operationalState === OperationalState.Paused)
+                if (isInState(attributes.operationalState, OperationalState.Stopped, OperationalState.Running, OperationalState.Paused))
                     stop('docked', true);
             });
             if (cleanModeIds.length > 0) {
@@ -719,11 +715,12 @@ function booleanStateFeature(capabilityId, deviceType, toState) {
 function smokeCoAlarmFeature(device) {
     const hasSmoke = hasCapability(device, 'alarm_smoke');
     const hasCo = hasCapability(device, 'alarm_co');
+    const hasBattery = hasCapability(device, 'measure_battery') || hasCapability(device, 'alarm_battery');
     const alarmState = (value) => (value === true ? SmokeCoAlarm.AlarmState.Critical : SmokeCoAlarm.AlarmState.Normal);
     return {
         name: 'smokecoalarm',
         capabilities: ['alarm_smoke', 'alarm_co'],
-        deviceTypes: [smokeCoAlarm],
+        deviceTypes: [smokeCoAlarm, powerSource],
         clusters: ['SmokeCoAlarm'],
         build: (context) => {
             const { endpoint } = context;
@@ -733,6 +730,8 @@ function smokeCoAlarmFeature(device) {
                 endpoint.createSmokeOnlySmokeCOAlarmClusterServer(alarmState(context.value('alarm_smoke')));
             else
                 endpoint.createCoOnlySmokeCOAlarmClusterServer(alarmState(context.value('alarm_co')));
+            if (!hasBattery)
+                endpoint.createDefaultPowerSourceWiredClusterServer();
             if (hasSmoke) {
                 context.bind('alarm_smoke', async (value) => {
                     await endpoint.updateAttribute(SmokeCoAlarm, 'smokeState', alarmState(value), endpoint.log);

package/dist/module.js

@@ -55,6 +55,7 @@ export class HomeyPlatform extends MatterbridgeDynamicPlatform {
     bridgedDevices = new Map();
     zones = [];
     newDeviceIds = new Set();
+    knownDeviceIds = new Set();
     areDevicesConfigured = false;
     deviceChanges = Promise.resolve();
     constructor(matterbridge, log, config, homey) {
@@ -76,18 +77,12 @@ export class HomeyPlatform extends MatterbridgeDynamicPlatform {
         this.config.outletList = isValidArray(config.outletList) ? config.outletList : [];
         this.config.capabilityBlackList = isValidArray(config.capabilityBlackList) ? config.capabilityBlackList : [];
         this.config.deviceCapabilityBlackList = isValidObject(config.deviceCapabilityBlackList) ? config.deviceCapabilityBlackList : {};
-        this.config.exposeNewDevices ??= true;
+        this.config.newDevices = config.newDevices === 'whiteList' || config.newDevices === 'blackList' ? config.newDevices : 'default';
         this.config.debug ??= false;
         this.config.unregisterOnShutdown ??= false;
         this.homey =
             homey ?? new HomeyApiConnection(config.address, config.token, 15000, config.debug ? (message) => this.log.debug(`[homey-api] ${message}`) : undefined);
         this.homey.on('device.create', (device) => {
-            if (!this.config.exposeNewDevices) {
-                this.log.notice(`New Homey device ${CYAN}${device.name}${nf}: restart Matterbridge to expose it`);
-                if (this.isConfigured)
-                    this.wssSendRestartRequired();
-                return;
-            }
             this.log.notice(`New Homey device ${CYAN}${device.name}${nf}`);
             fireAndForget(this.serialize(async () => this.addNewDevice(device)), this.log, `addition of ${device.name}`);
         });
@@ -127,9 +122,12 @@ export class HomeyPlatform extends MatterbridgeDynamicPlatform {
             this.zones = zones;
             this.log.info(`Found ${CYAN}${devices.length}${nf} devices in ${CYAN}${zones.length}${nf} zones`);
             const names = getUniqueDeviceNames(devices, zones);
+            const knownDeviceIds = await this.context?.get('knownDeviceIds');
             for (const device of devices.toSorted((a, b) => a.name.localeCompare(b.name))) {
-                await this.addDevice(device, names.get(device.id) ?? device.name, zones);
+                await this.addDevice(device, names.get(device.id) ?? device.name, zones, knownDeviceIds?.includes(device.id) === false);
+                this.knownDeviceIds.add(device.id);
             }
+            await this.saveKnownDevices();
         });
         this.log.info(`Started platform ${idn}${this.config.name}${rs}${nf} with ${CYAN}${this.bridgedDevices.size}${nf} devices`);
     }
@@ -170,7 +168,7 @@ export class HomeyPlatform extends MatterbridgeDynamicPlatform {
         this.bridgedDevices.clear();
         this.log.info(`Shut down platform ${idn}${this.config.name}${rs}${nf}`);
     }
-    async addDevice(device, name, zones) {
+    async addDevice(device, name, zones, isNew = false) {
         const serial = getSerialNumber(device.id);
         const keys = [name, device.name, device.id, serial];
         const isListed = (list) => keys.some((key) => list.includes(key));
@@ -190,6 +188,8 @@ export class HomeyPlatform extends MatterbridgeDynamicPlatform {
         for (const entity of entities)
             this.setSelectEntity(entity.name, entity.description, 'component');
         this.setSelectDevice(serial, name, configUrl, 'hub', entities);
+        if (isNew)
+            this.listNewDevice(keys);
         if (!this.validateDevice(keys))
             return;
         const excludedCapabilities = new Set([...this.config.capabilityBlackList, ...keys.flatMap((key) => this.config.deviceCapabilityBlackList[key] ?? [])]);
@@ -220,12 +220,16 @@ export class HomeyPlatform extends MatterbridgeDynamicPlatform {
     async addNewDevice(device) {
         if (this.bridgedDevices.has(device.id))
             return;
+        if (!this.knownDeviceIds.has(device.id)) {
+            this.knownDeviceIds.add(device.id);
+            await this.saveKnownDevices();
+        }
         const [devices, zones] = await Promise.all([this.homey.getDevices(), this.homey.getZones()]);
         this.zones = zones;
         const names = getUniqueDeviceNames([...devices.filter((other) => other.id !== device.id), device], zones);
         for (const [deviceId, bridged] of this.bridgedDevices)
             await bridged.setName(names.get(deviceId) ?? bridged.device.name);
-        await this.addDevice(device, names.get(device.id) ?? device.name, zones);
+        await this.addDevice(device, names.get(device.id) ?? device.name, zones, true);
         const bridgedDevice = this.bridgedDevices.get(device.id);
         if (!bridgedDevice) {
             this.newDeviceIds.add(device.id);
@@ -254,6 +258,8 @@ export class HomeyPlatform extends MatterbridgeDynamicPlatform {
     }
     async removeDevice(deviceId) {
         this.newDeviceIds.delete(deviceId);
+        if (this.knownDeviceIds.delete(deviceId))
+            await this.saveKnownDevices();
         const bridgedDevice = this.bridgedDevices.get(deviceId);
         if (!bridgedDevice)
             return;
@@ -262,6 +268,20 @@ export class HomeyPlatform extends MatterbridgeDynamicPlatform {
         this.bridgedDevices.delete(deviceId);
         await this.unregisterDevice(bridgedDevice.endpoint);
     }
+    listNewDevice(keys) {
+        const listName = this.config.newDevices;
+        if (listName === 'default' || (listName === 'whiteList' && this.config.whiteList.length === 0))
+            return;
+        const list = this.config[listName];
+        if (keys.some((key) => list.includes(key)))
+            return;
+        list.push(keys[0]);
+        this.log.notice(`Added the new device ${CYAN}${keys[0]}${nf} to the ${listName === 'whiteList' ? 'white' : 'black'} list`);
+        this.saveConfig(this.config);
+    }
+    async saveKnownDevices() {
+        await this.context?.set('knownDeviceIds', [...this.knownDeviceIds]);
+    }
     async serialize(change) {
         const result = this.deviceChanges.then(change);
         this.deviceChanges = result.catch(() => {

package/matterbridge-homey.config.json

@@ -10,7 +10,7 @@
   "outletList": [],
   "capabilityBlackList": [],
   "deviceCapabilityBlackList": {},
-  "exposeNewDevices": true,
+  "newDevices": "default",
   "debug": false,
   "unregisterOnShutdown": false
 }

package/matterbridge-homey.schema.json

@@ -104,11 +104,12 @@
         "selectDeviceEntityFrom": "name"
       }
     },
-    "exposeNewDevices": {
-      "title": "Expose New Devices",
-      "description": "Expose the devices added to Homey right away, without restarting Matterbridge. The white list, black list and zone white list still apply. When off, new devices are exposed after the next restart.",
-      "type": "boolean",
-      "default": true
+    "newDevices": {
+      "title": "New Devices",
+      "description": "What happens to the devices added to Homey, also while Matterbridge is stopped. default: the lists apply as they are, so with an empty white list new devices are exposed right away. whiteList: new devices are added to the white list, so they are exposed (only when the white list isn't empty). blackList: new devices are added to the black list, so they aren't exposed until you remove them from it.",
+      "type": "string",
+      "enum": ["default", "whiteList", "blackList"],
+      "default": "default"
     },
     "debug": {
       "title": "Enable Debug",

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "matterbridge-homey",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "matterbridge-homey",
-      "version": "0.3.0",
+      "version": "0.4.0",
       "license": "Apache-2.0",
       "dependencies": {
         "homey-api": "3.20.0"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "matterbridge-homey",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Matterbridge plugin that exposes Athom Homey Pro devices to Matter",
   "author": "Stefan Schweiger",
   "license": "Apache-2.0",