@switchbot/homebridge-switchbot 5.0.0-beta.70 → 5.0.0-beta.72

package/package.json

@@ -2,7 +2,7 @@
   "name": "@switchbot/homebridge-switchbot",
   "displayName": "SwitchBot",
   "type": "module",
-  "version": "5.0.0-beta.70",
+  "version": "5.0.0-beta.72",
   "description": "The SwitchBot plugin allows you to access your SwitchBot device(s) from HomeKit.",
   "author": "SwitchBot <support@wondertechlabs.com> (https://github.com/SwitchBot)",
   "contributors": [
@@ -58,12 +58,15 @@
     "homebridge": "^2.0.0-beta.50",
     "node": "^20 || ^22 || ^24"
   },
+  "directories": {
+    "doc": "docs"
+  },
   "scripts": {
     "check": "npm install && npm outdated",
     "lint": "eslint src/**/*.ts",
     "lint:fix": "eslint src/**/*.ts --fix",
     "watch": "npm run build && npm run plugin-ui && npm link && nodemon",
-    "plugin-ui": "rsync ./src/homebridge-ui/public/index.html ./dist/homebridge-ui/public/",
+    "plugin-ui": "mkdir -p ./dist/homebridge-ui/public && if [ -d ./src/homebridge-ui/public ]; then rsync -a ./src/homebridge-ui/public/ ./dist/homebridge-ui/public/; fi",
     "build": "npm run clean && tsc && npm run plugin-ui",
     "prepublishOnly": "npm run lint && npm run build && npm run plugin-ui && npm run docs && npm run docs:lint",
     "postpublish": "npm run clean && npm ci",
@@ -74,40 +77,38 @@
     "docs": "typedoc",
     "docs:lint": "typedoc --emit none --treatWarningsAsErrors"
   },
+  "bin": {},
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@homebridge/plugin-ui-utils": "^2.1.1-beta.0",
+    "@homebridge/plugin-ui-utils": "^2.2.0",
     "async-mqtt": "^2.6.3",
     "fakegato-history": "^0.6.7",
-    "homebridge-lib": "^7.1.12",
-    "node-switchbot": "^3.6.0",
+    "homebridge-lib": "^7.3.1",
+    "node-switchbot": "^4.0.0-beta.1",
     "rxjs": "^7.8.2"
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^6.2.0",
+    "@antfu/eslint-config": "^6.7.3",
     "@types/aes-js": "^3.1.4",
     "@types/debug": "^4.1.12",
     "@types/fs-extra": "^11.0.4",
     "@types/mdast": "^4.0.4",
-    "@types/node": "^24.10.0w",
+    "@types/node": "^24.11.0",
     "@types/semver": "^7.7.1",
     "@types/source-map-support": "^0.5.10",
-    "@vitest/coverage-v8": "^4.0.7",
-    "eslint": "^9.39.1",
-    "eslint-plugin-format": "^1.0.2",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^9.39.3",
+    "eslint-plugin-format": "^1.5.0",
     "eslint-plugin-import": "^2.32.0",
-    "homebridge": "^2.0.0-beta.50",
-    "homebridge-config-ui-x": "^5.9.0",
-    "nodemon": "^3.1.10",
+    "homebridge": "^2.0.0-beta.76",
+    "homebridge-config-ui-x": "^5.18.0",
+    "nodemon": "^3.1.14",
     "shx": "^0.4.0",
     "ts-node": "^10.9.2",
-    "typedoc": "^0.28.14",
+    "typedoc": "^0.28.17",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.7"
-  },
-  "directories": {
-    "doc": "docs"
+    "vitest": "^4.0.18"
   }
 }

package/scripts/e2e/README.md

