@switchbot/homebridge-switchbot 5.0.0-beta.11 → 5.0.0-beta.111

package/.github/ISSUE_TEMPLATE/e2e-verification.md

@@ -0,0 +1,36 @@
+---
+name: E2E Verification Results
+about: Submit manual E2E test results for homebridge-switchbot changes (Matter + node-switchbot v4)
+title: "[E2E] <device-type> verification"
+labels: e2e, testing
+assignees: ''
+---
+
+### Environment
+- Homebridge version:
+- Plugin commit / branch:
+- macOS version:
+- Bluetooth available: (yes/no)
+- openApiToken used: (yes/no)
+
+### Device under test
+- Device type: (Light / Fan / Curtain / Lock)
+- Device model:
+- Connection used: (BLE / OpenAPI)
+
+### Steps performed
+- Start Homebridge with plugin linked/built
+- Verified Matter registration: (yes/no)
+- Verified HAP fallback when Matter unavailable: (yes/no)
+- Operations tested: (list)
+
+### Results
+- Observed behavior (brief):
+- Any errors in plugin logs (paste relevant snippets):
+
+### Verdict
+- Pass/Fail:
+- Notes and follow-ups:
+
+### Attachments
+- Logs, screenshots, videos

package/.github/copilot-instructions.md

@@ -2,6 +2,45 @@
 
 Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
 
+## Topic-Based Reference Priority
+
+When a prompt includes the topics below, consult these upstream references first before implementation decisions.
+
+### Matter (keyword examples: "Matter", "child bridge", "cluster", "conformance")
+
+Primary references:
+- https://github.com/homebridge-plugins/homebridge-matter
+- https://github.com/homebridge/homebridge/ - only if latest is 2.0.0 or later and contains Matter-related code or reference: 
+   - https://github.com/homebridge/homebridge/tree/beta-2.0.0/
+- https://github.com/matter-js/matter.js
+
+Usage rule:
+- For Matter behavior, conformance, clustering, or registration logic, align implementation with these references before applying local changes.
+
+### SwitchBot BLE (keyword examples: "BLE", "Bluetooth", "RSSI", "advertisement", "scan")
+
+Primary references:
+- https://github.com/OpenWonderLabs/SwitchBotAPI-BLE
+- https://github.com/sblibs/pySwitchbot
+
+Usage rule:
+- For BLE command/state/scan behavior, prefer these references for protocol expectations and payload shape.
+
+### SwitchBot OpenAPI (keyword examples: "OpenAPI", "cloud API", "device list", "command")
+
+Primary reference:
+- https://github.com/OpenWonderLabs/SwitchBotAPI
+
+Usage rule:
+- For OpenAPI device models, commands, and response fields, prioritize this reference for compatibility.
+
+### Conflict Resolution
+
+If references conflict:
+1. Prefer official upstream docs/API specs.
+2. Keep existing plugin behavior unless a clear bug is identified.
+3. Document any intentional deviation in PR notes.
+
 ## Branch Targeting Strategy
 
 When creating pull requests, ALWAYS follow this branch targeting strategy:

package/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: ["main", "latest", "beta-*"]
+  pull_request:
+    branches: ["main", "latest"]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20, 22]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci --legacy-peer-deps
+
+      - name: Build
+        run: npm run build
+
+      - name: Run tests
+        run: npm run test

package/.github/workflows/manual-e2e.yml

