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

package/config.schema.json

@@ -27,14 +27,29 @@
         "description": "Optional OpenAPI secret for certain account setups.",
         "format": "password"
       },
+      "enableBLE": {
+        "type": "boolean",
+        "title": "Enable BLE (Bluetooth)",
+        "description": "Enable or disable BLE (Bluetooth Low Energy) support. If disabled, only OpenAPI (cloud) will be used.",
+        "default": true
+      },
       "devices": {
         "type": "array",
         "title": "Devices",
         "description": "List of SwitchBot devices to manage. Use the UI to add devices and copy device IDs.",
         "items": {
           "type": "object",
-          "required": ["deviceId", "configDeviceType"],
+          "required": [
+            "deviceId",
+            "configDeviceType"
+          ],
           "properties": {
+            "enabled": {
+              "type": "boolean",
+              "title": "Enabled",
+              "description": "Enable or disable this device without removing it from the config.",
+              "default": true
+            },
             "configDeviceName": {
               "type": "string",
               "title": "Name",
@@ -50,55 +65,222 @@
               "title": "Device Type",
               "description": "Select the device type so the plugin can expose the correct HomeKit/Matter services and characteristics.",
               "enum": [
-                "bot",
-                "curtain",
-                "fan",
-                "light",
-                "lightstrip",
-                "motion",
-                "contact",
-                "vacuum",
-                "lock",
-                "humidifier",
-                "temperature",
-                "relay",
-                "plug",
-                "wosweeper",
-                "blindtilt",
-                "curtain3",
-                "rollershade",
-                "meter",
-                "waterdetector",
-                "walletfinder",
-                "unknown"
-              ],
-              "default": "unknown"
+                "Blind Tilt",
+                "Curtain",
+                "Curtain3",
+                "Roller Shade",
+                "Keypad",
+                "Keypad Touch",
+                "Keypad Vision",
+                "Keypad Vision Pro",
+                "Lock Vision Pro",
+                "Lock Lite",
+                "Smart Lock",
+                "Smart Lock Pro",
+                "Smart Lock Ultra",
+                "Video Doorbell",
+                "Contact Sensor",
+                "Motion Sensor",
+                "Presence Sensor",
+                "Water Detector",
+                "Candle Warmer Lamp",
+                "Ceiling Light",
+                "Ceiling Light Pro",
+                "Color Bulb",
+                "Floor Lamp",
+                "RGBIC Neon Rope Light",
+                "RGBIC Neon Wire Rope Light",
+                "RGBICWW Floor Lamp",
+                "RGBICWW Strip Light",
+                "Strip Light",
+                "Strip Light 3",
+                "Air Purifier PM2.5",
+                "Air Purifier Table PM2.5",
+                "Air Purifier VOC",
+                "Air Purifier Table VOC",
+                "Battery Circulator Fan",
+                "Circulator Fan",
+                "Humidifier",
+                "Humidifier2",
+                "Meter",
+                "MeterPlus",
+                "Meter Plus",
+                "MeterPro",
+                "Meter Pro",
+                "MeterPro(CO2)",
+                "Meter Pro (CO2)",
+                "Smart Radiator Thermostat",
+                "Standing Circulator Fan",
+                "WoIOSensor",
+                "Garage Door Opener",
+                "Plug",
+                "Plug Mini (EU)",
+                "Plug Mini (JP)",
+                "Plug Mini (US)",
+                "Relay Switch 1",
+                "Relay Switch 1PM",
+                "Relay Switch 2PM",
+                "K10+",
+                "K10+ Pro",
+                "Robot Vacuum Cleaner K10+ Pro Combo",
+                "Robot Vacuum Cleaner K11+",
+                "Robot Vacuum Cleaner K20 Plus Pro",
+                "Robot Vacuum Cleaner S1",
+                "Robot Vacuum Cleaner S1 Plus",
+                "Robot Vacuum Cleaner S10",
+                "Robot Vacuum Cleaner S20",
+                "AI Hub",
+                "Hub",
+                "Hub 2",
+                "Hub 3",
+                "Hub Mini",
+                "Hub Plus",
+                "Indoor Cam",
+                "Pan/Tilt Cam",
+                "Pan/Tilt Cam 2K",
+                "Pan/Tilt Cam Plus 2K",
+                "Pan/Tilt Cam Plus 3K",
+                "Air Conditioner",
+                "Air Purifier",
+                "Camera",
+                "DVD",
+                "Fan",
+                "Light",
+                "Others",
+                "Projector",
+                "Set Top Box",
+                "Speaker",
+                "Streamer",
+                "TV",
+                "Vacuum Cleaner",
+                "Water Heater",
+                "AI Art Frame",
+                "Bot",
+                "Home Climate Panel",
+                "Remote",
+                "remote with screen"
+              ]
             },
             "connectionPreference": {
               "type": "string",
               "title": "Connection Preference",
               "description": "Select whether this device should prefer BLE, OpenAPI, or auto-detect (hybrid).",
-              "enum": ["auto", "ble", "openapi"],
+              "enum": [
+                "auto",
+                "ble",
+                "openapi"
+              ],
               "default": "auto"
             },
             "room": {
               "type": "string",
               "title": "Room",
               "description": "Optional room/location metadata for the device."
+            },
+            "encryptionKey": {
+              "type": "string",
+              "title": "BLE Encryption Key",
+              "description": "(Advanced) Optional BLE encryption key for this device. Required for some locks, relays, air purifiers, and light strips. See plugin docs for how to obtain this key.",
+              "format": "password"
+            },
+            "keyId": {
+              "type": "string",
+              "title": "BLE Key ID",
+              "description": "(Advanced) Optional BLE key ID for this device (usually 2 hex characters, e.g. 'ff'). Only required for some locks."
+            },
+            "refreshRate": {
+              "type": "integer",
+              "title": "OpenAPI Polling Interval (seconds)",
+              "description": "How often to poll this device via OpenAPI for status (in seconds). Overrides platform value if set. Default: 300 (5 minutes). Minimum: 30.",
+              "default": 300,
+              "minimum": 30
             }
           }
         }