@@ -0,0 +1,25 @@
+# E2E scripts
+
+This folder contains small helper scripts used by the vitest E2E harness `test/e2e/run-e2e.spec.ts`.
+
+Usage
+
+- Export `HB_URL` and `HB_TOKEN` for Homebridge UI access. Optionally set `ACCESSORY_ID` or accessory-specific env vars like `LIGHT_ACCESSORY_ID`.
+- Run a single script:
+
+```bash
+export HB_URL="http://localhost:8581"
+export HB_TOKEN="<token>"
+export ACCESSORY_ID="<aid_or_uuid_or_context.deviceId>"
+bash light-e2e.sh
+```
+
+- Or run the harness via vitest:
+
+```bash
+RUN_E2E=1 npx vitest run test/e2e/run-e2e.spec.ts
+```
+
+Security
+
+- Keep the `HB_TOKEN` value secret. Use CI secret storage when running in automation.

package/scripts/e2e/curtain-e2e.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# Lightweight automated E2E helper for curtains (window coverings).
+# Usage:
+# 1) Ensure Homebridge is running and the plugin is installed/linked.
+# 2) Populate `HB_URL`, `HB_TOKEN`, and `ACCESSORY_ID` below (or export them).
+# 3) Run: `bash scripts/e2e/curtain-e2e.sh`
+
+set -euo pipefail
+
+: ${HB_URL:="http://localhost:8581"}
+: ${HB_TOKEN:=""}
+: ${ACCESSORY_ID:=""}
+: ${ACCESSORY_NAME:=""}
+
+# Resolve accessory id (aid) from Homebridge API when ACCESSORY_NAME supplied
+resolve_accessory_id() {
+  if [[ -n "$ACCESSORY_ID" ]]; then
+    return 0
+  fi
+  if [[ -z "$ACCESSORY_NAME" ]]; then
+    return 1
+  fi
+  local resp
+  resp=$(curl -sS -H "Authorization: Bearer ${HB_TOKEN}" "${HB_URL}/api/accessories") || return 1
+  ACCESSORY_ID=$(printf '%s' "$resp" | node -e "const fs=require('fs');const name=process.argv[1];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);}}}process.exit(1);" "$ACCESSORY_NAME") || return 1
+  return 0
+}
+
+if [[ -z "$HB_TOKEN" ]]; then
+  echo "Please set HB_TOKEN environment variable or edit the top of this script."
+  exit 1
+fi
+
+if [[ -z "$ACCESSORY_ID" ]]; then
+  if resolve_accessory_id; then
+    echo "Discovered ACCESSORY_ID=${ACCESSORY_ID} for name '${ACCESSORY_NAME}'"
+  else
+    echo "No ACCESSORY_ID or ACCESSORY_NAME resolved. Please set one." && exit 1
+  fi
+fi
+
+echo "Running curtain E2E script against $HB_URL (accessory $ACCESSORY_ID)"
+
+curl_common() {
+  local method="$1" path="$2" data="$3"
+  if [[ "$method" == "GET" ]]; then
+    curl -sS -H "Authorization: Bearer ${HB_TOKEN}" "${HB_URL}${path}"
+  else
+    curl -sS -X "$method" -H "Authorization: Bearer ${HB_TOKEN}" -H "Content-Type: application/json" -d "$data" "${HB_URL}${path}"
+  fi
+}
+
+echo "1) Fetch accessories listing"
+curl_common GET "/api/accessories" ""
+
+echo
+echo "2) Open (set target position to 0)"
+curl_common POST "/api/accessories/${ACCESSORY_ID}/characteristics" '{ "characteristics": [{"aid":1,"iid":12,"value":0}] }'
+sleep 1
+
+echo
+echo "3) Set position to 50%"
+curl_common POST "/api/accessories/${ACCESSORY_ID}/characteristics" '{ "characteristics": [{"aid":1,"iid":12,"value":50}] }'
+sleep 1
+
+echo
+echo "4) Close (set target position to 100)"
+curl_common POST "/api/accessories/${ACCESSORY_ID}/characteristics" '{ "characteristics": [{"aid":1,"iid":12,"value":100}] }'
+
+echo "Done. Review Homebridge logs and physical device behavior."

