@switchbot/homebridge-switchbot 5.1.0-beta.9 → 5.1.0

package/src/{Platform.Matter.ts → SwitchBotMatterPlatform.ts}

@@ -1,11 +1,10 @@
-import type { API, Logger, PlatformConfig } from 'homebridge'
-
 import type { SwitchBotPluginConfig } from './settings.js'
+import type { API, Logger, PlatformConfig } from 'homebridge'
 
 import { createDevice } from './deviceFactory.js'
 import { PLATFORM_NAME, PLUGIN_NAME } from './settings.js'
 import { SwitchBotClient } from './switchbotClient.js'
-import { createMatterHandlers, DEVICE_MATTER_CLUSTERS, DEVICE_MATTER_SUPPORTED, normalizeTypeForMatter, resolveExternalPublishProtocol, resolveMatterDeviceType } from './utils.js'
+import { createMatterHandlers, DEVICE_MATTER_CLUSTERS, DEVICE_MATTER_SUPPORTED, normalizeTypeForMatter, resolveMatterDeviceType } from './utils.js'
 
 /**
  * Homebridge platform class for SwitchBot Matter integration.
@@ -114,7 +113,7 @@ export class SwitchBotMatterPlatform {
     }
 
     const devices = (this.config as any)?.devices ?? []
-    const createdDevices: { created: any, d: any, type: string, useMatter: boolean, matterAvailable: boolean, externalPublishProtocol: 'none' | 'hap' | 'matter' }[] = []
+    const createdDevices: { created: any, d: any, type: string, useMatter: boolean, matterAvailable: boolean }[] = []
     for (const raw of devices) {
       // Normalize config keys from UI schema to internal shape (for cross-platform consistency)
       const d: any = {
@@ -126,7 +125,6 @@ export class SwitchBotMatterPlatform {
         _raw: raw,
       }
       const type: string = normalizeTypeForMatter(d.type)
-      const externalPublishProtocol = resolveExternalPublishProtocol(raw)
       const deviceOpts: any = { id: d.id, type, name: d.name, encryptionKey: d.encryptionKey, keyId: d.keyId, log: this.log }
       this.log.debug(`[Matter/Debug] Device options for ${d.name ?? d.id}:`, JSON.stringify(deviceOpts, null, 2))
       const matterSupported = !!DEVICE_MATTER_SUPPORTED[(type || '').toLowerCase()]
@@ -136,7 +134,7 @@ export class SwitchBotMatterPlatform {
       try {
         const created = await createDevice(deviceOpts, this.config, useMatter)
         this.devices.push(created)
-        createdDevices.push({ created, d, type, useMatter, matterAvailable, externalPublishProtocol })
+        createdDevices.push({ created, d, type, useMatter, matterAvailable })
         if (useMatter) {
           this.log.info(`Prepared Matter accessory for ${d.id} (${type})${matterAvailable ? ' (auto-detected)' : ' (manually enabled)'}`)
         } else {
@@ -181,15 +179,14 @@ export class SwitchBotMatterPlatform {
    * If the Homebridge Matter API is not available, registration is skipped and a log message is emitted.
    * Accessories that are not enabled for Matter are ignored.
    */