@@ -0,0 +1,115 @@
+name: Manual E2E (build + optional E2E)
+
+on:
+  workflow_dispatch:
+    inputs:
+      run_e2e:
+        description: 'Set to true to run the E2E scripts (requires network-accessible Homebridge and valid tokens)'
+        required: false
+        default: 'false'
+      hb_url:
+        description: 'Homebridge UI URL (e.g. http://host:8581)'
+        required: false
+      hb_token:
+        description: 'Homebridge UI token (store as secret or pass here)'
+        required: false
+      light_accessory_id:
+        description: 'Accessory ID for light (when running E2E)'
+        required: false
+      fan_accessory_id:
+        description: 'Accessory ID for fan (when running E2E)'
+        required: false
+      curtain_accessory_id:
+        description: 'Accessory ID for curtain (when running E2E)'
+        required: false
+      lock_accessory_id:
+        description: 'Accessory ID for lock (when running E2E)'
+        required: false
+      light_accessory_name:
+        description: 'Accessory display name for light (optional, used to resolve ID)'
+        required: false
+      fan_accessory_name:
+        description: 'Accessory display name for fan (optional, used to resolve ID)'
+        required: false
+      curtain_accessory_name:
+        description: 'Accessory display name for curtain (optional, used to resolve ID)'
+        required: false
+      lock_accessory_name:
+        description: 'Accessory display name for lock (optional, used to resolve ID)'
+        required: false
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+
+      - name: Install dependencies
+        run: npm ci --prefer-offline --no-audit --progress=false
+
+      - name: Build
+        run: npm run build
+
+      - name: Run unit tests
+        run: npm run test
+
+      - name: "Optional: Run E2E scripts"
+        if: ${{ github.event.inputs.run_e2e == 'true' }}
+        env:
+          HB_URL: ${{ github.event.inputs.hb_url }}
+          HB_TOKEN: ${{ github.event.inputs.hb_token }}
+          LIGHT_ACCESSORY_ID: ${{ github.event.inputs.light_accessory_id }}
+          FAN_ACCESSORY_ID: ${{ github.event.inputs.fan_accessory_id }}
+          CURTAIN_ACCESSORY_ID: ${{ github.event.inputs.curtain_accessory_id }}
+          LOCK_ACCESSORY_ID: ${{ github.event.inputs.lock_accessory_id }}
+          LIGHT_ACCESSORY_NAME: ${{ github.event.inputs.light_accessory_name }}
+          FAN_ACCESSORY_NAME: ${{ github.event.inputs.fan_accessory_name }}
+          CURTAIN_ACCESSORY_NAME: ${{ github.event.inputs.curtain_accessory_name }}
+          LOCK_ACCESSORY_NAME: ${{ github.event.inputs.lock_accessory_name }}
+        run: |
+          echo "Running E2E scripts on runner ($HB_URL) - ensure the runner can access Homebridge and devices"
+          # resolve accessory IDs from names when IDs not provided
+          echo "Resolving accessory IDs from names (if provided)..."
+          rm -f resolved_ids.env || true
+          touch resolved_ids.env
+
+          resolve() {
+            idvar="$1"
+            namevar="$2"
+            nameval="$(eval echo \"\$$namevar\")"
+            idval="$(eval echo \"\$$idvar\")"
+            if [[ -z "$idval" && -n "$nameval" ]]; then
+              resp=$(curl -sS -H "Authorization: Bearer ${HB_TOKEN}" "${HB_URL}/api/accessories" || true)
+              found=$(printf '%s' "$resp" | node -e "const fs=require('fs');const name=process.argv[1];try{const j=JSON.parse(fs.readFileSync(0,'utf8'));const arr=Array.isArray(j)?j:(j.accessories||j)||[];for(const a of arr){if(a.displayName===name||a.name===name||(a.context&&a.context.deviceId===name)){if(a.aid){console.log(a.aid);process.exit(0);}else if(a.UUID){console.log(a.UUID);process.exit(0);}}} }catch(e){}" "$nameval" )
+              if [[ -n "$found" ]]; then
+                echo "Resolved $idvar=$found"
+                echo "$idvar=$found" >> resolved_ids.env
+                export "$idvar"="$found"
+              else
+                echo "Could not resolve $namevar='$nameval' to an id"
+              fi
+            fi
+          }
+
+          resolve LIGHT_ACCESSORY_ID LIGHT_ACCESSORY_NAME
+          resolve FAN_ACCESSORY_ID FAN_ACCESSORY_NAME
+          resolve CURTAIN_ACCESSORY_ID CURTAIN_ACCESSORY_NAME
+          resolve LOCK_ACCESSORY_ID LOCK_ACCESSORY_NAME
+
+          # set RUN_E2E so the conditional Vitest harness executes
+          export RUN_E2E=true
+          npm run test
+
+      - name: Upload logs (if any)
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-logs
+          path: |
+            test-output.log

package/.github/workflows/release.yml

@@ -22,8 +22,6 @@ jobs:
     with:
       release_type: ${{ needs.determine-release-type.outputs.release_type }}
       is_esm: ${{ needs.determine-release-type.outputs.is_esm == 'true' }}
-    secrets:
-      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
 
   # 3️⃣ Publish to NPM and create GitHub release
   publish-release:
@@ -48,8 +46,6 @@ jobs:
       branch_name: ${{ needs.determine-release-type.outputs.branch_name }}
       release_type: ${{ needs.determine-release-type.outputs.release_type }}
       is_esm: ${{ needs.determine-release-type.outputs.is_esm == 'true' }}
-    secrets:
-      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
 
   # 5️⃣ Notify if any previous job fails
   workflow-failure:

package/CHANGELOG.md

@@ -1,7 +1,42 @@
 # Changelog
 