package/scripts/e2e/fan-e2e.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# Lightweight automated E2E helper for fans.
+# Usage:
+# 1) Ensure Homebridge is running and the plugin is installed/linked.
+# 2) Populate `HB_URL`, `HB_TOKEN`, and `ACCESSORY_ID` below (or export them).
+# 3) Run: `bash scripts/e2e/fan-e2e.sh`
+
+set -euo pipefail
+
+: ${HB_URL:="http://localhost:8581"}
+: ${HB_TOKEN:=""}
+: ${ACCESSORY_ID:=""}
+: ${ACCESSORY_NAME:=""}
+
+# Resolve accessory id (aid) from Homebridge API when ACCESSORY_NAME supplied
+resolve_accessory_id() {
+  if [[ -n "$ACCESSORY_ID" ]]; then
+    return 0
+  fi
+  if [[ -z "$ACCESSORY_NAME" ]]; then
+    return 1
+  fi
+  local resp
+  resp=$(curl -sS -H "Authorization: Bearer ${HB_TOKEN}" "${HB_URL}/api/accessories") || return 1
+  ACCESSORY_ID=$(printf '%s' "$resp" | node -e "const fs=require('fs');const name=process.argv[1];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);}}}process.exit(1);" "$ACCESSORY_NAME") || return 1
+  return 0
+}
+
+if [[ -z "$HB_TOKEN" ]]; then
+  echo "Please set HB_TOKEN environment variable or edit the top of this script."
+  exit 1
+fi
+
+if [[ -z "$ACCESSORY_ID" ]]; then
+  if resolve_accessory_id; then
+    echo "Discovered ACCESSORY_ID=${ACCESSORY_ID} for name '${ACCESSORY_NAME}'"
+  else
+    echo "No ACCESSORY_ID or ACCESSORY_NAME resolved. Please set one." && exit 1
+  fi
+fi
+
+echo "Running fan E2E script against $HB_URL (accessory $ACCESSORY_ID)"
+
+curl_common() {
+  local method="$1" path="$2" data="$3"
+  if [[ "$method" == "GET" ]]; then
+    curl -sS -H "Authorization: Bearer ${HB_TOKEN}" "${HB_URL}${path}"
+  else
+    curl -sS -X "$method" -H "Authorization: Bearer ${HB_TOKEN}" -H "Content-Type: application/json" -d "$data" "${HB_URL}${path}"
+  fi
+}
+
+echo "1) Fetch accessories listing"
+curl_common GET "/api/accessories" ""
+
+echo
+echo "2) Toggle On"
+curl_common POST "/api/accessories/${ACCESSORY_ID}/characteristics" '{ "characteristics": [{"aid":1,"iid":11,"value":true}] }'
+sleep 1
+
+echo
+echo "3) Set RotationSpeed to 50%"
+curl_common POST "/api/accessories/${ACCESSORY_ID}/characteristics" '{ "characteristics": [{"aid":1,"iid":12,"value":50}] }'
+sleep 1
+
+echo
+echo "4) Toggle Oscillation (swing)"
+curl_common POST "/api/accessories/${ACCESSORY_ID}/characteristics" '{ "characteristics": [{"aid":1,"iid":13,"value":true}] }'
+sleep 1
+
+echo
+echo "5) Toggle Off"
+curl_common POST "/api/accessories/${ACCESSORY_ID}/characteristics" '{ "characteristics": [{"aid":1,"iid":11,"value":false}] }'
+
+echo "Done. Review Homebridge logs and physical device behavior."

