@homebridge-plugins/homebridge-matter 0.1.3 → 0.1.4

package/dist/devices/section-4-lighting/dimmable-light.js

@@ -3,29 +3,12 @@
  *
  * A lighting device with on/off and level control (brightness).
  *
- * ═══════════════════════════════════════════════════════════════════════════════
- * ARCHITECTURE: THE TWO-WAY FLOW (applies to all Matter accessories)
- * ═══════════════════════════════════════════════════════════════════════════════
+ * For comprehensive documentation, see: ../../../MATTER_API.md
  *
- * FLOW A: Home App → Physical Device (AUTOMATIC - via handlers)
- * ────────────────────────────────────────────────────────────────
- * 1. User controls via Home App
- * 2. Matter command → Homebridge → Your handler runs
- * 3. You control your physical device (API, MQTT, etc.)
- * 4. Homebridge AUTOMATICALLY updates Matter state (calls super methods)
- * 5. All controllers are notified
- * ✅ No manual state update needed!
- *
- * FLOW B: Physical Device → Home App (MANUAL - you must update state)
- * ────────────────────────────────────────────────────────────────
- * 1. Physical device changes (button press, cloud app, automation)
- * 2. ❌ Homebridge has NO IDEA this happened!
- * 3. You MUST monitor device (events/polling) and detect change
- * 4. You MUST call api.matter.updateAccessoryState() to update Matter
- * 5. Then all controllers are notified
- *
- * This example demonstrates BOTH flows with multiple clusters (on/off + brightness).
- * ═══════════════════════════════════════════════════════════════════════════════
+ * This example demonstrates:
+ * - Multiple clusters (OnOff + LevelControl)
+ * - Type-safe handlers with MatterRequests
+ * - Brightness value conversion (Matter 1-254 ↔ Percent 0-100%)
  */
 export function registerDimmableLight(context) {
     const { api, log, config } = context;
@@ -42,325 +25,63 @@ export function registerDimmableLight(context) {
         model: 'DimmableLight v1',
         clusters: {
             onOff: {
-                onOff: false, // Initial state: off
+                onOff: false,
             },
             levelControl: {
-                currentLevel: 127, // Current brightness: 50% (range 1-254, where 254 = 100%)
-                minLevel: 1, // Minimum brightness (Matter spec minimum)
-                maxLevel: 254, // Maximum brightness (Matter spec maximum, 0 is reserved for "off")
+                currentLevel: 127, // 50% brightness (range 1-254)
+                minLevel: 1,
+                maxLevel: 254,
             },
         },
-        // ═══════════════════════════════════════════════════════════════════════════
-        // FLOW A: HOME APP → PHYSICAL DEVICE
-        // ═══════════════════════════════════════════════════════════════════════════
-        // These handlers are called when users control via Home app
-        // After your handler runs, Homebridge AUTOMATICALLY updates Matter state
         handlers: {
             onOff: {
-                /**
-                 * Called when user turns the light ON via Home app
-                 *
-                 * IMPORTANT: After this handler completes, Homebridge AUTOMATICALLY
-                 * updates the Matter onOff state and notifies all controllers.
-                 * You do NOT need to call api.matter.updateAccessoryState() here!
-                 */
                 on: async () => {
-                    log.info('[Dimmable Light] ✓ Handler `on` called (Home app → Physical device)');
-                    // ─────────────────────────────────────────────────────────────────────
-                    // OPTIONAL: Read current state
-                    // ─────────────────────────────────────────────────────────────────────
-                    const isOn = accessory.clusters.onOff.onOff;
-                    const brightness = accessory.clusters.levelControl.currentLevel;
-                    const brightnessPercent = Math.round((brightness / 254) * 100);
-                    log.info(`[Dimmable Light] Current Matter state: ${isOn ? 'ON' : 'OFF'} at ${brightnessPercent}%`);
-                    // When turning on, the brightness stays at its last value
-                    // Example: If light was at 80% when turned off, it turns back on at 80%
-                    // ─────────────────────────────────────────────────────────────────────
-                    // YOUR JOB: Control your physical device
-                    // ─────────────────────────────────────────────────────────────────────
-                    // TODO: Add your actual light control logic here
-                    // await myLightAPI.turnOn()
-                    // Note: brightness is already set, just need to turn on
-                    log.info('[Dimmable Light] Physical device turned ON');
-                    // Homebridge automatically updates Matter state after this handler
+                    log.info('[Dimmable Light] Turning ON');
+                    // TODO: await myLightAPI.turnOn()
                 },
-                /**
-                 * Called when user turns the light OFF via Home app
-                 */
                 off: async () => {
-                    log.info('[Dimmable Light] ✓ Handler `off` called (Home app → Physical device)');
-                    const brightness = accessory.clusters.levelControl.currentLevel;
-                    const brightnessPercent = Math.round((brightness / 254) * 100);
-                    log.info(`[Dimmable Light] Turning off (brightness will remain at ${brightnessPercent}% for next on)`);
-                    // TODO: Control your physical device
-                    // await myLightAPI.turnOff()
-                    // Note: Don't change the brightness value, it's preserved for next "on"
-                    log.info('[Dimmable Light] Physical device turned OFF');
-                    // Homebridge automatically updates Matter state to OFF after this handler
+                    log.info('[Dimmable Light] Turning OFF');
+                    // TODO: await myLightAPI.turnOff()
                 },
             },
             levelControl: {
-                /**
-                 * Called when user changes brightness
-                 * This handler is called for brightness changes AND can turn the light on/off
-                 */
+                // Type-safe handler with MatterRequests
                 moveToLevelWithOnOff: async (request) => {
-                    const { level, transitionTime, optionsMask, optionsOverride } = request;
+                    const { level, transitionTime } = request;
                     // Convert Matter level (1-254) to percentage (0-100%)
                     const brightnessPercent = Math.round((level / 254) * 100);
-                    log.info(`[Dimmable Light] ✓ Handler \`moveToLevel\` called with level=${level} (${brightnessPercent}%)`);
-                    // ─────────────────────────────────────────────────────────────────────
-                    // READING STATE: Check current state before applying change
-                    // ─────────────────────────────────────────────────────────────────────
-                    const wasOn = accessory.clusters.onOff.onOff;
-                    const oldLevel = accessory.clusters.levelControl.currentLevel;
-                    const oldPercent = Math.round((oldLevel / 254) * 100);
-                    log.info(`[Dimmable Light] Changing from ${oldPercent}% to ${brightnessPercent}% (was ${wasOn ? 'ON' : 'OFF'})`);
-                    // Important note about transitionTime:
-                    // - transitionTime is in 1/10 second units (tenths of a second)
-                    // - transitionTime: 10 = 1 second, 50 = 5 seconds
-                    // - If your device API supports fade/transition, use this value
-                    if (transitionTime !== undefined && transitionTime !== null) {
-                        const seconds = transitionTime / 10;
-                        log.info(`[Dimmable Light] Transition time: ${seconds}s`);
-                    }
-                    // ─────────────────────────────────────────────────────────────────────
-                    // CONTROL YOUR DEVICE: Send brightness command
-                    // ─────────────────────────────────────────────────────────────────────
-                    // TODO: Replace with your actual device control logic
-                    //
-                    // Example 1: API that accepts percentage
-                    // await myLightAPI.setBrightness(brightnessPercent)
-                    //
-                    // Example 2: API that accepts 0-255 range
-                    // await myLightAPI.setBrightness(level)
-                    //
-                    // Example 3: With transition/fade support
-                    // await myLightAPI.setBrightness(brightnessPercent, transitionTime / 10)
-                    //
-                    // Example 4: Cloud API
-                    // await fetch('https://api.mysmartlight.com/devices/light-002/brightness', {
-                    //   method: 'PUT',
-                    //   body: JSON.stringify({ brightness: brightnessPercent })
-                    // })
-                    // IMPORTANT: moveToLevelWithOnOff can also turn the light on/off!
-                    // - If level > 0: Light turns ON at that brightness
-                    // - If level = 0: Light turns OFF (but some implementations may not allow 0)
-                    // HomeKit automatically updates both onOff and levelControl clusters after this handler
+                    log.info(`[Dimmable Light] Setting brightness to ${brightnessPercent}% (level: ${level})`);
+                    // TODO: await myLightAPI.setBrightness(brightnessPercent, transitionTime)
                 },
             },
         },
     };
     accessories.push(accessory);
-    // ═════════════════════════════════════════════════════════════════════════════
-    // FLOW B: PHYSICAL DEVICE → HOME APP
-    // ═════════════════════════════════════════════════════════════════════════════
-    //
-    // For a dimmable light, you need to monitor TWO properties:
-    // 1. On/Off state (onOff cluster)
-    // 2. Brightness level (levelControl cluster)
-    //
-    // When your physical device changes externally, you may need to update one or both.
-    //
-    // THE KEY API: api.matter.updateAccessoryState(uuid, cluster, attributes)
-    // This updates Matter state AND notifies all controllers.
-    /**
-     * Example: Polling for state changes (checking both on/off and brightness)
-     */
-    const startPollingExample = () => {
-        setInterval(async () => {
-            try {
-                // TODO: Fetch state from your device
-                // const state = await myLightAPI.getState(accessory.context.deviceId)
-                // const deviceIsOn = state.power === 'on'
-                // const deviceBrightness = state.brightness // Assuming this is 0-100
-                // For this example, simulate fetching device state:
-                // const deviceIsOn = true
-                // const deviceBrightness = 75 // 75%
-                // ──────────────────────────────────────────────────────────────────────
-                // READING CURRENT MATTER STATE
-                // ──────────────────────────────────────────────────────────────────────
-                const currentMatterIsOn = accessory.clusters.onOff.onOff;
-                const currentMatterLevel = accessory.clusters.levelControl.currentLevel;
-                const currentMatterPercent = Math.round((currentMatterLevel / 254) * 100);
-                // ──────────────────────────────────────────────────────────────────────
-                // SCENARIO 1: Only on/off changed (brightness stayed the same)
-                // ──────────────────────────────────────────────────────────────────────
-                // if (deviceIsOn !== currentMatterIsOn) {
-                //   log.info(`[Dimmable Light] Physical device power changed: ${deviceIsOn ? 'ON' : 'OFF'}`)
-                //
-                //   // Update Matter state using Homebridge API
-                //   api.matter.updateAccessoryState(
-                //     accessory.uuid,
-                //     api.matter.clusterNames.OnOff,
-                //     { onOff: deviceIsOn },
-                //   )
-                //
-                //   log.info(`[Dimmable Light] ✓ Matter state updated (Physical device → Home app)`)
-                // }
-                // ──────────────────────────────────────────────────────────────────────
-                // SCENARIO 2: Only brightness changed (on/off stayed the same)
-                // ──────────────────────────────────────────────────────────────────────
-                // if (deviceBrightness !== currentMatterPercent) {
-                //   log.info(`[Dimmable Light] Physical device brightness changed: ${deviceBrightness}%`)
-                //
-                //   // Convert percentage (0-100) to Matter level (1-254)
-                //   const newLevel = Math.max(1, Math.round((deviceBrightness / 100) * 254))
-                //
-                //   // Update Matter state using Homebridge API
-                //   api.matter.updateAccessoryState(
-                //     accessory.uuid,
-                //     api.matter.clusterNames.LevelControl,
-                //     { currentLevel: newLevel },
-                //   )
-                //
-                //   log.info(`[Dimmable Light] ✓ Matter state updated: ${deviceBrightness}% (level ${newLevel})`)
-                // }
-                // ──────────────────────────────────────────────────────────────────────
-                // SCENARIO 3: Both on/off AND brightness changed
-                // ──────────────────────────────────────────────────────────────────────
-                // Update each cluster separately with api.matter.updateAccessoryState()
-                // const brightnessChanged = deviceBrightness !== currentMatterPercent
-                // const powerChanged = deviceIsOn !== currentMatterIsOn
-                //
-                // if (powerChanged || brightnessChanged) {
-                //   log.info(`[Dimmable Light] Physical device changed - Power: ${deviceIsOn ? 'ON' : 'OFF'}, Brightness: ${deviceBrightness}%`)
-                //
-                //   // Update on/off if changed
-                //   if (powerChanged) {
-                //     api.matter.updateAccessoryState(
-                //       accessory.uuid,
-                //       api.matter.clusterNames.OnOff,
-                //       { onOff: deviceIsOn },
-                //     )
-                //   }
-                //
-                //   // Update brightness if changed
-                //   if (brightnessChanged) {
-                //     const newLevel = Math.max(1, Math.round((deviceBrightness / 100) * 254))
-                //     api.matter.updateAccessoryState(
-                //       accessory.uuid,
-                //       api.matter.clusterNames.LevelControl,
-                //       { currentLevel: newLevel },
-                //     )
-                //   }
-                //
-                //   log.info(`[Dimmable Light] ✓ Matter state updated (Physical device → Home app)`)
-                // }
-            }
-            catch (error) {
-                log.error(`[Dimmable Light] Error polling device state: ${error}`);
-            }
-        }, 5000); // Poll every 5 seconds
-    };
-    // Uncomment to enable polling:
-    // startPollingExample()
-    /**
-     * RECOMMENDED: Event-based updates with multiple properties
-     *
-     * ⚡ This is the BEST approach - instant updates when device changes
-     */
-    const startEventListenerExample = () => {
-        // Example: MQTT listener for a dimmable light
-        // import mqtt from 'mqtt'
-        // const mqttClient = mqtt.connect('mqtt://your-broker-url')
-        //
-        // mqttClient.subscribe('home/dimmable-light/status')
-        // mqttClient.on('message', (topic, message) => {
-        //   if (topic === 'home/dimmable-light/status') {
-        //     const deviceState = JSON.parse(message.toString())
-        //     // Example payload: { "state": "ON", "brightness": 75 }
-        //
-        //     const deviceIsOn = deviceState.state === 'ON'
-        //     const deviceBrightness = deviceState.brightness // 0-100
-        //
-        //     // Check what changed compared to current Matter state
-        //     const currentMatterIsOn = accessory.clusters.onOff.onOff
-        //     const currentMatterPercent = Math.round((accessory.clusters.levelControl.currentLevel / 254) * 100)
-        //     const powerChanged = deviceIsOn !== currentMatterIsOn
-        //     const brightnessChanged = deviceBrightness !== currentMatterPercent
-        //
-        //     if (powerChanged || brightnessChanged) {
-        //       log.info(`[Dimmable Light] Physical device changed (MQTT): ${deviceIsOn ? 'ON' : 'OFF'} at ${deviceBrightness}%`)
-        //
-        //       // Update on/off if changed
-        //       if (powerChanged) {
-        //         api.matter.updateAccessoryState(
-        //           accessory.uuid,
-        //           api.matter.clusterNames.OnOff,
-        //           { onOff: deviceIsOn },
-        //         )
-        //       }
-        //
-        //       // Update brightness if changed
-        //       if (brightnessChanged) {
-        //         const newLevel = Math.max(1, Math.round((deviceBrightness / 100) * 254))
-        //         api.matter.updateAccessoryState(
-        //           accessory.uuid,
-        //           api.matter.clusterNames.LevelControl,
-        //           { currentLevel: newLevel },
-        //         )
-        //       }
-        //
-        //       log.info(`[Dimmable Light] ✓ Matter state updated (Physical device → Home app)`)
-        //     }
-        //   }
-        // })
-    };
-    // Uncomment to enable event listeners:
-    // startEventListenerExample()
-    // ═════════════════════════════════════════════════════════════════════════════
-    // KEY TAKEAWAYS FOR MULTI-CLUSTER DEVICES:
-    // ═════════════════════════════════════════════════════════════════════════════
-    //
-    // 1. TWO SEPARATE FLOWS:
-    //    FLOW A (Home App → Physical Device):
-    //    - Handlers run when user controls via Home app
-    //    - You control the physical device
-    //    - Homebridge AUTOMATICALLY updates Matter state after handler
-    //    - DO NOT call api.matter.updateAccessoryState() in handlers!
-    //
-    //    FLOW B (Physical Device → Home App):
-    //    - Physical device changes externally (button, cloud, automation)
-    //    - You MUST monitor device (events/polling) and detect changes
-    //    - You MUST call api.matter.updateAccessoryState() for each cluster
-    //    - Then all controllers are notified
-    //
-    // 2. READING MULTIPLE PROPERTIES:
-    //    - On/Off: accessory.clusters.onOff.onOff
-    //    - Brightness: accessory.clusters.levelControl.currentLevel
-    //    - Convert level to %: Math.round((level / 254) * 100)
-    //
-    // 3. UPDATING MULTIPLE PROPERTIES (Physical Device → Home App):
-    //    - Update each cluster separately:
-    //      api.matter.updateAccessoryState(uuid, api.matter.clusterNames.OnOff, { onOff: value })
-    //      api.matter.updateAccessoryState(uuid, api.matter.clusterNames.LevelControl, { currentLevel: level })
-    //    - You can update one or both depending on what changed
-    //    - ONLY use this for FLOW B (external changes), NOT in handlers!
-    //
-    // 4. BRIGHTNESS CONVERSION:
-    //    - Matter uses 1-254 range (0 is reserved, means "off")
-    //    - Your device API probably uses 0-100 percentage
-    //    - Convert TO Matter: Math.max(1, Math.round((percent / 100) * 254))
-    //    - Convert FROM Matter: Math.round((level / 254) * 100)
-    //
-    // 5. HANDLER BEHAVIOR (FLOW A):
-    //    - on/off handlers: Only change power state, brightness is preserved
-    //    - moveToLevelWithOnOff: Can change BOTH brightness and power state
-    //    - If user sets brightness to 0, light may turn off (implementation dependent)
-    //    - Homebridge automatically updates Matter state after handlers complete
+    // FLOW B: Monitor for external changes
+    // Example: MQTT listener
+    // mqttClient.on('message', (topic, message) => {
+    //   const { state, brightness } = JSON.parse(message.toString())
     //
-    // 6. TRANSITION TIME:
-    //    - Provided in 1/10 second units (10 = 1 second)
-    //    - Use this if your device supports fade/transition effects
-    //    - Example: await myLightAPI.setBrightness(level, transitionTime / 10)
+    //   // Update on/off state
+    //   const deviceIsOn = state === 'ON'
+    //   if (deviceIsOn !== accessory.clusters.onOff.onOff) {
+    //     api.matter.updateAccessoryState(
+    //       accessory.uuid,
+    //       api.matter.clusterNames.OnOff,
+    //       { onOff: deviceIsOn }
+    //     )
+    //   }
     //
-    // 7. BEST PRACTICES:
-    //    - Always compare states before calling updateAccessoryState() (avoid unnecessary updates)
-    //    - Use events (MQTT, WebSocket, webhooks) whenever possible
-    //    - Update only the clusters that actually changed
-    //    - Log clearly: "Physical device → Home app" vs "Home app → Physical device"
-    // ═════════════════════════════════════════════════════════════════════════════
+    //   // Update brightness (convert percent to Matter level)
+    //   const matterLevel = Math.max(1, Math.round((brightness / 100) * 254))
+    //   if (matterLevel !== accessory.clusters.levelControl.currentLevel) {
+    //     api.matter.updateAccessoryState(
+    //       accessory.uuid,
+    //       api.matter.clusterNames.LevelControl,
+    //       { currentLevel: matterLevel }
+    //     )
+    //   }
+    // })
     return accessories;
 }
 //# sourceMappingURL=dimmable-light.js.map

