@switchbot/homebridge-switchbot 5.0.0-beta.6 → 5.0.0-beta.60

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file. This project uses [Semantic Versioning](https://semver.org/)
 
+## [Unreleased]
+
+### What's Changed
+- Matter platform: register only devices discovered via the SwitchBot OpenAPI by default. Per-device config overrides (by deviceId) are correctly merged into discovered devices.
+- Add `options.allowConfigOnlyDevices` (boolean) to opt-in to registering devices that exist only in config (not discovered).
+- Add unit tests for per-device merging and config-only behavior.
+ - Matter (Matter platform): default to discovery-first registration and automatically remove previously-registered "stale" accessories that are no longer discovered or configured.
+ - Add `options.keepStaleAccessories` (Advanced Settings) — opt-in to preserve previously-registered accessories when set to true. Default: false (stale accessories are removed automatically).
+ - Implement per-device OpenAPI polling with tracked timers and proper lifecycle cleanup (timers and BLE handlers cleared on unregister/shutdown).
+ - Centralize OpenAPI/BLE -> Matter mapping and expand BLE/OpenAPI parsing to include PM2.5/PM10/VOC/CO2, temperature/humidity, improved color parsing, and additional sensor/robot-vacuum fields.
+ - Prefer accessory-specific update helpers where available; fall back to generic Matter updates otherwise.
+ - Add unit tests covering BLE parsing, stale-accessory behavior, mapping helpers, and lifecycle cleanup.
+ - Add `options.dailyApiResetLocalMidnight` (boolean) to control whether the daily API budget resets at local midnight (true) or UTC midnight (false, default).
+ - Fix configuration schema placement for the "Reset Daily Counter at Local Midnight" option: remove erroneous insertion inside IR remote type list and expose it correctly under platform `options`.
+
 ## [4.3.1](https://github.com/OpenWonderLabs/homebridge-switchbot/releases/tag/v4.3.1) (2025-03-04)
 
 # *No New Releases During Lent*

package/README.md

@@ -52,16 +52,13 @@
 ## Troubleshooting
 
 - ### If using Linux / Raspberry Pi OS
-
   1. `bluetoothctl` must be installed on the device, otherwise it cannot communicate via Bluetooth. Enable it with `sudo bluetoothctl power on`.
 
   2. If errors occur, while enabling it, restart the process:
-
      - `rfkill block bluetooth`
      - `rfkill unblock bluetooth`
 
   3. Also make sure, that the computer can discover the SwitchBot device:
-
      - `sudo bluetoothctl`
      - `scan on`
 
@@ -218,6 +215,51 @@
     - Supports Fan Device Type
   - Allows for On/Off Controls
 
+## Matter Platform
+
+### Batched refresh and API load control
+
+By default, the Matter platform uses a single batched refresh to update device status. You can tune or override this behavior with the following options under `options`:
+
+- `matterBatchEnabled` (boolean, default true): enable/disable platform-level batched refresh. Devices with a per-device `refreshRate` still run their own timers.
+- `matterBatchRefreshRate` (number, seconds): batch interval (falls back to `options.refreshRate`, then 300 if not set).
+- `matterBatchConcurrency` (number): limit of parallel OpenAPI status calls during a batch (default 5).
+- `matterBatchJitter` (number, seconds): random startup delay before the first batch to reduce synchronized spikes.
+
+Device-level override:
+
+- If a device sets `refreshRate` in its config, it uses a per-device timer and is excluded from the platform batch.
+
+Reliability and rate-limiting:
+
+- Each device status call retries with exponential backoff on non-success responses.
+- After exhausting retries, the device enters a short cooldown before being retried; cooldowns are persisted across restarts.
+- The batch worklist is randomized every cycle to further distribute API load.
+
+These controls keep API usage smooth and predictable while preserving per-device control when needed.
+
+## OpenAPI rate limiting and daily budget
+
+To prevent hitting SwitchBot’s daily OpenAPI limit, the plugin provides several platform-level options under `options`:
+
+- `dailyApiLimit` (number, default 10000): maximum OpenAPI requests per day that the plugin will allow.
+- `dailyApiReserveForCommands` (number, default 1000): requests reserved for user actions so background polling pauses before the hard limit.
+- `webhookOnlyOnReserve` (boolean, default false): when remaining budget reaches the reserve, pause background polling/discovery; webhooks and commands continue until the hard limit.
+- `dailyApiResetLocalMidnight` (boolean, default false): if true, resets the daily counter at local midnight; when false, resets at UTC midnight.
+
+Example (excerpt):
+
+```json
+{
+  "options": {
+    "dailyApiLimit": 10000,
+    "dailyApiReserveForCommands": 1000,
+    "webhookOnlyOnReserve": false,
+    "dailyApiResetLocalMidnight": true
+  }
+}
+```
+
 ## SwitchBot APIs
 
 - [OpenWonderLabs/node-switchbot](https://github.com/OpenWonderLabs/node-switchbot)