-      },
-      "enableMatter": {
-        "type": "boolean",
-        "title": "Enable Matter Support (Override)",
-        "description": "Manually enable Matter support. By default, Matter is auto-detected from the child bridge configuration. Only change this if you need to override the auto-detection."
-      },
-      "preferMatter": {
-        "type": "boolean",
-        "title": "Prefer Matter when available",
-        "description": "If enabled and Matter is available, devices will be presented as Matter accessories where supported (instead of HAP)."
       }
+    },
+    "openApiRefreshRate": {
+      "type": "integer",
+      "title": "OpenAPI Polling Interval (seconds)",
+      "description": "How often to poll devices via OpenAPI for status (in seconds). Default: 300 (5 minutes). Minimum: 30. Can be overridden per device.",
+      "default": 300,
+      "minimum": 30
+    },
+    "matterBatchEnabled": {
+      "type": "boolean",
+      "title": "Enable Batched OpenAPI Polling",
+      "description": "If enabled, the platform will poll all OpenAPI devices in a single batch at the configured interval. Devices with per-device refreshRate are excluded from the batch.",
+      "default": true
+    },
+    "matterBatchRefreshRate": {
+      "type": "integer",
+      "title": "OpenAPI Batch Polling Interval (seconds)",
+      "description": "Interval for batched OpenAPI polling (in seconds). Falls back to openApiRefreshRate if not set. Default: 300.",
+      "default": 300,
+      "minimum": 30
+    },
+    "dailyApiLimit": {
+      "type": "integer",
+      "title": "OpenAPI Daily Request Limit",
+      "description": "Maximum OpenAPI requests per day allowed by the plugin. Default: 10000.",
+      "default": 10000,
+      "minimum": 1000
+    },
+    "dailyApiReserveForCommands": {
+      "type": "integer",
+      "title": "OpenAPI Reserve for Commands",
+      "description": "Requests reserved for user actions (commands/webhooks). When remaining budget reaches this value, background polling pauses. Default: 1000.",
+      "default": 1000,
+      "minimum": 0
+    },
+    "dailyApiResetLocalMidnight": {
+      "type": "boolean",
+      "title": "Reset OpenAPI Counter at Local Midnight",
+      "description": "If true, resets the daily OpenAPI request counter at local midnight. If false, resets at UTC midnight.",
+      "default": false
+    },
+    "webhookOnlyOnReserve": {
+      "type": "boolean",
+      "title": "Only Allow Webhooks on Reserve",
+      "description": "When remaining OpenAPI budget reaches the reserve, only webhooks and user commands are allowed. Background polling/discovery pauses.",
+      "default": false
+    },
+    "matterBatchConcurrency": {
+      "type": "integer",
+      "title": "OpenAPI Batch Concurrency",
+      "description": "Maximum number of parallel OpenAPI status calls during a batch. Default: 5.",
+      "default": 5,
+      "minimum": 1
+    },
+    "matterBatchJitter": {
+      "type": "integer",
+      "title": "OpenAPI Batch Jitter (seconds)",
+      "description": "Random startup delay before the first batch to reduce synchronized spikes. Default: 0.",
+      "default": 0,
+      "minimum": 0
+    },
+    "enableMatter": {
+      "type": "boolean",
+      "title": "Enable Matter Support (Override)",
+      "description": "Manually enable Matter support. By default, Matter is auto-detected from the child bridge configuration. Only change this if you need to override the auto-detection."
+    },
+    "preferMatter": {
+      "type": "boolean",
+      "title": "Prefer Matter when available",
+      "description": "If enabled and Matter is available, devices will be presented as Matter accessories where supported (instead of HAP)."
+    },
+    "blePollingEnabled": {
+      "type": "boolean",
+      "title": "Enable BLE Polling Fallback",
+      "description": "If enabled, the plugin will periodically poll BLE devices for status as a safety net in addition to real-time notifications. This helps recover from missed notifications or connection loss. Recommended for reliability. Can be overridden per device.",
+      "default": true
+    },
+    "blePollIntervalMs": {
+      "type": "integer",
+      "title": "BLE Polling Interval (ms)",
+      "description": "How often to poll BLE devices for status (in milliseconds). Default is 600000 (10 minutes). Set higher to reduce battery drain. Minimum 60000 (1 minute). Can be overridden per device.",
+      "default": 600000,
+      "minimum": 60000
     }
   },
   "layout": [
@@ -127,7 +309,18 @@
       "expanded": false,
       "items": [
         "enableMatter",
-        "preferMatter"
+        "preferMatter",
+        "blePollingEnabled",
+        "blePollIntervalMs",
+        "openApiRefreshRate",
+        "matterBatchEnabled",
+        "matterBatchRefreshRate",
+        "dailyApiLimit",
+        "dailyApiReserveForCommands",
+        "dailyApiResetLocalMidnight",
+        "webhookOnlyOnReserve",
+        "matterBatchConcurrency",
+        "matterBatchJitter"
       ]
     }
   ]

