@homebridge-plugins/homebridge-matter 0.1.3 → 0.1.4

package/dist/devices/section-4-lighting/on-off-light.js

@@ -1,36 +1,16 @@
 /**
  * On/Off Light Device (Matter Spec § 4.1)
  *
- * The On/Off Light is a lighting device that is capable of being switched on or off.
+ * A basic lighting device that can be switched on or off.
  *
- * ═══════════════════════════════════════════════════════════════════════════════
- * CRITICAL ARCHITECTURE UNDERSTANDING - THE TWO-WAY FLOW:
- * ═══════════════════════════════════════════════════════════════════════════════
+ * For comprehensive documentation on Matter concepts, handlers, state management,
+ * and the two-way flow architecture, see:
+ * ../../../MATTER_API.md
  *
- * There are TWO separate flows for a Homebridge Matter plugin:
- *
- * FLOW A: Home App → Physical Device (AUTOMATIC - via handlers)
- * ────────────────────────────────────────────────────────────────
- * 1. User taps in Home App
- * 2. Matter command received by Homebridge
- * 3. Your handler runs (on/off methods below)
- * 4. You control your physical device (API call, MQTT, etc.)
- * 5. Homebridge AUTOMATICALLY updates Matter state
- * 6. All controllers (iPhone, iPad, etc.) are notified
- * ✅ No manual state update needed!
- *
- * FLOW B: Physical Device → Home App (MANUAL - you must update state)
- * ────────────────────────────────────────────────────────────────
- * 1. User presses physical button on device (OR cloud app, automation, etc.)
- * 2. Physical device changes state
- * 3. ❌ Homebridge has NO IDEA this happened!
- * 4. You MUST detect the change (via polling, MQTT, webhook, etc.)
- * 5. You MUST call api.matter.updateAccessoryState() to update Matter
- * 6. Then all controllers are notified
- * ⚠️  If you don't do step 5, Home App shows wrong state!
- *
- * This example demonstrates BOTH flows in detail.
- * ═══════════════════════════════════════════════════════════════════════════════
+ * This example demonstrates:
+ * - Basic OnOff cluster implementation
+ * - Handler setup for on/off commands (Flow A)
+ * - Event-based state monitoring (Flow B)
  */
 export function registerOnOffLight(context) {
     const { api, log, config } = context;
@@ -38,7 +18,6 @@ export function registerOnOffLight(context) {
     if (!config.enableOnOffLight) {
         return accessories;
     }
-    // Create the accessory configuration
     const accessory = {
         uuid: api.matter.uuid.generate('matter-onoff-light'),
         displayName: 'On/Off Light',
@@ -47,457 +26,108 @@ export function registerOnOffLight(context) {
         manufacturer: 'Matter Examples',
         model: 'OnOffLight v1',
         // Optional: Store custom data that persists across restarts
-        // This works the same as PlatformAccessory.context for HAP accessories
-        // Use this to cache device state, API tokens, or any custom data
         // context: {
         //   deviceId: 'my-light-123',
-        //   lastKnownState: true,
-        //   apiToken: 'your-token-here'
+        //   apiToken: 'your-token-here',
         // },
-        // Clusters define the functionality and state of the device
+        // Initial state (persisted automatically after first creation)
         clusters: {
             onOff: {
-                onOff: true, // Initial state: light is on (true) or off (false)
+                onOff: true, // Initial state: light is on
             },
         },
-        // ═══════════════════════════════════════════════════════════════════════════
-        // FLOW A: HOME APP → PHYSICAL DEVICE
-        // ═══════════════════════════════════════════════════════════════════════════
-        // These handlers are called when users control the device via Home app
-        // After your handler runs, Homebridge AUTOMATICALLY updates the Matter state
+        // FLOW A: Home App → Physical Device
+        // Handlers are called when users control via Home app
+        // State updates automatically after handler completes
         handlers: {
             onOff: {
-                /**
-                 * Called when user turns the light ON via Home app
-                 *
-                 * IMPORTANT: After this handler completes successfully, Homebridge
-                 * AUTOMATICALLY calls super.on() which updates the Matter state to ON
-                 * and notifies all connected devices. You don't need to manually update state!
-                 */
                 on: async () => {
-                    log.info('[On/Off Light] ✓ Handler `on` called (Home app → Physical device)');
-                    // ─────────────────────────────────────────────────────────────────────
-                    // OPTIONAL: Read current state before change
-                    // ─────────────────────────────────────────────────────────────────────
-                    const currentState = accessory.clusters.onOff.onOff;
-                    log.info(`[On/Off Light] Current Matter state: ${currentState ? 'ON' : 'OFF'}`);
-                    // ─────────────────────────────────────────────────────────────────────
-                    // YOUR JOB: Control your physical device
-                    // ─────────────────────────────────────────────────────────────────────
-                    // TODO: Replace this with your actual device control logic
-                    //
-                    // Example 1: Cloud API
-                    // await fetch('https://api.mysmartlight.com/devices/light-001/on', {
-                    //   method: 'POST',
-                    //   headers: { 'Authorization': `Bearer ${accessory.context.apiToken}` }
-                    // })
-                    //
-                    // Example 2: Local HTTP API
+                    log.info('[On/Off Light] Turning ON');
+                    // TODO: Control your physical device
+                    // Examples:
+                    // await fetch('https://api.mydevice.com/light/on', { method: 'POST' })
                     // await fetch('http://192.168.1.50/api/light/on')
-                    //
-                    // Example 3: MQTT
-                    // mqttClient.publish('home/light-001/command', JSON.stringify({ state: 'ON' }))
-                    //
-                    // Example 4: Custom library
+                    // mqttClient.publish('home/light/command', JSON.stringify({ state: 'ON' }))
                     // await myLightAPI.turnOn(accessory.context.deviceId)
                     log.info('[On/Off Light] Physical device turned ON');
-                    // ─────────────────────────────────────────────────────────────────────
-                    // AUTOMATIC: Homebridge updates Matter state after this handler
-                    // ─────────────────────────────────────────────────────────────────────
-                    // You don't need to call api.matter.updateAccessoryState() here!
-                    // Homebridge automatically:
-                    // 1. Calls super.on() which sets this.state.onOff = true
-                    // 2. Syncs to cache for persistence
-                    // 3. Notifies all Matter controllers
+                    // State automatically updated by Homebridge
                 },
-                /**
-                 * Called when user turns the light OFF via Home app
-                 */
                 off: async () => {
-                    log.info('[On/Off Light] ✓ Handler `off` called (Home app → Physical device)');
-                    const currentState = accessory.clusters.onOff.onOff;
-                    log.info(`[On/Off Light] Current Matter state: ${currentState ? 'ON' : 'OFF'}`);
+                    log.info('[On/Off Light] Turning OFF');
                     // TODO: Control your physical device
-                    // Example: await myLightAPI.turnOff(accessory.context.deviceId)
+                    // await myLightAPI.turnOff(accessory.context.deviceId)
                     log.info('[On/Off Light] Physical device turned OFF');
-                    // Homebridge automatically updates Matter state to OFF after this handler
+                    // State automatically updated by Homebridge
                 },
             },
         },
     };
     accessories.push(accessory);
-    // ═════════════════════════════════════════════════════════════════════════════
-    // FLOW B: PHYSICAL DEVICE → HOME APP
-    // ═════════════════════════════════════════════════════════════════════════════
-    //
-    // CRITICAL: The handlers above only run when the user controls via Home app.
-    // But what if your light changes state externally? For example:
-    // - User presses physical button on the light
-    // - User controls via manufacturer's cloud app
-    // - Automation from another system
-    // - Device state changes independently
-    //
-    // In these cases, Homebridge has NO IDEA the device changed!
-    // You MUST monitor your device and call api.matter.updateAccessoryState()
-    //
-    // WHY NO AUTOMATIC DETECTION?
-    // Your physical device is NOT a Matter device - it's a regular IoT device
-    // (cloud API, HTTP, MQTT, etc.). The virtual Matter device in Homebridge
-    // can't magically detect when the physical device changes. YOU must tell it!
-    //
-    // THE KEY API: api.matter.updateAccessoryState(uuid, cluster, attributes)
-    // This updates the Matter state AND notifies all connected controllers.
-    /**
-     * RECOMMENDED: Event-based updates (MQTT, WebSocket, webhooks, SSE)
-     *
-     * This is the BEST approach if your device supports push notifications.
-     * When your device changes, you get instant notification and update Matter.
-     *
-     * ⚡ Pros: Instant updates, efficient, the best user experience
-     * ⚠️  Requires: Device API that supports events/push notifications
-     */
-    const startEventListenerExample = () => {
-        // ───────────────────────────────────────────────────────────────────────────
-        // Example A: MQTT listener
-        // ───────────────────────────────────────────────────────────────────────────
-        // import mqtt from 'mqtt'
-        // const mqttClient = mqtt.connect('mqtt://your-broker-url')
-        //
-        // mqttClient.subscribe('home/light-001/status')  // Subscribe to status topic
+    // ═══════════════════════════════════════════════════════════════════════════
+    // FLOW B: Physical Device → Home App
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Monitor your physical device and call updateAccessoryState() when it changes
+    // See MATTER_API.md "Monitoring External Changes" for detailed examples
+    // Example: Event-based monitoring (recommended)
+    const startEventListener = () => {
+        // MQTT Example:
+        // mqttClient.subscribe('home/light/status')
         // mqttClient.on('message', (topic, message) => {
-        //   if (topic === 'home/light-001/status') {
-        //     const deviceState = JSON.parse(message.toString())
-        //     const deviceIsOn = deviceState.state === 'ON'
+        //   const { state } = JSON.parse(message.toString())
+        //   const deviceIsOn = state === 'ON'
+        //   const currentState = accessory.clusters.onOff.onOff
         //
-        //     // Check if state actually changed (avoid unnecessary updates)
-        //     const currentMatterState = accessory.clusters.onOff.onOff
-        //     if (deviceIsOn !== currentMatterState) {
-        //       log.info(`[On/Off Light] Physical device changed (MQTT): ${deviceIsOn ? 'ON' : 'OFF'}`)
-        //
-        //       // ─────────────────────────────────────────────────────────────────
-        //       // UPDATE MATTER STATE: This is the critical API call!
-        //       // ─────────────────────────────────────────────────────────────────
-        //       api.matter.updateAccessoryState(
-        //         accessory.uuid,                    // UUID of the accessory
-        //         api.matter.clusterNames.OnOff,     // Cluster name (use constants!)
-        //         { onOff: deviceIsOn },             // New attribute values
-        //       )
-        //
-        //       // This updates the Matter state AND notifies all controllers
-        //       log.info(`[On/Off Light] ✓ Matter state updated (Physical device → Home app)`)
-        //     }
+        //   if (deviceIsOn !== currentState) {
+        //     api.matter.updateAccessoryState(
+        //       accessory.uuid,
+        //       api.matter.clusterNames.OnOff,
+        //       { onOff: deviceIsOn }
+        //     )
+        //     log.info(`[On/Off Light] State synced: ${deviceIsOn ? 'ON' : 'OFF'}`)
         //   }
         // })
-        // ───────────────────────────────────────────────────────────────────────────
-        // Example B: WebSocket listener
-        // ───────────────────────────────────────────────────────────────────────────
-        // import WebSocket from 'ws'
-        // const ws = new WebSocket('wss://api.mysmartlight.com/devices/light-001/events')
-        //
+        // WebSocket Example:
+        // const ws = new WebSocket('wss://api.mydevice.com/events')
         // ws.on('message', (data) => {
         //   const event = JSON.parse(data.toString())
         //   if (event.type === 'state_changed') {
         //     const deviceIsOn = event.state === 'ON'
-        //     const currentMatterState = accessory.clusters.onOff.onOff
-        //
-        //     if (deviceIsOn !== currentMatterState) {
-        //       log.info(`[On/Off Light] Physical device changed (WebSocket): ${deviceIsOn ? 'ON' : 'OFF'}`)
+        //     const currentState = accessory.clusters.onOff.onOff
         //
+        //     if (deviceIsOn !== currentState) {
         //       api.matter.updateAccessoryState(
         //         accessory.uuid,
         //         api.matter.clusterNames.OnOff,
-        //         { onOff: deviceIsOn },
+        //         { onOff: deviceIsOn }
         //       )
-        //
-        //       log.info(`[On/Off Light] ✓ Matter state updated`)
         //     }
         //   }
         // })
-        //
-        // // Handle reconnection on disconnect
-        // ws.on('close', () => {
-        //   log.warn('[On/Off Light] WebSocket disconnected, reconnecting in 5s...')
-        //   setTimeout(() => startEventListenerExample(), 5000)
-        // })
-        // ───────────────────────────────────────────────────────────────────────────
-        // Example C: HTTP Webhook listener (requires setting up an HTTP server)
-        // ───────────────────────────────────────────────────────────────────────────
-        // import express from 'express'
-        // const app = express()
-        // app.use(express.json())
-        //
-        // app.post('/webhook/light-001/state', (req, res) => {
-        //   const deviceIsOn = req.body.state === 'ON'
-        //   const currentMatterState = accessory.clusters.onOff.onOff
-        //
-        //   if (deviceIsOn !== currentMatterState) {
-        //     log.info(`[On/Off Light] Physical device changed (webhook): ${deviceIsOn ? 'ON' : 'OFF'}`)
-        //
-        //     api.matter.updateAccessoryState(
-        //       accessory.uuid,
-        //       api.matter.clusterNames.OnOff,
-        //       { onOff: deviceIsOn },
-        //     )
-        //
-        //     log.info(`[On/Off Light] ✓ Matter state updated`)
-        //   }
-        //   res.sendStatus(200)
-        // })
-        //
-        // app.listen(3000, () => log.info('[On/Off Light] Webhook server listening on port 3000'))
-        // ───────────────────────────────────────────────────────────────────────────
-        // Example D: Server-Sent Events (SSE)
-        // ───────────────────────────────────────────────────────────────────────────
-        // const EventSource = require('eventsource')
-        // const eventSource = new EventSource('https://api.mysmartlight.com/devices/light-001/events')
-        //
-        // eventSource.addEventListener('state', (event) => {
-        //   const data = JSON.parse(event.data)
-        //   const deviceIsOn = data.power === 'on'
-        //   const currentMatterState = accessory.clusters.onOff.onOff
-        //
-        //   if (deviceIsOn !== currentMatterState) {
-        //     log.info(`[On/Off Light] Physical device changed (SSE): ${deviceIsOn ? 'ON' : 'OFF'}`)
-        //
-        //     api.matter.updateAccessoryState(
-        //       accessory.uuid,
-        //       api.matter.clusterNames.OnOff,
-        //       { onOff: deviceIsOn },
-        //     )
-        //
-        //     log.info(`[On/Off Light] ✓ Matter state updated`)
-        //   }
-        // })
     };
-    // Uncomment to enable event listeners:
-    // startEventListenerExample()
-    /**
-     * FALLBACK: Polling-based updates (only if events aren't available)
-     *
-     * Use this approach ONLY if your device doesn't support push notifications.
-     * Polling is less efficient and has delays, but works with any REST API.
-     *
-     * 🐢 Pros: Works with any HTTP API
-     * ⚠️  Cons: Delayed updates, higher overhead, can strain APIs
-     */
-    const startPollingExample = () => {
-        // Poll every 5-10 seconds (adjust based on your needs)
-        // WARNING: Frequent polling can strain your device's API and network
+    // Uncomment to enable event listener:
+    // startEventListener()
+    // Example: Polling-based monitoring (fallback)
+    const startPolling = () => {
         setInterval(async () => {
             try {
-                // ─────────────────────────────────────────────────────────────────────
-                // STEP 1: Fetch state from your physical device
-                // ─────────────────────────────────────────────────────────────────────
-                // TODO: Replace with your actual device state fetching logic
-                //
-                // Example 1: REST API
-                // const response = await fetch('https://api.mysmartlight.com/devices/light-001/state')
+                // TODO: Fetch state from your physical device
+                // const response = await fetch('https://api.mydevice.com/light/state')
                 // const data = await response.json()
-                // const deviceIsOn = data.state === 'ON'
-                //
-                // Example 2: Custom library
-                // const deviceIsOn = await myLightAPI.getState(accessory.context.deviceId)
-                //
-                // Example 3: Local device
-                // const deviceIsOn = await fetch('http://192.168.1.50/status').then(r => r.json()).then(d => d.on)
-                // For this example, simulate fetching device state
-                // const deviceIsOn = true
-                // ─────────────────────────────────────────────────────────────────────
-                // STEP 2: Compare with current Matter state
-                // ─────────────────────────────────────────────────────────────────────
-                // const currentMatterState = accessory.clusters.onOff.onOff
-                //
-                // // Only update if the state actually changed (avoid unnecessary updates)
-                // if (deviceIsOn !== currentMatterState) {
-                //   log.info(`[On/Off Light] Physical device changed (polling): ${deviceIsOn ? 'ON' : 'OFF'}`)
-                //
-                //   // ───────────────────────────────────────────────────────────────────
-                //   // STEP 3: Update Matter state
-                //   // ───────────────────────────────────────────────────────────────────
-                //   api.matter.updateAccessoryState(
-                //     accessory.uuid,
-                //     api.matter.clusterNames.OnOff,
-                //     { onOff: deviceIsOn },
-                //   )
-                //
-                //   log.info(`[On/Off Light] ✓ Matter state updated (Physical device → Home app)`)
-                // }
+                // const deviceIsOn = data.power === 'on'
+                const deviceIsOn = true; // Replace with actual fetch
+                const currentState = accessory.clusters.onOff.onOff;
+                if (deviceIsOn !== currentState) {
+                    api.matter.updateAccessoryState(accessory.uuid, api.matter.clusterNames.OnOff, { onOff: deviceIsOn });
+                    log.info(`[On/Off Light] State synced: ${deviceIsOn ? 'ON' : 'OFF'}`);
+                }
             }
             catch (error) {
-                log.error(`[On/Off Light] Error polling device state: ${error}`);
+                log.error(`[On/Off Light] Polling error: ${error}`);
             }
-        }, 5000); // Poll every 5 seconds (adjust as needed)
+        }, 5000); // Poll every 5 seconds
     };
-    // Uncomment to enable polling (only if events aren't available):
-    // startPollingExample()
-    // ═════════════════════════════════════════════════════════════════════════════
-    // KEY TAKEAWAYS - THE TWO-WAY FLOW:
-    // ═════════════════════════════════════════════════════════════════════════════
-    //
-    // 1. TWO SEPARATE FLOWS:
-    //    FLOW A (Home App → Physical Device):
-    //    - Your handler runs when user controls via Home app
-    //    - You control the physical device (API call, MQTT, etc.)
-    //    - Homebridge AUTOMATICALLY updates Matter state after your handler
-    //    - DO NOT call api.matter.updateAccessoryState() in handlers!
-    //
-    //    FLOW B (Physical Device → Home App):
-    //    - Physical device changes (button press, cloud app, etc.)
-    //    - Homebridge has NO IDEA this happened!
-    //    - You MUST monitor device (events/polling) and detect the change
-    //    - You MUST call api.matter.updateAccessoryState() to update Matter
-    //    - Then all controllers are notified
-    //
-    // 2. READING STATE:
-    //    - Access via: accessory.clusters.onOff.onOff
-    //    - This gives you the current Matter state
-    //    - Use this to compare with physical device state before updating
-    //
-    // 3. UPDATING STATE (Physical Device → Home App):
-    //    - Use the Homebridge API:
-    //      api.matter.updateAccessoryState(
-    //        accessory.uuid,
-    //        api.matter.clusterNames.OnOff,
-    //        { onOff: newValue }
-    //      )
-    //    - This updates Matter state AND notifies all controllers
-    //    - ONLY use this for external changes (FLOW B), NOT in handlers (FLOW A)!
-    //
-    // 4. WHY NO AUTOMATIC DETECTION?
-    //    - Your physical device is NOT a Matter device (it's HTTP, MQTT, cloud, etc.)
-    //    - The virtual Matter device in Homebridge can't detect physical changes
-    //    - You must explicitly monitor your device and call updateAccessoryState()
-    //
-    // 5. CHOOSING MONITORING METHOD:
-    //    Event-based (RECOMMENDED): MQTT, WebSocket, webhooks, SSE
-    //      ✅ Instant updates
-    //      ✅ More efficient
-    //      ✅ Better user experience
-    //      ✅ Lower overhead
-    //
-    //    Polling (FALLBACK): Only if device has no event support
-    //      ⚠️  Delayed updates (depends on interval)
-    //      ⚠️  Higher network overhead
-    //      ⚠️  Can strain device APIs
-    //      ⚠️  Use 5-10 second intervals minimum
-    //
-    // 6. BEST PRACTICES:
-    //    - Always compare states before calling updateAccessoryState() (avoid unnecessary updates)
-    //    - Use events whenever possible for better performance
-    //    - Handle errors gracefully in monitoring logic
-    //    - Store connection objects (MQTT, WebSocket) for cleanup on plugin shutdown
-    //    - Reconnect automatically if event connection drops
-    //    - Log clearly: "Physical device → Home app" vs "Home app → Physical device"
-    //
-    // 7. DISCOVERING CLUSTER ATTRIBUTES & TYPES:
-    //    Q: "How do I know what attributes are available for my device type?"
-    //    A: Three ways to discover this:
-    //
-    //    METHOD 1: TypeScript Autocomplete (EASIEST for simple types)
-    //    When you type `accessory.clusters.`, TypeScript will show available clusters.
-    //    When you type `onOff: `, TypeScript knows the type (boolean).
-    //    This works well for simple types like booleans and numbers.
-    //
-    //    METHOD 2: Programmatic Discovery (for attribute names)
-    //    All clusters are available via api.matter.clusters:
-    //    ```typescript
-    //    // See all OnOff attributes
-    //    const onOffAttrs = api.matter.clusters.OnOffCluster.attributes
-    //    console.log(Object.keys(onOffAttrs))
-    //    // Shows: ['onOff', 'clusterRevision', 'featureMap', ...]
-    //
-    //    // See all FanControl attributes
-    //    const fanAttrs = api.matter.clusters.FanControlCluster.attributes
-    //    console.log(Object.keys(fanAttrs))
-    //    // Shows: ['fanMode', 'fanModeSequence', 'percentSetting', 'percentCurrent', ...]
-    //    ```
-    //
-    //    METHOD 3: api.matter.types Namespace (BEST - for enum values with type safety!)
-    //    Homebridge exports ALL Matter.js cluster types via the api.matter.types namespace.
-    //    This gives you full access to enums, types, and constants with TypeScript autocomplete!
-    //
-    //    EXAMPLE: Fan Speed Values (using api.matter.types)
-    //    For a fan, you might wonder: "What values can fanMode accept?"
-    //    ```typescript
-    //    // Access FanMode enum with full type safety and autocomplete (no import needed!)
-    //    api.matter.updateAccessoryState(
-    //      fanUuid,
-    //      api.matter.clusterNames.FanControl,
-    //      { fanMode: api.matter.types.FanControl.FanMode.High }
-    //    )
-    //
-    //    // All FanMode values available:
-    //    // - api.matter.types.FanControl.FanMode.Off      (0)
-    //    // - api.matter.types.FanControl.FanMode.Low      (1)
-    //    // - api.matter.types.FanControl.FanMode.Medium   (2)
-    //    // - api.matter.types.FanControl.FanMode.High     (3)
-    //    // - api.matter.types.FanControl.FanMode.On       (4)
-    //    // - api.matter.types.FanControl.FanMode.Auto     (5)
-    //    // - api.matter.types.FanControl.FanMode.Smart    (6)
-    //    ```
-    //
-    //    EXAMPLE: Thermostat System Mode (using api.matter.types)
-    //    ```typescript
-    //    api.matter.updateAccessoryState(
-    //      thermostatUuid,
-    //      api.matter.clusterNames.Thermostat,
-    //      {
-    //        localTemperature: 2200,           // 22.00°C (hundredths)
-    //        occupiedHeatingSetpoint: 2000,    // 20.00°C
-    //        occupiedCoolingSetpoint: 2400,    // 24.00°C
-    //        systemMode: api.matter.types.Thermostat.SystemMode.Heat,
-    //      }
-    //    )
-    //
-    //    // All SystemMode values available:
-    //    // - api.matter.types.Thermostat.SystemMode.Off             (0)
-    //    // - api.matter.types.Thermostat.SystemMode.Auto            (1)
-    //    // - api.matter.types.Thermostat.SystemMode.Cool            (3)
-    //    // - api.matter.types.Thermostat.SystemMode.Heat            (4)
-    //    // - api.matter.types.Thermostat.SystemMode.EmergencyHeat   (5)
-    //    // - api.matter.types.Thermostat.SystemMode.Precooling      (6)
-    //    // - api.matter.types.Thermostat.SystemMode.FanOnly         (7)
-    //    ```
-    //
-    //    EXAMPLE: Door Lock State (using api.matter.types)
-    //    ```typescript
-    //    api.matter.updateAccessoryState(
-    //      lockUuid,
-    //      api.matter.clusterNames.DoorLock,
-    //      { lockState: api.matter.types.DoorLock.LockState.Locked }
-    //    )
-    //
-    //    // All LockState values available:
-    //    // - api.matter.types.DoorLock.LockState.NotFullyLocked  (0)
-    //    // - api.matter.types.DoorLock.LockState.Locked          (1)
-    //    // - api.matter.types.DoorLock.LockState.Unlocked        (2)
-    //    ```
-    //
-    //    DISCOVERING ENUM VALUES:
-    //    Three ways to find available enum values:
-    //    1. TypeScript Autocomplete: Type `api.matter.types.FanControl.` and see suggestions
-    //    2. Matter.js Reference: https://github.com/project-chip/matter.js
-    //    3. Matter Specification: https://csa-iot.org/developer-resource/specifications-download-request/
-    //
-    //    ALL AVAILABLE CLUSTERS IN api.matter.types:
-    //    api.matter.types exports ALL 130+ Matter clusters using original matter.js names:
-    //    - api.matter.types.FanControl
-    //    - api.matter.types.Thermostat
-    //    - api.matter.types.DoorLock
-    //    - api.matter.types.ColorControl
-    //    - api.matter.types.WindowCovering
-    //    - api.matter.types.SmokeCoAlarm
-    //    - api.matter.types.OccupancySensing
-    //    - api.matter.types.TemperatureMeasurement
-    //    - ... and 120+ more!
-    //
-    //    COMMON ATTRIBUTE VALUE TYPES:
-    //    - Boolean: true/false (e.g., onOff, occupied)
-    //    - Uint8/Uint16: 0-254, 0-100, 0-65535 (e.g., currentLevel, hue, saturation)
-    //    - Enum: Use api.matter.types for type-safe enum values (see examples above)
-    //    - Temperature: Usually in hundredths of degrees C (2500 = 25.00°C)
-    //    - Percentage: Usually 0-100 for sensors, 0-254 for controls (Matter range)
-    // ═════════════════════════════════════════════════════════════════════════════
+    // Uncomment to enable polling (use events if possible!):
+    // startPolling()
     return accessories;
 }
 //# sourceMappingURL=on-off-light.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"on-off-light.js","sourceRoot":"","sources":["../../../src/devices/section-4-lighting/on-off-light.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"on-off-light.js","sourceRoot":"","sources":["../../../src/devices/section-4-lighting/on-off-light.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,MAAM,UAAU,kBAAkB,CAAC,OAAsB;IACvD,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAA;IACpC,MAAM,WAAW,GAAU,EAAE,CAAA;IAE7B,IAAI,CAAC,MAAM,CAAC,gBAAgB,EAAE,CAAC;QAC7B,OAAO,WAAW,CAAA;IACpB,CAAC;IAED,MAAM,SAAS,GAAG;QAChB,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,oBAAoB,CAAC;QACpD,WAAW,EAAE,cAAc;QAC3B,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,UAAU;QAC7C,YAAY,EAAE,WAAW;QACzB,YAAY,EAAE,iBAAiB;QAC/B,KAAK,EAAE,eAAe;QAEtB,4DAA4D;QAC5D,aAAa;QACb,8BAA8B;QAC9B,iCAAiC;QACjC,KAAK;QAEL,+DAA+D;QAC/D,QAAQ,EAAE;YACR,KAAK,EAAE;gBACL,KAAK,EAAE,IAAI,EAAE,6BAA6B;aAC3C;SACF;QAED,qCAAqC;QACrC,sDAAsD;QACtD,sDAAsD;QACtD,QAAQ,EAAE;YACR,KAAK,EAAE;gBACL,EAAE,EAAE,KAAK,IAAI,EAAE;oBACb,GAAG,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAA;oBAErC,qCAAqC;oBACrC,YAAY;oBACZ,uEAAuE;oBACvE,kDAAkD;oBAClD,4EAA4E;oBAC5E,sDAAsD;oBAEtD,GAAG,CAAC,IAAI,CAAC,0CAA0C,CAAC,CAAA;oBACpD,4CAA4C;gBAC9C,CAAC;gBAED,GAAG,EAAE,KAAK,IAAI,EAAE;oBACd,GAAG,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAA;oBAEtC,qCAAqC;oBACrC,uDAAuD;oBAEvD,GAAG,CAAC,IAAI,CAAC,2CAA2C,CAAC,CAAA;oBACrD,4CAA4C;gBAC9C,CAAC;aACF;SACF;KACF,CAAA;IAED,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;IAE3B,8EAA8E;IAC9E,qCAAqC;IACrC,8EAA8E;IAC9E,+EAA+E;IAC/E,wEAAwE;IAExE,gDAAgD;IAChD,MAAM,kBAAkB,GAAG,GAAG,EAAE;QAC9B,gBAAgB;QAChB,4CAA4C;QAC5C,iDAAiD;QACjD,qDAAqD;QACrD,sCAAsC;QACtC,wDAAwD;QACxD,EAAE;QACF,uCAAuC;QACvC,uCAAuC;QACvC,wBAAwB;QACxB,uCAAuC;QACvC,8BAA8B;QAC9B,QAAQ;QACR,4EAA4E;QAC5E,MAAM;QACN,KAAK;QAEL,qBAAqB;QACrB,4DAA4D;QAC5D,+BAA+B;QAC/B,8CAA8C;QAC9C,0CAA0C;QAC1C,8CAA8C;QAC9C,0DAA0D;QAC1D,EAAE;QACF,yCAAyC;QACzC,yCAAyC;QACzC,0BAA0B;QAC1B,yCAAyC;QACzC,gCAAgC;QAChC,UAAU;QACV,QAAQ;QACR,MAAM;QACN,KAAK;IACP,CAAC,CAAA;IAED,sCAAsC;IACtC,uBAAuB;IAEvB,+CAA+C;IAC/C,MAAM,YAAY,GAAG,GAAG,EAAE;QACxB,WAAW,CAAC,KAAK,IAAI,EAAE;YACrB,IAAI,CAAC;gBACH,8CAA8C;gBAC9C,uEAAuE;gBACvE,qCAAqC;gBACrC,yCAAyC;gBACzC,MAAM,UAAU,GAAG,IAAI,CAAA,CAAC,4BAA4B;gBAEpD,MAAM,YAAY,GAAG,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAA;gBACnD,IAAI,UAAU,KAAK,YAAY,EAAE,CAAC;oBAChC,GAAG,CAAC,MAAM,CAAC,oBAAoB,CAC7B,SAAS,CAAC,IAAI,EACd,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC,KAAK,EAC7B,EAAE,KAAK,EAAE,UAAU,EAAE,CACtB,CAAA;oBACD,GAAG,CAAC,IAAI,CAAC,gCAAgC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAA;gBACvE,CAAC;YACH,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,GAAG,CAAC,KAAK,CAAC,iCAAiC,KAAK,EAAE,CAAC,CAAA;YACrD,CAAC;QACH,CAAC,EAAE,IAAI,CAAC,CAAA,CAAC,uBAAuB;IAClC,CAAC,CAAA;IAED,yDAAyD;IACzD,iBAAiB;IAEjB,OAAO,WAAW,CAAA;AACpB,CAAC"}

package/dist/devices/section-5-smart-plugs/dimmable-plug-in-unit.d.ts

@@ -2,6 +2,12 @@
  * Dimmable Plug-in Unit Device (Matter Spec § 5.2)
  *
  * A plug-in unit with on/off and level control.
+ *
+ * For comprehensive documentation, see: ../../../MATTER_API.md
+ *
+ * This example demonstrates:
+ * - Multiple clusters (OnOff + LevelControl) for outlets
+ * - Type-safe handlers with MatterRequests
  */
 import type { DeviceContext } from '../types.js';
 export declare function registerDimmablePlugInUnit(context: DeviceContext): any[];