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

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,
+    })
+  }
+}

package/src/devices-matter/FanAccessory.ts

@@ -0,0 +1,87 @@
+/**
+ * Fan Accessory Class
+ */
+
+import type { API, Logger, MatterRequests } from 'homebridge'
+
+import { BaseMatterAccessory } from './BaseMatterAccessory.js'
+
+export class FanAccessory extends BaseMatterAccessory {
+  constructor(api: API, log: Logger) {
+    const serialNumber = 'FAN-001'
+    super(api, log, {
+      uuid: api.matter.uuid.generate(serialNumber),
+      displayName: 'Fan',
+      deviceType: api.matter.deviceTypes.Fan,
+      serialNumber,
+      manufacturer: 'Homebridge Matter',
+      model: 'HB-MATTER-FAN',
+      firmwareRevision: '2.0.0',
+      hardwareRevision: '1.0.0',
+
+      clusters: {
+        fanControl: {
+          fanMode: api.matter.types.FanControl.FanMode.Off,
+          fanModeSequence: api.matter.types.FanControl.FanModeSequence.OffLowMedHigh,
+          percentSetting: 0,
+          percentCurrent: 0,
+        },
+      },
+
+      handlers: {
+        fanControl: {
+          step: async (request: MatterRequests.FanStep) => this.handleStep(request),
+          fanModeChange: async (request: { fanMode: number, oldFanMode: number }) => this.handleFanModeChange(request),
+          percentSettingChange: async (request: { percentSetting: number | null, oldPercentSetting: number | null }) =>
+            this.handlePercentSettingChange(request),
+        },
+      },
+    })
+
+    this.logInfo('initialized.')
+  }
+
+  private async handleStep(request: MatterRequests.FanStep): Promise<void> {
+    this.logInfo(`FanStep request: ${JSON.stringify(request)}`)
+    const { direction, wrap, lowestOff } = request
+    const dirStr = direction === 0 ? 'increase' : 'decrease'
+    this.logInfo(`step ${dirStr} (wrap: ${wrap}, lowestoff: ${lowestOff}).`)
+    // TODO: await myFanAPI.step(direction, wrap, lowestOff)
+  }
+
+  private async handleFanModeChange(request: { fanMode: number, oldFanMode: number }): Promise<void> {
+    this.logInfo(`FanMode change: ${JSON.stringify(request)}`)
+    const modeNames = ['Off', 'Low', 'Medium', 'High', 'On', 'Auto', 'Smart']
+    const modeName = modeNames[request.fanMode] || `Unknown (${request.fanMode})`
+    this.logInfo(`fan mode changed to: ${modeName}.`)
+    // TODO: await myFanAPI.setMode(request.fanMode)
+  }
+
+  private async handlePercentSettingChange(request: { percentSetting: number | null, oldPercentSetting: number | null }): Promise<void> {
+    this.logInfo(`PercentSetting change: ${JSON.stringify(request)}`)
+    const percent = request.percentSetting ?? 0
+    const isOff = percent === 0
+    const wasOff = (request.oldPercentSetting ?? 0) === 0
+
+    if (isOff !== wasOff) {
+      this.logInfo(`fan turned ${isOff ? 'off' : 'on'}.`)
+    }
+
+    if (!isOff) {
+      this.logInfo(`fan speed changed to: ${percent}%.`)
+    }
+    // TODO: await myFanAPI.setSpeed(percent)
+  }
+
+  public updateFanMode(mode: number): void {
+    this.updateState(this.api.matter.clusterNames.FanControl, { fanMode: mode })
+  }
+
+  public updateFanSpeed(percent: number): void {
+    this.updateState(this.api.matter.clusterNames.FanControl, {
+      percentSetting: percent,
+      percentCurrent: percent,
+    })
+    this.logInfo(`fan speed: ${percent}%.`)
+  }
+}

package/src/devices-matter/HumiditySensorAccessory.ts

@@ -0,0 +1,39 @@
+/**
+ * Humidity Sensor Accessory Class
+ */
+
+import type { API, Logger } from 'homebridge'
+
+import { BaseMatterAccessory } from './BaseMatterAccessory.js'
+
+export class HumiditySensorAccessory extends BaseMatterAccessory {
+  constructor(api: API, log: Logger) {
+    const serialNumber = 'SENSOR-005'
+    super(api, log, {
+      uuid: api.matter.uuid.generate(serialNumber),
+      displayName: 'Humidity Sensor',
+      deviceType: api.matter.deviceTypes.HumiditySensor,
+      serialNumber,
+      manufacturer: 'Homebridge Matter',
+      model: 'HB-MATTER-SENSOR-HUMIDITY',
+      firmwareRevision: '2.0.0',
+      hardwareRevision: '1.0.0',
+
+      clusters: {
+        relativeHumidityMeasurement: {
+          measuredValue: 5500, // 55% (in hundredths of a percent)
+          minMeasuredValue: 0,
+          maxMeasuredValue: 10000,
+        },
+      },
+    })
+
+    this.logInfo('initialized.')
+  }
+
+  public updateHumidity(percent: number): void {
+    const value = Math.round(percent * 100) // convert to hundredths
+    this.updateState('relativeHumidityMeasurement', { measuredValue: value })
+    this.logInfo(`humidity: ${percent}%.`)
+  }
+}

