@switchbot/homebridge-switchbot 5.0.0-beta.12 → 5.0.0-beta.13

package/src/baseMatterAccessory.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { BaseMatterAccessory } from './devices-matter/BaseMatterAccessory.js'
+
+// Minimal concrete subclass for testing
+class TestAccessory extends BaseMatterAccessory {
+  constructor(api: any, log: any, opts?: any) {
+    super(api, log, {
+      uuid: opts?.uuid ?? api.matter.uuid.generate('test'),
+      displayName: opts?.displayName ?? 'Test',
+      deviceType: opts?.deviceType ?? ('OnOffLight' as any),
+      serialNumber: opts?.serialNumber ?? 'TEST-1',
+      manufacturer: opts?.manufacturer ?? 'TestCo',
+      model: opts?.model ?? 'T-1',
+      firmwareRevision: opts?.firmwareRevision ?? '1.0',
+      hardwareRevision: opts?.hardwareRevision ?? '1.0',
+      context: opts?.context ?? {},
+      clusters: opts?.clusters,
+      handlers: opts?.handlers,
+    })
+  }
+}
+
+describe('baseMatterAccessory helpers', () => {
+  it('sendOnCommand uses OpenAPI helper and updates state', async () => {
+    const update = vi.fn()
+    const sendOpenAPI = vi.fn(async () => ({ response: {}, statusCode: 200 }))
+    const api: any = { matter: { clusterNames: { OnOff: 'onOff', LevelControl: 'level', ColorControl: 'color' }, uuid: { generate: () => 'uuid-1' }, updateAccessoryState: update } }
+    const log: any = { info: vi.fn(), debug: vi.fn(), error: vi.fn(), warn: vi.fn() }
+
+    const ctx = { deviceId: 'DEV-1', sendOpenAPI, connectionType: 'OpenAPI' }
+    const acc = new TestAccessory(api, log, { context: ctx })
+
+    await acc.sendOnCommand()
+
+    expect(sendOpenAPI).toHaveBeenCalledWith('turnOn', 'default')
+    expect(update).toHaveBeenCalledWith(acc.uuid, 'onOff', { onOff: true })
+  })
+
+  it('sendOnCommand uses BLE helper when connectionType is BLE', async () => {
+    const update = vi.fn()
+    const sendBLE = vi.fn(async () => true)
+    const api: any = { matter: { clusterNames: { OnOff: 'onOff', LevelControl: 'level', ColorControl: 'color' }, uuid: { generate: () => 'uuid-2' }, updateAccessoryState: update } }
+    const log: any = { info: vi.fn(), debug: vi.fn(), error: vi.fn(), warn: vi.fn() }
+
+    const ctx = { deviceId: 'DEV-2', sendBLE, connectionType: 'BLE' }
+    const acc = new TestAccessory(api, log, { context: ctx })
+
+    await acc.sendOnCommand()
+
+    expect(sendBLE).toHaveBeenCalledWith('turnOn')
+    expect(update).toHaveBeenCalledWith(acc.uuid, 'onOff', { onOff: true })
+  })
+
+  it('sendSetBrightness sends percent and updates LevelControl', async () => {
+    const update = vi.fn()
+    const sendOpenAPI = vi.fn(async () => ({ response: {}, statusCode: 200 }))
+    const api: any = { matter: { clusterNames: { OnOff: 'onOff', LevelControl: 'level', ColorControl: 'color' }, uuid: { generate: () => 'uuid-3' }, updateAccessoryState: update } }
+    const log: any = { info: vi.fn(), debug: vi.fn(), error: vi.fn(), warn: vi.fn() }
+
+    const ctx = { deviceId: 'DEV-3', sendOpenAPI, connectionType: 'OpenAPI' }
+    const acc = new TestAccessory(api, log, { context: ctx })
+
+    await acc.sendSetBrightness(50)
+
+    expect(sendOpenAPI).toHaveBeenCalledWith('setBrightness', '50')
+    const expectedLevel = Math.round((50 / 100) * 254)
+    expect(update).toHaveBeenCalledWith(acc.uuid, 'level', { currentLevel: expectedLevel })
+  })
+
+  it('sendSetColor sends RGB and updates ColorControl', async () => {
+    const update = vi.fn()
+    const sendOpenAPI = vi.fn(async () => ({ response: {}, statusCode: 200 }))
+    const api: any = { matter: { clusterNames: { OnOff: 'onOff', LevelControl: 'level', ColorControl: 'color' }, uuid: { generate: () => 'uuid-4' }, updateAccessoryState: update } }
+    const log: any = { info: vi.fn(), debug: vi.fn(), error: vi.fn(), warn: vi.fn() }
+
+    const ctx = { deviceId: 'DEV-4', sendOpenAPI, connectionType: 'OpenAPI' }
+    const acc = new TestAccessory(api, log, { context: ctx })
+
+    await acc.sendSetColor(255, 128, 0)
+
+    expect(sendOpenAPI).toHaveBeenCalledWith('setColor', '255:128:0')
+    expect(update).toHaveBeenCalled()
+    // Ensure we updated ColorControl cluster with numeric attributes
+    const calledWith = (update.mock.calls[0] || update.mock.calls[1])
+    expect(calledWith[1] === 'color' || calledWith[1] === api.matter.clusterNames.ColorControl).toBeTruthy()
+  })
+})