package/scripts/e2e/light-advanced-e2e.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# Advanced light E2E helper: exercises On/Off, Brightness steps, Color Temperature and RGB color where supported.
+# Usage:
+# 1) Ensure Homebridge is running and the plugin is installed/linked.
+# 2) Populate `HB_URL`, `HB_TOKEN`, and `ACCESSORY_ID` below (or export them).
+# 3) Run: `bash scripts/e2e/light-advanced-e2e.sh`
+
+set -euo pipefail
+
+: ${HB_URL:="http://localhost:8581"}
+: ${HB_TOKEN:=""}
+: ${ACCESSORY_ID:=""}
+: ${ACCESSORY_NAME:=""}
+
+# Resolve accessory id (aid) from Homebridge API when ACCESSORY_NAME supplied
+resolve_accessory_id() {
+  if [[ -n "$ACCESSORY_ID" ]]; then
+    return 0
+  fi
+  if [[ -z "$ACCESSORY_NAME" ]]; then
+    return 1
+  fi
+  local resp
+  resp=$(curl -sS -H "Authorization: Bearer ${HB_TOKEN}" "${HB_URL}/api/accessories") || return 1
+  ACCESSORY_ID=$(printf '%s' "$resp" | node -e "const fs=require('fs');const name=process.argv[1];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);}}}process.exit(1);" "$ACCESSORY_NAME") || return 1
+  return 0
+}
+
+if [[ -z "$HB_TOKEN" ]]; then
+  echo "Please set HB_TOKEN environment variable or edit the top of this script."
+  exit 1
+fi
+
+if [[ -z "$ACCESSORY_ID" ]]; then
+  if resolve_accessory_id; then
+    echo "Discovered ACCESSORY_ID=${ACCESSORY_ID} for name '${ACCESSORY_NAME}'"
+  else
+    echo "No ACCESSORY_ID or ACCESSORY_NAME resolved. Please set one." && exit 1
+  fi
+fi
+
+echo "Running advanced light E2E script against $HB_URL (accessory $ACCESSORY_ID)"
+
+curl_common() {
+  local method="$1" path="$2" data="$3"
+  if [[ "$method" == "GET" ]]; then
+    curl -sS -H "Authorization: Bearer ${HB_TOKEN}" "${HB_URL}${path}"
+  else
+    curl -sS -X "$method" -H "Authorization: Bearer ${HB_TOKEN}" -H "Content-Type: application/json" -d "$data" "${HB_URL}${path}"
+  fi
+}
+
+echo "1) Fetch accessories listing"
+curl_common GET "/api/accessories" ""
+
+echo
+echo "2) Toggle On"
+curl_common POST "/api/accessories/${ACCESSORY_ID}/characteristics" '{ "characteristics": [{"aid":1,"iid":11,"value":true}] }'
+sleep 1
+
+echo
+echo "3) Brightness sweep: 10% -> 50% -> 100%"
+curl_common POST "/api/accessories/${ACCESSORY_ID}/characteristics" '{ "characteristics": [{"aid":1,"iid":12,"value":10}] }'
+sleep 1
+curl_common POST "/api/accessories/${ACCESSORY_ID}/characteristics" '{ "characteristics": [{"aid":1,"iid":12,"value":50}] }'
+sleep 1
+curl_common POST "/api/accessories/${ACCESSORY_ID}/characteristics" '{ "characteristics": [{"aid":1,"iid":12,"value":100}] }'
+sleep 1
+
+echo
+echo "4) Color Temperature test (if supported): 2700K -> 4000K -> 6500K"
+# HomeKit uses Mireds for color temperature; approximate conversions used here
+MIREDS_2700=370
+MIREDS_4000=250
+MIREDS_6500=154
+curl_common POST "/api/accessories/${ACCESSORY_ID}/characteristics" "{ \"characteristics\": [{\"aid\":1,\"iid\":14,\"value\":${MIREDS_2700}}] }"
+sleep 1
+curl_common POST "/api/accessories/${ACCESSORY_ID}/characteristics" "{ \"characteristics\": [{\"aid\":1,\"iid\":14,\"value\":${MIREDS_4000}}] }"
+sleep 1
+curl_common POST "/api/accessories/${ACCESSORY_ID}/characteristics" "{ \"characteristics\": [{\"aid\":1,\"iid\":14,\"value\":${MIREDS_6500}}] }"
+sleep 1
+
+echo
+echo "5) Color (RGB) test (if supported): Red -> Green -> Blue"
+# Many HomeKit bridges expose Hue (iid 15) and Saturation (iid 16). We'll set hue and sat values accordingly.
+curl_common POST "/api/accessories/${ACCESSORY_ID}/characteristics" '{ "characteristics": [{"aid":1,"iid":15,"value":0},{"aid":1,"iid":16,"value":100}] }'
+sleep 1
+curl_common POST "/api/accessories/${ACCESSORY_ID}/characteristics" '{ "characteristics": [{"aid":1,"iid":15,"value":120},{"aid":1,"iid":16,"value":100}] }'
+sleep 1
+curl_common POST "/api/accessories/${ACCESSORY_ID}/characteristics" '{ "characteristics": [{"aid":1,"iid":15,"value":240},{"aid":1,"iid":16,"value":100}] }'
+sleep 1
+
+echo
+echo "6) Toggle Off"
+curl_common POST "/api/accessories/${ACCESSORY_ID}/characteristics" '{ "characteristics": [{"aid":1,"iid":11,"value":false}] }'
+
+echo "Done. Review Homebridge logs and physical device behavior."