-  async registerMatterAccessories(createdDevices: { created: any, d: any, type: string, useMatter: boolean, matterAvailable: boolean, externalPublishProtocol: 'none' | 'hap' | 'matter' }[]): Promise<void> {
+  async registerMatterAccessories(createdDevices: { created: any, d: any, type: string, useMatter: boolean, matterAvailable: boolean }[]): Promise<void> {
     if (!this.api || !(this.api as any).matter || typeof (this.api as any).matter.registerPlatformAccessories !== 'function') {
       this.log.info('Homebridge Matter API not available; skipping Matter accessory registration')
       return
     }
     const matterApi = (this.api as any).matter
     const accessoriesToRegister: any[] = []
-    const externalAccessoriesToPublish: any[] = []
-    for (const { created, d, type, useMatter, matterAvailable, externalPublishProtocol } of createdDevices) {
+    for (const { created, d, type, useMatter, matterAvailable } of createdDevices) {
       // Only register accessories where Matter is enabled and supported
       if (!useMatter) {
         // Log reason for skipping registration
@@ -240,11 +237,7 @@ export class SwitchBotMatterPlatform {
             handlers: createdDesc.handlers || createMatterHandlers(this.log, d.id, type, (this.config as any)?._client) || undefined,
             context: { deviceId: d.id, type, created: true },
           }
-          if (externalPublishProtocol === 'matter') {
-            externalAccessoriesToPublish.push(accessory)
-          } else {
-            accessoriesToRegister.push(accessory)
-          }
+          accessoriesToRegister.push(accessory)
           this.accessories.set(uuid, accessory)
         } else {
           // Ensure context and update properties for restored accessory
@@ -267,11 +260,7 @@ export class SwitchBotMatterPlatform {
           accessory.handlers = createdDesc.handlers || createMatterHandlers(this.log, d.id, type, (this.config as any)?._client) || undefined
           accessory.displayName = createdDesc.name || d.name || type
           accessory.UUID = accessory.UUID || accessory.uuid || uuid
-          if (externalPublishProtocol === 'matter') {
-            externalAccessoriesToPublish.push(accessory)
-          } else {
-            accessoriesToRegister.push(accessory)
-          }
+          accessoriesToRegister.push(accessory)
           this.accessories.set(accessory.UUID || uuid, accessory)
         }
         this.log.info(`Created/updated Matter accessory ${d.id} (${type})`)
@@ -289,49 +278,6 @@ export class SwitchBotMatterPlatform {
     } else {
       this.log.info('No Matter accessories to register')
     }
-    if (externalAccessoriesToPublish.length > 0) {
-      try {
-        if (typeof matterApi.publishExternalAccessories === 'function') {
-          await matterApi.publishExternalAccessories(PLUGIN_NAME, externalAccessoriesToPublish)
-          this.log.info(`Published ${externalAccessoriesToPublish.length} Matter external accessory(ies) with Homebridge`)
-        } else if (typeof matterApi.registerExternalAccessories === 'function') {
-          await matterApi.registerExternalAccessories(PLUGIN_NAME, PLATFORM_NAME, externalAccessoriesToPublish)
-          this.log.info(`Registered ${externalAccessoriesToPublish.length} Matter external accessory(ies) with Homebridge`)
-        } else if (await this.publishMatterExternalAccessories(externalAccessoriesToPublish)) {
-          this.log.info(`Published ${externalAccessoriesToPublish.length} Matter external accessory(ies) with Homebridge`)
-        } else {
-          this.log.warn('Matter external accessory publishing API not available; falling back to regular platform registration')
-          await matterApi.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, externalAccessoriesToPublish)
-          this.log.info(`Registered ${externalAccessoriesToPublish.length} Matter accessory(ies) as fallback (external publishing unavailable)`)
-        }
-      } catch (e) {
-        this.log.warn('Failed to publish/register Matter external accessories', e)
-      }
-    }
-  }
-
-  private async publishMatterExternalAccessories(accessories: any[]): Promise<boolean> {
-    const api = this.api as any
-    if (!api || typeof api.emit !== 'function') {
-      return false
-    }
-
-    const pendingRegistrations = api._pendingExternalRegistrations
-    if (!(pendingRegistrations instanceof Map) && pendingRegistrations !== undefined) {
-      return false
-    }
-
-    const registrationId = `${PLUGIN_NAME}-${Date.now()}-${Math.random()}`
-    const registrationPromise = new Promise<void>((resolve) => {
-      if (!(api._pendingExternalRegistrations instanceof Map)) {
-        api._pendingExternalRegistrations = new Map()
-      }
-      api._pendingExternalRegistrations.set(registrationId, resolve)
-    })
-
-    api.emit('publishExternalMatterAccessories', accessories, registrationId)
-    await registrationPromise
-    return true
   }
 
   /**
@@ -366,7 +312,6 @@ export class SwitchBotMatterPlatform {
       id: d.deviceId ?? d.id,
       type: d.configDeviceType ?? d.type,
       name: d.configDeviceName ?? d.name,
-      externalPublishProtocol: resolveExternalPublishProtocol(d),
     })))
   }
 

package/src/deviceFactory.ts

@@ -109,6 +109,7 @@ const DEVICE_CLASS_MAP: Record<string, any> = {
   'meter': MeterDevice,
   'meter plus (jp)': MeterDevice,
   'water detector': WaterDetectorDevice,
+  'waterdetector': WaterDetectorDevice,
   'smart fan': SmartFanDevice,
   'strip light': StripLightDevice,
   'wosweeper': WoSweeperDevice,
@@ -176,20 +177,10 @@ export async function createDevice(opts: DeviceOptions, cfg: SwitchBotPluginConf
   const device = new DeviceCtor(deviceOpts, mergedCfg)
   await device.init()
 
-  // Attach a simple getState delegator to the client where appropriate
-  const originalGetState = device.getState.bind(device)
-  device.getState = async () => {
-    try {
-      // Prefer client-backed getDevice when available
-      const dev = await client.getDevice(opts.id)
-      if (dev) {
-        return dev
-      }
-    } catch (e) {
-      // ignore and fallback to device implementation
-    }
-    return originalGetState()
-  }
+  // No getState() override here: the device's own implementation already
+  // prefers the client-backed lookup, and it converts the result into a status.
+  // An override that returned the client device directly shadowed it, and that
+  // object carries no readings.
 
   // Provide accessory factory based on platform selection
   return {

package/src/devices/genericDevice.ts

@@ -186,7 +186,44 @@ export class GenericDevice extends DeviceBase {
     })
   }
 
+  /**
+   * How long a fetched state is reused. HomeKit reads every characteristic of
+   * an accessory together, so without this a single read costs one API request
+   * per characteristic.
+   */
+  private static readonly STATE_TTL_MS = 15_000
+
+  /** Marks a state that carries no readings, so a caller can skip it. */
+  static readonly UNREADABLE = Symbol('unreadable')
+
+  private stateCache?: { at: number, value: any }
+  private stateInFlight?: Promise<any>
+
   async getState(): Promise<any> {
+    if (this.stateCache && (Date.now() - this.stateCache.at) < GenericDevice.STATE_TTL_MS) {
+      return this.stateCache.value
+    }
+    // Collapse the burst of reads HomeKit makes into a single fetch.
+    if (this.stateInFlight) {
+      return this.stateInFlight
+    }
+    this.stateInFlight = this.fetchState()
+      .then((value) => {
+        if (value === GenericDevice.UNREADABLE) {
+          // Do not cache a failure. Caching it would hold every characteristic
+          // at its fallback for the whole window after one transient error.
+          return { id: this.opts.id, type: this.opts.type, unreadable: true }
+        }
+        this.stateCache = { at: Date.now(), value }
+        return value
+      })
+      .finally(() => {
+        this.stateInFlight = undefined
+      })
+    return this.stateInFlight
+  }
+
+  protected async fetchState(): Promise<any> {
     // Default: return minimal info; implementations should override
     if (this.client && typeof this.client.getDevice === 'function') {
       try {
@@ -201,15 +238,27 @@ export class GenericDevice extends DeviceBase {
         // Normalize common response shapes
         try {
           const device = raw?.body ?? raw
-          return device
-        } catch (e) {
-          return raw
+          // node-switchbot returns a device instance, not a status. The instance
+          // exposes id/name/deviceType/mac but carries no readings, so a caller
+          // reading state.temperature would get undefined. Ask it for status.
+          if (device && typeof device.getStatus === 'function') {
+            const status = await device.getStatus()
+            if (status && typeof status === 'object') {
+              return status
+            }
+            // Fall through to the minimal info below rather than returning the
+            // instance, which would look like a state with every field missing.
+          } else {
+            return device
+          }
+        } catch (e: any) {
+          this.log?.debug?.(`getState: could not read status for ${this.opts.id}:`, e instanceof Error ? e.message : e)
         }
       } catch (e) {
         // ignore and fallback
       }
     }
-    return { id: this.opts.id, type: this.opts.type }
+    return GenericDevice.UNREADABLE
   }
 
   async setState(change: any): Promise<any> {
@@ -483,6 +532,38 @@ export class GenericDevice extends DeviceBase {
 export class BotDevice extends GenericDevice {}
 
 export class CurtainDevice extends GenericDevice {
+  private lastKnownPosition = 0
+  private lastTargetPosition = 0
+  private positionState = 2
+  private preferLocalPositionUntil = 0
+
+  private clampHomeKitPosition(position: number): number {
+    return Math.max(0, Math.min(100, Math.round(Number(position))))
+  }
+
+  private toHomeKitPosition(switchBotPosition: number): number {
+    return 100 - this.clampHomeKitPosition(switchBotPosition)
+  }
+
+  private toSwitchBotPosition(homeKitPosition: number): number {
+    return 100 - this.clampHomeKitPosition(homeKitPosition)
+  }
+
+  private async getPositionForHomeKit(): Promise<number> {
+    if (Date.now() < this.preferLocalPositionUntil) {
+      return this.lastKnownPosition
+    }
+    const state = await Promise.race([
+      this.getState(),
+      new Promise(resolve => setTimeout(resolve, 1000)),
+    ])
+    if (typeof state?.position === 'number') {
+      this.lastKnownPosition = this.toHomeKitPosition(Number(state.position))
+      this.lastTargetPosition = this.lastKnownPosition
+    }
+    return this.lastKnownPosition
+  }
+
   createHAPAccessory(api: any) {
     return {
       services: [
@@ -491,18 +572,27 @@ export class CurtainDevice extends GenericDevice {
           characteristics: {
             CurrentPosition: {
               get: async () => {
-                const s = await this.getState()
-                return typeof s.position === 'number' ? s.position : 0
+                return this.getPositionForHomeKit()
               },
             },
+            PositionState: {
+              get: async () => this.positionState,
+            },
             TargetPosition: {
               get: async () => {
-                const s = await this.getState()
-                return typeof s.position === 'number' ? s.position : 0
+                await this.getPositionForHomeKit()
+                return this.lastTargetPosition
               },
               set: async (v: any) => {
-                await this.setState({ position: Number(v) })
+                const position = this.clampHomeKitPosition(Number(v))
+                this.lastTargetPosition = position
+                this.positionState = position > this.lastKnownPosition ? 1 : position < this.lastKnownPosition ? 0 : 2
+                await this.setState({ position: this.toSwitchBotPosition(position) })
+                this.lastKnownPosition = position
+                this.preferLocalPositionUntil = Date.now() + 30000
+                this.positionState = 2
               },
+              refreshAfterSet: ['CurrentPosition', 'TargetPosition', 'PositionState'],
             },
           },
         },
@@ -1306,6 +1396,161 @@ export class MeterDevice extends GenericDevice {
 }
 
 export class WaterDetectorDevice extends GenericDevice {
+  private _leakRefreshing = false
+  private _leakRefreshTs = 0
+  private lastLeakDetected?: boolean
+  private readonly LEAK_REFRESH_TTL_MS = 30_000
+
+  private lastBatteryLevel?: number
+  private _batteryRefreshing = false
+  private _batteryRefreshTs = 0
+  private readonly BATTERY_REFRESH_TTL_MS = 30_000
+
+  async init(): Promise<void> {
+    await super.init()
+    await this._refreshLeakState(!this.client)
+    await this._refreshBattery()
+  }
+
+  private normalizeLeakDetected(state: any): boolean | undefined {
+    if (typeof state?.leak === 'boolean') {
+      return state.leak
+    }
+    if (typeof state?.waterLeakDetected === 'boolean') {
+      return state.waterLeakDetected
+    }
+    if (typeof state?.body?.waterLeakDetected === 'boolean') {
+      return state.body.waterLeakDetected
+    }
+    const status = state?.status ?? state?.body?.status
+    if (typeof status === 'number') {
+      return status === 1
+    }
+    if (typeof status === 'string') {
+      return ['1', 'leak', 'leaked', 'detected', 'water_leak_detected'].includes(status.toLowerCase())
+    }
+    return undefined
+  }
+
+  private normalizeBatteryLevel(state: any): number | undefined {
+    const raw = state?.battery ?? state?.body?.battery
+    if (typeof raw !== 'number' || !Number.isFinite(raw)) {
+      return undefined
+    }
+    return Math.max(0, Math.min(100, raw))
+  }
+
+  private async getOpenAPIStatus(): Promise<any> {
+    const token = this.cfg?.openApiToken
+    const secret = this.cfg?.openApiSecret
+    if (!token || !secret) {
+      return undefined
+    }
+
+    try {
+      const { OpenAPIClient } = await import('node-switchbot')
+      const apiClient = new OpenAPIClient(token, secret)
+      return await apiClient.getStatus(this.opts.id)
+    } catch (e) {
+      this.log?.debug?.(`[WaterDetector] direct OpenAPI refresh failed: ${(e as Error)?.message}`)
+    }
+
+    return undefined
+  }
+
+  private async readLeakDetected(fallbackToDeviceState = true): Promise<boolean | undefined> {
+    const status = await this.getOpenAPIStatus()
+    if (status) {
+      const leak = this.normalizeLeakDetected(status)
+      if (typeof leak === 'boolean') {
+        return leak
+      }
+    }
+    if (!fallbackToDeviceState) {
+      return undefined
+    }
+
+    try {
+      return this.normalizeLeakDetected(await this.getState())
+    } catch (e) {
+      this.log?.debug?.(`[WaterDetector] leak refresh failed: ${(e as Error)?.message}`)
+    }
+
+    return undefined
+  }
+
+  private async readBatteryLevel(): Promise<number | undefined> {
+    const status = await this.getOpenAPIStatus()
+    if (status) {
+      const battery = this.normalizeBatteryLevel(status)
+      if (typeof battery === 'number') {
+        return battery
+      }
+    }
+
+    return undefined
+  }
+
+  private async _refreshLeakState(fallbackToDeviceState = true): Promise<void> {
+    if (this._leakRefreshing) {
+      return
+    }
+    this._leakRefreshing = true
+    try {
+      const leakDetected = await this.readLeakDetected(fallbackToDeviceState)
+      if (typeof leakDetected === 'boolean') {
+        this.lastLeakDetected = leakDetected
+        this._leakRefreshTs = Date.now()
+      }
+    } catch (e) {
+      this.log?.debug?.(`[WaterDetector] leak refresh failed: ${(e as Error)?.message}`)
+    } finally {
+      this._leakRefreshing = false
+    }
+  }
+
+  private async _refreshBattery(): Promise<void> {
+    if (this._batteryRefreshing) {
+      return
+    }
+    this._batteryRefreshing = true
+    try {
+      const battery = await this.readBatteryLevel()
+      if (typeof battery === 'number') {
+        this.lastBatteryLevel = battery
+        this._batteryRefreshTs = Date.now()
+      }
+    } catch (e) {
+      this.log?.debug?.(`[WaterDetector] battery refresh failed: ${(e as Error)?.message}`)
+    } finally {
+      this._batteryRefreshing = false
+    }
+  }
+
+  private getLeakDetectedFast(api: any): number {
+    if (Date.now() - this._leakRefreshTs >= this.LEAK_REFRESH_TTL_MS) {
+      this._refreshLeakState().catch(() => undefined)
+    }
+    if (typeof this.lastLeakDetected === 'boolean') {
+      return this.lastLeakDetected ? 1 : 0
+    }
+    throw new api.hap.HapStatusError(api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE)
+  }
+
+  // Returns the cached battery level immediately and triggers a background
+  // refresh if the cache is stale. Throws HapStatusError on true cold start
+  // so HomeKit shows "Not Available" rather than fabricating a misleading
+  // value or timing out (which surfaces as 0% in the Home app).
+  private getBatteryFast(api: any): number {
+    if (Date.now() - this._batteryRefreshTs >= this.BATTERY_REFRESH_TTL_MS) {
+      this._refreshBattery().catch(() => undefined)
+    }
+    if (typeof this.lastBatteryLevel === 'number') {
+      return this.lastBatteryLevel
+    }
+    throw new api.hap.HapStatusError(api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE)
+  }
+
   createHAPAccessory(api: any) {
     return {
       services: [
@@ -1313,11 +1558,25 @@ export class WaterDetectorDevice extends GenericDevice {
           type: 'LeakSensor',
           characteristics: {
             LeakDetected: {
-              get: async () => {
-                const s = await this.getState()
-                return s && s.leak ? 1 : 0
+              get: () => this.getLeakDetectedFast(api),
+            },
+          },
+        },
+        {
+          type: 'Battery',
+          characteristics: {
+            BatteryLevel: {
+              get: () => this.getBatteryFast(api),
+            },
+            StatusLowBattery: {
+              get: () => {
+                const b = this.getBatteryFast(api)
+                return b < 20 ? 1 : 0
               },
             },
+            ChargingState: {
+              get: () => 2,
+            },
           },
         },
       ],

package/src/homebridge-ui/endpoints/config.ts

@@ -4,7 +4,7 @@ import { RequestError } from '@homebridge/plugin-ui-utils'
 import fs from 'node:fs/promises'
 
 import { isValidDeviceType } from '../../device-types.js'
-import { getAllDevices, isV4Config, SWITCHBOT_PLATFORM_REGEX } from '../utils/config-parser.js'
+import { getAllDevices, SWITCHBOT_PLATFORM_REGEX } from '../utils/config-parser.js'
 import { validateAndMigrateDeviceType } from '../utils/device-migration.js'
 import { uiLog } from '../utils/logger.js'
 
@@ -31,7 +31,6 @@ export function registerConfigEndpoints(server: HomebridgePluginUiServer) {
         typeValidationWarning?: string
       }> = []
       const invalidTypeDevices: Array<{ name: string, type: string, suggestion?: string }> = []
-      let v4ConfigDetected = false
 
       const platforms = Array.isArray(cfg.platforms) ? cfg.platforms : []
       for (const p of platforms) {
@@ -42,12 +41,6 @@ export function registerConfigEndpoints(server: HomebridgePluginUiServer) {
             continue
           }
 
-          // Detect legacy v4 config format
-          if (isV4Config(p)) {
-            v4ConfigDetected = true
-            uiLog.warn('Detected legacy v4 config format (credentials/options.devices). This config is not compatible with v5+. Please migrate to the v5 config format.')
-          }
-
           const devices = getAllDevices(p)
           for (const d of devices) {
             const id = d.deviceId ?? d.id
@@ -101,12 +94,11 @@ export function registerConfigEndpoints(server: HomebridgePluginUiServer) {
         )
       }
 
-      uiLog.info(`GET /devices - Found ${found.length} devices in ${cfgPath}${invalidTypeDevices.length > 0 ? ` (${invalidTypeDevices.length} with validation warnings)` : ''}${v4ConfigDetected ? ' [v4 config detected]' : ''}`)
+      uiLog.info(`GET /devices - Found ${found.length} devices in ${cfgPath}${invalidTypeDevices.length > 0 ? ` (${invalidTypeDevices.length} with validation warnings)` : ''}`)
       return {
         success: true,
         data: found,
         ...(invalidTypeDevices.length > 0 && { validationWarnings: invalidTypeDevices }),
-        ...(v4ConfigDetected && { v4ConfigDetected: true }),
       }
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e)

package/src/homebridge-ui/public/css/styles.css

@@ -480,64 +480,4 @@ ul.device-grid {
 
 .discovery-scanning-pulse {
   animation: pulse 1.5s ease-in-out infinite;
-}
-/* v4 config incompatibility warning banner */
-.v4-config-warning {
-  background: #7c3015;
-  color: #fff;
-  border: 1px solid #a04020;
-  border-radius: 8px;
-  padding: 14px 18px;
-  margin-bottom: 18px;
-  font-size: 13px;
-  line-height: 1.5;
-}
-
-.v4-config-warning strong {
-  display: block;
-  font-size: 15px;
-  margin-bottom: 8px;
-}
-
-.v4-config-warning p {
-  margin: 6px 0;
-}
-
-.v4-config-warning ul {
-  margin: 6px 0 6px 18px;
-  padding: 0;
-}
-
-.v4-config-warning li {
-  margin-bottom: 3px;
-}
-
-.v4-config-warning code {
-  background: rgba(255, 255, 255, 0.15);
-  border-radius: 3px;
-  padding: 1px 4px;
-  font-size: 12px;
-  color: #ffd;
-}
-
-.v4-config-warning a {
-  color: #ffd;
-  text-decoration: underline;
-}
-
-@media (prefers-color-scheme: light) {
-  .v4-config-warning {
-    background: #fff3cd;
-    color: #7c3015;
-    border-color: #f0ad4e;
-  }
-
-  .v4-config-warning code {
-    background: rgba(124, 48, 21, 0.1);
-    color: #7c3015;
-  }
-
-  .v4-config-warning a {
-    color: #7c3015;
-  }
-}
+}