+## Unreleased — beta-4.3.3
+
+### Added
+- Matter support (child-bridge) with Matter-first registration and HAP fallback.
+- Hybrid `node-switchbot@4` client adapter (BLE + OpenAPI) with OpenAPI fallback.
+- Manual and automated E2E scripts for lights, fans, curtains, and locks (`scripts/e2e/*`).
+- Conditional Vitest E2E harness (`RUN_E2E=true`) and a manual GitHub Actions workflow to run E2E.
+
+### Changed
+- Centralized Matter cluster/attribute numeric ID maps in `src/utils.ts`.
+- Device descriptors refactored to use canonical Matter IDs.
+- OpenAPI fallback hardened with timeouts, retries, backoff, and per-device retry limits.
+
+### Tests
+- Added integration tests and a Matter test harness under `test/`.
+
+### Notes
+- This is a beta release; follow migration notes in MIGRATION.md before upgrading.
+# Changelog
+
 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/E2E-VERIFICATION.md

@@ -0,0 +1,121 @@
+# Manual End-to-End Verification
+
+This guide walks through manual end-to-end verification for representative devices (light, fan, curtain, lock) across BLE and OpenAPI paths, and verifies Matter-first behavior with HAP fallback.
+
+## Prerequisites
+
+- macOS with Bluetooth (for BLE verification)
+- Local development environment set up (Node.js, npm)
+- Homebridge installed locally or available (for running a test instance)
+- SwitchBot devices available (at least one light, one fan, one curtain, one lock) OR corresponding cloud-hub access
+- `openApiToken` when testing OpenAPI path
+
+## Quick setup
+
+1. Install dependencies:
+
+```bash
+npm install --legacy-peer-deps
+```
+
+2. Build the plugin:
+
+```bash
+npm run build
+```
+
+3. Recommended: run the watch task which links the plugin and restarts on changes (requires a local Homebridge installation):
+
+```bash
+npm run watch
+```
+
+Alternative (manual linking):
+
+```bash
+npm run build && npm link
+# then run your Homebridge instance (system/homebridge UI) so it picks up the linked plugin
+```
+
+## Example platform config snippets
+
+OpenAPI (cloud) path — enable Matter preference:
+
+```json
+{
+  "platform": "SwitchBot",
+  "openApiToken": "<YOUR_OPENAPI_TOKEN>",
+  "enableMatter": true,
+  "preferMatter": true
+}
+```
+
+BLE (direct) path — specify device by MAC address and prefer Matter:
+
+```json
+{
+  "platform": "SwitchBot",
+  "devices": [
+    { "deviceId": "AA:BB:CC:DD:EE:FF", "type": "Light" }
+  ],
+  "enableMatter": true,
+  "preferMatter": true
+}
+```
+
+## Verification checklist
+
+Run the steps below for each device type; repeat once using BLE and once using OpenAPI (where applicable).
+
+- Start Homebridge (with the plugin linked) and verify the plugin logs indicate Matter registration attempt.
+  - Look for log lines: `Attempting Matter registration for ...` or `Homebridge Matter API not available; will fallback to HAP`.
+- Confirm accessories are registered in Matter (if Homebridge Matter child-bridge present) or appear as HAP accessories otherwise.
+
+Device-specific tests
+
+- Light
+  - Toggle On/Off from Home app (or Homebridge UI) and confirm device responds.
+  - Set brightness to 25%, 50%, 100% and confirm device reports matching levels.
+  - If supported, change color temperature and/or color; confirm device applies new values.
+
+- Fan
+  - Toggle On/Off and verify.
+  - Change rotation speed in steps (e.g., 25%, 50%, 100%).
+  - Toggle oscillation / swing and verify position changes.
+
+- Curtain
+  - Open and Close via Home app / controller and verify movement.
+  - Set specific position (e.g., 50%) and verify accurate reporting.
+
+- Lock
+  - Lock and Unlock from controller and verify state.
+  - If lock user management supported, add/remove a test user per plugin UI and verify expected behavior.
+
+## Logs & debugging
+
+- Enable verbose logs from Homebridge or the plugin. Example: start Homebridge with a higher log level, or watch console output from `npm run watch`.
+- Capture logs while you perform each operation; note the request path used by the plugin:
+  - For OpenAPI: logs will show `https://api.switch-bot.com/v1.0/...` calls.
+  - For BLE: logs will show local device discovery / BLE connect attempts.
+
+## Run validation script (optional)
+
+You can run the TypeScript build and unit tests to confirm the codebase is healthy before manual tests:
+
+```bash
+npm run build && npm run test
+```
+
+## Expected outcomes
+
+- Matter-first registration: when Homebridge Matter API is available and `enableMatter` is true, accessories should be registered as Matter child-bridge accessories and re-used if restored from cache.
+- HAP fallback: when Matter API is not available, the plugin must continue to register HAP accessories and reuse restored accessories by `accessory.context.deviceId`.
+- Hybrid client paths: when `openApiToken` present the plugin should prefer OpenAPI for devices reachable via cloud; when BLE is available and configured the plugin should connect directly via BLE.
+- Logs should show robust retry attempts for transient network errors and per-device retry throttling if configured.
+
+## Next steps I can take
+
+- Create small automated verification scripts that use the Homebridge API test harness to toggle characteristic values (requires more test harness code).
+- Generate a printable checklist or a GitHub issue template for manual verification results.
+
+If you want, I can add the automated verification scripts now — would you prefer a simple script that exercises On/Off and Brightness for lights, or a broader script covering all device types?

