@switchbot/homebridge-switchbot 5.0.0-beta.98 → 5.0.0

package/dist/devices/genericDevice.d.ts

@@ -1,11 +1,66 @@
+/**
+ * Status Update Strategy for BLE and OpenAPI
+ *
+ * BLE (Bluetooth Low Energy):
+ * - Primary: Subscribes to device notifications for real-time state updates using _subscribeBLENotifications().
+ * - Fallback: (Recommended) Optionally, a low-frequency polling timer (e.g., every 5–10 minutes) can call getState() to recover from missed notifications or connection loss.
+ *   - This ensures state stays in sync even if notifications are unreliable or the device reconnects.
+ *   - Polling should be infrequent to avoid battery drain and BLE congestion.
+ *
+ * BLE Polling Options (config & per-device):
+ * - blePollingEnabled (boolean): Enable/disable BLE polling fallback (default: true).
+ * - blePollIntervalMs (integer): Polling interval in ms (default: 600000, min: 60000).
+ *   - These can be set globally in config or overridden per device.
+ *   - Setting a lower interval increases update frequency but may drain battery faster.
+ *   - Setting a higher interval reduces battery impact but may delay state recovery.
+ *
+ * OpenAPI (Cloud):
+ * - Uses periodic polling to fetch device status at a configurable interval (default: 300 seconds, can be set per device or platform).
+ * - Platform supports batched refresh (matterBatchEnabled, matterBatchRefreshRate, etc.) and per-device refreshRate overrides.
+ * - Rate limiting:
+ *   - Default daily limit: 10,000 OpenAPI requests (configurable via options.dailyApiLimit).
+ *   - Reserve: 1,000 requests for user commands (options.dailyApiReserveForCommands).
+ *   - When the remaining budget reaches the reserve, background polling/discovery pauses, but user commands and webhooks continue.
+ *   - Counter resets at local or UTC midnight (options.dailyApiResetLocalMidnight).
+ *
+ * Best Practices:
+ * - BLE: Use notifications for instant updates, add periodic polling as a safety net.
+ * - OpenAPI: Tune polling intervals to balance freshness and rate limit budget.
+ * - Both: Document and expose polling intervals and rate limit settings in config.
+ *
+ * See README.md and docs for more details.
+ */
 import type { SwitchBotPluginConfig } from '../settings.js';
+import { Buffer } from 'node:buffer';
 import { DeviceBase } from './deviceBase.js';
 export declare class GenericDevice extends DeviceBase {
+    protected log: import('homebridge').Logger;
+    private _blePollTimer;
+    private _blePollIntervalMs;
+    private _blePollingEnabled;
     constructor(opts: any, cfg: SwitchBotPluginConfig);
+    /**
+     * Start periodic BLE polling as a fallback to notifications.
+     */
+    private _startBlePolling;
+    /**
+     * Clean up BLE polling timer on destroy.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Subscribe to BLE notifications for this device (if supported by node-switchbot)
+     * Logs unsolicited notifications and enables per-command notification futures.
+     */
+    private _subscribeBLENotifications;
+    /**
+     * Await a BLE notification for this device (for advanced use in subclasses)
+     * Returns the notification payload or throws on timeout.
+     */
+    protected _awaitBLENotification(timeoutMs?: number): Promise<Buffer>;
     getState(): Promise<any>;
     setState(change: any): Promise<any>;
     createHAPAccessory(api: any): any;
-    createMatterAccessory(api: any): any;
+    createMatterAccessory(api: any): Promise<any>;
 }
 export declare class BotDevice extends GenericDevice {
 }
@@ -24,7 +79,7 @@ export declare class CurtainDevice extends GenericDevice {
             };
         }[];
     };
-    createMatterAccessory(api: any): any;
+    createMatterAccessory(api: any): Promise<any>;
 }
 export declare class FanDevice extends GenericDevice {
     createHAPAccessory(api: any): {
@@ -154,7 +209,7 @@ export declare class HumidifierDevice extends GenericDevice {
                     set: (v: any) => Promise<void>;
                 };
                 CurrentHumidifierDehumidifierState: {
-                    get: () => Promise<2 | 0>;
+                    get: () => Promise<0 | 2>;
                 };
                 TargetHumidifierDehumidifierState: {
                     get: () => Promise<number>;
@@ -173,40 +228,7 @@ export declare class HumidifierDevice extends GenericDevice {
     setState(change: any): Promise<any>;
 }
 export declare class HumidifierMatterDevice extends HumidifierDevice {
-    createMatterAccessory(api: any): {
-        id: string;
-        name: string;
-        protocol: string;
-        clusters: ({
-            type: string;
-            clusterId: 1029;
-            attributes: {
-                currentRelativeHumidity: {
-                    read: () => Promise<any>;
-                    write: undefined;
-                };
-                0: {
-                    read: () => Promise<any>;
-                    write: undefined;
-                };
-                onOff?: undefined;
-            };
-        } | {
-            type: string;
-            clusterId: 6;
-            attributes: {
-                onOff: {
-                    read: () => Promise<boolean>;
-                    write: (v: any) => Promise<any>;
-                };
-                0: {
-                    read: () => Promise<boolean>;
-                    write: (v: any) => Promise<any>;
-                };
-                currentRelativeHumidity?: undefined;
-            };
-        })[];
-    };
+    createMatterAccessory(api: any): Promise<any>;
 }
 export declare class TemperatureSensorDevice extends GenericDevice {
     createHAPAccessory(api: any): {

package/dist/devices/genericDevice.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"genericDevice.d.ts","sourceRoot":"","sources":["../../src/devices/genericDevice.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"genericDevice.d.ts","sourceRoot":"","sources":["../../src/devices/genericDevice.ts"],"names":[],"mappings":"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"}