package/src/devices-matter/BaseMatterAccessory.ts

@@ -10,6 +10,8 @@
 
 import type { API, EndpointType, Logger, MatterAccessory } from 'homebridge'
 
+import { rgb2hs } from '../utils.js'
+
 export interface BaseMatterAccessoryConfig {
   uuid: string
   displayName: string
@@ -108,6 +110,122 @@ export abstract class BaseMatterAccessory implements MatterAccessory {
     this.log.warn(`[${this.displayName}] ${message}`, ...args)
   }
 
+  /**
+   * Convenience helpers that delegate OpenAPI/BLE commands to platform-provided
+   * functions that are injected into the accessory `context` by
+   * `platform-matter` when the accessory is created from a discovered device.
+   *
+   * These methods are intentionally thin wrappers — the platform controls
+   * retries, discovery and client lifecycle via the helper functions.
+   */
+  protected async sendOpenAPICommand(command: string, parameter = 'default'): Promise<any> {
+    const ctx: any = this.context as any
+    const fn = ctx?.sendOpenAPI
+    if (typeof fn === 'function') {
+      return fn(command, parameter)
+    }
+    throw new Error('OpenAPI helper not available')
+  }
+
+  protected async sendBLECommand(methodName: string, ...args: any[]): Promise<any> {
+    const ctx: any = this.context as any
+    const fn = ctx?.sendBLE
+    if (typeof fn === 'function') {
+      return fn(methodName, ...args)
+    }
+    throw new Error('BLE helper not available')
+  }
+
+  public async sendOnCommand(deviceId?: string): Promise<void> {
+    const ctx: any = this.context as any
+    const id = deviceId ?? ctx?.deviceId
+    try {
+      if (ctx?.connectionType === 'BLE') {
+        await this.sendBLECommand('turnOn')
+      } else {
+        await this.sendOpenAPICommand('turnOn')
+      }
+      // update our matter state
+      await this.updateState(this.api.matter.clusterNames.OnOff, { onOff: true })
+      this.logInfo(`sendOnCommand successful for ${id}`)
+    } catch (e: any) {
+      this.logError(`sendOnCommand failed for ${id}: ${String(e?.message ?? e)}`)
+      throw e
+    }
+  }
+
+  public async sendOffCommand(deviceId?: string): Promise<void> {
+    const ctx: any = this.context as any
+    const id = deviceId ?? ctx?.deviceId
+    try {
+      if (ctx?.connectionType === 'BLE') {
+        await this.sendBLECommand('turnOff')
+      } else {
+        await this.sendOpenAPICommand('turnOff')
+      }
+      await this.updateState(this.api.matter.clusterNames.OnOff, { onOff: false })
+      this.logInfo(`sendOffCommand successful for ${id}`)
+    } catch (e: any) {
+      this.logError(`sendOffCommand failed for ${id}: ${String(e?.message ?? e)}`)
+      throw e
+    }
+  }
+
+  public async sendSetBrightness(percent: number, deviceId?: string): Promise<void> {
+    const ctx: any = this.context as any
+    const id = deviceId ?? ctx?.deviceId
+    try {
+      if (ctx?.connectionType === 'BLE') {
+        await this.sendBLECommand('setBrightness', percent)
+      } else {
+        await this.sendOpenAPICommand('setBrightness', String(percent))
+      }
+      const level = Math.round((percent / 100) * 254)
+      await this.updateState(this.api.matter.clusterNames.LevelControl, { currentLevel: level })
+      this.logInfo(`sendSetBrightness successful for ${id}: ${percent}%`)
+    } catch (e: any) {
+      this.logError(`sendSetBrightness failed for ${id}: ${String(e?.message ?? e)}`)
+      throw e
+    }
+  }
+
+  public async sendSetColor(r: number, g: number, b: number, deviceId?: string): Promise<void> {
+    const ctx: any = this.context as any
+    const id = deviceId ?? ctx?.deviceId
+    try {
+      if (ctx?.connectionType === 'BLE') {
+        await this.sendBLECommand('setRGB', r, g, b)
+      } else {
+        await this.sendOpenAPICommand('setColor', `${r}:${g}:${b}`)
+      }
+      // Convert to hue/sat for matter state update
+      const [h, s] = rgb2hs(r, g, b)
+      await this.updateState(this.api.matter.clusterNames.ColorControl, { currentHue: Math.round((h / 360) * 254), currentSaturation: Math.round((s / 100) * 254) })
+      this.logInfo(`sendSetColor successful for ${id}: ${r},${g},${b}`)
+    } catch (e: any) {
+      this.logError(`sendSetColor failed for ${id}: ${String(e?.message ?? e)}`)
+      throw e
+    }
+  }
+
+  public async sendSetColorTemperature(kelvin: number, deviceId?: string): Promise<void> {
+    const ctx: any = this.context as any
+    const id = deviceId ?? ctx?.deviceId
+    try {
+      if (ctx?.connectionType === 'BLE') {
+        await this.sendBLECommand('setColorTemperature', kelvin)
+      } else {
+        await this.sendOpenAPICommand('setColorTemperature', `${kelvin}`)
+      }
+      const mireds = Math.round(1000000 / kelvin)
+      await this.updateState(this.api.matter.clusterNames.ColorControl, { colorTemperatureMireds: mireds })
+      this.logInfo(`sendSetColorTemperature successful for ${id}: ${kelvin}K`)
+    } catch (e: any) {
+      this.logError(`sendSetColorTemperature failed for ${id}: ${String(e?.message ?? e)}`)
+      throw e
+    }
+  }
+
   /**
    * Convert this class instance to a plain MatterAccessory object
    * This is what gets registered with Homebridge

package/src/devices-matter/ColorLightAccessory.ts

@@ -5,6 +5,7 @@
 
 import type { API, Logger, MatterRequests } from 'homebridge'
 
+import { hs2rgb } from '../utils.js'
 import { BaseMatterAccessory } from './BaseMatterAccessory.js'
 
 export class ColorLightAccessory extends BaseMatterAccessory {
@@ -56,38 +57,37 @@ export class ColorLightAccessory extends BaseMatterAccessory {
 
   private async handleOn(): Promise<void> {
     this.logInfo('turning on.')
-    // TODO: await myLightAPI.turnOn()
+    await this.sendOnCommand()
   }
 
   private async handleOff(): Promise<void> {
     this.logInfo('turning off.')
-    // TODO: await myLightAPI.turnOff()
+    await this.sendOffCommand()
   }
 
   private async handleSetLevel(request: MatterRequests.MoveToLevel): Promise<void> {
     this.logInfo(`MoveToLevel request: ${JSON.stringify(request)}`)
     const { level } = request
     const brightnessPercent = Math.round((level / 254) * 100)
-    this.logInfo(`setting brightness to ${brightnessPercent}%.`)
-    // TODO: await myLightAPI.setBrightness(brightnessPercent)
+    await this.sendSetBrightness(brightnessPercent)
   }
 
   private async handleSetColor(request: MatterRequests.MoveToColor): Promise<void> {
     this.logInfo(`MoveToColor request: ${JSON.stringify(request)}`)
-    const { colorX, colorY, transitionTime } = request
-    const xFloat = (colorX / 65535).toFixed(4)
-    const yFloat = (colorY / 65535).toFixed(4)
-    this.logInfo(`setting xy color to (${xFloat}, ${yFloat}) with transition ${transitionTime}.`)
-    // TODO: await myLightAPI.setXY(xFloat, yFloat, transitionTime)
+    const { colorX, colorY } = request
+    const hueApprox = Math.round((colorX / 65535) * 360)
+    const satApprox = Math.round((colorY / 65535) * 100)
+    const [r, g, b] = hs2rgb(hueApprox, satApprox)
+    await this.sendSetColor(r, g, b)
   }
 
   private async handleSetHueSaturation(request: MatterRequests.MoveToHueAndSaturation): Promise<void> {
     this.logInfo(`MoveToHueAndSaturation request: ${JSON.stringify(request)}`)
-    const { hue, saturation, transitionTime } = request
+    const { hue, saturation } = request
     const hueDegrees = Math.round((hue / 254) * 360)
     const saturationPercent = Math.round((saturation / 254) * 100)
-    this.logInfo(`setting color to ${hueDegrees}°, ${saturationPercent}% with transition ${transitionTime}.`)
-    // TODO: await myLightAPI.setColor(hueDegrees, saturationPercent, transitionTime)
+    const [r, g, b] = hs2rgb(hueDegrees, saturationPercent)
+    await this.sendSetColor(r, g, b)
   }
 
   public updateOnOffState(isOn: boolean): void {

package/src/devices-matter/ColorTemperatureLightAccessory.ts

@@ -52,28 +52,26 @@ export class ColorTemperatureLightAccessory extends BaseMatterAccessory {
 
   private async handleOn(): Promise<void> {
     this.logInfo('turning on.')
-    // TODO: await myLightAPI.turnOn()
+    await this.sendOnCommand()
   }
 
   private async handleOff(): Promise<void> {
     this.logInfo('turning off.')
-    // TODO: await myLightAPI.turnOff()
+    await this.sendOffCommand()
   }
 
   private async handleSetLevel(request: MatterRequests.MoveToLevel): Promise<void> {
     this.logInfo(`MoveToLevel request: ${JSON.stringify(request)}`)
     const { level } = request
     const brightnessPercent = Math.round((level / 254) * 100)
-    this.logInfo(`setting brightness to ${brightnessPercent}% (level: ${level}).`)
-    // TODO: await myLightAPI.setBrightness(brightnessPercent)
+    await this.sendSetBrightness(brightnessPercent)
   }
 
   private async handleSetColorTemperature(request: MatterRequests.MoveToColorTemperature): Promise<void> {
     this.logInfo(`MoveToColorTemperature request: ${JSON.stringify(request)}`)
-    const { colorTemperatureMireds, transitionTime } = request
+    const { colorTemperatureMireds } = request
     const kelvin = Math.round(1000000 / colorTemperatureMireds)
-    this.logInfo(`setting color temp to ${kelvin}k (${colorTemperatureMireds} mireds) with transitionTime=${transitionTime}.`)
-    // TODO: await myLightAPI.setColorTemperature(kelvin, transitionTime)
+    await this.sendSetColorTemperature(kelvin)
   }
 
   public updateOnOffState(isOn: boolean): void {

package/src/devices-matter/DimmableLightAccessory.ts

@@ -69,10 +69,10 @@ export class DimmableLightAccessory extends BaseMatterAccessory {
     this.logInfo('turning on.')
 
     try {
-      // TODO: Control your physical device
-      // await myLightAPI.turnOn()
+      // Use platform helper (OpenAPI/BLE) when available
+      await this.sendOnCommand()
 
-      this.logInfo('physical device turned on.')
+      this.logInfo('physical device turned on (via platform helper).')
     } catch (error) {
       this.logError('failed to turn on:', error)
       throw error
@@ -86,10 +86,10 @@ export class DimmableLightAccessory extends BaseMatterAccessory {
     this.logInfo('turning off.')
 
     try {
-      // TODO: Control your physical device
-      // await myLightAPI.turnOff()
+      // Use platform helper (OpenAPI/BLE) when available
+      await this.sendOffCommand()
 
-      this.logInfo('physical device turned off.')
+      this.logInfo('physical device turned off (via platform helper).')
     } catch (error) {
       this.logError('failed to turn off:', error)
       throw error
@@ -110,10 +110,10 @@ export class DimmableLightAccessory extends BaseMatterAccessory {
     this.logInfo(`setting brightness to ${brightnessPercent}% (level: ${level}), transitionTime: ${transitionTime}.`)
 
     try {
-      // TODO: Control your physical device
-      // await myLightAPI.setBrightness(brightnessPercent, transitionTime)
+      // Use platform helper (OpenAPI/BLE) when available
+      await this.sendSetBrightness(brightnessPercent)
 
-      this.logInfo(`physical device brightness set to ${brightnessPercent}%.`)
+      this.logInfo(`physical device brightness set to ${brightnessPercent}% (via platform helper).`)
     } catch (error) {
       this.logError('Failed to set brightness:', error)
       throw error

package/src/devices-matter/ExtendedColorLightAccessory.ts

@@ -5,6 +5,7 @@
 
 import type { API, Logger, MatterRequests } from 'homebridge'
 
+import { hs2rgb } from '../utils.js'
 import { BaseMatterAccessory } from './BaseMatterAccessory.js'
 
 export class ExtendedColorLightAccessory extends BaseMatterAccessory {
@@ -61,46 +62,44 @@ export class ExtendedColorLightAccessory extends BaseMatterAccessory {
 
   private async handleOn(): Promise<void> {
     this.logInfo('turning on.')
-    // TODO: await myLightAPI.turnOn()
+    await this.sendOnCommand()
   }
 
   private async handleOff(): Promise<void> {
     this.logInfo('turning off.')
-    // TODO: await myLightAPI.turnOff()
+    await this.sendOffCommand()
   }
 
   private async handleSetLevel(request: MatterRequests.MoveToLevel): Promise<void> {
     this.logInfo(`MoveToLevel request: ${JSON.stringify(request)}`)
     const { level } = request
     const brightnessPercent = Math.round((level / 254) * 100)
-    this.logInfo(`setting brightness to ${brightnessPercent}%.`)
-    // TODO: await myLightAPI.setBrightness(brightnessPercent)
+    await this.sendSetBrightness(brightnessPercent)
   }
 
   private async handleSetColor(request: MatterRequests.MoveToColor): Promise<void> {
     this.logInfo(`MoveToColor request: ${JSON.stringify(request)}`)
-    const { colorX, colorY, transitionTime } = request
-    const xFloat = (colorX / 65535).toFixed(4)
-    const yFloat = (colorY / 65535).toFixed(4)
-    this.logInfo(`setting xy color to (${xFloat}, ${yFloat}), ${transitionTime}ms.`)
-    // TODO: await myLightAPI.setXY(xFloat, yFloat, transitionTime)
+    const { colorX, colorY } = request
+    const hueApprox = Math.round((colorX / 65535) * 360)
+    const satApprox = Math.round((colorY / 65535) * 100)
+    const [r, g, b] = hs2rgb(hueApprox, satApprox)
+    await this.sendSetColor(r, g, b)
   }
 
   private async handleSetHueSaturation(request: MatterRequests.MoveToHueAndSaturation): Promise<void> {
     this.logInfo(`MoveToHueAndSaturation request: ${JSON.stringify(request)}`)
-    const { hue, saturation, transitionTime } = request
+    const { hue, saturation } = request
     const hueDegrees = Math.round((hue / 254) * 360)
     const saturationPercent = Math.round((saturation / 254) * 100)
-    this.logInfo(`setting color to ${hueDegrees}°, ${saturationPercent}%, ${transitionTime}ms.`)
-    // TODO: await myLightAPI.setColor(hueDegrees, saturationPercent, transitionTime)
+    const [r, g, b] = hs2rgb(hueDegrees, saturationPercent)
+    await this.sendSetColor(r, g, b)
   }
 
   private async handleSetColorTemperature(request: MatterRequests.MoveToColorTemperature): Promise<void> {
     this.logInfo(`MoveToColorTemperature request: ${JSON.stringify(request)}`)
-    const { colorTemperatureMireds, transitionTime } = request
+    const { colorTemperatureMireds } = request
     const kelvin = Math.round(1000000 / colorTemperatureMireds)
-    this.logInfo(`setting color temp to ${kelvin}k, ${transitionTime}ms.`)
-    // TODO: await myLightAPI.setColorTemperature(kelvin, transitionTime)
+    await this.sendSetColorTemperature(kelvin)
   }
 
   public updateOnOffState(isOn: boolean): void {

package/src/devices-matter/OnOffLightAccessory.ts

@@ -27,12 +27,8 @@ export class OnOffLightAccessory extends BaseMatterAccessory {
     const clusters = opts?.clusters ?? { onOff: { onOff: true } }
     const handlers = opts?.handlers ?? {
       onOff: {
-        on: async () => {
-          log.debug(`${displayName} on handler invoked (default no-op).`)
-        },
-        off: async () => {
-          log.debug(`${displayName} off handler invoked (default no-op).`)
-        },
+        on: async () => this.handleOnCommand(),
+        off: async () => this.handleOffCommand(),
       },
     }
 
@@ -61,14 +57,10 @@ export class OnOffLightAccessory extends BaseMatterAccessory {
     this.logInfo('turning on.')
 
     try {
-      // TODO: Control your physical device here
-      // Examples:
-      // await fetch('https://api.mydevice.com/light/on', { method: 'POST' })
-      // await fetch('http://192.168.1.50/api/light/on')
-      // mqttClient.publish('home/light/command', JSON.stringify({ state: 'ON' }))
-      // await myLightAPI.turnOn(this.context.deviceId)
+      // Delegate to the platform-provided helper (OpenAPI/BLE) when available
+      await this.sendOnCommand()
 
-      this.logInfo('physical device turned on.')
+      this.logInfo('physical device turned on (via platform helper).')
 
       // State automatically updated by Homebridge after handler completes
     } catch (error) {
@@ -84,10 +76,10 @@ export class OnOffLightAccessory extends BaseMatterAccessory {
     this.logInfo('turning off.')
 
     try {
-      // TODO: Control your physical device here
-      // await myLightAPI.turnOff(this.context.deviceId)
+      // Delegate to the platform-provided helper (OpenAPI/BLE) when available
+      await this.sendOffCommand()
 
-      this.logInfo('physical device turned off.')
+      this.logInfo('physical device turned off (via platform helper).')
 
       // State automatically updated by Homebridge after handler completes
     } catch (error) {

package/src/devices-matter/OnOffOutletAccessory.ts

@@ -13,13 +13,8 @@ export class OnOffOutletAccessory extends BaseMatterAccessory {
     const clusters = opts?.clusters ?? { onOff: { onOff: false } }
     const handlers = opts?.handlers ?? {
       onOff: {
-        on: async () => {
-          // default no-op; platform may inject handlers via opts.handlers
-          log.debug(`${displayName} on handler invoked (default no-op).`)
-        },
-        off: async () => {
-          log.debug(`${displayName} off handler invoked (default no-op).`)
-        },
+        on: async () => this.handleOn(),
+        off: async () => this.handleOff(),
       },
     }
 
@@ -43,4 +38,14 @@ export class OnOffOutletAccessory extends BaseMatterAccessory {
   public updateOnOffState(isOn: boolean): void {
     this.updateState(this.api.matter.clusterNames.OnOff, { onOff: isOn })
   }
+
+  private async handleOn(): Promise<void> {
+    this.logInfo('turning on.')
+    await this.sendOnCommand()
+  }
+
+  private async handleOff(): Promise<void> {
+    this.logInfo('turning off.')
+    await this.sendOffCommand()
+  }
 }

package/src/devices-matter/OnOffSwitchAccessory.ts

@@ -37,12 +37,12 @@ export class OnOffSwitchAccessory extends BaseMatterAccessory {
 
   private async handleOn(): Promise<void> {
     this.logInfo('turning on.')
-    // TODO: await mySwitchAPI.turnOn()
+    await this.sendOnCommand()
   }
 
   private async handleOff(): Promise<void> {
     this.logInfo('turning off.')
-    // TODO: await mySwitchAPI.turnOff()
+    await this.sendOffCommand()
   }
 
   public updateOnOffState(isOn: boolean): void {