package/scripts/e2e/light-e2e.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# Lightweight automated E2E helper for lights.
+# Usage:
+# 1) Ensure Homebridge is running and the plugin is installed/linked.
+# 2) Populate `HB_URL`, `HB_TOKEN`, and `ACCESSORY_ID` below (or export them).
+# 3) Run: `bash scripts/e2e/light-e2e.sh`
+
+set -euo pipefail
+
+: ${HB_URL:="http://localhost:8581"}
+: ${HB_TOKEN:=""}
+: ${ACCESSORY_ID:=""}
+: ${ACCESSORY_NAME:=""}
+
+# Resolve accessory id (aid) from Homebridge API when ACCESSORY_NAME supplied
+resolve_accessory_id() {
+  if [[ -n "$ACCESSORY_ID" ]]; then
+    return 0
+  fi
+  if [[ -z "$ACCESSORY_NAME" ]]; then
+    return 1
+  fi
+  local resp
+  resp=$(curl -sS -H "Authorization: Bearer ${HB_TOKEN}" "${HB_URL}/api/accessories") || return 1
+  ACCESSORY_ID=$(printf '%s' "$resp" | node -e "const fs=require('fs');const name=process.argv[1];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);}}}process.exit(1);" "$ACCESSORY_NAME") || return 1
+  return 0
+}
+
+if [[ -z "$HB_TOKEN" ]]; then
+  echo "Please set HB_TOKEN environment variable or edit the top of this script."
+  exit 1
+fi
+
+if [[ -z "$ACCESSORY_ID" ]]; then
+  if resolve_accessory_id; then
+    echo "Discovered ACCESSORY_ID=${ACCESSORY_ID} for name '${ACCESSORY_NAME}'"
+  else
+    echo "No ACCESSORY_ID or ACCESSORY_NAME resolved. Please set one." && exit 1
+  fi
+fi
+
+echo "Running light E2E script against $HB_URL (accessory $ACCESSORY_ID)"
+
+curl_common() {
+  local method="$1" path="$2" data="$3"
+  if [[ "$method" == "GET" ]]; then
+    curl -sS -H "Authorization: Bearer ${HB_TOKEN}" "${HB_URL}${path}"
+  else
+    curl -sS -X "$method" -H "Authorization: Bearer ${HB_TOKEN}" -H "Content-Type: application/json" -d "$data" "${HB_URL}${path}"
+  fi
+}
+
+echo "1) Fetch accessories listing (to verify connectivity)"
+curl_common GET "/api/accessories" ""
+
+echo
+echo "2) Toggle On"
+curl_common POST "/api/accessories/${ACCESSORY_ID}/characteristics" '{ "characteristics": [{"aid":1,"iid":11,"value":true}] }'
+sleep 1
+
+echo
+echo "3) Set Brightness to 25%"
+curl_common POST "/api/accessories/${ACCESSORY_ID}/characteristics" '{ "characteristics": [{"aid":1,"iid":12,"value":25}] }'
+sleep 1
+
+echo
+echo "4) Set Brightness to 100%"
+curl_common POST "/api/accessories/${ACCESSORY_ID}/characteristics" '{ "characteristics": [{"aid":1,"iid":12,"value":100}] }'
+sleep 1
+
+echo
+echo "5) Toggle Off"
+curl_common POST "/api/accessories/${ACCESSORY_ID}/characteristics" '{ "characteristics": [{"aid":1,"iid":11,"value":false}] }'
+
+echo "Done. Review Homebridge logs and physical device behavior."