package/src/devices-matter/LeakSensorAccessory.ts

@@ -0,0 +1,36 @@
+/**
+ * Leak Sensor Accessory Class
+ */
+
+import type { API, Logger } from 'homebridge'
+
+import { BaseMatterAccessory } from './BaseMatterAccessory.js'
+
+export class LeakSensorAccessory extends BaseMatterAccessory {
+  constructor(api: API, log: Logger) {
+    const serialNumber = 'SENSOR-007'
+    super(api, log, {
+      uuid: api.matter.uuid.generate(serialNumber),
+      displayName: 'Leak Sensor',
+      deviceType: api.matter.deviceTypes.LeakSensor,
+      serialNumber,
+      manufacturer: 'Homebridge Matter',
+      model: 'HB-MATTER-SENSOR-LEAK',
+      firmwareRevision: '2.0.0',
+      hardwareRevision: '1.0.0',
+
+      clusters: {
+        booleanState: {
+          stateValue: false, // false = dry, true = leak
+        },
+      },
+    })
+
+    this.logInfo('initialized.')
+  }
+
+  public updateLeakState(leakDetected: boolean): void {
+    this.updateState(this.api.matter.clusterNames.BooleanState, { stateValue: leakDetected })
+    this.logInfo(`leak: ${leakDetected ? 'detected' : 'none'}.`)
+  }
+}

package/src/devices-matter/LightSensorAccessory.ts

@@ -0,0 +1,39 @@
+/**
+ * Light Sensor Accessory Class
+ */
+
+import type { API, Logger } from 'homebridge'
+
+import { BaseMatterAccessory } from './BaseMatterAccessory.js'
+
+export class LightSensorAccessory extends BaseMatterAccessory {
+  constructor(api: API, log: Logger) {
+    const serialNumber = 'SENSOR-002'
+    super(api, log, {
+      uuid: api.matter.uuid.generate(serialNumber),
+      displayName: 'Light Sensor',
+      deviceType: api.matter.deviceTypes.LightSensor,
+      serialNumber,
+      manufacturer: 'Homebridge Matter',
+      model: 'HB-MATTER-SENSOR-LIGHT',
+      firmwareRevision: '2.0.0',
+      hardwareRevision: '1.0.0',
+
+      clusters: {
+        illuminanceMeasurement: {
+          measuredValue: 5000,
+          minMeasuredValue: 1,
+          maxMeasuredValue: 65534,
+        },
+      },
+    })
+
+    this.logInfo('initialized.')
+  }
+
+  public updateIlluminance(lux: number): void {
+    const value = Math.round(10000 * Math.log10(lux))
+    this.updateState('illuminanceMeasurement', { measuredValue: value })
+    this.logInfo(`illuminance: ${lux} lux.`)
+  }
+}

package/src/devices-matter/OccupancySensorAccessory.ts

@@ -0,0 +1,52 @@
+/**
+ * Occupancy Sensor Accessory Class
+ */
+
+import type { API, Logger } from 'homebridge'
+
+import { BaseMatterAccessory } from './BaseMatterAccessory.js'
+
+export class OccupancySensorAccessory extends BaseMatterAccessory {
+  constructor(api: API, log: Logger) {
+    const serialNumber = 'SENSOR-003'
+    // Note: Matter.js API calls this "MotionSensor" but it's actually an Occupancy Sensor
+    const OccupancySensingServer = api.matter.deviceTypes.MotionSensor.requirements.OccupancySensingServer
+    const OccupancySensorWithPIR = api.matter.deviceTypes.MotionSensor.with(
+      OccupancySensingServer.with('PassiveInfrared'),
+    )
+
+    super(api, log, {
+      uuid: api.matter.uuid.generate(serialNumber),
+      displayName: 'Occupancy Sensor',
+      deviceType: OccupancySensorWithPIR,
+      serialNumber,
+      manufacturer: 'Homebridge Matter',
+      model: 'HB-MATTER-SENSOR-OCCUPANCY',
+      firmwareRevision: '2.0.0',
+      hardwareRevision: '1.0.0',
+
+      clusters: {
+        occupancySensing: {
+          occupancy: {
+            occupied: false,
+          },
+          occupancySensorType: 0,
+          occupancySensorTypeBitmap: {
+            pir: true,
+            ultrasonic: false,
+            physicalContact: false,
+          },
+        },
+      },
+    })
+
+    this.logInfo('initialized.')
+  }
+
+  public updateOccupancyDetected(detected: boolean): void {
+    this.updateState('occupancySensing', {
+      occupancy: { occupied: detected },
+    })
+    this.logInfo(`occupancy: ${detected ? 'detected' : 'clear'}.`)
+  }
+}