@homebridge-plugins/homebridge-govee 11.32.2-beta.4 → 11.32.2-beta.6

package/CHANGELOG.md

@@ -17,6 +17,8 @@ All notable changes to `@homebridge-plugins/homebridge-govee` will be documented
 - feat: work out for itself whether a heater reports the room temperature, and add the H7137 and H713E
 - feat: add support for 85 more light models, covering everything currently sold that was missing
 - feat: add 24 more light models, three thermo-hygrometers and a leak detector
+- feat: add the H7103 and H7112 fans and the H5085 plug, with unknown controls saying so instead of guessing
+- feat: give every appliance type a starting handler, so a new model works for on and off and asks for the rest
 
 ## v11.32.1 (2026-08-02)
 

package/lib/device/appliance-basic.js

@@ -0,0 +1,280 @@
+import { base64ToHex, getTwoItemPosition, hexToTwoItems, parseError } from '../utils/functions.js'
+import platformLang from '../utils/lang-en.js'
+import { logUnknownData, reportUnsupportedControl } from '../utils/report-unknown.js'
+
+/**
+ * A starting point for any appliance whose power command is known but whose
+ * other controls are not.
+ *
+ * Govee uses the same on/off command for every appliance the plugin handles, so
+ * power can be offered with confidence for a model nobody has tested. The
+ * settings that differ per model - speeds, modes, sizes - are the risky part,
+ * and getting one wrong is worse than not offering it. So those controls appear
+ * but report what they need and fail the request, rather than sending a guess.
+ *
+ * Failing rather than doing nothing is deliberate: HomeKit shows the control as
+ * not responding, which is what sends the owner to the log, where they find a
+ * line to paste into an issue. That turns every owner of an untested model into
+ * the source of the data needed to finish it.
+ *
+ * Once that data arrives the model gets a proper handler and stops using this.
+ */
+class ApplianceBasic {
+  constructor(platform, accessory, config) {
+    // Set up variables from the platform
+    this.hapChar = platform.api.hap.Characteristic
+    this.hapErr = platform.api.hap.HapStatusError
+    this.hapServ = platform.api.hap.Service
+    this.platform = platform
+
+    // Set up variables from the accessory
+    this.accessory = accessory
+    this.config = config
+
+    // Some appliances can have a richer tile, but only if the device reports
+    // the reading that tile needs - HomeKit's humidifier, for example, has to
+    // show a current humidity, and plenty of Govee humidifiers never send one.
+    // Where Govee tells us the device has that sensor, use the better tile;
+    // otherwise fall back to the plain one, which needs nothing extra.
+    const hasSensor = config.richCapability
+      && !!accessory.context.openApiCapabilities?.[config.richCapability]
+    const serviceName = (config.richService && hasSensor) ? config.richService : config.service
+    this.usingRichService = serviceName === config.richService
+
+    // Drop the other service if this device has switched between the two
+    const otherName = this.usingRichService ? config.service : config.richService
+    if (otherName && this.hapServ[otherName]) {
+      const stale = this.accessory.getService(this.hapServ[otherName])
+      if (stale) {
+        this.accessory.removeService(stale)
+      }
+    }
+
+    const serviceType = this.hapServ[serviceName]
+    this.service = this.accessory.getService(serviceType)
+      || this.accessory.addService(serviceType)
+
+    // The plain Fan service switches on a boolean `On`, while Fanv2 and
+    // AirPurifier use `Active`. Follow whichever this service uses, so these
+    // tiles behave like the hand-written handlers for the same kind of device.
+    const usesOn = serviceName === 'Fan'
+    this.powerChar = usesOn ? this.hapChar.On : this.hapChar.Active
+    this.powerOn = usesOn ? true : 1
+    this.powerOff = usesOn ? false : 0
+
+    // Add the set handler to the power characteristic
+    this.service
+      .getCharacteristic(this.powerChar)
+      .onSet(async value => this.internalStateUpdate(value))
+    this.cacheState = this.service.getCharacteristic(this.powerChar).value ? 'on' : 'off'
+
+    // Some services need a current-state characteristic to look right in the
+    // Home app. It belongs to the richer tile, so it is skipped when a device
+    // has fallen back to the plain fan for want of a sensor.
+    const fellBackToPlain = !!config.richService && !this.usingRichService
+    if (config.currentStateChar && !fellBackToPlain) {
+      this.currentStateChar = this.hapChar[config.currentStateChar]
+      this.service.updateCharacteristic(
+        this.currentStateChar,
+        this.cacheState === 'on' ? config.currentStateOn : config.currentStateOff,
+      )
+    }
+
+    // Offer the variable control so the device can be asked about it, but make
+    // it clear it does nothing yet rather than sending a guessed command. The
+    // richer services name this control differently, so follow the service.
+    const variableChar = this.usingRichService && config.richVariableChar
+      ? config.richVariableChar
+      : config.variableChar
+    if (variableChar) {
+      this.variableChar = this.hapChar[variableChar]
+      this.service
+        .getCharacteristic(this.variableChar)
+        .onSet(async value => this.internalVariableUpdate(value))
+      this.cacheVariable = this.service.getCharacteristic(this.variableChar).value
+    }
+
+    // Output the customised options to the log
+    const opts = JSON.stringify({})
+    platform.log('[%s] %s %s.', accessory.displayName, platformLang.devInitOpts, opts)
+    this.accessory.log(`on and off are supported for this model, the ${config.variableLabel || 'other settings'} are not known yet`)
+  }
+
+  async internalStateUpdate(value) {
+    try {
+      const newValue = value ? 'on' : 'off'
+
+      // Don't continue if the new value is the same as before
+      if (this.cacheState === newValue) {
+        return
+      }
+
+      // This power command is the same for every govee appliance, so it is safe
+      // to send for a model that has not been tested
+      await this.platform.sendDeviceUpdate(this.accessory, {
+        cmd: 'ptReal',
+        value: value ? 'MwEBAAAAAAAAAAAAAAAAAAAAADM=' : 'MwEAAAAAAAAAAAAAAAAAAAAAADI=',
+        openApi: this.accessory.context.openApiCapabilities?.powerSwitch
+          ? { instance: 'powerSwitch', capabilityType: 'devices.capabilities.on_off', value: value ? 1 : 0 }
+          : undefined,
+      })
+
+      // Cache the new state and log if appropriate
+      this.cacheState = newValue
+      if (this.currentStateChar) {
+        this.service.updateCharacteristic(
+          this.currentStateChar,
+          value ? this.config.currentStateOn : this.config.currentStateOff,
+        )
+      }
+      this.accessory.log(`${platformLang.curState} [${newValue}]`)
+    } catch (err) {
+      // Catch any errors during the process
+      this.accessory.logWarn(`${platformLang.devNotUpdated} ${parseError(err)}`)
+
+      // Throw a 'no response' error and set a timeout to revert this after 2 seconds
+      setTimeout(() => {
+        this.service.updateCharacteristic(this.hapChar.Active, this.cacheState === 'on' ? 1 : 0)
+      }, 2000)
+      throw new this.hapErr(-70402)
+    }
+  }
+
+  async internalVariableUpdate(value) {
+    // 0 is the control following the device being turned off, not a request
+    if (value === 0) {
+      return
+    }
+
+    reportUnsupportedControl(this.accessory, {
+      control: this.config.variableLabel || 'setting',
+      value,
+    })
+
+    // Put the control back, and fail the request so HomeKit shows it as not
+    // responding - that is what sends the owner to the log
+    setTimeout(() => {
+      this.service.updateCharacteristic(this.variableChar, this.cacheVariable)
+    }, 2000)
+    throw new this.hapErr(-70402)
+  }
+
+  externalUpdate(params) {
+    // Feed the sensor reading through when the richer tile is in use - HomeKit
+    // needs it, and it is the reason that tile was chosen
+    if (this.usingRichService && this.config.richReadingChar && params.humidity !== undefined) {
+      const reading = Number(params.humidity)
+      if (Number.isFinite(reading) && reading !== this.cacheReading) {
+        this.cacheReading = reading
+        this.service.updateCharacteristic(this.hapChar[this.config.richReadingChar], reading)
+      }
+    }
+
+    // Power is the one thing that can be read back with confidence
+    if (params.state && params.state !== this.cacheState) {
+      this.cacheState = params.state
+      this.service.updateCharacteristic(this.hapChar.Active, this.cacheState === 'on' ? 1 : 0)
+      if (this.currentStateChar) {
+        this.service.updateCharacteristic(
+          this.currentStateChar,
+          this.cacheState === 'on' ? this.config.currentStateOn : this.config.currentStateOff,
+        )
+      }
+      this.accessory.log(`${platformLang.curState} [${this.cacheState}]`)
+    }
+
+    // Everything else gets reported so the model can be finished off
+    ;(params.commands || []).forEach((command) => {
+      const hexString = base64ToHex(command)
+      const hexParts = hexToTwoItems(hexString)
+
+      if (getTwoItemPosition(hexParts, 1) !== 'aa') {
+        return
+      }
+
+      // The power report is understood, anything else is worth sending in
+      if (getTwoItemPosition(hexParts, 2) === '01') {
+        const newState = getTwoItemPosition(hexParts, 3) === '01' ? 'on' : 'off'
+        if (this.cacheState !== newState) {
+          this.cacheState = newState
+          this.service.updateCharacteristic(this.hapChar.Active, this.cacheState === 'on' ? 1 : 0)
+          this.accessory.log(`${platformLang.curState} [${this.cacheState}]`)
+        }
+        return
+      }
+
+      logUnknownData(this.accessory, {
+        kind: 'scene',
+        source: params.source,
+        raw: command,
+        hex: hexString,
+      })
+    })
+  }
+}
+
+/**
+ * Build a basic handler for a kind of appliance.
+ *
+ * @param {object} config how this kind of appliance should appear
+ * @returns {Function} a handler class the platform can construct
+ */
+export function makeBasicAppliance(config) {
+  return class extends ApplianceBasic {
+    constructor(platform, accessory) {
+      super(platform, accessory, config)
+    }
+  }
+}
+
+// Fan-shaped appliances: a speed slider that is not worked out yet
+export const deviceFanBasic = makeBasicAppliance({
+  service: 'Fanv2',
+  variableChar: 'RotationSpeed',
+  variableLabel: 'fan speed',
+})
+
+// Ice makers reuse the fan tile, with the slider standing in for ice size
+export const deviceIceMakerBasic = makeBasicAppliance({
+  service: 'Fanv2',
+  variableChar: 'RotationSpeed',
+  variableLabel: 'ice size',
+})
+
+// Humidifiers get the plain fan tile by default, because HomeKit's humidifier
+// has to show a current humidity and many Govee humidifiers never report one.
+// A model that does report it gets the proper humidifier tile instead.
+export const deviceHumidifierBasic = makeBasicAppliance({
+  service: 'Fan',
+  variableChar: 'RotationSpeed',
+  variableLabel: 'mist level',
+  richService: 'HumidifierDehumidifier',
+  richCapability: 'sensorHumidity',
+  richVariableChar: 'RelativeHumidityHumidifierThreshold',
+  richReadingChar: 'CurrentRelativeHumidity',
+  currentStateChar: 'CurrentHumidifierDehumidifierState',
+  currentStateOn: 2, // humidifying
+  currentStateOff: 0, // inactive
+})
+
+export const deviceDehumidifierBasic = makeBasicAppliance({
+  service: 'Fan',
+  variableChar: 'RotationSpeed',
+  variableLabel: 'fan speed',
+  richService: 'HumidifierDehumidifier',
+  richCapability: 'sensorHumidity',
+  richVariableChar: 'RelativeHumidityDehumidifierThreshold',
+  richReadingChar: 'CurrentRelativeHumidity',
+  currentStateChar: 'CurrentHumidifierDehumidifierState',
+  currentStateOn: 3, // dehumidifying
+  currentStateOff: 0, // inactive
+})
+
+export const devicePurifierBasic = makeBasicAppliance({
+  service: 'AirPurifier',
+  variableChar: 'RotationSpeed',
+  variableLabel: 'fan speed',
+  currentStateChar: 'CurrentAirPurifierState',
+  currentStateOn: 2, // purifying air
+  currentStateOff: 0, // inactive
+})