package/scripts/e2e/list-accessories.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# List accessories from Homebridge UI and print name, aid/UUID, and context.deviceId
+# Usage:
+#   export HB_URL=http://localhost:8581
+#   export HB_TOKEN=your_token
+#   bash scripts/e2e/list-accessories.sh
+
+set -euo pipefail
+
+: ${HB_URL:="http://localhost:8581"}
+: ${HB_TOKEN:=""}
+
+if [[ -z "$HB_TOKEN" ]]; then
+  echo "Please set HB_TOKEN environment variable (Homebridge UI token)."
+  exit 1
+fi
+
+resp=$(curl -sS -H "Authorization: Bearer ${HB_TOKEN}" "${HB_URL}/api/accessories")
+node -e "const fs=require('fs');const j=JSON.parse(fs.readFileSync(0,'utf8'));const arr=Array.isArray(j)?j:(j.accessories||j)||[];console.log('Name | aid/UUID | context.deviceId');for(const a of arr){const name=a.displayName||a.name||'(unknown)';const id=a.aid||a.UUID||'';const ctx=(a.context&&a.context.deviceId)||'';console.log(`${name} | ${id} | ${ctx}`);}" <<< "$resp"

package/scripts/e2e/lock-e2e.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# Lightweight automated E2E helper for locks.
+# Usage:
+# 1) Ensure Homebridge is running and the plugin is installed/linked.
+# 2) Populate `HB_URL`, `HB_TOKEN`, and `ACCESSORY_ID` below (or export them).
+# 3) Run: `bash scripts/e2e/lock-e2e.sh`
+
+set -euo pipefail
+
+: ${HB_URL:="http://localhost:8581"}
+: ${HB_TOKEN:=""}
+: ${ACCESSORY_ID:=""}
+: ${ACCESSORY_NAME:=""}
+
+# Resolve accessory id (aid) from Homebridge API when ACCESSORY_NAME supplied
+resolve_accessory_id() {
+  if [[ -n "$ACCESSORY_ID" ]]; then
+    return 0
+  fi
+  if [[ -z "$ACCESSORY_NAME" ]]; then
+    return 1
+  fi
+  local resp
+  resp=$(curl -sS -H "Authorization: Bearer ${HB_TOKEN}" "${HB_URL}/api/accessories") || return 1
+  ACCESSORY_ID=$(printf '%s' "$resp" | node -e "const fs=require('fs');const name=process.argv[1];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);}}}process.exit(1);" "$ACCESSORY_NAME") || return 1
+  return 0
+}
+
+if [[ -z "$HB_TOKEN" ]]; then
+  echo "Please set HB_TOKEN environment variable or edit the top of this script."
+  exit 1
+fi
+
+if [[ -z "$ACCESSORY_ID" ]]; then
+  if resolve_accessory_id; then
+    echo "Discovered ACCESSORY_ID=${ACCESSORY_ID} for name '${ACCESSORY_NAME}'"
+  else
+    echo "No ACCESSORY_ID or ACCESSORY_NAME resolved. Please set one." && exit 1
+  fi
+fi
+
+echo "Running lock E2E script against $HB_URL (accessory $ACCESSORY_ID)"
+
+curl_common() {
+  local method="$1" path="$2" data="$3"
+  if [[ "$method" == "GET" ]]; then
+    curl -sS -H "Authorization: Bearer ${HB_TOKEN}" "${HB_URL}${path}"
+  else
+    curl -sS -X "$method" -H "Authorization: Bearer ${HB_TOKEN}" -H "Content-Type: application/json" -d "$data" "${HB_URL}${path}"
+  fi
+}
+
+echo "1) Fetch accessories listing"
+curl_common GET "/api/accessories" ""
+
+echo
+echo "2) Lock"
+curl_common POST "/api/accessories/${ACCESSORY_ID}/characteristics" '{ "characteristics": [{"aid":1,"iid":11,"value":1}] }'
+sleep 1
+
+echo
+echo "3) Unlock"
+curl_common POST "/api/accessories/${ACCESSORY_ID}/characteristics" '{ "characteristics": [{"aid":1,"iid":11,"value":0}] }'
+
+echo "Done. Review Homebridge logs and physical device behavior."

