@switchbot/homebridge-switchbot 4.3.2-beta.9 → 5.0.0-beta.1

package/src/devices-matter/ColorLightAccessory.ts

@@ -0,0 +1,113 @@
+/**
+ * Color Light Accessory Class (HS only)
+ * Hue and Saturation color control
+ */
+
+import type { API, Logger, MatterRequests } from 'homebridge'
+
+import { BaseMatterAccessory } from './BaseMatterAccessory.js'
+
+export class ColorLightAccessory extends BaseMatterAccessory {
+  constructor(api: API, log: Logger) {
+    const serialNumber = 'LIGHT-004'
+    super(api, log, {
+      uuid: api.matter.uuid.generate(serialNumber),
+      displayName: 'Colour Light (HS)',
+      deviceType: api.matter.deviceTypes.ExtendedColorLight,
+      serialNumber,
+      manufacturer: 'Homebridge Matter',
+      model: 'HB-MATTER-LIGHT-COLOUR-HS',
+      firmwareRevision: '2.0.0',
+      hardwareRevision: '1.0.0',
+
+      clusters: {
+        onOff: { onOff: false },
+        levelControl: {
+          currentLevel: 127,
+          minLevel: 1,
+          maxLevel: 254,
+        },
+        colorControl: {
+          colorMode: api.matter.types.ColorControl.ColorMode.CurrentHueAndCurrentSaturation,
+          currentHue: 0,
+          currentSaturation: 254,
+          currentX: 41942,
+          currentY: 21626,
+        },
+      },
+
+      handlers: {
+        onOff: {
+          on: async () => this.handleOn(),
+          off: async () => this.handleOff(),
+        },
+        levelControl: {
+          moveToLevelWithOnOff: async (request: MatterRequests.MoveToLevel) =>
+            this.handleSetLevel(request),
+        },
+        colorControl: {
+          moveToColorLogic: async (request: MatterRequests.MoveToColor) =>
+            this.handleSetColor(request),
+          moveToHueAndSaturationLogic: async (request: MatterRequests.MoveToHueAndSaturation) =>
+            this.handleSetHueSaturation(request),
+        },
+      },
+    })
+
+    this.logInfo('initialized.')
+  }
+
+  private async handleOn(): Promise<void> {
+    this.logInfo('turning on.')
+    // TODO: await myLightAPI.turnOn()
+  }
+
+  private async handleOff(): Promise<void> {
+    this.logInfo('turning off.')
+    // TODO: await myLightAPI.turnOff()
+  }
+
+  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)
+  }
+
+  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)
+  }
+
+  private async handleSetHueSaturation(request: MatterRequests.MoveToHueAndSaturation): Promise<void> {
+    this.logInfo(`MoveToHueAndSaturation request: ${JSON.stringify(request)}`)
+    const { hue, saturation, transitionTime } = 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)
+  }
+
+  public updateOnOffState(isOn: boolean): void {
+    this.updateState(this.api.matter.clusterNames.OnOff, { onOff: isOn })
+  }
+
+  public updateBrightness(percent: number): void {
+    const matterLevel = Math.max(1, Math.round((percent / 100) * 254))
+    this.updateState(this.api.matter.clusterNames.LevelControl, { currentLevel: matterLevel })
+  }
+
+  public updateHueSaturation(hue: number, saturation: number): void {
+    const matterHue = Math.round((hue / 360) * 254)
+    const matterSat = Math.round((saturation / 100) * 254)
+    this.updateState(this.api.matter.clusterNames.ColorControl, {
+      currentHue: matterHue,
+      currentSaturation: matterSat,
+    })
+  }
+}

package/src/devices-matter/ColorTemperatureLightAccessory.ts

