@homebridge-plugins/homebridge-matter 0.1.4-beta.0 → 0.1.4

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to `@homebridge-plugins/homebridge-matter` will be documented in this file.
 
+## v0.1.4 (2025-10-23)
+
+### Changes
+
+- consolidate device code comments in docs
+- fix switch device implementation example
+
 ## v0.1.3 (2025-10-22)
 
 ### Changes

package/MATTER_API.md

@@ -13,7 +13,8 @@ This document serves as a comprehensive guide for integrating Matter devices int
 5. [Monitoring External Changes](#monitoring-external-changes)
 6. [Using Matter Types](#using-matter-types)
 7. [Best Practices](#best-practices)
-8. [Device Reference](#device-reference)
+8. [API Reference](#api-reference)
+9. [Device Reference](#device-reference)
 
 ---
 
@@ -172,46 +173,46 @@ handlers: {
 
 #### Level Control
 ```typescript
-MatterRequests.MoveToLevel          // { level, transitionTime?, optionsMask?, optionsOverride? }
-MatterRequests.Move                 // { moveMode, rate?, optionsMask?, optionsOverride? }
-MatterRequests.Step                 // { stepMode, stepSize, transitionTime?, ... }
-MatterRequests.Stop                 // { optionsMask?, optionsOverride? }
+MatterRequests.MoveToLevel // { level, transitionTime?, optionsMask?, optionsOverride? }
+MatterRequests.Move // { moveMode, rate?, optionsMask?, optionsOverride? }
+MatterRequests.Step // { stepMode, stepSize, transitionTime?, ... }
+MatterRequests.Stop // { optionsMask?, optionsOverride? }
 ```
 
 #### Color Control
 ```typescript
-MatterRequests.MoveToHue                    // { hue, direction, transitionTime?, ... }
-MatterRequests.MoveToSaturation             // { saturation, transitionTime?, ... }
-MatterRequests.MoveToHueAndSaturation       // { hue, saturation, transitionTime?, ... }
-MatterRequests.MoveToColorTemperature       // { colorTemperatureMireds, transitionTime?, ... }
-MatterRequests.MoveHue                      // { moveMode, rate?, ... }
-MatterRequests.MoveSaturation               // { moveMode, rate?, ... }
-MatterRequests.MoveColorTemperature         // { moveMode, rate?, ... }
-MatterRequests.StepHue                      // { stepMode, stepSize, transitionTime?, ... }
-MatterRequests.StepSaturation               // { stepMode, stepSize, transitionTime?, ... }
-MatterRequests.StepColorTemperature         // { stepMode, stepSize, transitionTime?, ... }
+MatterRequests.MoveToHue // { hue, direction, transitionTime?, ... }
+MatterRequests.MoveToSaturation // { saturation, transitionTime?, ... }
+MatterRequests.MoveToHueAndSaturation // { hue, saturation, transitionTime?, ... }
+MatterRequests.MoveToColorTemperature // { colorTemperatureMireds, transitionTime?, ... }
+MatterRequests.MoveHue // { moveMode, rate?, ... }
+MatterRequests.MoveSaturation // { moveMode, rate?, ... }
+MatterRequests.MoveColorTemperature // { moveMode, rate?, ... }
+MatterRequests.StepHue // { stepMode, stepSize, transitionTime?, ... }
+MatterRequests.StepSaturation // { stepMode, stepSize, transitionTime?, ... }
+MatterRequests.StepColorTemperature // { stepMode, stepSize, transitionTime?, ... }
 ```
 
 #### Door Lock
 ```typescript
-MatterRequests.LockDoor              // { pinCode? }
-MatterRequests.UnlockDoor            // { pinCode? }
+MatterRequests.LockDoor // { pinCode? }
+MatterRequests.UnlockDoor // { pinCode? }
 ```
 
 #### Window Covering
 ```typescript
-MatterRequests.GoToLiftPercentage    // { liftPercent100thsValue }
-MatterRequests.GoToTiltPercentage    // { tiltPercent100thsValue }
+MatterRequests.GoToLiftPercentage // { liftPercent100thsValue }
+MatterRequests.GoToTiltPercentage // { tiltPercent100thsValue }
 ```
 
 #### Thermostat
 ```typescript
-MatterRequests.SetpointRaiseLower    // { mode, amount }
+MatterRequests.SetpointRaiseLower // { mode, amount }
 ```
 
 #### Fan Control
 ```typescript
-MatterRequests.FanStep               // { direction, wrap?, lowestOff? }
+MatterRequests.FanStep // { direction, wrap?, lowestOff? }
 ```
 
 </details>
@@ -276,7 +277,7 @@ const accessory = {
 
   // These are CLUSTERS within the endpoint
   clusters: {
-    onOff: { onOff: false },           // OnOff cluster
+    onOff: { onOff: false }, // OnOff cluster
     levelControl: { currentLevel: 127 }, // LevelControl cluster
   },
 }
@@ -581,15 +582,15 @@ Access cluster attributes directly from the accessory object:
 
 ```typescript
 // Read power state
-const isOn = accessory.clusters.onOff.onOff  // boolean
+const isOn = accessory.clusters.onOff.onOff // boolean
 
 // Read brightness
-const level = accessory.clusters.levelControl.currentLevel  // 1-254
-const percent = Math.round((level / 254) * 100)  // Convert to percentage
+const level = accessory.clusters.levelControl.currentLevel // 1-254
+const percent = Math.round((level / 254) * 100) // Convert to percentage
 
 // Read color
-const hue = accessory.clusters.colorControl.currentHue  // 0-254
-const saturation = accessory.clusters.colorControl.currentSaturation  // 0-254
+const hue = accessory.clusters.colorControl.currentHue // 0-254
+const saturation = accessory.clusters.colorControl.currentSaturation // 0-254
 ```
 
 **When to use**: This is the recommended approach in most cases when you have a reference to the accessory object.
@@ -608,13 +609,13 @@ Use the API method when you don't have a reference to the accessory object:
 // Read state by UUID
 const state = api.matter.getAccessoryState(uuid, api.matter.clusterNames.OnOff)
 if (state) {
-  const isOn = state.onOff  // boolean
+  const isOn = state.onOff // boolean
 }
 
 // Read brightness
 const levelState = api.matter.getAccessoryState(uuid, api.matter.clusterNames.LevelControl)
 if (levelState) {
-  const level = levelState.currentLevel  // 1-254
+  const level = levelState.currentLevel // 1-254
 }
 ```
 
@@ -632,9 +633,9 @@ Use `updateAccessoryState()` to manually update cluster attributes:
 
 ```typescript
 api.matter.updateAccessoryState(
-  accessory.uuid,                      // UUID of the accessory
-  api.matter.clusterNames.OnOff,       // Cluster name (use constants!)
-  { onOff: true }                      // New attribute values
+  accessory.uuid, // UUID of the accessory
+  api.matter.clusterNames.OnOff, // Cluster name (use constants!)
+  { onOff: true } // New attribute values
 )
 ```
 
@@ -910,7 +911,7 @@ setInterval(async () => {
   } catch (error) {
     log.error(`Error polling device: ${error}`)
   }
-}, 5000)  // Poll every 5 seconds
+}, 5000) // Poll every 5 seconds
 ```
 
 ---
@@ -1099,123 +1100,478 @@ api.matter.updateAccessoryState(uuid, 'onOff', {...})
 
 ---
 
-## Device Reference
+## API Reference
 
-This section documents all available Matter device types with their clusters, attributes, handlers, and usage examples.
+Complete reference for all Matter API methods and properties available in Homebridge.
 
-### On/Off Light
+### Platform API Methods
 
-**Device Type**: `api.matter.deviceTypes.OnOffLight`
+#### `api.isMatterAvailable(): boolean`
 
-**Description**: A lighting device capable of being switched on or off.
+Check if Matter is available in the current version of Homebridge.
 
-**Matter Specification**: § 4.1
+**Returns:** `true` if Homebridge version is >= 2.0.0-alpha.0
 
-#### Required Clusters
+**Usage:**
+```typescript
+if (api.isMatterAvailable()) {
+  log.info('Matter is available in this Homebridge version')
+} else {
+  log.warn('Matter requires Homebridge >= 2.0.0-alpha.0')
+}
+```
 
-##### OnOff Cluster
+**When to use:**
+- Plugin compatibility checks
+- Conditional feature loading
+- Version-specific functionality
 
-Controls the power state of the light.
+---
 
-**Attributes**:
+#### `api.isMatterEnabled(): boolean`
 
-| Attribute | Type    | Range/Values    | Description                      |
-|-----------|---------|-----------------|----------------------------------|
-| `onOff`   | boolean | `true`, `false` | Power state (true=on, false=off) |
+Check if Matter is enabled for this bridge instance.
+
+**Returns:** `true` if Matter is enabled in the bridge configuration
 
-**Handlers**:
+**Configuration:**
+- For main bridge: Set `bridge.matter = true` in config.json
+- For child bridge: Set `_bridge.matter = true` in platform config
 
+**Usage:**
 ```typescript
-handlers: {
-  onOff: {
-    /**
-     * Called when user turns light ON via Home app
-     */
-    on: async () => {
-      // Control your physical device
-      await myLightAPI.turnOn()
-      // State automatically updated by Homebridge
-    },
+if (api.isMatterEnabled()) {
+  // Register Matter accessories
+  api.matter.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, accessories)
+} else {
+  log.info('Matter is not enabled for this bridge')
+}
+```
 
-    /**
-     * Called when user turns light OFF via Home app
-     */
-    off: async () => {
-      // Control your physical device
-      await myLightAPI.turnOff()
-      // State automatically updated by Homebridge
-    },
-  },
+**When to use:**
+- Runtime checks before registering Matter accessories
+- Conditional accessory registration
+- User feedback about Matter status
+
+---
+
+### Matter API Properties
+
+All properties are accessed via `api.matter.*`
+
+#### `api.matter.uuid`
+
+UUID generator for creating unique accessory identifiers (alias of `api.hap.uuid`).
+
+**Type:** `HAP['uuid']`
+
+**Methods:**
+- `generate(data: string): string` - Generate deterministic UUID from string
+- `isValid(uuid: string): boolean` - Validate UUID format
+
+**Usage:**
+```typescript
+const uuid = api.matter.uuid.generate('my-light-123')
+// Output: 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
+
+if (api.matter.uuid.isValid(uuid)) {
+  // UUID is valid
 }
 ```
 
-#### Optional Clusters
+**Important:**
+- UUIDs must be deterministic (same input = same output)
+- Use unique identifiers (device ID, MAC address, etc.)
+- UUIDs persist across restarts for state restoration
+
+---
+
+#### `api.matter.deviceTypes`
+
+Available Matter device types for creating accessories.
 
-- **LevelControl**: Adds brightness control (see Dimmable Light)
-- **ScenesManagement**: Enables scene support
-- **Groups**: Enables grouping with other devices
-- **OccupancySensing**: Can respond to occupancy sensors
+**Type:** `typeof deviceTypes` (from Matter.js)
 
-#### Complete Example
+**Common Device Types:**
+- Lighting: `OnOffLight`, `DimmableLight`, `ColorTemperatureLight`, `ExtendedColorLight`
+- Switches & Outlets: `OnOffSwitch`, `OnOffOutlet`, `DimmableOutlet`
+- Sensors: `ContactSensor`, `TemperatureSensor`, `HumiditySensor`, `OccupancySensor`, etc.
+- HVAC: `Thermostat`, `Fan`
+- Closure: `DoorLock`, `WindowCovering`
+- Robotic: `RoboticVacuumCleaner`
 
+**Usage:**
 ```typescript
 const accessory = {
-  uuid: api.matter.uuid.generate('onoff-light-001'),
-  displayName: 'On/Off Light',
-  deviceType: api.matter.deviceTypes.OnOffLight,
-  serialNumber: 'LIGHT-001',
-  manufacturer: 'My Company',
-  model: 'OnOffLight v1',
+  uuid: api.matter.uuid.generate('my-light'),
+  displayName: 'Living Room Light',
+  deviceType: api.matter.deviceTypes.DimmableLight,
+  // ...
+}
+```
 
-  clusters: {
-    onOff: {
-      onOff: false,  // Initial state: off
-    },
-  },
+**See:** [Available Device Types](#available-device-types) for complete list
 
-  handlers: {
-    onOff: {
-      on: async () => {
-        log.info('[Light] Turning ON')
-        await myLightAPI.turnOn()
-      },
-      off: async () => {
-        log.info('[Light] Turning OFF')
-        await myLightAPI.turnOff()
-      },
-    },
-  },
+---
+
+#### `api.matter.clusters`
+
+Direct access to Matter.js cluster definitions for advanced use cases.
+
+**Type:** `typeof clusters` (from Matter.js)
+
+**Usage:**
+```typescript
+// Access cluster attributes programmatically
+const onOffAttrs = api.matter.clusters.OnOffCluster.attributes
+console.log(Object.keys(onOffAttrs))
+// Output: ['onOff', 'clusterRevision', 'featureMap', ...]
+
+// Check if cluster supports specific features
+const levelControlFeatures = api.matter.clusters.LevelControlCluster.features
+```
+
+**When to use:**
+- Advanced cluster introspection
+- Dynamic attribute discovery
+- Custom cluster implementations
+
+**Note:** Most plugins should use the higher-level APIs instead.
+
+---
+
+#### `api.matter.clusterNames`
+
+Cluster name constants for type safety and autocomplete with state methods.
+
+**Type:** `typeof clusterNames`
+
+**Available Names:**
+- `OnOff`, `LevelControl`, `ColorControl`
+- `DoorLock`, `WindowCovering`
+- `Thermostat`, `FanControl`
+- `TemperatureMeasurement`, `RelativeHumidityMeasurement`
+- And many more...
+
+**Usage:**
+```typescript
+// Type-safe cluster references
+api.matter.updateAccessoryState(
+  uuid,
+  api.matter.clusterNames.OnOff, // Autocomplete available!
+  { onOff: true }
+)
+
+const state = api.matter.getAccessoryState(
+  uuid,
+  api.matter.clusterNames.LevelControl
+)
+```
+
+**Benefits:**
+- Autocomplete in IDEs
+- Compile-time error checking
+- Prevents typos in cluster names
+
+---
+
+#### `api.matter.types`
+
+Type-safe enum values for cluster attributes (modes, states, etc.).
+
+**Type:** `typeof MatterTypes` (from Homebridge)
+
+**Common Types:**
+- `DoorLock.LockState` - Lock states (Locked, Unlocked, etc.)
+- `DoorLock.LockType` - Lock types (DeadBolt, Magnetic, etc.)
+- `FanControl.FanMode` - Fan modes (Off, Low, Medium, High, Auto, etc.)
+- `FanControl.FanModeSequence` - Supported mode sequences
+- `Thermostat.SystemMode` - HVAC modes (Off, Heat, Cool, Auto, etc.)
+- `ColorControl.ColorMode` - Color modes (HS, XY, ColorTemperature)
+- `RvcRunMode.ModeTag` - Vacuum run mode tags (Idle, Cleaning, Mapping)
+- `RvcCleanMode.ModeTag` - Vacuum clean mode tags (Vacuum, Mop)
+- `RvcOperationalState.OperationalState` - Vacuum states (Stopped, Running, Docked, etc.)
+
+**Usage:**
+```typescript
+// Door lock states
+clusters: {
+  doorLock: {
+    lockState: api.matter.types.DoorLock.LockState.Unlocked,
+    lockType: api.matter.types.DoorLock.LockType.DeadBolt
+  }
 }
 
-// Monitor external changes (Flow B)
-mqttClient.on('message', (topic, message) => {
-  const { state } = JSON.parse(message.toString())
-  const deviceIsOn = state === 'ON'
+// Fan modes
+clusters: {
+  fanControl: {
+    fanMode: api.matter.types.FanControl.FanMode.Auto,
+    fanModeSequence: api.matter.types.FanControl.FanModeSequence.OffLowMedHigh
+  }
+}
 
-  if (deviceIsOn !== accessory.clusters.onOff.onOff) {
-    api.matter.updateAccessoryState(
-      accessory.uuid,
-      api.matter.clusterNames.OnOff,
-      { onOff: deviceIsOn }
-    )
+// Color modes
+clusters: {
+  colorControl: {
+    colorMode: api.matter.types.ColorControl.ColorMode.ColorTemperatureMireds
   }
-})
+}
 ```
 
-#### Cluster Reference
+**Benefits:**
+- Type safety prevents invalid values
+- IDE autocomplete shows available options
+- Self-documenting code
+- Compile-time validation
+
+**See:** [Using Matter Types](#using-matter-types) for detailed examples
+
+---
+
+### Matter API Methods
+
+#### `api.matter.registerPlatformAccessories()`
 
-Access cluster attributes programmatically:
+Register Matter accessories with the platform (standard registration method).
 
+**Signature:**
 ```typescript
-// Reading state
-const isOn = accessory.clusters.onOff.onOff
+registerPlatformAccessories(
+  pluginIdentifier: string,
+  platformName: string,
+  accessories: MatterAccessory[]
+): void
+```
 
-// All OnOff cluster attributes via api.matter
-const onOffAttrs = api.matter.clusters.OnOffCluster.attributes
-console.log(Object.keys(onOffAttrs))
-// Output: ['onOff', 'clusterRevision', 'featureMap', ...]
+**Parameters:**
+- `pluginIdentifier` - Plugin identifier (e.g., `'homebridge-example'`)
+- `platformName` - Platform name (e.g., `'ExamplePlatform'`)
+- `accessories` - Array of Matter accessories to register
+
+**Usage:**
+```typescript
+const PLUGIN_NAME = 'homebridge-example'
+const PLATFORM_NAME = 'ExamplePlatform'
+
+const accessories = [
+  {
+    uuid: api.matter.uuid.generate('my-light'),
+    displayName: 'Living Room Light',
+    deviceType: api.matter.deviceTypes.OnOffLight,
+    // ...
+  }
+]
+
+api.matter.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, accessories)
+```
+
+**When to use:**
+- Standard accessory registration
+- Multiple accessories on shared bridge
+- Most common use case
+
+**See also:** `publishExternalAccessories()` for isolated accessories
+
+---
+
+#### `api.matter.unregisterPlatformAccessories()`
+
+Unregister Matter accessories by UUID.
+
+**Signature:**
+```typescript
+unregisterPlatformAccessories(
+  pluginIdentifier: string,
+  platformName: string,
+  accessories: MatterAccessory[]
+): void
+```
+
+**Parameters:**
+- `pluginIdentifier` - Plugin identifier
+- `platformName` - Platform name
+- `accessories` - Array of accessories to unregister (only `uuid` is required)
+
+**Usage:**
+```typescript
+// Unregister accessories
+const accessoriesToRemove = [
+  { uuid: 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' }
+]
+
+api.matter.unregisterPlatformAccessories(
+  PLUGIN_NAME,
+  PLATFORM_NAME,
+  accessoriesToRemove
+)
+```
+
+**When to use:**
+- Removing accessories from Homebridge
+- Cleanup during plugin shutdown
+- User-initiated accessory removal
+
+---
+
+#### `api.matter.publishExternalAccessories()`
+
+Publish accessories on dedicated Matter bridges (isolated from other accessories).
+
+**Signature:**
+```typescript
+publishExternalAccessories(
+  pluginIdentifier: string,
+  accessories: MatterAccessory[]
+): void
+```
+
+**Parameters:**
+- `pluginIdentifier` - Plugin identifier
+- `accessories` - Array of accessories to publish externally
+
+**Usage:**
+```typescript
+const accessories = [
+  {
+    uuid: api.matter.uuid.generate('robot-vacuum'),
+    displayName: 'Robot Vacuum',
+    deviceType: api.matter.deviceTypes.RoboticVacuumCleaner,
+    // ...
+  }
+]
+
+// Publish on dedicated bridge
+api.matter.publishExternalAccessories(PLUGIN_NAME, accessories)
+```
+
+**When to use:**
+- Robotic Vacuum Cleaners (required by Apple Home)
+- Cameras and video doorbells
+- Devices requiring isolation
+- Testing single accessories
+
+**Behavior:**
+- Each accessory gets its own Matter server instance
+- Separate port allocation (e.g., 5541, 5542, etc.)
+- Independent QR codes for commissioning
+- Complete isolation from other accessories
+
+**Similar to:** HAP's `api.publishExternalAccessories()`
+
+---
+
+#### `api.matter.updateAccessoryState()`
+
+Update accessory cluster state when device changes externally (Flow B).
+
+**Signature:**
+```typescript
+updateAccessoryState(
+  uuid: string,
+  cluster: string,
+  attributes: Record<string, any>
+): void
+```
+
+**Parameters:**
+- `uuid` - Accessory UUID
+- `cluster` - Cluster name (use `api.matter.clusterNames.*`)
+- `attributes` - Attributes to update (key-value pairs)
+
+**Usage:**
+```typescript
+// Device turned on via native app
+api.matter.updateAccessoryState(
+  uuid,
+  api.matter.clusterNames.OnOff,
+  { onOff: true }
+)
+
+// Brightness changed via physical button
+api.matter.updateAccessoryState(
+  uuid,
+  api.matter.clusterNames.LevelControl,
+  { currentLevel: 200 }
+)
+
+// Update multiple attributes at once
+api.matter.updateAccessoryState(
+  uuid,
+  api.matter.clusterNames.ColorControl,
+  {
+    colorMode: api.matter.types.ColorControl.ColorMode.ColorTemperatureMireds,
+    colorTemperatureMireds: 250
+  }
+)
+```
+
+**IMPORTANT:**
+- ❌ **DO NOT** use inside handlers (state updates automatically)
+- ✅ **DO** use for external changes (webhooks, polling, events)
+
+**When to use:**
+- Native app controls
+- Physical button presses
+- Webhook notifications
+- Polling results
+- MQTT/WebSocket messages
+
+**See:** [Flow B: Physical Device → Home App](#flow-b-physical-device--home-app-manual)
+
+---
+
+#### `api.matter.getAccessoryState()`
+
+Get current cluster state from a Matter accessory.
+
+**Signature:**
+```typescript
+getAccessoryState(
+  uuid: string,
+  cluster: string
+): Record<string, any> | undefined
+```
+
+**Parameters:**
+- `uuid` - Accessory UUID
+- `cluster` - Cluster name (use `api.matter.clusterNames.*`)
+
+**Returns:**
+- Object with current attribute values, or `undefined` if not found
+
+**Usage:**
+```typescript
+// Read OnOff state
+const state = api.matter.getAccessoryState(uuid, api.matter.clusterNames.OnOff)
+if (state?.onOff) {
+  log.info('Light is currently on')
+}
+
+// Read level control state
+const levelState = api.matter.getAccessoryState(
+  uuid,
+  api.matter.clusterNames.LevelControl
+)
+log.info(`Current brightness: ${levelState?.currentLevel}`)
+
+// Check color mode
+const colorState = api.matter.getAccessoryState(
+  uuid,
+  api.matter.clusterNames.ColorControl
+)
+if (colorState?.colorMode === api.matter.types.ColorControl.ColorMode.ColorTemperatureMireds) {
+  log.info(`Color temp: ${colorState.colorTemperatureMireds} mireds`)
+}
 ```
 
+**When to use:**
+- Reading state after plugin restart
+- Verifying current state before changes
+- Debugging and logging
+- Conditional logic based on state
+
+**Note:** State is persisted across restarts automatically.
+
 ---
 
 ## Additional Resources
@@ -1304,3 +1660,544 @@ const matterTemp = Math.round(celsius * 100)
 // From Matter
 const celsius = matterTemp / 100
 ```
+
+---
+
+## Device Reference
+
+This section documents all available Matter device types with their clusters, attributes, handlers, and usage examples.
+
+### On/Off Light
+
+| Property                 | Value                                                  |
+|--------------------------|--------------------------------------------------------|
+| **Device Type**          | `api.matter.deviceTypes.OnOffLight`                    |
+| **Description**          | A lighting device capable of being switched on or off. |
+| **Matter Specification** | § 4.1                                                  |
+
+#### Required Clusters
+
+###### `OnOff` Cluster
+
+Controls the power state of the light.
+
+**Attributes**:
+
+```typescript
+// All OnOff cluster attributes via api.matter
+const onOffAttrs = api.matter.clusters.OnOffCluster.attributes
+console.log(Object.keys(onOffAttrs))
+// Output: ['onOff', 'clusterRevision', 'featureMap', ...]
+```
+
+| Attribute | Type    | Range/Values    | Description                      |
+|-----------|---------|-----------------|----------------------------------|
+| `onOff`   | boolean | `true`, `false` | Power state (true=on, false=off) |
+
+**Reading State**:
+
+```typescript
+const isOn = accessory.clusters.onOff.onOff
+```
+
+<details>
+<summary><strong>Handlers</strong></summary>
+
+```typescript
+handlers: {
+  onOff: {
+    /**
+     * Called when user turns light ON via Home app
+     */
+    on: async () => {
+      // Control your physical device
+      await myLightAPI.turnOn()
+      // State automatically updated by Homebridge
+    },
+
+    /**
+     * Called when user turns light OFF via Home app
+     */
+    off: async () => {
+      // Control your physical device
+      await myLightAPI.turnOff()
+      // State automatically updated by Homebridge
+    },
+  },
+}
+```
+
+</details>
+
+### Dimmable Light
+
+| Property                 | Value                                                  |
+|--------------------------|--------------------------------------------------------|
+| **Device Type**          | `api.matter.deviceTypes.DimmableLight`                 |
+| **Description**          | A lighting device with on/off and brightness control.  |
+| **Matter Specification** | § 4.2                                                  |
+
+#### Required Clusters
+
+###### `OnOff` Cluster
+
+Controls the power state of the light.
+
+**Attributes**:
+
+| Attribute | Type    | Range/Values    | Description                      |
+|-----------|---------|-----------------|----------------------------------|
+| `onOff`   | boolean | `true`, `false` | Power state (true=on, false=off) |
+
+**Reading State**:
+
+```typescript
+const isOn = accessory.clusters.onOff.onOff
+```
+
+###### `LevelControl` Cluster
+
+Controls the brightness level of the light.
+
+**Attributes**:
+
+```typescript
+// All LevelControl cluster attributes via api.matter
+const levelAttrs = api.matter.clusters.LevelControlCluster.attributes
+console.log(Object.keys(levelAttrs))
+// Output: ['currentLevel', 'minLevel', 'maxLevel', 'onLevel', 'options', ...]
+```
+
+| Attribute      | Type   | Range/Values | Description                                      |
+|----------------|--------|--------------|--------------------------------------------------|
+| `currentLevel` | number | 1-254        | Current brightness (1 = 0.4%, 254 = 100%)        |
+| `minLevel`     | number | 1-254        | Minimum brightness level                         |
+| `maxLevel`     | number | 1-254        | Maximum brightness level                         |
+| `onLevel`      | number | 0-254        | Brightness when turned on (0 = restore previous) |
+
+**Reading State**:
+
+```typescript
+const level = accessory.clusters.levelControl.currentLevel
+const brightnessPercent = Math.round((level / 254) * 100)
+```
+
+<details>
+<summary><strong>Handlers</strong></summary>
+
+```typescript
+handlers: {
+  onOff: {
+    on: async () => {
+      log.info('[Dimmable Light] Turning ON')
+      await myLightAPI.turnOn()
+    },
+
+    off: async () => {
+      log.info('[Dimmable Light] Turning OFF')
+      await myLightAPI.turnOff()
+    },
+  },
+
+  levelControl: {
+    /**
+     * Called when user adjusts brightness via Home app
+     * Also called when turning on with specific brightness
+     */
+    moveToLevelWithOnOff: async (request: MatterRequests.MoveToLevel) => {
+      const { level, transitionTime } = request
+      const brightnessPercent = Math.round((level / 254) * 100)
+
+      log.info(`[Dimmable Light] Setting brightness to ${brightnessPercent}%`)
+      await myLightAPI.setBrightness(brightnessPercent, transitionTime)
+    },
+  },
+}
+```
+
+</details>
+
+---
+
+### Color Temperature Light
+
+| Property                 | Value                                                                     |
+|--------------------------|---------------------------------------------------------------------------|
+| **Device Type**          | `api.matter.deviceTypes.ColorTemperatureLight`                            |
+| **Description**          | A lighting device with on/off, brightness, and color temperature control. |
+| **Matter Specification** | § 4.3                                                                     |
+
+#### Required Clusters
+
+###### `OnOff` Cluster
+
+Controls the power state of the light.
+
+**Attributes**:
+
+| Attribute | Type    | Range/Values    | Description                      |
+|-----------|---------|-----------------|----------------------------------|
+| `onOff`   | boolean | `true`, `false` | Power state (true=on, false=off) |
+
+###### `LevelControl` Cluster
+
+Controls the brightness level of the light.
+
+**Attributes**:
+
+| Attribute      | Type   | Range/Values | Description                                      |
+|----------------|--------|--------------|--------------------------------------------------|
+| `currentLevel` | number | 1-254        | Current brightness (1 = 0.4%, 254 = 100%)        |
+| `minLevel`     | number | 1-254        | Minimum brightness level                         |
+| `maxLevel`     | number | 1-254        | Maximum brightness level                         |
+
+###### `ColorControl` Cluster
+
+Controls the color temperature of the light.
+
+**Attributes**:
+
+```typescript
+// All ColorControl cluster attributes via api.matter
+const colorAttrs = api.matter.clusters.ColorControlCluster.attributes
+console.log(Object.keys(colorAttrs))
+```
+
+| Attribute                       | Type   | Range/Values | Description                                           |
+|---------------------------------|--------|--------------|-------------------------------------------------------|
+| `colorMode`                     | number | 0-2          | Current color mode (2 = Color Temperature)            |
+| `colorTemperatureMireds`        | number | 147-454      | Color temp in mireds (reciprocal megakelvin)          |
+| `colorTempPhysicalMinMireds`    | number | 147-500      | Coolest temperature supported (e.g., 147 = ~6800K)    |
+| `colorTempPhysicalMaxMireds`    | number | 147-500      | Warmest temperature supported (e.g., 454 = ~2200K)    |
+
+**Reading State**:
+
+```typescript
+const mireds = accessory.clusters.colorControl.colorTemperatureMireds
+const kelvin = Math.round(1000000 / mireds)
+```
+
+**Value Conversions**:
+
+```typescript
+// Kelvin to Mireds
+const mireds = Math.round(1000000 / kelvin)
+
+// Mireds to Kelvin
+const kelvin = Math.round(1000000 / mireds)
+```
+
+<details>
+<summary><strong>Handlers</strong></summary>
+
+```typescript
+handlers: {
+  onOff: {
+    on: async () => {
+      log.info('[CCT Light] Turning ON')
+      await myLightAPI.turnOn()
+    },
+
+    off: async () => {
+      log.info('[CCT Light] Turning OFF')
+      await myLightAPI.turnOff()
+    },
+  },
+
+  levelControl: {
+    moveToLevelWithOnOff: async (request: MatterRequests.MoveToLevel) => {
+      const { level } = request
+      const brightnessPercent = Math.round((level / 254) * 100)
+
+      log.info(`[CCT Light] Setting brightness to ${brightnessPercent}%`)
+      await myLightAPI.setBrightness(brightnessPercent)
+    },
+  },
+
+  colorControl: {
+    /**
+     * Called when user adjusts color temperature via Home app
+     */
+    moveToColorTemperatureLogic: async (request: { targetMireds: number, transitionTime: number }) => {
+      const { targetMireds, transitionTime } = request
+      const kelvin = Math.round(1000000 / targetMireds)
+
+      log.info(`[CCT Light] Setting color temp to ${kelvin}K (${targetMireds} mireds)`)
+      await myLightAPI.setColorTemperature(kelvin, transitionTime)
+    },
+  },
+}
+```
+
+</details>
+
+---
+
+### Color Light
+
+| Property                 | Value                                                                          |
+|--------------------------|--------------------------------------------------------------------------------|
+| **Device Type**          | `api.matter.deviceTypes.ExtendedColorLight`                                    |
+| **Description**          | A lighting device with on/off, brightness, and color (Hue/Saturation) control. |
+| **Matter Specification** | § 4.4                                                                          |
+
+#### Required Clusters
+
+###### `OnOff` Cluster
+
+Controls the power state of the light.
+
+**Attributes**:
+
+| Attribute | Type    | Range/Values    | Description                      |
+|-----------|---------|-----------------|----------------------------------|
+| `onOff`   | boolean | `true`, `false` | Power state (true=on, false=off) |
+
+###### `LevelControl` Cluster
+
+Controls the brightness level of the light.
+
+**Attributes**:
+
+| Attribute      | Type   | Range/Values | Description                                      |
+|----------------|--------|--------------|--------------------------------------------------|
+| `currentLevel` | number | 1-254        | Current brightness (1 = 0.4%, 254 = 100%)        |
+| `minLevel`     | number | 1-254        | Minimum brightness level                         |
+| `maxLevel`     | number | 1-254        | Maximum brightness level                         |
+
+###### `ColorControl` Cluster
+
+Controls the color (Hue/Saturation or XY) of the light.
+
+**Attributes**:
+
+| Attribute          | Type   | Range/Values | Description                                           |
+|--------------------|--------|--------------|-------------------------------------------------------|
+| `colorMode`        | number | 0-2          | Current color mode (0 = HS, 1 = XY)                   |
+| `currentHue`       | number | 0-254        | Current hue (maps to 0-360 degrees)                   |
+| `currentSaturation`| number | 0-254        | Current saturation (maps to 0-100%)                   |
+| `currentX`         | number | 0-65535      | CIE 1931 x coordinate                                 |
+| `currentY`         | number | 0-65535      | CIE 1931 y coordinate                                 |
+
+**Reading State**:
+
+```typescript
+const hue = accessory.clusters.colorControl.currentHue
+const saturation = accessory.clusters.colorControl.currentSaturation
+
+// Convert to degrees/percentage
+const hueDegrees = Math.round((hue / 254) * 360)
+const saturationPercent = Math.round((saturation / 254) * 100)
+```
+
+**Value Conversions**:
+
+```typescript
+// Hue: Degrees (0-360) to Matter (0-254)
+const matterHue = Math.round((degrees / 360) * 254)
+const degrees = Math.round((matterHue / 254) * 360)
+
+// Saturation: Percent (0-100) to Matter (0-254)
+const matterSat = Math.round((percent / 100) * 254)
+const percent = Math.round((matterSat / 254) * 100)
+
+// XY: Float (0.0-1.0) to Matter (0-65535)
+const matterX = Math.round(floatX * 65535)
+const floatX = matterX / 65535
+```
+
+<details>
+<summary><strong>Handlers</strong></summary>
+
+```typescript
+handlers: {
+  onOff: {
+    on: async () => {
+      log.info('[Color Light] Turning ON')
+      await myLightAPI.turnOn()
+    },
+
+    off: async () => {
+      log.info('[Color Light] Turning OFF')
+      await myLightAPI.turnOff()
+    },
+  },
+
+  levelControl: {
+    moveToLevelWithOnOff: async (request: MatterRequests.MoveToLevel) => {
+      const { level } = request
+      const brightnessPercent = Math.round((level / 254) * 100)
+
+      log.info(`[Color Light] Setting brightness to ${brightnessPercent}%`)
+      await myLightAPI.setBrightness(brightnessPercent)
+    },
+  },
+
+  colorControl: {
+    /**
+     * Called when user adjusts color via XY coordinates in Home app
+     */
+    moveToColorLogic: async (request: { targetX: number, targetY: number, transitionTime: number }) => {
+      const { targetX, targetY, transitionTime } = request
+      const xFloat = (targetX / 65535).toFixed(4)
+      const yFloat = (targetY / 65535).toFixed(4)
+
+      log.info(`[Color Light] Setting XY color to (${xFloat}, ${yFloat})`)
+      await myLightAPI.setColorXY(xFloat, yFloat, transitionTime)
+    },
+
+    /**
+     * Called when user adjusts color via Hue/Saturation in Home app
+     */
+    moveToHueAndSaturationLogic: async (request: { targetHue: number, targetSaturation: number, transitionTime: number }) => {
+      const { targetHue, targetSaturation, transitionTime } = request
+      const hueDegrees = Math.round((targetHue / 254) * 360)
+      const saturationPercent = Math.round((targetSaturation / 254) * 100)
+
+      log.info(`[Color Light] Setting color to ${hueDegrees}°, ${saturationPercent}%`)
+      await myLightAPI.setColorHS(hueDegrees, saturationPercent, transitionTime)
+    },
+  },
+}
+```
+
+</details>
+
+---
+
+### Extended Color Light
+
+| Property                 | Value                                                                                             |
+|--------------------------|---------------------------------------------------------------------------------------------------|
+| **Device Type**          | `api.matter.deviceTypes.ExtendedColorLight`                                                       |
+| **Description**          | A lighting device with on/off, brightness, color (Hue/Saturation), and color temperature control. |
+| **Matter Specification** | § 4.4                                                                                             |
+
+#### Required Clusters
+
+###### `OnOff` Cluster
+
+Controls the power state of the light.
+
+**Attributes**:
+
+| Attribute | Type    | Range/Values    | Description                      |
+|-----------|---------|-----------------|----------------------------------|
+| `onOff`   | boolean | `true`, `false` | Power state (true=on, false=off) |
+
+###### `LevelControl` Cluster
+
+Controls the brightness level of the light.
+
+**Attributes**:
+
+| Attribute      | Type   | Range/Values | Description                                      |
+|----------------|--------|--------------|--------------------------------------------------|
+| `currentLevel` | number | 1-254        | Current brightness (1 = 0.4%, 254 = 100%)        |
+| `minLevel`     | number | 1-254        | Minimum brightness level                         |
+| `maxLevel`     | number | 1-254        | Maximum brightness level                         |
+
+###### `ColorControl` Cluster
+
+Controls both color (Hue/Saturation or XY) and color temperature of the light.
+
+When updating state for Extended Color Light (Flow B), always update the `colorMode` attribute along with the color/temperature values to indicate which mode is active.
+
+**Attributes**:
+
+| Attribute                       | Type   | Range/Values | Description                                           |
+|---------------------------------|--------|--------------|-------------------------------------------------------|
+| `colorMode`                     | number | 0-2          | Current color mode (0 = HS, 1 = XY, 2 = ColorTemp)    |
+| `currentHue`                    | number | 0-254        | Current hue (maps to 0-360 degrees)                   |
+| `currentSaturation`             | number | 0-254        | Current saturation (maps to 0-100%)                   |
+| `currentX`                      | number | 0-65535      | CIE 1931 x coordinate                                 |
+| `currentY`                      | number | 0-65535      | CIE 1931 y coordinate                                 |
+| `colorTemperatureMireds`        | number | 147-454      | Color temp in mireds (when in ColorTemp mode)         |
+| `colorTempPhysicalMinMireds`    | number | 147-500      | Coolest temperature supported                         |
+| `colorTempPhysicalMaxMireds`    | number | 147-500      | Warmest temperature supported                         |
+
+**Reading State**:
+
+```typescript
+// Check current mode
+const mode = accessory.clusters.colorControl.colorMode
+const ColorMode = api.matter.types.ColorControl.ColorMode
+
+if (mode === ColorMode.CurrentHueAndCurrentSaturation || mode === ColorMode.CurrentXAndCurrentY) {
+  // Light is in color mode
+  const hue = accessory.clusters.colorControl.currentHue
+  const sat = accessory.clusters.colorControl.currentSaturation
+} else if (mode === ColorMode.ColorTemperatureMireds) {
+  // Light is in white/CCT mode
+  const mireds = accessory.clusters.colorControl.colorTemperatureMireds
+  const kelvin = Math.round(1000000 / mireds)
+}
+```
+
+<details>
+<summary><strong>Handlers</strong></summary>
+
+```typescript
+handlers: {
+  onOff: {
+    on: async () => {
+      log.info('[Extended Color Light] Turning ON')
+      await myLightAPI.turnOn()
+    },
+
+    off: async () => {
+      log.info('[Extended Color Light] Turning OFF')
+      await myLightAPI.turnOff()
+    },
+  },
+
+  levelControl: {
+    moveToLevelWithOnOff: async (request: MatterRequests.MoveToLevel) => {
+      const { level } = request
+      const brightnessPercent = Math.round((level / 254) * 100)
+
+      log.info(`[Extended Color Light] Setting brightness to ${brightnessPercent}%`)
+      await myLightAPI.setBrightness(brightnessPercent)
+    },
+  },
+
+  colorControl: {
+    /**
+     * Called when user adjusts color via XY coordinates in Home app
+     */
+    moveToColorLogic: async (request: { targetX: number, targetY: number, transitionTime: number }) => {
+      const { targetX, targetY, transitionTime } = request
+      const xFloat = (targetX / 65535).toFixed(4)
+      const yFloat = (targetY / 65535).toFixed(4)
+
+      log.info(`[Extended Color Light] Setting XY color to (${xFloat}, ${yFloat})`)
+      await myLightAPI.setColorXY(xFloat, yFloat, transitionTime)
+    },
+
+    /**
+     * Called when user adjusts color via Hue/Saturation in Home app
+     */
+    moveToHueAndSaturationLogic: async (request: { targetHue: number, targetSaturation: number, transitionTime: number }) => {
+      const { targetHue, targetSaturation, transitionTime } = request
+      const hueDegrees = Math.round((targetHue / 254) * 360)
+      const saturationPercent = Math.round((targetSaturation / 254) * 100)
+
+      log.info(`[Extended Color Light] Setting color to ${hueDegrees}°, ${saturationPercent}%`)
+      await myLightAPI.setColorHS(hueDegrees, saturationPercent, transitionTime)
+    },
+
+    /**
+     * Called when user adjusts color temperature via Home app
+     */
+    moveToColorTemperatureLogic: async (request: { targetMireds: number, transitionTime: number }) => {
+      const { targetMireds, transitionTime } = request
+      const kelvin = Math.round(1000000 / targetMireds)
+
+      log.info(`[Extended Color Light] Setting color temp to ${kelvin}K (${targetMireds} mireds)`)
+      await myLightAPI.setColorTemperature(kelvin, transitionTime)
+    },
+  },
+}
+```
+
+</details>

package/README.md

@@ -68,7 +68,7 @@ This plugin provides example implementations of Matter device types in Homebridg
 
 - 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.63 <2.0.0-beta.0` - refer to link for more information and installation instructions.
+  - [Homebridge](https://homebridge.io): `>=2.0.0-alpha.64 <2.0.0-beta.0` - refer to link for more information and installation instructions.
 
 ### Help/About
 

package/dist/devices/section-6-switches/on-off-light-switch.js

@@ -9,7 +9,7 @@
  * - Switch device implementation (input device, sends commands)
  */
 export function registerOnOffLightSwitch(context) {
-    const { api, config } = context;
+    const { api, log, config } = context;
     const accessories = [];
     if (!config.enableOnOffSwitch) {
         return accessories;
@@ -22,12 +22,21 @@ export function registerOnOffLightSwitch(context) {
         manufacturer: 'Matter Examples',
         model: 'OnOffSwitch v1',
         clusters: {
-        // Switches are input devices - they send commands rather than expose state
-        // The switch cluster configuration depends on the specific implementation
+            onOff: {
+                onOff: false,
+            },
         },
         handlers: {
-        // Switch handlers depend on the specific switch implementation
-        // Typically, switches trigger events rather than respond to commands
+            onOff: {
+                on: async () => {
+                    log.info('[On/Off Switch] Turning ON');
+                    // TODO: await mySwitchAPI.turnOn()
+                },
+                off: async () => {
+                    log.info('[On/Off Switch] Turning OFF');
+                    // TODO: await mySwitchAPI.turnOff()
+                },
+            },
         },
     });
     return accessories;

package/dist/devices/section-6-switches/on-off-light-switch.js.map

@@ -1 +1 @@
-{"version":3,"file":"on-off-light-switch.js","sourceRoot":"","sources":["../../../src/devices/section-6-switches/on-off-light-switch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,UAAU,wBAAwB,CAAC,OAAsB;IAC7D,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAA;IAC/B,MAAM,WAAW,GAAU,EAAE,CAAA;IAE7B,IAAI,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC;QAC9B,OAAO,WAAW,CAAA;IACpB,CAAC;IAED,WAAW,CAAC,IAAI,CAAC;QACf,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,qBAAqB,CAAC;QACrD,WAAW,EAAE,eAAe;QAC5B,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,WAAW;QAC9C,YAAY,EAAE,YAAY;QAC1B,YAAY,EAAE,iBAAiB;QAC/B,KAAK,EAAE,gBAAgB;QAEvB,QAAQ,EAAE;QACR,2EAA2E;QAC3E,0EAA0E;SAC3E;QAED,QAAQ,EAAE;QACR,+DAA+D;QAC/D,qEAAqE;SACtE;KACF,CAAC,CAAA;IAEF,OAAO,WAAW,CAAA;AACpB,CAAC"}
+{"version":3,"file":"on-off-light-switch.js","sourceRoot":"","sources":["../../../src/devices/section-6-switches/on-off-light-switch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,UAAU,wBAAwB,CAAC,OAAsB;IAC7D,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAA;IACpC,MAAM,WAAW,GAAU,EAAE,CAAA;IAE7B,IAAI,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC;QAC9B,OAAO,WAAW,CAAA;IACpB,CAAC;IAED,WAAW,CAAC,IAAI,CAAC;QACf,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,qBAAqB,CAAC;QACrD,WAAW,EAAE,eAAe;QAC5B,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,WAAW;QAC9C,YAAY,EAAE,YAAY;QAC1B,YAAY,EAAE,iBAAiB;QAC/B,KAAK,EAAE,gBAAgB;QAEvB,QAAQ,EAAE;YACR,KAAK,EAAE;gBACL,KAAK,EAAE,KAAK;aACb;SACF;QAED,QAAQ,EAAE;YACR,KAAK,EAAE;gBACL,EAAE,EAAE,KAAK,IAAI,EAAE;oBACb,GAAG,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAA;oBACtC,mCAAmC;gBACrC,CAAC;gBAED,GAAG,EAAE,KAAK,IAAI,EAAE;oBACd,GAAG,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAA;oBACvC,oCAAoC;gBACtC,CAAC;aACF;SACF;KACF,CAAC,CAAA;IAEF,OAAO,WAAW,CAAA;AACpB,CAAC"}

package/package.json

@@ -3,7 +3,7 @@
   "displayName": "Homebridge Matter",
   "alias": "Matter",
   "type": "module",
-  "version": "0.1.4-beta.0",
+  "version": "0.1.4",
   "description": "Homebridge plugin to showcase examples of Matter devices in Homebridge.",
   "author": {
     "name": "bwp91",
@@ -49,7 +49,7 @@
   "main": "dist/index.js",
   "engines": {
     "node": "^20.18.0 || ^22.10.0 || ^24.0.0",
-    "homebridge": ">=2.0.0-alpha.63 <2.0.0-beta.0"
+    "homebridge": ">=2.0.0-alpha.64 <2.0.0-beta.0"
   },
   "scripts": {
     "build": "rimraf ./dist && tsc && npm run plugin-ui",
@@ -65,7 +65,7 @@
   "devDependencies": {
     "@antfu/eslint-config": "^6.0.0",
     "@types/node": "^24.9.1",
-    "homebridge": "2.0.0-alpha.63",
+    "homebridge": "2.0.0-alpha.64",
     "rimraf": "^6.0.1",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3"