package/lib/device/appliance-basic.test.js

@@ -0,0 +1,150 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { resetReportedUnknowns } from '../utils/report-unknown.js'
+import { deviceHumidifierBasic, devicePurifierBasic } from './appliance-basic.js'
+
+/**
+ * Minimal stand-ins for the HomeKit objects. Enough to see which service a
+ * device is given and which controls it ends up with.
+ */
+function makeCharacteristic(value) {
+  return {
+    value,
+    onSet(fn) {
+      this.setHandler = fn
+      return this
+    },
+    setProps() {
+      return this
+    },
+  }
+}
+
+function makeService(name) {
+  const chars = new Map()
+  return {
+    name,
+    getCharacteristic(char) {
+      if (!chars.has(char)) {
+        chars.set(char, makeCharacteristic(char === 'On' ? false : 0))
+      }
+      return chars.get(char)
+    },
+    updateCharacteristic(char, value) {
+      this.getCharacteristic(char).value = value
+      return this
+    },
+    testCharacteristic: char => chars.has(char),
+    removeCharacteristic() {},
+    chars,
+  }
+}
+
+function makePlatform() {
+  // Service and characteristic names stand in for themselves, so a test can
+  // assert on which one was picked
+  const proxy = new Proxy({}, { get: (_t, prop) => prop })
+  return {
+    log: Object.assign(vi.fn(), { warn: vi.fn(), debug: vi.fn() }),
+    api: { hap: { Service: proxy, Characteristic: proxy, HapStatusError: class {} } },
+  }
+}
+
+function makeAccessory(capabilities) {
+  const services = new Map()
+  return {
+    displayName: 'Test Appliance',
+    context: {
+      gvModel: 'H7146',
+      gvDeviceId: 'AA:BB',
+      openApiCapabilities: capabilities,
+    },
+    getService: name => services.get(name),
+    addService(name) {
+      const svc = makeService(name)
+      services.set(name, svc)
+      return svc
+    },
+    removeService(svc) {
+      services.delete(svc.name)
+    },
+    log: vi.fn(),
+    logWarn: vi.fn(),
+    logDebug: vi.fn(),
+    services,
+  }
+}
+
+describe('basic appliance handler', () => {
+  beforeEach(() => {
+    resetReportedUnknowns()
+  })
+
+  describe('choosing the tile for a humidifier', () => {
+    it('uses the plain fan when the device reports no humidity', () => {
+      // HomeKit's humidifier must show a current humidity, and many govee
+      // humidifiers never send one - so the safe tile is the plain fan
+      const accessory = makeAccessory({})
+      const device = new deviceHumidifierBasic(makePlatform(), accessory)
+
+      expect(device.service.name).toBe('Fan')
+      expect(accessory.services.has('HumidifierDehumidifier')).toBe(false)
+    })
+
+    it('uses the proper humidifier when the device does report humidity', () => {
+      const accessory = makeAccessory({ sensorHumidity: { type: 'sensor' } })
+      const device = new deviceHumidifierBasic(makePlatform(), accessory)
+
+      expect(device.service.name).toBe('HumidifierDehumidifier')
+    })
+
+    it('switches the power characteristic to suit the tile', () => {
+      // the plain fan switches on a boolean, the humidifier on active
+      const plain = new deviceHumidifierBasic(makePlatform(), makeAccessory({}))
+      const rich = new deviceHumidifierBasic(
+        makePlatform(),
+        makeAccessory({ sensorHumidity: {} }),
+      )
+
+      expect(plain.powerChar).toBe('On')
+      expect(plain.powerOn).toBe(true)
+      expect(rich.powerChar).toBe('Active')
+      expect(rich.powerOn).toBe(1)
+    })
+
+    it('passes a humidity reading through only on the richer tile', () => {
+      const rich = new deviceHumidifierBasic(
+        makePlatform(),
+        makeAccessory({ sensorHumidity: {} }),
+      )
+      rich.externalUpdate({ humidity: 55 })
+
+      expect(rich.service.getCharacteristic('CurrentRelativeHumidity').value).toBe(55)
+    })
+  })
+
+  it('keeps the current-state characteristic on a purifier', () => {
+    // the purifier has no fallback tile, so its state characteristic must stay
+    const device = new devicePurifierBasic(makePlatform(), makeAccessory({}))
+
+    expect(device.service.name).toBe('AirPurifier')
+    expect(device.currentStateChar).toBe('CurrentAirPurifierState')
+  })
+
+  it('reports an unknown control and fails the request', async () => {
+    const accessory = makeAccessory({})
+    const device = new deviceHumidifierBasic(makePlatform(), accessory)
+
+    await expect(device.internalVariableUpdate(50)).rejects.toBeDefined()
+    expect(accessory.logWarn).toHaveBeenCalledTimes(1)
+    expect(accessory.logWarn.mock.calls[0][0]).toContain('mist level')
+  })
+
+  it('ignores the control following the device being switched off', async () => {
+    const accessory = makeAccessory({})
+    const device = new deviceHumidifierBasic(makePlatform(), accessory)
+
+    await expect(device.internalVariableUpdate(0)).resolves.toBeUndefined()
+    expect(accessory.logWarn).not.toHaveBeenCalled()
+  })
+})

