matterbridge-homey 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,22 @@ 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.2.0] - 2026-10-18
+
+### Added
+
+- [devices]: Robotic vacuum cleaners with the standard Homey capabilities: start, stop, pause, resume and go home, the state, the clean modes and the battery.
+
+### Changed
+
+- [docs]: The README explains the default color temperature range of lights and installing the plugin from npm.
+
+### Fixed
+
+- [devices]: The Off mode of a thermostat or air conditioner turns `onoff` off instead of setting the `off` mode, which some drivers ignore.
+- [platform]: A device that fails to build is skipped with an error instead of stopping the plugin from starting.
+- [build]: Test builds of `npm run pack:tarball` are marked private, so Matterbridge reinstalls them from the uploaded tarball when the Docker container is recreated, instead of failing to find a `dev` version on npm.
+
 ## [0.1.0] - 2026-10-13
 
 ### Added

package/README.md

@@ -52,6 +52,9 @@ The Matter device type follows the Homey device class (or the class you chose fo
 | `windowcoverings`, `blinds`, `curtain`, `sunshade`, `shutterblinds` | `windowcoverings_set`, `windowcoverings_state`                                     | Window covering (lift)                                            |
 | `lock`                                                              | `locked`                                                                           | Door lock                                                         |
 | `fan`, `airpurifier`                                                | `onoff`, `fan_speed`                                                               | Fan                                                               |
+| `vacuumcleaner`                                                     | `vacuumcleaner_state` or `onoff`, `operational_state`, `vacuumcleaner_job_mode`    | Robotic vacuum cleaner                                            |
+
+The Off mode of a thermostat or air conditioner turns `onoff` off, and the other modes turn it back on. Only devices without `onoff` get the `off` value of `thermostat_mode`, because some drivers don't switch the device off with it.
 
 Sensors are added to any device that has them:
 
@@ -67,6 +70,26 @@ Sensors are added to any device that has them:
 
 Sub-capabilities of sensors, e.g. `measure_temperature.inside`, are exposed too. The outdoor temperature of a thermostat or air conditioner (e.g. `measure_temperature.outdoorTemperature`) is part of the thermostat.
 
+### Color temperature of lights
+
+Homey doesn't give the color temperature of a light in Kelvin or mireds. Its `light_temperature` goes from 0 (the coldest white of the light) to 1 (the warmest white), and Homey doesn't tell which Kelvin range that is for the light.
+
+The plugin therefore maps it onto a default range of 6500 K (153 mireds) to 2000 K (500 mireds) for every light. The coldest and warmest settings of the controller are the coldest and warmest white of the light, but the Kelvin values in between are approximate: a light that only goes from 2700 K to 6500 K looks colder than the controller shows.
+
+### Robotic vacuum cleaners
+
+Vacuums are supported with the standard Homey capabilities and values only:
+
+- Start and stop (the Matter run modes Idle and Cleaning) set `vacuumcleaner_state` to `cleaning` or `stopped`, or turn `onoff` on or off.
+- Go home sets `vacuumcleaner_state` to `docked`. Homey has no standard pause: pause stops the vacuum, resume starts it again.
+- The state comes from `vacuumcleaner_state` (cleaning, docked, charging, stopped) and the standard values of `operational_state` (paused, error).
+- The standard values of `vacuumcleaner_job_mode` (normal, high, turbo, mop, auto) are the Matter clean modes. Matter only changes them while the vacuum is idle.
+- No rooms or maps: Homey has no standard capability for them.
+
+Vacuums without `vacuumcleaner_state` or `onoff` aren't exposed. This includes Matter vacuums paired with Homey: Homey's Matter driver uses the Matter state and mode numbers instead of the standard values. Add such a vacuum to your Matter controller directly instead.
+
+Apple Home doesn't support a vacuum in a bridge, and the whole bridge becomes unstable. If you use Apple Home, add your vacuums to the black list.
+
 ### How devices are composed
 
 Each Homey device is one Matter bridged device. Its main function and as many sensors as possible share one endpoint, so controllers show one device instead of one per function (Alexa shows every endpoint as a separate device). A function that can't share the endpoint gets a child endpoint: a second sensor of the same kind (e.g. `alarm_motion` and `alarm_presence`) or a sub-capability (e.g. `onoff.output2`).
@@ -92,11 +115,15 @@ The white and black lists accept Homey device IDs as well as names. Entries by n
 
 - New Homey devices need a Matterbridge restart; the frontend asks for it. Deleted devices are removed right away.
 - 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`), vacuum cleaners, window covering tilt, plant moisture, `level_aqi`.
+- Not supported yet: buttons and remotes, media players and TVs (only their `onoff`), window covering tilt, plant moisture, `level_aqi`.
 
 ## Install
 
-The plugin isn't published on npm yet. Build a tarball and upload it to Matterbridge:
+On the Home page of the Matterbridge frontend, enter `matterbridge-homey` in the **Install plugins** panel and click **Install**. Then set the address and API key in the plugin configuration and restart.
+
+### Test builds
+
+To test changes before they are published, build a tarball and upload it to Matterbridge:
 
 ```bash
 npm install
@@ -104,9 +131,9 @@ npm link matterbridge
 npm run pack:tarball
 ```
 
-This creates `matterbridge-homey-<version>-dev-<date>-<time>.tgz` in the project folder (`npm run pack:tarball -- --release` keeps the plain version). On the Home page of the Matterbridge frontend, click **Upload** in the **Install plugins** panel and choose the tarball (the panel is hidden when Matterbridge runs read-only). Matterbridge installs it with `npm install -g <tarball> --omit=dev`, so the host needs access to the npm registry for `homey-api`. Then set the address and API key in the plugin configuration and restart.
+This creates `matterbridge-homey-<version>-dev-<date>-<time>.tgz` in the project folder (`npm run pack:tarball -- --release` keeps the plain version). On the Home page of the Matterbridge frontend, click **Upload** in the **Install plugins** panel and choose the tarball (the panel is hidden when Matterbridge runs read-only). Matterbridge installs it with `npm install -g <tarball> --omit=dev`, so the host needs access to the npm registry for `homey-api`.
 
-Uploading a newer tarball replaces the installed version.
+Uploading a newer tarball replaces the installed version. Test builds are marked private in their `package.json`: when the plugin is missing at start, e.g. after Docker recreated the Matterbridge container for an image update, Matterbridge reinstalls a private plugin from the last uploaded tarball instead of from npm. Release builds are reinstalled from npm.
 
 ## Development
 

package/dist/features.js

@@ -1,5 +1,6 @@
-import { airQualitySensor, colorTemperatureLight, contactSensor, dimmableLight, dimmablePlugInUnit, doorLock, electricalSensor, extendedColorLight, fan, humiditySensor, lightSensor, occupancySensor, onOffLight, onOffPlugInUnit, pressureSensor, rainSensor, smokeCoAlarm, temperatureSensor, thermostat, waterLeakDetector, windowCovering, } from 'matterbridge';
-import { AirQuality, BooleanState, CarbonDioxideConcentrationMeasurement, CarbonMonoxideConcentrationMeasurement, ColorControl, DoorLock, ElectricalEnergyMeasurement, ElectricalPowerMeasurement, FanControl, IlluminanceMeasurement, LevelControl, OccupancySensing, OnOff, Pm10ConcentrationMeasurement, Pm25ConcentrationMeasurement, PressureMeasurement, RelativeHumidityMeasurement, SmokeCoAlarm, TemperatureMeasurement, Thermostat, TotalVolatileOrganicCompoundsConcentrationMeasurement, WindowCovering, } from 'matterbridge/matter/clusters';
+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 { 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';
 import { colorTemperatureMaxMireds, colorTemperatureMinMireds, dimToLevel, levelToDim, lightTemperatureToMireds, liftToWindowCoveringsSet, luxToMatter, matterColorToUnit, miredsToLightTemperature, setpointToTargetTemperature, toHundredths, toThousandths, unitToMatterColor, windowCoveringsSetToLift, } from './converters.js';
 const lightClasses = new Set(['light']);
@@ -8,6 +9,7 @@ const coolingClasses = new Set(['airconditioning']);
 const coveringClasses = new Set(['windowcoverings', 'blinds', 'curtain', 'sunshade', 'shutterblinds']);
 const fanClasses = new Set(['fan', 'airpurifier']);
 const lockClasses = new Set(['lock']);
+const vacuumClasses = new Set(['vacuumcleaner']);
 const outputClasses = new Set(['socket', 'other']);
 export function hasCapability(device, capabilityId) {
     return device.capabilities.includes(capabilityId);
@@ -44,6 +46,8 @@ export function planFeatures(device) {
         features.push(doorLockFeature());
     else if (fanClasses.has(deviceClass) && hasOnOff)
         features.push(fanFeature(device));
+    else if (vacuumClasses.has(deviceClass) && (hasOnOff || hasCapability(device, 'vacuumcleaner_state')))
+        features.push(vacuumFeature(device));
     else if (hasOnOff && deviceClass !== 'sensor')
         features.push(plugFeature(device, 'onoff'));
     if (!climate)
@@ -61,7 +65,7 @@ export function planFeatures(device) {
     addSensor(features, device, 'measure_luminance', illuminanceFeature);
     if (['measure_co2', 'measure_co', 'measure_pm25', 'measure_pm10', 'measure_tvoc'].some((id) => hasCapability(device, id)))
         features.push(airQualityFeature(device));
-    let hasMainFunction = features.length > 0 && features[0].clusters.some((cluster) => ['OnOff', 'Thermostat', 'WindowCovering', 'DoorLock', 'FanControl'].includes(cluster));
+    let hasMainFunction = features.length > 0 && features[0].clusters.some((cluster) => ['OnOff', 'Thermostat', 'WindowCovering', 'DoorLock', 'FanControl', 'RvcRunMode'].includes(cluster));
     for (const capabilityId of device.capabilities) {
         const [base, sub] = capabilityId.split('.');
         if (sub === undefined)
@@ -319,7 +323,7 @@ function climateFeature(device, isCooling) {
                 if (!isFromController(actionContext))
                     return;
                 const modeId = Object.keys(systemModes).find((id) => systemModes[id] === value);
-                if (value === Thermostat.SystemMode.Off && !modeIds.has('off') && hasOnOff)
+                if (value === Thermostat.SystemMode.Off && hasOnOff)
                     context.set('onoff', false);
                 else if (modeId !== undefined && modeIds.has(modeId))
                     context.set('thermostat_mode', modeId);
@@ -469,6 +473,149 @@ function doorLockFeature() {
         },
     };
 }
+const vacuumIdleMode = 1;
+const vacuumCleaningMode = 2;
+const vacuumCleanModes = {
+    normal: { label: 'Normal', mode: 1, modeTags: [{ value: RvcCleanMode.ModeTag.Vacuum }] },
+    high: { label: 'High', mode: 2, modeTags: [{ value: RvcCleanMode.ModeTag.Vacuum }, { value: RvcCleanMode.ModeTag.DeepClean }] },
+    turbo: { label: 'Turbo', mode: 3, modeTags: [{ value: RvcCleanMode.ModeTag.Vacuum }, { value: RvcCleanMode.ModeTag.Max }] },
+    mop: { label: 'Mop', mode: 4, modeTags: [{ value: RvcCleanMode.ModeTag.Mop }] },
+    auto: { label: 'Auto', mode: 5, modeTags: [{ value: RvcCleanMode.ModeTag.Auto }, { value: RvcCleanMode.ModeTag.Vacuum }] },
+};
+const vacuumStates = {
+    cleaning: RvcOperationalState.OperationalState.Running,
+    spot_cleaning: RvcOperationalState.OperationalState.Running,
+    docked: RvcOperationalState.OperationalState.Docked,
+    charging: RvcOperationalState.OperationalState.Charging,
+    stopped: RvcOperationalState.OperationalState.Stopped,
+};
+const vacuumOperationalStates = {
+    stopped: RvcOperationalState.OperationalState.Stopped,
+    running: RvcOperationalState.OperationalState.Running,
+    paused: RvcOperationalState.OperationalState.Paused,
+    error: RvcOperationalState.OperationalState.Error,
+};
+export function getVacuumCleanModes(device) {
+    if (!hasCapability(device, 'vacuumcleaner_job_mode'))
+        return [];
+    const values = getCapability(device, 'vacuumcleaner_job_mode')?.values?.map((value) => value.id) ?? Object.keys(vacuumCleanModes);
+    return values.filter((value) => Object.hasOwn(vacuumCleanModes, value));
+}
+function mapStandardValue(mapping, value) {
+    return typeof value === 'string' && Object.hasOwn(mapping, value) ? mapping[value] : undefined;
+}
+function vacuumFeature(device) {
+    const hasState = hasCapability(device, 'vacuumcleaner_state');
+    const cleanModeIds = getVacuumCleanModes(device);
+    const { OperationalState } = RvcOperationalState;
+    return {
+        name: 'vacuum',
+        capabilities: ['vacuumcleaner_state', 'onoff', 'operational_state', 'vacuumcleaner_job_mode'],
+        deviceTypes: [roboticVacuumCleaner],
+        clusters: ['RvcRunMode', 'RvcCleanMode', 'RvcOperationalState'],
+        build: (context) => {
+            const { endpoint } = context;
+            const operationalState = () => {
+                const operational = mapStandardValue(vacuumOperationalStates, context.value('operational_state'));
+                if (operational === OperationalState.Paused || operational === OperationalState.Error)
+                    return operational;
+                return (mapStandardValue(vacuumStates, context.value('vacuumcleaner_state')) ??
+                    operational ??
+                    (context.value('onoff') === true ? OperationalState.Running : OperationalState.Stopped));
+            };
+            const operationalError = (state) => state === OperationalState.Error
+                ? { errorStateId: RvcOperationalState.ErrorState.UnableToCompleteOperation }
+                : { errorStateId: RvcOperationalState.ErrorState.NoError, errorStateDetails: 'Fully operational' };
+            const runMode = (state) => state === OperationalState.Running || state === OperationalState.Paused ? vacuumCleaningMode : vacuumIdleMode;
+            const cleanMode = () => {
+                const jobMode = context.value('vacuumcleaner_job_mode');
+                return vacuumCleanModes[typeof jobMode === 'string' && cleanModeIds.includes(jobMode) ? jobMode : cleanModeIds[0]].mode;
+            };
+            const state = operationalState();
+            endpoint.behaviors.require(MatterbridgeRvcRunModeServer, {
+                supportedModes: [
+                    { label: 'Idle', mode: vacuumIdleMode, modeTags: [{ value: RvcRunMode.ModeTag.Idle }] },
+                    { label: 'Cleaning', mode: vacuumCleaningMode, modeTags: [{ value: RvcRunMode.ModeTag.Cleaning }] },
+                ],
+                currentMode: runMode(state),
+            });
+            if (cleanModeIds.length > 0) {
+                endpoint.behaviors.require(MatterbridgeRvcCleanModeServer, { supportedModes: cleanModeIds.map((id) => vacuumCleanModes[id]), currentMode: cleanMode() });
+            }
+            endpoint.behaviors.require(MatterbridgeRvcOperationalStateServer, {
+                phaseList: null,
+                currentPhase: null,
+                countdownTime: null,
+                operationalStateList: [
+                    OperationalState.Stopped,
+                    OperationalState.Running,
+                    OperationalState.Paused,
+                    OperationalState.Error,
+                    OperationalState.SeekingCharger,
+                    OperationalState.Charging,
+                    OperationalState.Docked,
+                ].map((operationalStateId) => ({ operationalStateId })),
+                operationalState: state,
+                operationalError: operationalError(state),
+            });
+            const start = () => {
+                if (hasState)
+                    context.set('vacuumcleaner_state', 'cleaning', true);
+                else
+                    context.set('onoff', true, true);
+            };
+            const stop = (vacuumState, reflect) => {
+                if (hasState)
+                    context.set('vacuumcleaner_state', vacuumState, reflect);
+                else
+                    context.set('onoff', false, reflect);
+            };
+            endpoint.addCommandHandler('RvcRunMode.changeToMode', ({ request, attributes }) => {
+                if (request.newMode === attributes.currentMode)
+                    return;
+                if (request.newMode === vacuumCleaningMode)
+                    start();
+                else if (request.newMode === vacuumIdleMode)
+                    stop('stopped', true);
+            });
+            endpoint.addCommandHandler('RvcOperationalState.pause', ({ attributes }) => {
+                if (attributes.operationalState === OperationalState.Running || attributes.operationalState === OperationalState.SeekingCharger)
+                    stop('stopped', false);
+            });
+            endpoint.addCommandHandler('RvcOperationalState.resume', ({ attributes }) => {
+                if (attributes.operationalState === OperationalState.Paused)
+                    start();
+            });
+            endpoint.addCommandHandler('RvcOperationalState.goHome', ({ attributes }) => {
+                if (attributes.operationalState === OperationalState.Stopped ||
+                    attributes.operationalState === OperationalState.Running ||
+                    attributes.operationalState === OperationalState.Paused)
+                    stop('docked', true);
+            });
+            if (cleanModeIds.length > 0) {
+                endpoint.addCommandHandler('RvcCleanMode.changeToMode', ({ request, attributes }) => {
+                    const modeId = cleanModeIds.find((id) => vacuumCleanModes[id].mode === request.newMode);
+                    if (modeId === undefined || request.newMode === attributes.currentMode || endpoint.getAttribute(RvcRunMode, 'currentMode') !== vacuumIdleMode)
+                        return;
+                    context.set('vacuumcleaner_job_mode', modeId, true);
+                });
+            }
+            const update = async () => {
+                const newState = operationalState();
+                await endpoint.updateAttribute(RvcOperationalState, 'operationalState', newState, endpoint.log);
+                await endpoint.updateAttribute(RvcOperationalState, 'operationalError', operationalError(newState), endpoint.log);
+                await endpoint.updateAttribute(RvcRunMode, 'currentMode', runMode(newState), endpoint.log);
+            };
+            for (const capabilityId of ['vacuumcleaner_state', 'operational_state', 'onoff'])
+                context.bind(capabilityId, update);
+            if (cleanModeIds.length > 0) {
+                context.bind('vacuumcleaner_job_mode', async () => {
+                    await endpoint.updateAttribute(RvcCleanMode, 'currentMode', cleanMode(), endpoint.log);
+                });
+            }
+        },
+    };
+}
 function temperatureFeature(capabilityId) {
     return {
         name: capabilityId,

package/dist/module.js

@@ -1,5 +1,5 @@
-import { MatterbridgeDynamicPlatform } from 'matterbridge';
-import { CYAN, db, idn, nf, rs } from 'matterbridge/logger';
+import { MatterbridgeDynamicPlatform, roboticVacuumCleaner } from 'matterbridge';
+import { CYAN, db, idn, nf, rs, wr } from 'matterbridge/logger';
 import { fireAndForget, getErrorMessage, inspectError, isValidArray, isValidObject, isValidString } from 'matterbridge/utils';
 import { getExposedCapabilities } from './features.js';
 import { HomeyApiConnection } from './homey.js';
@@ -179,22 +179,25 @@ export class HomeyPlatform extends MatterbridgeDynamicPlatform {
         if (!this.validateDevice(keys))
             return;
         const excludedCapabilities = new Set([...this.config.capabilityBlackList, ...keys.flatMap((key) => this.config.deviceCapabilityBlackList[key] ?? [])]);
-        const bridgedDevice = HomeyBridgedDevice.create({
-            device: customizeDevice(remapped, undefined, excludedCapabilities),
-            name,
-            connection: this.homey,
-            vendorId: this.matterbridge.aggregatorVendorId,
-            logLevel: this.log.logLevel,
-            configUrl,
-        });
-        if (!bridgedDevice) {
-            this.log.info(`Device ${CYAN}${name}${nf} has no capabilities left after the capability black lists. Skipping...`);
-            return;
-        }
         try {
+            const bridgedDevice = HomeyBridgedDevice.create({
+                device: customizeDevice(remapped, undefined, excludedCapabilities),
+                name,
+                connection: this.homey,
+                vendorId: this.matterbridge.aggregatorVendorId,
+                logLevel: this.log.logLevel,
+                configUrl,
+            });
+            if (!bridgedDevice) {
+                this.log.info(`Device ${CYAN}${name}${nf} has no capabilities left after the capability black lists. Skipping...`);
+                return;
+            }
             this.log.info(`Registering device ${idn}${name}${rs}${nf} class ${CYAN}${remapped.virtualClass ?? remapped.class}${nf}...`);
             await this.registerDevice(bridgedDevice.endpoint);
             this.bridgedDevices.set(device.id, bridgedDevice);
+            if (bridgedDevice.endpoint.deviceTypes.has(roboticVacuumCleaner.code)) {
+                this.log.warn(`Device ${CYAN}${name}${wr} is a robotic vacuum cleaner: Apple Home doesn't support it in a bridge. If you use Apple Home, add it to the black list.`);
+            }
         }
         catch (error) {
             inspectError(this.log, `Failed to register device ${name}`, error);

package/npm-shrinkwrap.json

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

package/package.json

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