@homebridge-plugins/homebridge-matter 0.0.5 → 0.1.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to `@homebridge-plugins/homebridge-matter` will be documented in this file.
 
+## v0.1.0 (2025-10-20)
+
+### Changes
+
+- added plugin header image
+- update plugin repo meta files
+- added custom plugin ui
+- plugin code refactoring + more devices
+- add plugin workflows, including release workflows
+- Add Claude Code GitHub Workflow (#1)
+
+## v0.0.6 (2025-10-18)
+
+### Changes
+
+- allow configuration of examples to expose
+
 ## v0.0.5 (2025-10-18)
 
 ### Changes

package/README.md

@@ -1,52 +1,86 @@
 <p align="center">
+   <a href="https://github.com/homebridge-plugins/homebridge-matter"><img alt="Homebridge Verified" src="https://github.com/homebridge-plugins/homebridge-matter/blob/latest/plugin-header.png?raw=true" width="600px"></a>
+</p>
+<span align="center">
 
-<img src="https://github.com/homebridge/branding/raw/latest/logos/homebridge-wordmark-logo-vertical.png" width="150">
+# homebridge-matter
 
-</p>
+Homebridge plugin to showcase examples of Matter devices in Homebridge.
 
-<span align="center">
+[![npm](https://img.shields.io/npm/v/@homebridge-plugins/homebridge-matter/latest?label=latest)](https://www.npmjs.com/package/@homebridge-plugins/homebridge-matter)
+[![npm](https://img.shields.io/npm/v/@homebridge-plugins/homebridge-matter/beta?label=beta)](https://github.com/homebridge-plugins/homebridge-matter/wiki/Beta-Version)
+
+[![verified-by-homebridge](https://badgen.net/badge/homebridge/verified/purple)](https://github.com/homebridge/homebridge/wiki/Verified-Plugins)
 
-# Homebridge Matter
+[![npm](https://img.shields.io/npm/dt/@homebridge-plugins/homebridge-matter)](https://www.npmjs.com/package/@homebridge-plugins/homebridge-matter)
+[![Discord](https://img.shields.io/discord/432663330281226270?color=728ED5&logo=discord&label=hb-discord)](https://discord.com/channels/432663330281226270/742733745743855627)
 
 </span>
 
-### Customise Plugin
+### Plugin Information
+
+This plugin provides example implementations of Matter device types in Homebridge:
+
+- **21+ Matter Device Types**: Complete implementations across all major Matter device categories
+- **Demonstration & Testing**: Perfect for developers building Matter plugins or testing Matter integrations
+- **Example Code Reference**: Clean, documented examples showing how to implement Matter devices in Homebridge
+- **Apple Home Compatible**: Special support for devices like robotic vacuum cleaners that require dedicated bridges
+- **Production Ready**: Built on the official Matter specification with proper cluster implementations
+
+#### Supported Matter Device Types
+
+**Section 4: Lighting Devices** (Matter Spec § 4) - 5 devices
+- On/Off Light
+- Dimmable Light
+- Colour Temperature Light
+- Colour Light (HS)
+- Extended Colour Light (HS+CCT)
+
+**Section 5: Smart Plugs/Actuators** (Matter Spec § 5) - 2 devices
+- On/Off Outlet
+- Dimmable Outlet
+
+**Section 6: Switches & Controllers** (Matter Spec § 6) - 1 device
+- On/Off Light Switch
+
+**Section 7: Sensors** (Matter Spec § 7) - 7 devices
+- Contact Sensor
+- Light Sensor
+- Motion Sensor (Occupancy)
+- Temperature Sensor
+- Humidity Sensor
+- Smoke/CO Alarm
+- Water Leak Detector
 
-You can now start customising the plugin template to suit your requirements.
+**Section 8: Closure Devices** (Matter Spec § 8) - 3 devices
+- Door Lock
+- Window Blind
+- Venetian Blind (with Tilt)
 
-- [`src/platform.ts`](./src/platform.ts) - this is where your device setup and discovery should go.
-- [`src/platformAccessory.ts`](./src/platformAccessory.ts) - this is where your accessory control logic should go, you can rename or create multiple instances of this file for each accessory type you need to implement as part of your platform plugin. You can refer to the [developer documentation](https://developers.homebridge.io/) to see what characteristics you need to implement for each service type.
-- [`config.schema.json`](./config.schema.json) - update the config schema to match the config you expect from the user. See the [Plugin Config Schema Documentation](https://developers.homebridge.io/#/config-schema).
+**Section 9: HVAC** (Matter Spec § 9) - 2 devices
+- Thermostat
+- Fan
 
-### Matter State Management Guide
+**Section 12: Robotic Devices** (Matter Spec § 12) - 1 device
+- Robotic Vacuum Cleaner (published as an external accessory on a dedicated Matter bridge)
 
-**Important for Matter plugin developers:** Understanding how to manage accessory state is critical when working with Matter.
+### Prerequisites
 
-📖 **[Read the State Management Guide](./STATE_MANAGEMENT.md)** to learn:
+- To use this plugin, you will need to already have:
+  - [Node](https://nodejs.org): latest version of `v20`, `v22` or `v24` - any other major version is not supported.
+  - [Homebridge](https://homebridge.io): `>=2.0.0-alpha.55 <2.0.0-beta.0` - refer to link for more information and installation instructions.
 
-- **Handlers** (Home app → Device) - How to respond when users control devices via Home app
-- **State Updates** (Device → Home app) - How to sync state when devices change externally (native app, physical buttons, webhooks, etc.)
-- Complete working examples for outlets, lights, and sensors
-- Differences between Matter and HAP (HomeKit Accessory Protocol) patterns
+### Help/About
 
-**Quick Overview:**
+- [Support Request](https://github.com/homebridge-plugins/homebridge-matter/issues/new/choose)
+- [Changelog](https://github.com/homebridge-plugins/homebridge-matter/blob/latest/CHANGELOG.md)
+- [About Me](https://github.com/sponsors/bwp91)
 
-```typescript
-handlers: {
-  onOff: {
-    on: async () => {
-      await yourDeviceAPI.turnOn()
-    }
-  }
-}
+### Credits
 
-// Pattern 2: Device changes externally → Update Home app
-function handleExternalChange(newState: boolean) {
-  this.api.updateMatterAccessoryState('device-uuid', 'onOff', {
-    onOff: newState,
-  })
-}
-```
+- To the developers of [matter.js](https://github.com/matter-js/matter.js) who make the Matter integration possible.
 
-See [`STATE_MANAGEMENT.md`](./STATE_MANAGEMENT.md) for complete details and examples.
+### Disclaimer
 
+- I am in no way affiliated with Matter and this plugin is a personal project that I maintain in my free time.
+- Use this plugin entirely at your own risk - please see licence for more information.

package/config.schema.json

@@ -2,7 +2,10 @@
   "pluginAlias": "Matter",
   "pluginType": "platform",
   "singular": true,
-  "strictValidation": false,
+  "strictValidation": true,
+  "customUi": true,
+  "customUiPath": "./dist/homebridge-ui",
+  "headerDisplay": "<p align=\"center\"><img width=\"60%\" src=\"https://github.com/homebridge-plugins/homebridge-matter/blob/latest/plugin-header.png?raw=true\"></p><p align=\"center\">For help and support please visit our <a href=\"https://github.com/homebridge-plugins/homebridge-matter/wiki\">GitHub Wiki</a>. We hope you find this plugin useful!</p>",
   "schema": {
     "type": "object",
     "required": ["name"],
@@ -12,7 +15,224 @@
         "title": "Name",
         "type": "string",
         "default": "Homebridge Matter"
+      },
+      "enableOnOffLight": {
+        "title": "Enable On/Off Light",
+        "type": "boolean",
+        "default": false,
+        "description": "Enable the on/off light example accessory (Matter Spec § 4.1)."
+      },
+      "enableDimmableLight": {
+        "title": "Enable Dimmable Light",
+        "type": "boolean",
+        "default": false,
+        "description": "Enable the dimmable light example accessory (Matter Spec § 4.2)."
+      },
+      "enableColourTemperatureLight": {
+        "title": "Enable Colour Temperature Light",
+        "type": "boolean",
+        "default": false,
+        "description": "Enable the colour temperature light example accessory (Matter Spec § 4.3)."
+      },
+      "enableColourLight": {
+        "title": "Enable Colour Light (HS)",
+        "type": "boolean",
+        "default": false,
+        "description": "Enable the colour light (hue/saturation) example accessory (Matter Spec § 4.4)."
+      },
+      "enableExtendedColourLight": {
+        "title": "Enable Extended Colour Light (HS+CCT)",
+        "type": "boolean",
+        "default": false,
+        "description": "Enable the extended colour light (hue/saturation + colour temperature) example accessory (Matter Spec § 4.4)."
+      },
+      "enableOnOffOutlet": {
+        "title": "Enable On/Off Outlet",
+        "type": "boolean",
+        "default": false,
+        "description": "Enable the on/off outlet (smart plug) example accessory (Matter Spec § 5.1)."
+      },
+      "enableDimmableOutlet": {
+        "title": "Enable Dimmable Outlet",
+        "type": "boolean",
+        "default": false,
+        "description": "Enable the dimmable outlet example accessory (Matter Spec § 5.2)."
+      },
+      "enableOnOffSwitch": {
+        "title": "Enable On/Off Light Switch",
+        "type": "boolean",
+        "default": false,
+        "description": "Enable the on/off light switch example accessory (Matter Spec § 6.1)."
+      },
+      "enableContactSensor": {
+        "title": "Enable Contact Sensor",
+        "type": "boolean",
+        "default": false,
+        "description": "Enable the contact sensor example accessory (Matter Spec § 7.1)."
+      },
+      "enableLightSensor": {
+        "title": "Enable Light Sensor",
+        "type": "boolean",
+        "default": false,
+        "description": "Enable the light sensor example accessory (Matter Spec § 7.2)."
+      },
+      "enableMotionSensor": {
+        "title": "Enable Motion Sensor",
+        "type": "boolean",
+        "default": false,
+        "description": "Enable the motion sensor (occupancy sensor) example accessory (Matter Spec § 7.3)."
+      },
+      "enableTemperatureSensor": {
+        "title": "Enable Temperature Sensor",
+        "type": "boolean",
+        "default": false,
+        "description": "Enable the temperature sensor example accessory (Matter Spec § 7.4)."
+      },
+      "enableHumiditySensor": {
+        "title": "Enable Humidity Sensor",
+        "type": "boolean",
+        "default": false,
+        "description": "Enable the humidity sensor example accessory (Matter Spec § 7.7)."
+      },
+      "enableSmokeSensor": {
+        "title": "Enable Smoke/CO Alarm",
+        "type": "boolean",
+        "default": false,
+        "description": "Enable the smoke and carbon monoxide alarm example accessory (Matter Spec § 7.9)."
+      },
+      "enableLeakSensor": {
+        "title": "Enable Water Leak Detector",
+        "type": "boolean",
+        "default": false,
+        "description": "Enable the water leak detector example accessory (Matter Spec § 7.12)."
+      },
+      "enableDoorLock": {
+        "title": "Enable Door Lock",
+        "type": "boolean",
+        "default": false,
+        "description": "Enable the door lock example accessory (Matter Spec § 8.1)."
+      },
+      "enableWindowBlind": {
+        "title": "Enable Window Blind",
+        "type": "boolean",
+        "default": false,
+        "description": "Enable the window blind example accessory (Matter Spec § 8.3)."
+      },
+      "enableVenetianBlind": {
+        "title": "Enable Venetian Blind (Tilt)",
+        "type": "boolean",
+        "default": false,
+        "description": "Enable the Venetian blind with tilt control example accessory (Matter Spec § 8.3)."
+      },
+      "enableThermostat": {
+        "title": "Enable Thermostat",
+        "type": "boolean",
+        "default": false,
+        "description": "Enable the thermostat example accessory (Matter Spec § 9.1)."
+      },
+      "enableFan": {
+        "title": "Enable Fan",
+        "type": "boolean",
+        "default": false,
+        "description": "Enable the fan example accessory (Matter Spec § 9.2)."
+      },
+      "enableRobotVacuum": {
+        "title": "Enable Robotic Vacuum Cleaner (Apple Home Compatible)",
+        "type": "boolean",
+        "default": false,
+        "description": "✅ Enable the robotic vacuum cleaner example accessory (Matter Spec § 12.1). This device is automatically published on its own dedicated Matter bridge for Apple Home compatibility. You'll receive separate commissioning codes (QR code + manual code) for the robot vacuum."
       }
     }
-  }
+  },
+  "layout": [
+    {
+      "type": "fieldset",
+      "title": "Plugin Settings",
+      "items": ["name"]
+    },
+    {
+      "type": "fieldset",
+      "title": "Section 4: Lighting Devices",
+      "description": "Matter Specification § 4 - Fundamental lighting device types (5 devices implemented)",
+      "expandable": true,
+      "expanded": false,
+      "items": [
+        "enableOnOffLight",
+        "enableDimmableLight",
+        "enableColourTemperatureLight",
+        "enableColourLight",
+        "enableExtendedColourLight"
+      ]
+    },
+    {
+      "type": "fieldset",
+      "title": "Section 5: Smart Plugs/Actuators",
+      "description": "Matter Specification § 5 - Devices that control power and fluid flow (2 devices implemented)",
+      "expandable": true,
+      "expanded": false,
+      "items": [
+        "enableOnOffOutlet",
+        "enableDimmableOutlet"
+      ]
+    },
+    {
+      "type": "fieldset",
+      "title": "Section 6: Switches & Controllers",
+      "description": "Matter Specification § 6 - Input devices and control interfaces (1 device implemented)",
+      "expandable": true,
+      "expanded": false,
+      "items": [
+        "enableOnOffSwitch"
+      ]
+    },
+    {
+      "type": "fieldset",
+      "title": "Section 7: Sensors",
+      "description": "Matter Specification § 7 - All sensor types (7 devices implemented)",
+      "expandable": true,
+      "expanded": false,
+      "items": [
+        "enableContactSensor",
+        "enableLightSensor",
+        "enableMotionSensor",
+        "enableTemperatureSensor",
+        "enableHumiditySensor",
+        "enableSmokeSensor",
+        "enableLeakSensor"
+      ]
+    },
+    {
+      "type": "fieldset",
+      "title": "Section 8: Closure Devices",
+      "description": "Matter Specification § 8 - Locks and window coverings (3 devices implemented)",
+      "expandable": true,
+      "expanded": false,
+      "items": [
+        "enableDoorLock",
+        "enableWindowBlind",
+        "enableVenetianBlind"
+      ]
+    },
+    {
+      "type": "fieldset",
+      "title": "Section 9: HVAC",
+      "description": "Matter Specification § 9 - Heating, ventilation, and air conditioning (2 devices implemented)",
+      "expandable": true,
+      "expanded": false,
+      "items": [
+        "enableThermostat",
+        "enableFan"
+      ]
+    },
+    {
+      "type": "fieldset",
+      "title": "Section 12: Robotic Devices",
+      "description": "Matter Specification § 12 - Autonomous cleaning devices (1 device implemented)",
+      "expandable": true,
+      "expanded": false,
+      "items": [
+        "enableRobotVacuum"
+      ]
+    }
+  ]
 }

package/dist/devices/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Matter Device Implementations
+ *
+ * Organized by official Matter Specification v1.4.1 categories
+ */
+export * from './section-4-lighting/index.js';
+export * from './section-5-smart-plugs/index.js';
+export * from './section-6-switches/index.js';
+export * from './section-7-sensors/index.js';
+export * from './section-8-closure/index.js';
+export * from './section-9-hvac/index.js';
+export * from './section-12-robotic/index.js';
+export * from './types.js';

package/dist/devices/index.js

@@ -0,0 +1,22 @@
+/**
+ * Matter Device Implementations
+ *
+ * Organized by official Matter Specification v1.4.1 categories
+ */
+// Section 4: Lighting Devices
+export * from './section-4-lighting/index.js';
+// Section 5: Smart Plugs/Actuators
+export * from './section-5-smart-plugs/index.js';
+// Section 6: Switches & Controllers
+export * from './section-6-switches/index.js';
+// Section 7: Sensors
+export * from './section-7-sensors/index.js';
+// Section 8: Closure Devices
+export * from './section-8-closure/index.js';
+// Section 9: HVAC
+export * from './section-9-hvac/index.js';
+// Section 12: Robotic Devices
+export * from './section-12-robotic/index.js';
+// Common types
+export * from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/devices/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/devices/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,8BAA8B;AAC9B,cAAc,+BAA+B,CAAA;AAE7C,mCAAmC;AACnC,cAAc,kCAAkC,CAAA;AAEhD,oCAAoC;AACpC,cAAc,+BAA+B,CAAA;AAE7C,qBAAqB;AACrB,cAAc,8BAA8B,CAAA;AAE5C,6BAA6B;AAC7B,cAAc,8BAA8B,CAAA;AAE5C,kBAAkB;AAClB,cAAc,2BAA2B,CAAA;AAEzC,8BAA8B;AAC9B,cAAc,+BAA+B,CAAA;AAE7C,eAAe;AACf,cAAc,YAAY,CAAA"}

package/dist/devices/section-12-robotic/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Section 12: Robotic Devices
+ *
+ * Matter Specification § 12 - Autonomous cleaning devices
+ */
+export { registerRoboticVacuumCleaner } from './robotic-vacuum-cleaner.js';

package/dist/devices/section-12-robotic/index.js

@@ -0,0 +1,7 @@
+/**
+ * Section 12: Robotic Devices
+ *
+ * Matter Specification § 12 - Autonomous cleaning devices
+ */
+export { registerRoboticVacuumCleaner } from './robotic-vacuum-cleaner.js';
+//# sourceMappingURL=index.js.map

package/dist/devices/section-12-robotic/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/devices/section-12-robotic/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,4BAA4B,EAAE,MAAM,6BAA6B,CAAA"}

package/dist/devices/section-12-robotic/robotic-vacuum-cleaner.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Robotic Vacuum Cleaner Device (Matter Spec § 12.1)
+ *
+ * A robotic vacuum cleaner with autonomous cleaning capabilities.
+ *
+ * ✅ Apple Home Compatibility - EXTERNAL ACCESSORIES
+ * This device is published using api.matter.publishExternalAccessories() in platform.ts.
+ * RVC devices MUST be on their own dedicated Matter bridge for Apple Home compatibility.
+ *
+ * IMPORTANT: This function only CREATES the accessory configuration.
+ * The actual publishing happens in platform.ts using publishExternalAccessories().
+ *
+ * What happens when this device is published as external:
+ * ─────────────────────────────────────────────────────────────
+ * 1. Dedicated Matter Server: Gets its own MatterServer instance
+ * 2. Automatic Port Allocation: Receives a unique port (e.g., 5541)
+ * 3. Separate Commissioning: Gets its own QR code and manual pairing code
+ * 4. Isolation: Completely independent from other Matter accessories
+ * 5. Apple Home Compatible: Works properly with Apple Home's RVC requirements
+ *
+ * When you start Homebridge, you'll see logs like:
+ * ```
+ * [Matter] Publishing 1 external Matter accessory
+ * [Matter] Allocated port 5541 for external Matter accessory: Robot Vacuum
+ * [Matter] ✓ External Matter accessory published: Robot Vacuum on port 5541
+ * [Matter] 📱 Commissioning codes for Robot Vacuum:
+ * [Matter]    QR Code: MT:Y.K9042C00KA0648G00
+ * [Matter]    Manual Code: 3492-8840-7309-5200-911
+ * ```
+ *
+ * Use the separate QR code to commission this device in Apple Home.
+ *
+ * For developers implementing similar devices:
+ * ──────────────────────────────────────────────
+ * If you need to create your own device that requires isolation (like cameras,
+ * doorbells, or other complex devices that Apple Home requires on separate bridges),
+ * follow this pattern:
+ *
+ * 1. Create the accessory configuration in a device file (like this one)
+ * 2. Return it from your registration function
+ * 3. In platform.ts, use api.matter.publishExternalAccessories() instead of
+ *    api.matter.registerPlatformAccessories()
+ *
+ * Example in your platform.ts:
+ * ```typescript
+ * const accessories = [...registerYourDevice(context)]
+ * if (accessories.length > 0) {
+ *   // Use publishExternalAccessories for devices that need isolation
+ *   this.api.matter.publishExternalAccessories(PLUGIN_NAME, accessories)
+ * }
+ * ```
+ */
+import type { DeviceContext } from '../types.js';
+/**
+ * Registers a Robotic Vacuum Cleaner accessory.
+ *
+ * NOTE: This returns the accessory configuration but does NOT publish it.
+ * Publishing happens in platform.ts using api.matter.publishExternalAccessories().
+ *
+ * @param context - Device context containing API, logger, and config
+ * @returns Array of RVC accessory configurations (empty if disabled)
+ */
+export declare function registerRoboticVacuumCleaner(context: DeviceContext): any[];