@@ -0,0 +1,98 @@
+/**
+ * Color Temperature Light Accessory Class
+ */
+
+import type { API, Logger, MatterRequests } from 'homebridge'
+
+import { BaseMatterAccessory } from './BaseMatterAccessory.js'
+
+export class ColorTemperatureLightAccessory extends BaseMatterAccessory {
+  constructor(api: API, log: Logger) {
+    const serialNumber = 'LIGHT-003'
+    super(api, log, {
+      uuid: api.matter.uuid.generate(serialNumber),
+      displayName: 'Colour Temperature Light',
+      deviceType: api.matter.deviceTypes.ColorTemperatureLight,
+      serialNumber,
+      manufacturer: 'Homebridge Matter',
+      model: 'HB-MATTER-LIGHT-COLOUR-TEMP',
+      firmwareRevision: '2.0.0',
+      hardwareRevision: '1.0.0',
+
+      clusters: {
+        onOff: {
+          onOff: false,
+        },
+        levelControl: {
+          currentLevel: 127,
+          minLevel: 1,
+          maxLevel: 254,
+        },
+        colorControl: {
+          colorMode: api.matter.types.ColorControl.ColorMode.ColorTemperatureMireds,
+          colorTemperatureMireds: 250,
+          colorTempPhysicalMinMireds: 147,
+          colorTempPhysicalMaxMireds: 454,
+          coupleColorTempToLevelMinMireds: 147,
+        },
+      },
+
+      handlers: {
+        onOff: {
+          on: async () => this.handleOn(),
+          off: async () => this.handleOff(),
+        },
+        levelControl: {
+          moveToLevelWithOnOff: async (request: MatterRequests.MoveToLevel) =>
+            this.handleSetLevel(request),
+        },
+        colorControl: {
+          moveToColorTemperatureLogic: async (request: MatterRequests.MoveToColorTemperature) =>
+            this.handleSetColorTemperature(request),
+        },
+      },
+    })
+
+    this.logInfo('initialized.')
+  }
+
+  private async handleOn(): Promise<void> {
+    this.logInfo('turning on.')
+    // TODO: await myLightAPI.turnOn()
+  }
+
+  private async handleOff(): Promise<void> {
+    this.logInfo('turning off.')
+    // TODO: await myLightAPI.turnOff()
+  }
+
+  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)
+  }
+
+  private async handleSetColorTemperature(request: MatterRequests.MoveToColorTemperature): Promise<void> {
+    this.logInfo(`MoveToColorTemperature request: ${JSON.stringify(request)}`)
+    const { colorTemperatureMireds, transitionTime } = 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)
+  }
+
+  public updateOnOffState(isOn: boolean): void {
+    this.updateState(this.api.matter.clusterNames.OnOff, { onOff: isOn })
+  }
+
+  public updateBrightness(percent: number): void {
+    const matterLevel = Math.max(1, Math.round((percent / 100) * 254))
+    this.updateState(this.api.matter.clusterNames.LevelControl, { currentLevel: matterLevel })
+  }
+
+  public updateColorTemperature(kelvin: number): void {
+    const mireds = Math.round(1000000 / kelvin)
+    this.updateState(this.api.matter.clusterNames.ColorControl, { colorTemperatureMireds: mireds })
+  }
+}

package/src/devices-matter/ContactSensorAccessory.ts

@@ -0,0 +1,37 @@
+/**
+ * Contact Sensor Accessory Class
+ */
+
+import type { API, Logger } from 'homebridge'
+
+import { BaseMatterAccessory } from './BaseMatterAccessory.js'
+
+export class ContactSensorAccessory extends BaseMatterAccessory {
+  constructor(api: API, log: Logger) {
+    const serialNumber = 'SENSOR-001'
+    super(api, log, {
+      uuid: api.matter.uuid.generate(serialNumber),
+      displayName: 'Contact Sensor',
+      deviceType: api.matter.deviceTypes.ContactSensor,
+      serialNumber,
+      manufacturer: 'Homebridge Matter',
+      model: 'HB-MATTER-SENSOR-CONTACT',
+      firmwareRevision: '2.0.0',
+      hardwareRevision: '1.0.0',
+
+      clusters: {
+        booleanState: {
+          stateValue: true, // matter: true = closed/normal, false = open/triggered
+        },
+      },
+    })
+
+    this.logInfo('initialized.')
+  }
+
+  public updateContactState(isOpen: boolean): void {
+    // Matter BooleanState: false = open/triggered, true = closed/normal (inverted!)
+    this.updateState(this.api.matter.clusterNames.BooleanState, { stateValue: !isOpen })
+    this.logInfo(`contact state: ${isOpen ? 'OPEN' : 'CLOSED'}.`)
+  }
+}