package/dist/devices/section-4-lighting/dimmable-light.js.map

@@ -1 +1 @@
-{"version":3,"file":"dimmable-light.js","sourceRoot":"","sources":["../../../src/devices/section-4-lighting/dimmable-light.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dimmable-light.js","sourceRoot":"","sources":["../../../src/devices/section-4-lighting/dimmable-light.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,MAAM,UAAU,qBAAqB,CAAC,OAAsB;IAC1D,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAA;IACpC,MAAM,WAAW,GAAU,EAAE,CAAA;IAE7B,IAAI,CAAC,MAAM,CAAC,mBAAmB,EAAE,CAAC;QAChC,OAAO,WAAW,CAAA;IACpB,CAAC;IAED,MAAM,SAAS,GAAG;QAChB,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,uBAAuB,CAAC;QACvD,WAAW,EAAE,gBAAgB;QAC7B,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,aAAa;QAChD,YAAY,EAAE,WAAW;QACzB,YAAY,EAAE,iBAAiB;QAC/B,KAAK,EAAE,kBAAkB;QAEzB,QAAQ,EAAE;YACR,KAAK,EAAE;gBACL,KAAK,EAAE,KAAK;aACb;YACD,YAAY,EAAE;gBACZ,YAAY,EAAE,GAAG,EAAE,+BAA+B;gBAClD,QAAQ,EAAE,CAAC;gBACX,QAAQ,EAAE,GAAG;aACd;SACF;QAED,QAAQ,EAAE;YACR,KAAK,EAAE;gBACL,EAAE,EAAE,KAAK,IAAI,EAAE;oBACb,GAAG,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAA;oBACvC,kCAAkC;gBACpC,CAAC;gBAED,GAAG,EAAE,KAAK,IAAI,EAAE;oBACd,GAAG,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAA;oBACxC,mCAAmC;gBACrC,CAAC;aACF;YAED,YAAY,EAAE;gBACZ,wCAAwC;gBACxC,oBAAoB,EAAE,KAAK,EAAE,OAAmC,EAAE,EAAE;oBAClE,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,GAAG,OAAO,CAAA;oBAEzC,sDAAsD;oBACtD,MAAM,iBAAiB,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,CAAA;oBACzD,GAAG,CAAC,IAAI,CAAC,0CAA0C,iBAAiB,aAAa,KAAK,GAAG,CAAC,CAAA;oBAE1F,0EAA0E;gBAC5E,CAAC;aACF;SACF;KACF,CAAA;IAED,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;IAE3B,uCAAuC;IACvC,yBAAyB;IACzB,iDAAiD;IACjD,iEAAiE;IACjE,EAAE;IACF,2BAA2B;IAC3B,sCAAsC;IACtC,yDAAyD;IACzD,uCAAuC;IACvC,wBAAwB;IACxB,uCAAuC;IACvC,8BAA8B;IAC9B,QAAQ;IACR,MAAM;IACN,EAAE;IACF,2DAA2D;IAC3D,0EAA0E;IAC1E,wEAAwE;IACxE,uCAAuC;IACvC,wBAAwB;IACxB,8CAA8C;IAC9C,sCAAsC;IACtC,QAAQ;IACR,MAAM;IACN,KAAK;IAEL,OAAO,WAAW,CAAA;AACpB,CAAC"}

package/dist/devices/section-4-lighting/extended-color-light.d.ts

@@ -5,32 +5,13 @@
  * - Color Light (HS): Hue/Saturation only
  * - Extended Color Light (HS+CCT): Hue/Saturation + Color Temperature
  *
- * Both use the same Matter device type (ExtendedColorLight) but with different
- * cluster configurations.
+ * For comprehensive documentation, see: ../../../MATTER_API.md
  *
- * ═══════════════════════════════════════════════════════════════════════════════
- * ARCHITECTURE: THE TWO-WAY FLOW (applies to all Matter accessories)
- * ═══════════════════════════════════════════════════════════════════════════════
- *
- * FLOW A: Home App → Physical Device (AUTOMATIC - via handlers)
- * ────────────────────────────────────────────────────────────────
- * 1. User controls via Home App
- * 2. Matter command → Homebridge → Your handler runs
- * 3. You control your physical device (API, MQTT, etc.)
- * 4. Homebridge AUTOMATICALLY updates Matter state
- * 5. All controllers are notified
- * ✅ No manual state update needed!
- *
- * FLOW B: Physical Device → Home App (MANUAL - you must update state)
- * ────────────────────────────────────────────────────────────────
- * 1. Physical device changes (button, cloud app, automation)
- * 2. ❌ Homebridge has NO IDEA this happened!
- * 3. You MUST monitor device and detect changes
- * 4. You MUST call api.matter.updateAccessoryState() for changed clusters
- * 5. Then all controllers are notified
- *
- * This demonstrates the MOST COMPLEX case with multiple color modes and clusters.
- * ═══════════════════════════════════════════════════════════════════════════════
+ * This example demonstrates:
+ * - Multiple color modes (HS, XY, Color Temperature)
+ * - Color value conversions (hue/saturation, mireds/Kelvin, XY)
+ * - Type-safe handlers with MatterRequests
+ * - Most complex lighting scenario with mode switching
  */
 import type { DeviceContext } from '../types.js';
 export declare function registerExtendedColorLight(context: DeviceContext): any[];