package/dist/SwitchBotHAPPlatform.d.ts

@@ -0,0 +1,133 @@
+import type { SwitchBotPluginConfig } from './settings.js';
+import type { API, Logger, PlatformConfig } from 'homebridge';
+/**
+ * Homebridge platform class for SwitchBot HAP (HomeKit Accessory Protocol) integration.
+ * Handles device discovery, registration, polling, and accessory lifecycle for HAP-enabled SwitchBot devices.
+ *
+ * @class SwitchBotHAPPlatform
+ * @param {Logger} log - Homebridge logger instance
+ * @param {PlatformConfig} config - Platform configuration object
+ * @param {API} [api] - Optional Homebridge API instance
+ * @property {API | undefined} api - Homebridge API instance
+ * @property {Logger} log - Homebridge logger instance
+ * @property {SwitchBotPluginConfig} config - Parsed plugin config
+ * @property {any[]} devices - All created device instances
+ * @property {Map<string, any>} accessories - Map of accessory UUID to accessory object
+ * @property {string} lastConfigHash - Hash of last loaded config for change detection
+ * @property {NodeJS.Timeout | null} configReloadInterval - Interval for periodic config reload
+ * @property {Map<string, NodeJS.Timeout>} openApiPollTimers - Timers for per-device OpenAPI polling
+ * @property {NodeJS.Timeout | null} openApiBatchTimer - Timer for batched OpenAPI polling
+ * @property {number} openApiRequestsToday - Count of OpenAPI requests made today
+ * @property {number} openApiLastReset - Timestamp (ms) of last OpenAPI daily counter reset
+ */
+export declare class SwitchBotHAPPlatform {
+    /** Homebridge API instance */
+    api: API | undefined;
+    /** Homebridge logger instance */
+    log: Logger;
+    /** Parsed plugin config */
+    config: SwitchBotPluginConfig;
+    /** All created device instances */
+    devices: any[];
+    /** Map of accessory UUID to accessory object */
+    accessories: Map<string, any>;
+    /** Hash of last loaded config for change detection */
+    private lastConfigHash;
+    /** Interval for periodic config reload */
+    private configReloadInterval;
+    /** Timers for per-device OpenAPI polling */
+    private openApiPollTimers;
+    /** Timer for batched OpenAPI polling */
+    private openApiBatchTimer;
+    /** Count of OpenAPI requests made today */
+    private openApiRequestsToday;
+    /** Timestamp (ms) of last OpenAPI daily counter reset */
+    private openApiLastReset;
+    /**
+     * Construct the SwitchBot HAP platform.
+     * @param log Homebridge logger
+     * @param config Platform config
+     * @param api Homebridge API instance
+     */
+    constructor(log: Logger, config: PlatformConfig, api?: API);
+    /**
+     * Discover and create all device instances from config.
+     * Populates this.devices and registers HAP accessories for each device.
+     * Ensures Matter API is loaded before loading devices if available.
+     *
+     * @returns {Promise<void>} Resolves when all devices are loaded and registered
+     */
+    loadDevices(): Promise<void>;
+    /**
+     * Registers all HAP accessories with the Homebridge HAP API.
+     *
+     * This method is called after all device instances have been created. It handles both new and restored
+     * accessories, updating their context and adding or updating HAP services and characteristics as needed.
+     * Accessories are registered with Homebridge using the HAP API, and the internal accessory map is updated accordingly.
+     *
+     * @param {Array<{created: any, d: any, type: string}>} createdDevices - Array of device descriptors:
+     *   - created: The created device instance
+     *   - d: The normalized device config object
+     *   - type: The normalized device type string
+     * @returns {Promise<void>} Resolves when registration is complete
+     *
+     * Differences from Matter registration:
+     *   - Uses the HAP API (not Matter API) for accessory registration.
+     *   - Adds HAP services and characteristics to each accessory based on the device descriptor.
+     *   - Does not require or check for Matter support or availability.
+     *   - Accessory context and service wiring are HAP-specific.
+     *
+     * If the Homebridge HAP API is not available, registration is skipped and a log message is emitted.
+     */
+    private registerHAPAccessories;
+    /**
+     * Returns the timestamp (ms) of the last OpenAPI daily counter reset.
+     * @returns {number} Timestamp in ms
+     */
+    getOpenApiLastReset(): number;
+    /**
+     * Logs the last OpenAPI reset time in a human-readable format.
+     * @returns {void}
+     */
+    logOpenApiLastReset(): void;
+    /**
+     * Compute a hash of the current device config for change detection.
+     * @returns {string} JSON string hash of device config
+     */
+    private getConfigHash;
+    /**
+     * Reload devices if config has changed since last load.
+     * Unregisters accessories and removes devices no longer in config.
+     * Calls loadDevices to repopulate devices and accessories.
+     *
+     * @returns {Promise<void>} Resolves when reload is complete
+     */
+    private checkAndReloadDevices;
+    /**
+     * Cleanup method to clear config reload interval on shutdown.
+     * Called by Homebridge on shutdown event.
+     * @returns {void}
+     */
+    shutdown(): void;
+    /**
+     * Setup OpenAPI polling for all devices according to config (global, per-device, batch, rate limit).
+     * Handles daily request limits, per-device and batch polling, and resets.
+     *
+     * @returns {void}
+     */
+    private _setupOpenApiPolling;
+    /**
+     * Called by Homebridge to restore cached HAP accessories on startup.
+     * @param {any} accessory - The cached accessory object
+     * @returns {Promise<void>} Resolves when accessory is restored
+     */
+    configureAccessory(accessory: any): Promise<void>;
+    /**
+     * Called by Homebridge when a cached Matter accessory is restored (optional signature).
+     * @param {any} accessory - The cached accessory object
+     * @returns {void}
+     */
+    configureMatterAccessory?(accessory: any): void;
+}
+export default SwitchBotHAPPlatform;
+//# sourceMappingURL=SwitchBotHAPPlatform.d.ts.map