package/src/devices-matter/DimmableLightAccessory.ts

@@ -0,0 +1,196 @@
+/**
+ * Dimmable Light Accessory Class
+ *
+ * Example of a more complex device with multiple clusters.
+ * Shows how to handle devices with on/off + level control.
+ */
+
+import type { API, Logger, MatterRequests } from 'homebridge'
+
+import { BaseMatterAccessory } from './BaseMatterAccessory.js'
+
+/**
+ * Dimmable Light Device Class
+ *
+ * Demonstrates:
+ * - Multiple clusters (OnOff + LevelControl)
+ * - Type-safe request handlers
+ * - Value conversion (Matter level ↔ percentage)
+ * - Custom public methods for external control
+ */
+export class DimmableLightAccessory extends BaseMatterAccessory {
+  // Track current state
+  private currentLevel: number = 127 // 50% brightness
+
+  constructor(api: API, log: Logger) {
+    const serialNumber = 'LIGHT-002'
+    const displayName = 'Dimmable Light'
+    const manufacturer = 'Homebridge Matter'
+    const model = 'HB-MATTER-LIGHT-DIMMABLE'
+    const firmwareRevision = '2.0.0'
+    const hardwareRevision = '1.0.0'
+
+    super(api, log, {
+      uuid: api.matter.uuid.generate(serialNumber),
+      displayName,
+      deviceType: api.matter.deviceTypes.DimmableLight,
+      serialNumber,
+      manufacturer,
+      model,
+      firmwareRevision,
+      hardwareRevision,
+
+      clusters: {
+        onOff: {
+          onOff: false,
+        },
+        levelControl: {
+          currentLevel: 127, // 50% brightness (range 1-254)
+          minLevel: 1,
+          maxLevel: 254,
+        },
+      },
+
+      handlers: {
+        onOff: {
+          on: async () => this.handleOn(),
+          off: async () => this.handleOff(),
+        },
+        levelControl: {
+          moveToLevelWithOnOff: async (request: MatterRequests.MoveToLevel) =>
+            this.handleSetLevel(request),
+        },
+      },
+    })
+
+    this.logInfo('initialized.')
+  }
+
+  /**
+   * Handle the "on" command
+   */
+  private async handleOn(): Promise<void> {
+    this.logInfo('turning on.')
+
+    try {
+      // TODO: Control your physical device
+      // await myLightAPI.turnOn()
+
+      this.logInfo('physical device turned on.')
+    } catch (error) {
+      this.logError('failed to turn on:', error)
+      throw error
+    }
+  }
+
+  /**
+   * Handle the "off" command
+   */
+  private async handleOff(): Promise<void> {
+    this.logInfo('turning off.')
+
+    try {
+      // TODO: Control your physical device
+      // await myLightAPI.turnOff()
+
+      this.logInfo('physical device turned off.')
+    } catch (error) {
+      this.logError('failed to turn off:', error)
+      throw error
+    }
+  }
+
+  /**
+   * Handle brightness level changes
+   */
+  private async handleSetLevel(request: MatterRequests.MoveToLevel): Promise<void> {
+    this.logInfo(`MoveToLevel request: ${JSON.stringify(request)}`)
+    const { level, transitionTime } = request
+
+    // Convert Matter level (1-254) to percentage (0-100%)
+    const brightnessPercent = Math.round((level / 254) * 100)
+    this.currentLevel = level
+
+    this.logInfo(`setting brightness to ${brightnessPercent}% (level: ${level}), transitionTime: ${transitionTime}.`)
+
+    try {
+      // TODO: Control your physical device
+      // await myLightAPI.setBrightness(brightnessPercent, transitionTime)
+
+      this.logInfo(`physical device brightness set to ${brightnessPercent}%.`)
+    } catch (error) {
+      this.logError('Failed to set brightness:', error)
+      throw error
+    }
+  }
+
+  /**
+   * Update on/off state from external source
+   */
+  public updateOnOffState(isOn: boolean): void {
+    this.updateState(this.api.matter.clusterNames.OnOff, { onOff: isOn })
+    this.logInfo(`state synced: ${isOn ? 'ON' : 'OFF'}.`)
+  }
+
+  /**
+   * Update brightness level from external source
+   * @param percent - Brightness percentage (0-100)
+   */
+  public updateBrightness(percent: number): void {
+    // Validate input
+    if (percent < 0 || percent > 100) {
+      this.logWarn(`Invalid brightness percentage: ${percent}. Must be 0-100.`)
+      return
+    }
+
+    // Convert percent to Matter level (1-254)
+    const matterLevel = Math.max(1, Math.round((percent / 100) * 254))
+    this.currentLevel = matterLevel
+
+    this.updateState(this.api.matter.clusterNames.LevelControl, {
+      currentLevel: matterLevel,
+    })
+
+    this.logInfo(`brightness synced: ${percent}% (level: ${matterLevel}).`)
+  }
+
+  /**
+   * Get current brightness as percentage
+   */
+  public getBrightness(): number {
+    return Math.round((this.currentLevel / 254) * 100)
+  }
+
+  /**
+   * Set brightness and power state together
+   * Useful for syncing complete state from external source
+   */
+  public updateFullState(isOn: boolean, percent: number): void {
+    this.updateOnOffState(isOn)
+    if (isOn) {
+      this.updateBrightness(percent)
+    }
+  }
+
+  /**
+   * Example monitoring setup
+   */
+  public startMonitoring(): void {
+    // Example: MQTT listener
+    // mqttClient.on('message', (topic, message) => {
+    //   const { state, brightness } = JSON.parse(message.toString())
+    //   this.updateFullState(state === 'ON', brightness)
+    // })
+
+    // Example: Polling
+    // setInterval(async () => {
+    //   try {
+    //     const response = await fetch('https://api.mydevice.com/light/state')
+    //     const data = await response.json()
+    //     this.updateFullState(data.power === 'on', data.brightness)
+    //   } catch (error) {
+    //     this.logError('Polling error:', error)
+    //   }
+    // }, 5000)
+  }
+}

