@switchbot/homebridge-switchbot 5.1.1 → 5.1.2

package/src/devices/genericDevice.ts

@@ -529,7 +529,88 @@ export class GenericDevice extends DeviceBase {
 }
 
 // Specific device classes can extend GenericDevice for custom behavior.
-export class BotDevice extends GenericDevice {}
+export class BotDevice extends GenericDevice {
+  private lastCommand?: { on: boolean, at: number }
+
+  createHAPAccessory(api: any): any {
+    const config = this.cfg.devices?.find((device: any) => (device.deviceId ?? device.id) === this.opts.id)
+    // Keep the old per-device type override for configurations made before v5.
+    const display = config?.botDisplay ?? config?.type ?? 'switch'
+    const pressMode = config?.mode === 'press' || config?.mode === 'multipress'
+      || (display === 'door' && config?.mode !== 'switch')
+
+    const isOn = async () => {
+      if (pressMode) {
+        return false
+      }
+      if (this.lastCommand && Date.now() - this.lastCommand.at < 15_000) {
+        return this.lastCommand.on
+      }
+      const state = await this.getState()
+      return !!(state && (state.on === true || state.state === 'on' || state.power === 'on'))
+    }
+
+    const setOn = async (on: boolean) => {
+      if (pressMode && !on) {
+        return
+      }
+      const command = pressMode ? 'press' : on ? 'turnOn' : 'turnOff'
+      const result = await this.setState({ command, parameter: 'default', commandType: 'command' })
+      if (result !== true && result?.success !== true) {
+        throw new Error(`SwitchBot Bot ${command} failed: ${result?.reason ?? 'unknown error'}`)
+      }
+      if (!pressMode) {
+        this.lastCommand = { on, at: Date.now() }
+      }
+    }
+
+    const control = (name: string, active: number | boolean, inactive: number | boolean, requestedOn: (value: any) => boolean) => ({
+      get: async () => (await isOn()) ? active : inactive,
+      set: async (value: any) => setOn(requestedOn(value)),
+      ...(pressMode ? { refreshAfterSet: [name] } : {}),
+    })
+    const position = () => ({
+      CurrentPosition: { get: async () => (await isOn()) ? 100 : 0 },
+      PositionState: { get: async () => 2 },
+      TargetPosition: control('TargetPosition', 100, 0, value => Number(value) > 0),
+    })
+    const active = (value: any) => Number(value) === 1
+    const presentations: Record<string, { type: string, characteristics: Record<string, any> }> = {
+      switch: { type: 'Switch', characteristics: { On: control('On', true, false, value => value === true) } },
+      outlet: { type: 'Outlet', characteristics: { On: control('On', true, false, value => value === true) } },
+      door: { type: 'Door', characteristics: position() },
+      window: { type: 'Window', characteristics: position() },
+      windowcovering: { type: 'WindowCovering', characteristics: position() },
+      garagedoor: { type: 'GarageDoorOpener', characteristics: {
+        CurrentDoorState: { get: async () => (await isOn()) ? 0 : 1 },
+        TargetDoorState: control('TargetDoorState', 0, 1, value => Number(value) === 0),
+        ObstructionDetected: { get: async () => false },
+      } },
+      lock: { type: 'LockMechanism', characteristics: {
+        LockCurrentState: { get: async () => (await isOn()) ? 0 : 1 },
+        LockTargetState: control('LockTargetState', 0, 1, value => Number(value) === 0),
+      } },
+      faucet: { type: 'Faucet', characteristics: { Active: control('Active', 1, 0, active) } },
+      fan: { type: 'Fanv2', characteristics: { Active: control('Active', 1, 0, active) } },
+      stateful: { type: 'StatefulProgrammableSwitch', characteristics: {
+        ProgrammableSwitchEvent: {},
+        ProgrammableSwitchOutputState: {
+          ...control('ProgrammableSwitchOutputState', 1, 0, active),
+          ...(pressMode ? { refreshAfterSet: ['ProgrammableSwitchOutputState'] } : {}),
+          afterSet: (value: any, service: any, hap: any) => {
+            if (!pressMode || active(value)) {
+              service.getCharacteristic(hap.Characteristic.ProgrammableSwitchEvent).sendEventNotification(0)
+            }
+          },
+        },
+      } },
+    }
+
+    return {
+      services: [presentations[display] ?? presentations.switch],
+    }
+  }
+}
 
 export class CurtainDevice extends GenericDevice {
   private lastKnownPosition = 0
@@ -1364,34 +1445,69 @@ export class RollerShadeDevice extends CurtainDevice {}
 
 export class Hub2Device extends GenericDevice {}
 
+/** Default ppm at or above which HomeKit is told the CO2 level is abnormal. */
+const CO2_ABNORMAL_PPM_DEFAULT = 1000
+
 export class MeterDevice extends GenericDevice {
+  /**
+   * The Meter Pro (CO2) reports carbon dioxide as well. `opts.type` is 'meter'
+   * for every meter variant, so check the configured device type.
+   */
+  protected reportsCO2(): boolean {
+    return /co2/i.test(String((this.opts as any)?.deviceType ?? ''))
+  }
+
+  /** The ppm at which HomeKit reports carbon dioxide as detected. */
+  protected co2AbnormalThreshold(): number {
+    const value = Number((this.cfg as any)?.co2AbnormalThreshold)
+    return Number.isFinite(value) && value > 0 ? value : CO2_ABNORMAL_PPM_DEFAULT
+  }
+
   createHAPAccessory(api: any) {
-    return {
-      services: [
-        {
-          type: 'TemperatureSensor',
-          characteristics: {
-            CurrentTemperature: {
-              get: async () => {
-                const s = await this.getState()
-                return typeof s.temperature === 'number' ? s.temperature : 0
-              },
+    const services: any[] = [
+      {
+        type: 'TemperatureSensor',
+        characteristics: {
+          CurrentTemperature: {
+            get: async () => {
+              const s = await this.getState()
+              return typeof s.temperature === 'number' ? s.temperature : 0
             },
           },
         },
-        {
-          type: 'HumiditySensor',
-          characteristics: {
-            CurrentRelativeHumidity: {
-              get: async () => {
-                const s = await this.getState()
-                return typeof s.humidity === 'number' ? s.humidity : 0
-              },
+      },
+      {
+        type: 'HumiditySensor',
+        characteristics: {
+          CurrentRelativeHumidity: {
+            get: async () => {
+              const s = await this.getState()
+              return typeof s.humidity === 'number' ? s.humidity : 0
             },
           },
         },
-      ],
+      },
+    ]
+
+    if (this.reportsCO2()) {
+      const co2 = async (): Promise<number> => {
+        const s = await this.getState()
+        return typeof s.co2 === 'number' ? s.co2 : 0
+      }
+      services.push({
+        type: 'CarbonDioxideSensor',
+        characteristics: {
+          CarbonDioxideLevel: {
+            get: co2,
+          },
+          CarbonDioxideDetected: {
+            get: async () => ((await co2()) >= this.co2AbnormalThreshold() ? 1 : 0),
+          },
+        },
+      })
     }
+
+    return { services }
   }
 }
 

package/src/homebridge-ui/public/index.html

@@ -199,6 +199,11 @@
         <input type="number" id="matterBatchJitter" min="0" max="300" step="1" value="0" />
         <small>Random startup delay before the first batch to reduce synchronized spikes. Default: 0.</small>
       </div>
+      <div class="form-group">
+        <label for="co2AbnormalThreshold">CO2 Detected Threshold (ppm)</label>
+        <input type="number" id="co2AbnormalThreshold" min="400" max="5000" step="1" value="1000" />
+        <small>Meter Pro (CO2) only. At or above this level HomeKit reports carbon dioxide as detected. Default: 1000.</small>
+      </div>
       <button type="button" id="saveAdvancedSettingsBtn">Save Advanced Settings</button>
       <div id="advancedSettingsStatus" style="margin-top: 8px; font-size: 12px;"></div>
     </form>

package/src/homebridge-ui/public/js/advanced-settings.ts

@@ -29,6 +29,7 @@ async function loadAdvancedSettings(): Promise<void> {
     ;(document.getElementById('enableBLE') as HTMLInputElement).checked = config.enableBLE !== false
     ;(document.getElementById('blePollingEnabled') as HTMLInputElement).checked = config.blePollingEnabled !== false
     ;(document.getElementById('blePollIntervalMs') as HTMLInputElement).value = String(config.blePollIntervalMs ?? 600000)
+    ;(document.getElementById('co2AbnormalThreshold') as HTMLInputElement).value = String(config.co2AbnormalThreshold ?? 1000)
   } catch (e) {
     (document.getElementById('advancedSettingsStatus') as HTMLElement).textContent = 'Failed to load settings.'
   }
@@ -67,6 +68,7 @@ async function saveAdvancedSettings(): Promise<void> {
     config.enableBLE = (document.getElementById('enableBLE') as HTMLInputElement).checked
     config.blePollingEnabled = (document.getElementById('blePollingEnabled') as HTMLInputElement).checked
     config.blePollIntervalMs = Number((document.getElementById('blePollIntervalMs') as HTMLInputElement).value) || 600000
+    config.co2AbnormalThreshold = Number((document.getElementById('co2AbnormalThreshold') as HTMLInputElement).value) || 1000
 
     // Update config in memory and save to disk
     if (typeof homebridge.updatePluginConfig === 'function') {

package/test/device/bot-hap.spec.ts

@@ -0,0 +1,184 @@
+import { Accessory, Characteristic, Service, uuid } from '@homebridge/hap-nodejs'
+import { describe, expect, it, vi } from 'vitest'
+
+import { BotDevice } from '../../src/devices/genericDevice.js'
+import { SwitchBotHAPPlatform } from '../../src/SwitchBotHAPPlatform.js'
+
+const id = 'bot-door-test'
+const log = { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() }
+
+function bot(config: Record<string, unknown>, result: unknown = { success: true }) {
+  const setDeviceState = vi.fn(async () => result)
+  const device = new BotDevice(
+    { id, type: 'Bot', name: 'Entrance', log, blePollingEnabled: false },
+    { log, devices: [{ deviceId: id, configDeviceType: 'Bot', ...config }], _client: { setDeviceState } } as any,
+  )
+  return { device, setDeviceState }
+}
+
+const displays = [
+  ['switch', 'Switch', 'On', true, false],
+  ['outlet', 'Outlet', 'On', true, false],
+  ['door', 'Door', 'TargetPosition', 100, 0],
+  ['window', 'Window', 'TargetPosition', 100, 0],
+  ['windowcovering', 'WindowCovering', 'TargetPosition', 100, 0],
+  ['garagedoor', 'GarageDoorOpener', 'TargetDoorState', 0, 1],
+  ['lock', 'LockMechanism', 'LockTargetState', 0, 1],
+  ['faucet', 'Faucet', 'Active', 1, 0],
+  ['fan', 'Fanv2', 'Active', 1, 0],
+  ['stateful', 'StatefulProgrammableSwitch', 'ProgrammableSwitchOutputState', 1, 0],
+] as const
+
+describe('bot HomeKit presentation', () => {
+  it('keeps the default Switch presentation', () => {
+    expect(bot({}).device.createHAPAccessory({}).services[0].type).toBe('Switch')
+  })
+
+  it.each(displays)('restores %s as a HAP %s with Press Mode', async (display, serviceType, controlName, active, inactive) => {
+    const { device, setDeviceState } = bot({ botDisplay: display, mode: 'press' })
+    const descriptor = device.createHAPAccessory({}).services[0]
+    expect(descriptor.type).toBe(serviceType)
+    const required = new (Service as any)[serviceType]().characteristics
+    const provided = new Set(Object.keys(descriptor.characteristics).map(name => (Characteristic as any)[name]?.UUID))
+    for (const characteristic of required) {
+      expect(provided.has(characteristic.UUID)).toBe(true)
+    }
+    const control = descriptor.characteristics[controlName]
+    await control.set(active)
+    await control.set(inactive)
+    expect(await control.get()).toBe(inactive)
+    expect(setDeviceState).toHaveBeenCalledExactlyOnceWith(id, {
+      command: 'press',
+      parameter: 'default',
+      commandType: 'command',
+    })
+  })
+
+  it.each(displays)('registers %s and resets its HAP control after a press', async (display, serviceType, controlName, active, inactive) => {
+    const { device } = bot({ botDisplay: display, mode: 'press' })
+    const accessory = new Accessory('Entrance', uuid.generate(id))
+    accessory.addService(Service.Switch)
+    const api = { hap: { Service, Characteristic, uuid }, registerPlatformAccessories: vi.fn() }
+    const platform = Object.create(SwitchBotHAPPlatform.prototype) as any
+    platform.api = api
+    platform.log = log
+    platform.accessories = new Map([[uuid.generate(id), accessory]])
+    platform.hapPushTargets = new Map()
+    const created = { instance: device, createAccessory: () => device.createHAPAccessory(api) }
+
+    await platform.registerHAPAccessories([{ created, d: { id, name: 'Entrance' }, type: 'Bot' }])
+
+    const service = accessory.getService((Service as any)[serviceType])!
+    expect(service).toBeDefined()
+    if (serviceType !== 'Switch') {
+      expect(accessory.getService(Service.Switch)).toBeUndefined()
+    }
+    const characteristic = service.getCharacteristic((Characteristic as any)[controlName])
+    await characteristic.handleSetRequest(active)
+    await new Promise(resolve => setTimeout(resolve, 10))
+    expect(characteristic.value).toBe(inactive)
+  })
+
+  it('uses turnOn and turnOff for physical Switch Mode', async () => {
+    const { device, setDeviceState } = bot({ botDisplay: 'door', mode: 'switch' })
+    const target = device.createHAPAccessory({}).services[0].characteristics.TargetPosition
+    await target.set(100)
+    expect(await target.get()).toBe(100)
+    await target.set(0)
+    expect(await target.get()).toBe(0)
+    expect(setDeviceState.mock.calls.map(([, body]) => body.command)).toEqual(['turnOn', 'turnOff'])
+  })
+
+  it('reloads a Bot when its physical mode changes', async () => {
+    const platform = Object.create(SwitchBotHAPPlatform.prototype) as any
+    platform.config = { devices: [{ deviceId: id, configDeviceType: 'Bot', mode: 'switch' }] }
+    platform.lastConfigHash = platform.getConfigHash()
+    platform.config.devices[0].mode = 'press'
+    platform.log = log
+    platform.accessories = new Map()
+    platform.devices = []
+    platform.loadDevices = vi.fn(async () => {})
+
+    await platform.checkAndReloadDevices()
+
+    expect(platform.loadDevices).toHaveBeenCalledOnce()
+  })
+
+  it('emits each Stateful Programmable Switch press as an event', async () => {
+    const { device, setDeviceState } = bot({ botDisplay: 'stateful', mode: 'press' })
+    const accessory = new Accessory('Entrance', uuid.generate(id))
+    const api = { hap: { Service, Characteristic, uuid }, registerPlatformAccessories: vi.fn() }
+    const platform = Object.create(SwitchBotHAPPlatform.prototype) as any
+    platform.api = api
+    platform.log = log
+    platform.accessories = new Map([[uuid.generate(id), accessory]])
+    platform.hapPushTargets = new Map()
+    const created = { instance: device, createAccessory: () => device.createHAPAccessory(api) }
+    await platform.registerHAPAccessories([{ created, d: { id, name: 'Entrance' }, type: 'Bot' }])
+
+    const service = accessory.getService(Service.StatefulProgrammableSwitch)!
+    const event = service.getCharacteristic(Characteristic.ProgrammableSwitchEvent)
+    const notify = vi.spyOn(event, 'sendEventNotification')
+    const output = service.getCharacteristic(Characteristic.ProgrammableSwitchOutputState)
+    await output.handleSetRequest(1)
+    await new Promise(resolve => setTimeout(resolve, 10))
+    await output.handleSetRequest(1)
+    await new Promise(resolve => setTimeout(resolve, 10))
+    await output.handleSetRequest(0)
+    await new Promise(resolve => setTimeout(resolve, 10))
+
+    expect(notify).toHaveBeenCalledTimes(2)
+    expect(notify).toHaveBeenCalledWith(0)
+    expect(setDeviceState).toHaveBeenCalledTimes(2)
+  })
+
+  it('sends one press for Open and none for Close', async () => {
+    const { device, setDeviceState } = bot({ botDisplay: 'door' })
+    const chars = device.createHAPAccessory({}).services[0].characteristics
+    expect(await chars.TargetPosition.get()).toBe(0)
+    expect(await chars.CurrentPosition.get()).toBe(0)
+    expect(await chars.PositionState.get()).toBe(2)
+    await chars.TargetPosition.set(100)
+    await chars.TargetPosition.set(0)
+    expect(setDeviceState).toHaveBeenCalledExactlyOnceWith(id, {
+      command: 'press',
+      parameter: 'default',
+      commandType: 'command',
+    })
+  })
+
+  it('reports a failed press to HomeKit', async () => {
+    const { device } = bot({ type: 'door' }, { success: false, reason: 'offline' })
+    await expect(device.createHAPAccessory({}).services[0].characteristics.TargetPosition.set(100))
+      .rejects
+      .toThrow('offline')
+  })
+
+  it('replaces a cached Switch and resets TargetPosition after HAP commits the write', async () => {
+    const { device, setDeviceState } = bot({ botDisplay: 'door' })
+    const accessory = new Accessory('Entrance', uuid.generate(id))
+    accessory.addService(Service.Switch)
+    const api = {
+      hap: { Service, Characteristic, uuid },
+      registerPlatformAccessories: vi.fn(),
+    }
+    const platform = Object.create(SwitchBotHAPPlatform.prototype) as any
+    platform.api = api
+    platform.log = log
+    platform.accessories = new Map([[uuid.generate(id), accessory]])
+    platform.hapPushTargets = new Map()
+    const created = { instance: device, createAccessory: () => device.createHAPAccessory(api) }
+
+    await platform.registerHAPAccessories([{ created, d: { id, name: 'Entrance' }, type: 'Bot' }])
+
+    expect(accessory.getService(Service.Switch)).toBeUndefined()
+    const door = accessory.getService(Service.Door)!
+    expect(door.getCharacteristic(Characteristic.CurrentPosition)).toBeDefined()
+    expect(door.getCharacteristic(Characteristic.PositionState)).toBeDefined()
+    const target = door.getCharacteristic(Characteristic.TargetPosition)
+    await target.handleSetRequest(100)
+    await new Promise(resolve => setTimeout(resolve, 20))
+    expect(target.value).toBe(0)
+    expect(setDeviceState).toHaveBeenCalledTimes(1)
+  })
+})

package/test/device/meter-co2.spec.ts

@@ -0,0 +1,96 @@
+/* Copyright(C) 2021-2026, donavanbecker (https://github.com/donavanbecker). All rights reserved.
+ *
+ * meter-co2.spec.ts: the Meter Pro (CO2) exposes a CarbonDioxideSensor service
+ */
+
+import { WoSensorTHProCO2 } from 'node-switchbot'
+import { describe, expect, it, vi } from 'vitest'
+
+import { createDevice } from '../../src/deviceFactory.js'
+import { MeterDevice } from '../../src/devices/genericDevice.js'
+
+const log: any = { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn(), success: vi.fn() }
+
+function meter(deviceType: string | undefined, status: Record<string, unknown>, cfg: Record<string, unknown> = {}) {
+  const device = new MeterDevice({ id: 'B0E9FED044E3', type: 'meter', deviceType, name: 'Meter', log } as any, { log, ...cfg } as any)
+  vi.spyOn(device, 'getState').mockResolvedValue(status)
+  return device
+}
+
+function serviceTypes(device: MeterDevice) {
+  return device.createHAPAccessory(null).services.map((s: any) => s.type)
+}
+
+function read(device: MeterDevice, type: string, characteristic: string) {
+  const service = device.createHAPAccessory(null).services.find((s: any) => s.type === type)
+  return service.characteristics[characteristic].get()
+}
+
+const READING = { temperature: 22.7, humidity: 55, co2: 483 }
+
+describe('meterDevice CO2 service', () => {
+  it.each(['MeterPro(CO2)', 'Meter Pro (CO2)'])('is added for %s', (deviceType) => {
+    expect(serviceTypes(meter(deviceType, READING))).toEqual(['TemperatureSensor', 'HumiditySensor', 'CarbonDioxideSensor'])
+  })
+
+  it.each(['Meter', 'Meter Plus', 'MeterPro', 'Outdoor Meter', undefined])('is not added for %s', (deviceType) => {
+    expect(serviceTypes(meter(deviceType, READING))).toEqual(['TemperatureSensor', 'HumiditySensor'])
+  })
+
+  it('reports the CO2 level in ppm', async () => {
+    await expect(read(meter('MeterPro(CO2)', READING), 'CarbonDioxideSensor', 'CarbonDioxideLevel')).resolves.toBe(483)
+  })
+
+  it('leaves temperature and humidity as they were', async () => {
+    const device = meter('MeterPro(CO2)', READING)
+
+    await expect(read(device, 'TemperatureSensor', 'CurrentTemperature')).resolves.toBe(22.7)
+    await expect(read(device, 'HumiditySensor', 'CurrentRelativeHumidity')).resolves.toBe(55)
+  })
+})
+
+describe('meterDevice CO2 detected threshold', () => {
+  const detected = (co2: number, cfg: Record<string, unknown> = {}) =>
+    read(meter('MeterPro(CO2)', { ...READING, co2 }, cfg), 'CarbonDioxideSensor', 'CarbonDioxideDetected')
+
+  it('defaults to 1000 ppm', async () => {
+    await expect(detected(999)).resolves.toBe(0)
+    await expect(detected(1000)).resolves.toBe(1)
+  })
+
+  it('uses co2AbnormalThreshold when set', async () => {
+    await expect(detected(799, { co2AbnormalThreshold: 800 })).resolves.toBe(0)
+    await expect(detected(800, { co2AbnormalThreshold: 800 })).resolves.toBe(1)
+  })
+
+  it.each([['zero', 0], ['negative', -1], ['text', 'high'], ['missing', undefined]])(
+    'falls back to 1000 when the setting is %s',
+    async (_label, value) => {
+      await expect(detected(999, { co2AbnormalThreshold: value })).resolves.toBe(0)
+      await expect(detected(1000, { co2AbnormalThreshold: value })).resolves.toBe(1)
+    },
+  )
+})
+
+// End to end: the plugin's createDevice() with the real node-switchbot class,
+// fed the status body a real Meter Pro (CO2) returned from the OpenAPI.
+describe('a Meter Pro (CO2) end to end', () => {
+  it('reports CO2 to HomeKit through node-switchbot', async () => {
+    const apiBody = { version: 'V1.8', temperature: 22.7, battery: 100, humidity: 55, CO2: 483, deviceId: 'B0E9FED044E3', deviceType: 'MeterPro(CO2)', hubDeviceId: '000000000000' }
+    const switchBotDevice = new WoSensorTHProCO2(
+      { id: 'B0E9FED044E3', name: 'Meter Pro CO2 Monitor', deviceType: 'MeterPro(CO2)', connectionTypes: ['api'] } as any,
+      { apiClient: { getStatus: async () => apiBody } } as any,
+    )
+    const client = { init: async () => {}, getDevice: async () => switchBotDevice }
+
+    const created: any = await createDevice(
+      { id: 'B0E9FED044E3', type: 'meter', deviceType: 'MeterPro(CO2)', name: 'Meter Pro CO2 Monitor', log } as any,
+      { log, _client: client } as any,
+      false,
+    )
+    const service = created.createAccessory(null).services.find((s: any) => s.type === 'CarbonDioxideSensor')
+
+    await expect(service.characteristics.CarbonDioxideLevel.get()).resolves.toBe(483)
+    await expect(service.characteristics.CarbonDioxideDetected.get()).resolves.toBe(0)
+  })
+})