package/dist/SwitchBotHAPPlatform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SwitchBotHAPPlatform.d.ts","sourceRoot":"","sources":["../src/SwitchBotHAPPlatform.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AAC1D,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAO7D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,oBAAoB;IAC/B,8BAA8B;IAC9B,GAAG,EAAE,GAAG,GAAG,SAAS,CAAA;IACpB,iCAAiC;IACjC,GAAG,EAAE,MAAM,CAAA;IACX,2BAA2B;IAC3B,MAAM,EAAE,qBAAqB,CAAA;IAC7B,mCAAmC;IACnC,OAAO,EAAE,GAAG,EAAE,CAAK;IACnB,gDAAgD;IAChD,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC7B,sDAAsD;IACtD,OAAO,CAAC,cAAc,CAAa;IACnC,0CAA0C;IAC1C,OAAO,CAAC,oBAAoB,CAA8B;IAC1D,4CAA4C;IAC5C,OAAO,CAAC,iBAAiB,CAAyC;IAClE,wCAAwC;IACxC,OAAO,CAAC,iBAAiB,CAA8B;IACvD,2CAA2C;IAC3C,OAAO,CAAC,oBAAoB,CAAI;IAChC,yDAAyD;IACzD,OAAO,CAAC,gBAAgB,CAAI;IAE5B;;;;;OAKG;gBACS,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,GAAG,CAAC,EAAE,GAAG;IA2C1D;;;;;;OAMG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IA6DlC;;;;;;;;;;;;;;;;;;;;OAoBG;YACW,sBAAsB;IAgHpC;;;OAGG;IACH,mBAAmB,IAAI,MAAM;IAI7B;;;OAGG;IACH,mBAAmB,IAAI,IAAI;IAS3B;;;OAGG;IACH,OAAO,CAAC,aAAa;IAUrB;;;;;;OAMG;YACW,qBAAqB;IAiCnC;;;;OAIG;IACH,QAAQ,IAAI,IAAI;IAQhB;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAkI5B;;;;OAIG;IACG,kBAAkB,CAAC,SAAS,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAUvD;;;;OAIG;IACH,wBAAwB,CAAC,CAAC,SAAS,EAAE,GAAG,GAAG,IAAI;CAShD;AAED,eAAe,oBAAoB,CAAA"}