package/src/devices-matter/DoorLockAccessory.ts

@@ -0,0 +1,56 @@
+/**
+ * Door Lock Accessory Class
+ */
+
+import type { API, Logger } from 'homebridge'
+
+import { BaseMatterAccessory } from './BaseMatterAccessory.js'
+
+export class DoorLockAccessory extends BaseMatterAccessory {
+  constructor(api: API, log: Logger) {
+    const serialNumber = 'LOCK-001'
+    super(api, log, {
+      uuid: api.matter.uuid.generate(serialNumber),
+      displayName: 'Door Lock',
+      deviceType: api.matter.deviceTypes.DoorLock,
+      serialNumber,
+      manufacturer: 'Homebridge Matter',
+      model: 'HB-MATTER-LOCK-DOOR',
+      firmwareRevision: '2.0.0',
+      hardwareRevision: '1.0.0',
+
+      clusters: {
+        doorLock: {
+          lockState: api.matter.types.DoorLock.LockState.Unlocked,
+          lockType: api.matter.types.DoorLock.LockType.DeadBolt,
+          actuatorEnabled: true,
+          operatingMode: api.matter.types.DoorLock.OperatingMode.Normal,
+        },
+      },
+
+      handlers: {
+        doorLock: {
+          lockDoor: async () => this.handleLock(),
+          unlockDoor: async () => this.handleUnlock(),
+        },
+      },
+    })
+
+    this.logInfo('initialized.')
+  }
+
+  private async handleLock(): Promise<void> {
+    this.logInfo('locked.')
+  }
+
+  private async handleUnlock(): Promise<void> {
+    this.logInfo('unlocked.')
+  }
+
+  public updateLockState(state: 0 | 1 | 2): void {
+    // 0 = Not fully locked, 1 = Locked, 2 = Unlocked
+    this.updateState('doorLock', { lockState: state })
+    const stateStr = ['Not Fully Locked', 'Locked', 'Unlocked'][state]
+    this.logInfo(`lock state: ${stateStr}.`)
+  }
+}

package/src/devices-matter/ExtendedColorLightAccessory.ts

