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

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'}.`)
+  }
+}

package/src/devices-matter/OnOffLightAccessory.ts

@@ -0,0 +1,133 @@
+/**
+ * On/Off Light Accessory Class
+ *
+ * Example implementation of a device class that extends BaseMatterAccessory.
+ * This shows the pattern for creating device-specific classes.
+ */
+
+import type { API, Logger } from 'homebridge'
+
+import { BaseMatterAccessory } from './BaseMatterAccessory.js'
+
+/**
+ * On/Off Light Device Class
+ *
+ * This class represents an on/off light accessory.
+ * It extends BaseMatterAccessory to inherit common functionality.
+ */
+export class OnOffLightAccessory extends BaseMatterAccessory {
+  constructor(api: API, log: Logger) {
+    const serialNumber = 'LIGHT-001'
+    const displayName = 'On/Off Light'
+    const manufacturer = 'Homebridge Matter'
+    const model = 'HB-MATTER-LIGHT-ON-OFF'
+    const firmwareRevision = '2.0.0'
+    const hardwareRevision = '1.0.0'
+
+    // Call parent constructor with device configuration
+    super(api, log, {
+      uuid: api.matter.uuid.generate(serialNumber),
+      displayName,
+      deviceType: api.matter.deviceTypes.OnOffLight,
+      serialNumber,
+      manufacturer,
+      model,
+      firmwareRevision,
+      hardwareRevision,
+
+      // Initial cluster states
+      clusters: {
+        onOff: {
+          onOff: true, // initial state: light is on
+        },
+      },
+
+      // Command handlers
+      handlers: {
+        onOff: {
+          on: async () => this.handleOnCommand(),
+          off: async () => this.handleOffCommand(),
+        },
+      },
+    })
+
+    this.logInfo('initialized.')
+  }
+
+  /**
+   * Handle the "on" command from Matter
+   */
+  private async handleOnCommand(): Promise<void> {
+    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)
+
+      this.logInfo('physical device turned on.')
+
+      // State automatically updated by Homebridge after handler completes
+    } catch (error) {
+      this.logError('failed to turn on:', error)
+      throw error
+    }
+  }
+
+  /**
+   * Handle the "off" command from Matter
+   */
+  private async handleOffCommand(): Promise<void> {
+    this.logInfo('turning off.')
+
+    try {
+      // TODO: Control your physical device here
+      // await myLightAPI.turnOff(this.context.deviceId)
+
+      this.logInfo('physical device turned off.')
+
+      // State automatically updated by Homebridge after handler completes
+    } catch (error) {
+      this.logError('failed to turn off:', error)
+      throw error
+    }
+  }
+
+  /**
+   * Update the on/off state from external source
+   * Call this when your physical device state changes externally
+   */
+  public updateOnOffState(isOn: boolean): void {
+    this.updateState(this.api.matter.clusterNames.OnOff, { onOff: isOn })
+    this.logInfo(`state synced: ${isOn ? 'ON' : 'OFF'}.`)
+  }
+
+  /**
+   * Example: Start monitoring external state changes
+   * This shows how you might set up event listeners or polling
+   */
+  public startMonitoring(): void {
+    // Example: Event-based monitoring (recommended)
+    // mqttClient.subscribe('home/light/status')
+    // mqttClient.on('message', (topic, message) => {
+    //   const { state } = JSON.parse(message.toString())
+    //   const deviceIsOn = state === 'ON'
+    //   this.updateOnOffState(deviceIsOn)
+    // })
+
+    // Example: Polling-based monitoring (fallback)
+    // setInterval(async () => {
+    //   try {
+    //     const response = await fetch('https://api.mydevice.com/light/state')
+    //     const data = await response.json()
+    //     const deviceIsOn = data.power === 'on'
+    //     this.updateOnOffState(deviceIsOn)
+    //   } catch (error) {
+    //     this.logError('Polling error:', error)
+    //   }
+    // }, 5000) // Poll every 5 seconds
+  }
+}

package/src/devices-matter/OnOffOutletAccessory.ts

@@ -0,0 +1,52 @@
+/**
+ * On/Off Outlet Accessory Class
+ */
+
+import type { API, Logger } from 'homebridge'
+
+import { BaseMatterAccessory } from './BaseMatterAccessory.js'
+
+export class OnOffOutletAccessory extends BaseMatterAccessory {
+  constructor(api: API, log: Logger) {
+    const serialNumber = 'OUTLET-001'
+    super(api, log, {
+      uuid: api.matter.uuid.generate(serialNumber),
+      displayName: 'On/Off Outlet',
+      deviceType: api.matter.deviceTypes.OnOffOutlet,
+      serialNumber,
+      manufacturer: 'Homebridge Matter',
+      model: 'HB-MATTER-OUTLET-ON-OFF',
+      firmwareRevision: '2.0.0',
+      hardwareRevision: '1.0.0',
+
+      clusters: {
+        onOff: {
+          onOff: false,
+        },
+      },
+
+      handlers: {
+        onOff: {
+          on: async () => this.handleOn(),
+          off: async () => this.handleOff(),
+        },
+      },
+    })
+
+    this.logInfo('initialized.')
+  }
+
+  private async handleOn(): Promise<void> {
+    this.logInfo('turning on.')
+    // TODO: await myOutletAPI.turnOn()
+  }
+
+  private async handleOff(): Promise<void> {
+    this.logInfo('turning off.')
+    // TODO: await myOutletAPI.turnOff()
+  }
+
+  public updateOnOffState(isOn: boolean): void {
+    this.updateState(this.api.matter.clusterNames.OnOff, { onOff: isOn })
+  }
+}

package/src/devices-matter/OnOffSwitchAccessory.ts

@@ -0,0 +1,52 @@
+/**
+ * On/Off Switch Accessory Class
+ */
+
+import type { API, Logger } from 'homebridge'
+
+import { BaseMatterAccessory } from './BaseMatterAccessory.js'
+
+export class OnOffSwitchAccessory extends BaseMatterAccessory {
+  constructor(api: API, log: Logger) {
+    const serialNumber = 'SWITCH-001'
+    super(api, log, {
+      uuid: api.matter.uuid.generate(serialNumber),
+      displayName: 'On/Off Switch',
+      deviceType: api.matter.deviceTypes.OnOffSwitch,
+      serialNumber,
+      manufacturer: 'Homebridge Matter',
+      model: 'HB-MATTER-SWITCH-ON-OFF',
+      firmwareRevision: '2.0.0',
+      hardwareRevision: '1.0.0',
+
+      clusters: {
+        onOff: {
+          onOff: false,
+        },
+      },
+
+      handlers: {
+        onOff: {
+          on: async () => this.handleOn(),
+          off: async () => this.handleOff(),
+        },
+      },
+    })
+
+    this.logInfo('initialized.')
+  }
+
+  private async handleOn(): Promise<void> {
+    this.logInfo('turning on.')
+    // TODO: await mySwitchAPI.turnOn()
+  }
+
+  private async handleOff(): Promise<void> {
+    this.logInfo('turning off.')
+    // TODO: await mySwitchAPI.turnOff()
+  }
+
+  public updateOnOffState(isOn: boolean): void {
+    this.updateState(this.api.matter.clusterNames.OnOff, { onOff: isOn })
+  }
+}