package/scripts/generate-matter-maps.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+const fs = require('fs')
+const path = require('path')
+
+function usage() {
+  console.error('Usage: node scripts/generate-matter-maps.js <input-json> [output-file]')
+  process.exit(2)
+}
+
+const input = process.argv[2]
+const outFile = process.argv[3] || path.join(__dirname, '..', 'src', 'matter-maps.generated.ts')
+
+if (!input) usage()
+if (!fs.existsSync(input)) {
+  console.error('Input file not found:', input)
+  process.exit(2)
+}
+
+const json = JSON.parse(fs.readFileSync(input, 'utf8'))
+
+// Expecting structure: { clusters: [{ name, id, attributes: [{ name, id }, ...] }, ...] }
+const clusters = json.clusters || []
+
+const clusterMapEntries = []
+const attrGroups = {}
+
+for (const c of clusters) {
+  if (!c.name || typeof c.id === 'undefined') continue
+  const key = c.name.replace(/[^A-Za-z0-9_]/g, '')
+  clusterMapEntries.push(`  ${key}: 0x${parseInt(String(c.id), 10).toString(16)}`)
+  const attrs = {}
+  if (Array.isArray(c.attributes)) {
+    for (const a of c.attributes) {
+      if (!a.name || typeof a.id === 'undefined') continue
+      const an = a.name.replace(/[^A-Za-z0-9_]/g, '')
+      attrs[an] = `0x${parseInt(String(a.id), 10).toString(16)}`
+    }
+  }
+  if (Object.keys(attrs).length) attrGroups[key] = attrs
+}
+
+const clusterMap = `export const MATTER_CLUSTER_IDS = {
+${clusterMapEntries.join(',\n')}
+} as const
+\n`
+
+let attrText = 'export const MATTER_ATTRIBUTE_IDS = {\n'
+for (const [k, v] of Object.entries(attrGroups)) {
+  attrText += `  ${k}: {\n`
+  for (const [an, aid] of Object.entries(v)) {
+    attrText += `    ${an}: ${aid},\n`
+  }
+  attrText += `  },\n`
+}
+attrText += `} as const\n`
+
+const fileContent = `// GENERATED FILE - do not edit by hand.\n// Run: node scripts/generate-matter-maps.js <zap-matter.json>\n\n${clusterMap}\n${attrText}`
+
+fs.writeFileSync(outFile, fileContent, 'utf8')
+console.log('Wrote', outFile)

package/scripts/run-e2e-local.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# Wrapper to run the repository's E2E vitest harness locally.
+# Usage: export HB_URL HB_TOKEN [LIGHT_ACCESSORY_ID ...]; export RUN_E2E=1; bash scripts/run-e2e-local.sh
+
+set -euo pipefail
+
+: ${RUN_E2E:=1}
+
+echo "Running E2E vitest harness (RUN_E2E=${RUN_E2E})"
+
+# Run only the e2e spec file so the full unit test suite isn't executed
+npx vitest run test/e2e/run-e2e.spec.ts
+
+echo "E2E harness finished. Check logs for per-script output."