package/lib/device/index.js

@@ -1,3 +1,10 @@
+import {
+  deviceDehumidifierBasic,
+  deviceFanBasic,
+  deviceHumidifierBasic,
+  deviceIceMakerBasic,
+  devicePurifierBasic,
+} from './appliance-basic.js'
 import deviceCoolerSingle from './cooler-single.js'
 import deviceDehumidifierH7150 from './dehumidifier-H7150.js'
 import deviceDehumidifierH7151 from './dehumidifier-H7151.js'
@@ -73,6 +80,8 @@ export default {
   deviceDehumidifierH7152,
   deviceDiffuserH7161,
   deviceDiffuserH7162,
+  deviceDehumidifierBasic,
+  deviceFanBasic,
   deviceFanH1310,
   deviceFanH1370,
   deviceFanR1310: deviceFanH1310, // R1310 is the newer naming of the H1310
@@ -87,6 +96,7 @@ export default {
   deviceHeater1A,
   deviceHeater1B,
   deviceHeater2,
+  deviceHumidifierBasic,
   deviceHumidifierH714E,
   deviceHumidifierH7140,
   deviceHumidifierH7141,
@@ -97,6 +107,7 @@ export default {
   deviceHumidifierH7148,
   deviceHumidifierH7149,
   deviceHumidifierH7160,
+  deviceIceMakerBasic,
   deviceIceMakerH7172,
   deviceIceMakerH717D,
   deviceIceMakerH8120,
@@ -108,6 +119,7 @@ export default {
   deviceOutletDouble,
   deviceOutletSingle,
   deviceOutletTriple,
+  devicePurifierBasic,
   devicePurifierH712C,
   devicePurifierH7120,
   devicePurifierH7121,

package/lib/device/template.js

@@ -20,7 +20,14 @@ export default class {
   }
 
   externalUpdate(params) {
-    this.accessory.logWarn(JSON.stringify(params))
+    // These are the models actively being worked out, so every payload is worth
+    // reporting in the full form rather than as a bare dump - it is the whole
+    // reason the accessory exists at this stage
+    logUnknownData(this.accessory, {
+      kind: 'payload',
+      source: params.source,
+      raw: params,
+    })
 
     // Check for some other scene/mode change
     ;(params.commands || []).forEach((command) => {

package/lib/platform.js

@@ -1236,8 +1236,10 @@ export default class {
         doAWSPolling = true
         accessory = devicesInHB.get(uuid) || this.addAccessory(device)
       } else if (platformConsts.models.fan.includes(device.model)) {
-        // Device is a fan
-        devInstance = deviceTypes[`deviceFan${device.model}`]
+        // Device is a fan. Models whose speeds have not been worked out yet fall
+        // back to the basic handler, which offers on and off and asks for what
+        // it needs rather than leaving the device unsupported altogether
+        devInstance = deviceTypes[`deviceFan${device.model}`] || deviceTypes.deviceFanBasic
         accessory = devicesInHB.get(uuid) || this.addAccessory(device)
       } else if (platformConsts.models.heater1.includes(device.model)) {
         // Some of these heaters report the room temperature and some do not,
@@ -1263,16 +1265,16 @@ export default class {
       } else if (platformConsts.models.humidifier.includes(device.model)) {
         // Device is a humidifier
         doAWSPolling = true
-        devInstance = deviceTypes[`deviceHumidifier${device.model}`]
+        devInstance = deviceTypes[`deviceHumidifier${device.model}`] || deviceTypes.deviceHumidifierBasic
         accessory = devicesInHB.get(uuid) || this.addAccessory(device)
       } else if (platformConsts.models.dehumidifier.includes(device.model)) {
         // Device is a dehumidifier
-        devInstance = deviceTypes[`deviceDehumidifier${device.model}`]
+        devInstance = deviceTypes[`deviceDehumidifier${device.model}`] || deviceTypes.deviceDehumidifierBasic
         doAWSPolling = true
         accessory = devicesInHB.get(uuid) || this.addAccessory(device)
       } else if (platformConsts.models.purifier.includes(device.model)) {
         // Device is a purifier
-        devInstance = deviceTypes[`devicePurifier${device.model}`]
+        devInstance = deviceTypes[`devicePurifier${device.model}`] || deviceTypes.devicePurifierBasic
         doAWSPolling = true
         accessory = devicesInHB.get(uuid) || this.addAccessory(device)
       } else if (platformConsts.models.diffuser.includes(device.model)) {
@@ -1294,7 +1296,7 @@ export default class {
         accessory = devicesInHB.get(uuid) || this.addAccessory(device)
       } else if (platformConsts.models.iceMaker.includes(device.model)) {
         // Device is an ice maker
-        devInstance = deviceTypes[`deviceIceMaker${device.model}`]
+        devInstance = deviceTypes[`deviceIceMaker${device.model}`] || deviceTypes.deviceIceMakerBasic
         accessory = devicesInHB.get(uuid) || this.addAccessory(device)
       } else if (platformConsts.models.template.includes(device.model)) {
         // Device is a work-in-progress

package/lib/utils/constants.js

@@ -621,7 +621,7 @@ export default {
     // H5901 is a water timer, controlled only through the OpenAPI - it has no
     // usable AWS, BLE or LAN path, so it needs an API key configured. Set
     // showAs to 'valve' or 'tap' for a more fitting HomeKit tile (#1324)
-    switchSingle: ['H5001', 'H5080', 'H5081', 'H5083', 'H5086', 'H5901', 'H7014'],
+    switchSingle: ['H5001', 'H5080', 'H5081', 'H5083', 'H5085', 'H5086', 'H5901', 'H7014'],
     switchDouble: ['H5082', 'H5089'],
     switchTriple: ['H5160'],
     sensorLeak: ['H5054', 'H5058', 'H5059', 'H5830'],
@@ -660,14 +660,14 @@ export default {
     sensorThermo4: ['H5198'],
     sensorMonitor: ['H5106'],
     sensorCO2: ['H5140'], // CO2 + temp + humidity monitor, AWS opcode 0x0A — closes #1179
-    fan: ['H1310', 'H1370', 'H7100', 'H7101', 'H7102', 'H7105', 'H7106', 'H7107', 'H7111', 'R1310'],
+    fan: ['H1310', 'H1370', 'H7100', 'H7101', 'H7102', 'H7103', 'H7105', 'H7106', 'H7107', 'H7111', 'H7112', 'R1310'],
     heater1: ['H7130', 'H713A', 'H713B', 'H713C', 'H7137', 'H713E'],
     heater2: ['H7131', 'H7132', 'H7133', 'H7134', 'H7135'],
     dehumidifier: ['H7150', 'H7151', 'H7152'],
-    humidifier: ['H7140', 'H7141', 'H7142', 'H7143', 'H7145', 'H7147', 'H7148', 'H7149', 'H714E', 'H7160'],
+    humidifier: ['H7140', 'H7141', 'H7142', 'H7143', 'H7145', 'H7146', 'H7147', 'H7148', 'H7149', 'H714E', 'H7160'],
     purifier: ['H7120', 'H7121', 'H7122', 'H7123', 'H7124', 'H7126', 'H7127', 'H7128', 'H7129', 'H712C'],
     diffuser: ['H7161', 'H7162'],
-    iceMaker: ['H7172', 'H717D', 'H8120', 'H8121', 'H8122'],
+    iceMaker: ['H7172', 'H717D', 'H8102', 'H8120', 'H8121', 'H8122', 'H8131'],
     sensorButton: ['H5122'],
     sensorContact: ['H5123'],
     sensorPresence: ['H5127'],
@@ -679,8 +679,8 @@ export default {
       'H5024', // https://github.com/homebridge-plugins/homebridge-govee/issues/835
       'H5042', // https://github.com/homebridge-plugins/homebridge-govee/issues/849
       'H5043', // https://github.com/homebridge-plugins/homebridge-govee/issues/558
-      'H5085', // https://github.com/homebridge-plugins/homebridge-govee/issues/951
-      'H5111', // https://github.com/homebridge-plugins/homebridge-govee/issues/1117
+      // https://github.com/homebridge-plugins/homebridge-govee/issues/951
+      // https://github.com/homebridge-plugins/homebridge-govee/issues/1117
       'H5121', // https://github.com/homebridge-plugins/homebridge-govee/issues/913
       'H5124', // https://github.com/homebridge-plugins/homebridge-govee/issues/1119
       'H5126', // https://github.com/homebridge-plugins/homebridge-govee/issues/910

package/lib/utils/report-unknown.js

@@ -43,6 +43,51 @@ export function isFirstReport(fingerprint) {
   return true
 }
 
+/**
+ * Report a control the plugin knows the device has, but does not yet know the
+ * command for, and then fail the request.
+ *
+ * This is how a model gets added before every last detail is known. The things
+ * that are certain - usually power - work straight away, and anything still
+ * unknown says so out loud instead of pretending to work. Failing the request
+ * matters: HomeKit shows the control as not responding, which sends the owner
+ * to the log, where they find the line to paste into an issue. A control that
+ * silently did nothing would just look broken.
+ *
+ * @param {object} accessory the accessory the control belongs to
+ * @param {object} details
+ * @param {string} details.control what was asked for, eg 'fan speed'
+ * @param {*} [details.value] the value HomeKit asked for
+ * @returns {string} the message that was logged, mainly for tests
+ */
+export function reportUnsupportedControl(accessory, { control, value } = {}) {
+  const context = accessory?.context || {}
+  const report = {
+    model: context.gvModel,
+    firmware: context.firmware,
+    hardware: context.hardware,
+    control,
+    requested: value,
+  }
+  Object.keys(report).forEach((key) => {
+    if (report[key] === undefined || report[key] === null || report[key] === '') {
+      delete report[key]
+    }
+  })
+
+  const line = `the ${control} for this model is not known yet, so this did not happen - please report this line so it can be added: ${JSON.stringify(report)}`
+  const fingerprint = `${context.gvDeviceId || accessory?.displayName}|unsupported|${control}`
+
+  if (alreadyReported.has(fingerprint)) {
+    accessory?.logDebug?.(line)
+  } else {
+    alreadyReported.add(fingerprint)
+    accessory?.logWarn?.(line)
+  }
+
+  return line
+}
+
 /**
  * Log an unrecognised payload with everything needed to add support for it.
  *

package/lib/utils/report-unknown.test.js

@@ -1,6 +1,6 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
-import { isFirstReport, logUnknownData, resetReportedUnknowns } from './report-unknown.js'
+import { isFirstReport, logUnknownData, reportUnsupportedControl, resetReportedUnknowns } from './report-unknown.js'
 
 function makeAccessory(context = {}) {
   return {
@@ -131,6 +131,52 @@ describe('reporting unrecognised data', () => {
     expect(() => logUnknownData(undefined, { kind: 'scene', raw: 'abc' })).not.toThrow()
   })
 
+  describe('a control that is not worked out yet', () => {
+    it('names the control and what was asked for', () => {
+      const accessory = makeAccessory()
+      reportUnsupportedControl(accessory, { control: 'fan speed', value: 50 })
+
+      const line = reported(accessory)
+      expect(line).toContain('fan speed')
+      expect(line).toContain('did not happen')
+
+      const payload = JSON.parse(line.slice(line.indexOf('{')))
+      expect(payload.model).toBe('H6102')
+      expect(payload.firmware).toBe('1.03.01')
+      expect(payload.requested).toBe(50)
+    })
+
+    it('asks the user to report it', () => {
+      const accessory = makeAccessory()
+      reportUnsupportedControl(accessory, { control: 'fan speed', value: 1 })
+
+      expect(reported(accessory)).toContain('please report this line')
+    })
+
+    it('warns once per control, then keeps quiet', () => {
+      const accessory = makeAccessory()
+
+      reportUnsupportedControl(accessory, { control: 'fan speed', value: 25 })
+      reportUnsupportedControl(accessory, { control: 'fan speed', value: 50 })
+
+      expect(accessory.logWarn).toHaveBeenCalledTimes(1)
+      expect(accessory.logDebug).toHaveBeenCalledTimes(1)
+    })
+
+    it('still reports a different control on the same device', () => {
+      const accessory = makeAccessory()
+
+      reportUnsupportedControl(accessory, { control: 'fan speed', value: 25 })
+      reportUnsupportedControl(accessory, { control: 'ice size', value: 2 })
+
+      expect(accessory.logWarn).toHaveBeenCalledTimes(2)
+    })
+
+    it('does not throw when there is no accessory', () => {
+      expect(() => reportUnsupportedControl(undefined, { control: 'fan speed' })).not.toThrow()
+    })
+  })
+
   describe('isFirstReport', () => {
     it('is true once and false after', () => {
       expect(isFirstReport('a')).toBe(true)

package/package.json

@@ -2,7 +2,7 @@
   "name": "@homebridge-plugins/homebridge-govee",
   "alias": "Govee",
   "type": "module",
-  "version": "11.32.2-beta.4",
+  "version": "11.32.2-beta.6",
   "description": "Homebridge plugin to integrate Govee devices into HomeKit.",
   "author": {
     "name": "bwp91",