package/MIGRATION.md

@@ -0,0 +1,44 @@
+# Migration notes — v4.3.x → beta
+
+This document highlights important changes and recommended actions before upgrading to the beta containing Matter and `node-switchbot@4` support.
+
+1. Matter-first behavior
+   - The plugin will prefer registering accessories with Homebridge's Matter child-bridge when `enableMatter: true` and the Homebridge Matter API is available.
+   - If Matter is not available, the plugin falls back to HAP and will reuse restored accessories by `accessory.context.deviceId`.
+
+2. Configuration keys
+   - `enableMatter` (boolean) — enable Matter child-bridge registration.
+   - `preferMatter` (boolean) — prefer Matter for devices that support Matter descriptors; HAP fallback still available.
+   - `openApiToken` (string) — when present the plugin may prefer OpenAPI calls for cloud-reachable devices.
+   - `perDeviceMaxRetries`, `requestTimeout`, `maxRetries` — network retry/timing options for OpenAPI fallback.
+
+   - `writeDebounceMs` (number, milliseconds, default 100) — global write coalescing debounce window. Commands sent to the same device within this window are coalesced (last-write-wins) to reduce duplicate network/API commands. Set to `0` to disable coalescing if you require immediate, per-command delivery.
+
+3. Hybrid client
+   - The plugin dynamically imports `node-switchbot` when available and falls back to OpenAPI when an `openApiToken` is configured.
+   - If you rely on BLE-only operation, ensure devices and the host have BLE available.
+
+4. UI changes
+   - A small plugin UI was added; it's only enabled/copied into `dist/homebridge-ui` when `npm run build` is run and the UI files exist in `src/homebridge-ui/public`.
+
+   - The UI is always served when Homebridge UI support is present; there is no opt-out flag in the platform config. The server-side guard that previously allowed disabling the UI has been removed—if you need to restrict access, manage it via Homebridge UI / host network access controls.
+
+5. Tests and verification
+   - Manual E2E scripts are provided in `scripts/e2e/` and a GitHub `workflow_dispatch` job can optionally run them against a reachable Homebridge.
+   - Run the local test suite before upgrading to confirm TypeScript and unit tests pass: `npm run build && npm run test`.
+
+6. Rollback plan
+   - If the beta causes issues, revert to the previous stable plugin version by reinstalling the prior package or checking out the stable branch.
+
+7. Regenerating Matter ID maps
+
+- A helper script `scripts/generate-matter-maps.js` is included to generate `src/matter-maps.generated.ts` from official zap/matter JSON metadata. The script expects a JSON input with a `clusters` array and will write mapped `MATTER_CLUSTER_IDS` and `MATTER_ATTRIBUTE_IDS` constants.
+- Usage example:
+
+```bash
+node scripts/generate-matter-maps.js ./zap-matter.json
+```
+
+Place the official metadata JSON as `zap-matter.json` at the repo root (or pass a path) and commit the generated `src/matter-maps.generated.ts` to keep maps up to date.
+
+If you want, I can open a PR with these notes and the changelog stub targeting a beta branch I create next.

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,62 @@
     - 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.
+
+## What's new in the v4 beta (summary)
+
+- Matter-first: when Homebridge Matter is available the plugin now prefers registering Matter accessories (with HAP fallback).
+- Hybrid client: the plugin dynamically imports `node-switchbot@4` if available and falls back to OpenAPI when `openApiToken` is configured.
+- UI always served: the plugin UI is packaged into `dist/homebridge-ui` and is always served when Homebridge UI support is present; there is no platform-level opt-out.
+- OpenAPI hardening: OpenAPI calls have AbortController timeouts, jittered exponential backoff, per-device retry limits and cooldowns, and safe response parsing for resilient behavior.
+
+- Write coalescing (debounce): command writes to the same device are coalesced by default to avoid command floods. Configure with `writeDebounceMs` (milliseconds, default 100). Set to `0` to disable coalescing.
+
+See `MIGRATION.md` for migration notes and recommended upgrade steps.
+
+## 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)