@@ -0,0 +1,127 @@
+/**
+ * Extended Color Light Accessory Class (HS+CCT)
+ * Hue, Saturation, and Color Temperature control
+ */
+
+import type { API, Logger, MatterRequests } from 'homebridge'
+
+import { BaseMatterAccessory } from './BaseMatterAccessory.js'
+
+export class ExtendedColorLightAccessory extends BaseMatterAccessory {
+  constructor(api: API, log: Logger) {
+    const serialNumber = 'LIGHT-005'
+    super(api, log, {
+      uuid: api.matter.uuid.generate(serialNumber),
+      displayName: 'Extended Colour Light (HS+CCT)',
+      deviceType: api.matter.deviceTypes.ExtendedColorLight,
+      serialNumber,
+      manufacturer: 'Homebridge Matter',
+      model: 'HB-MATTER-LIGHT-EXTENDED-COLOUR',
+      firmwareRevision: '2.0.0',
+      hardwareRevision: '1.0.0',
+
+      clusters: {
+        onOff: { onOff: false },
+        levelControl: {
+          currentLevel: 127,
+          minLevel: 1,
+          maxLevel: 254,
+        },
+        colorControl: {
+          colorMode: api.matter.types.ColorControl.ColorMode.CurrentHueAndCurrentSaturation,
+          currentHue: 0,
+          currentSaturation: 254,
+          currentX: 41942,
+          currentY: 21626,
+          colorTemperatureMireds: 250,
+          colorTempPhysicalMinMireds: 147,
+          colorTempPhysicalMaxMireds: 454,
+          coupleColorTempToLevelMinMireds: 147,
+        },
+      },
+
+      handlers: {
+        onOff: {
+          on: async () => this.handleOn(),
+          off: async () => this.handleOff(),
+        },
+        levelControl: {
+          moveToLevelWithOnOff: async (request: MatterRequests.MoveToLevel) =>
+            this.handleSetLevel(request),
+        },
+        colorControl: {
+          moveToColorLogic: async (request: MatterRequests.MoveToColor) =>
+            this.handleSetColor(request),
+          moveToHueAndSaturationLogic: async (request: MatterRequests.MoveToHueAndSaturation) =>
+            this.handleSetHueSaturation(request),
+          moveToColorTemperatureLogic: async (request: MatterRequests.MoveToColorTemperature) =>
+            this.handleSetColorTemperature(request),
+        },
+      },
+    })
+
+    this.logInfo('initialized.')
+  }
+
+  private async handleOn(): Promise<void> {
+    this.logInfo('turning on.')
+    // TODO: await myLightAPI.turnOn()
+  }
+
+  private async handleOff(): Promise<void> {
+    this.logInfo('turning off.')
+    // TODO: await myLightAPI.turnOff()
+  }
+
+  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)
+  }
+
+  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)
+  }
+
+  private async handleSetHueSaturation(request: MatterRequests.MoveToHueAndSaturation): Promise<void> {
+    this.logInfo(`MoveToHueAndSaturation request: ${JSON.stringify(request)}`)
+    const { hue, saturation, transitionTime } = 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)
+  }
+
+  private async handleSetColorTemperature(request: MatterRequests.MoveToColorTemperature): Promise<void> {
+    this.logInfo(`MoveToColorTemperature request: ${JSON.stringify(request)}`)
+    const { colorTemperatureMireds, transitionTime } = request
+    const kelvin = Math.round(1000000 / colorTemperatureMireds)
+    this.logInfo(`setting color temp to ${kelvin}k, ${transitionTime}ms.`)
+    // TODO: await myLightAPI.setColorTemperature(kelvin, transitionTime)
+  }
+
+  public updateOnOffState(isOn: boolean): void {
+    this.updateState(this.api.matter.clusterNames.OnOff, { onOff: isOn })
+  }
+
+  public updateBrightness(percent: number): void {
+    const matterLevel = Math.max(1, Math.round((percent / 100) * 254))
+    this.updateState(this.api.matter.clusterNames.LevelControl, { currentLevel: matterLevel })
+  }
+
+  public updateHueSaturation(hue: number, saturation: number): void {
+    const matterHue = Math.round((hue / 360) * 254)
+    const matterSat = Math.round((saturation / 100) * 254)
+    this.updateState(this.api.matter.clusterNames.ColorControl, {
+      currentHue: matterHue,
+      currentSaturation: matterSat,
+    })
+  }
+}