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

package/CHANGELOG.md

@@ -17,6 +17,7 @@ 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
 
 ## v11.32.1 (2026-08-02)
 

package/lib/device/fan-basic.js

@@ -0,0 +1,143 @@
+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 fan whose power command is known but whose speeds are not.
+ *
+ * Govee's power command is the same across every appliance the plugin handles,
+ * so on and off can be offered with confidence for a model nobody has tested.
+ * The speeds are the part that differs per model, and getting the number of
+ * them wrong is worse than not offering them - so the slider reports what it
+ * needs and fails the request rather than quietly sending a guess.
+ *
+ * Once an owner sends in what their fan reports, the model gets its own handler
+ * with real speeds and stops using this one.
+ */
+export default class {
+  constructor(platform, accessory) {
+    // 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
+
+    // Add the fan service if it doesn't already exist
+    this.service = this.accessory.getService(this.hapServ.Fanv2)
+      || this.accessory.addService(this.hapServ.Fanv2)
+
+    // Add the set handler to the fan active characteristic
+    this.service
+      .getCharacteristic(this.hapChar.Active)
+      .onSet(async value => this.internalStateUpdate(value))
+    this.cacheState = this.service.getCharacteristic(this.hapChar.Active).value ? 'on' : 'off'
+
+    // Offer the speed slider so the fan can report what it wants, but make it
+    // clear it does nothing yet rather than sending a guessed command
+    this.service
+      .getCharacteristic(this.hapChar.RotationSpeed)
+      .setProps({
+        maxValue: 100,
+        minStep: 1,
+        minValue: 0,
+        unit: 'unitless',
+      })
+      .onSet(async value => this.internalSpeedUpdate(value))
+    this.cacheSpeed = this.service.getCharacteristic(this.hapChar.RotationSpeed).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 speeds 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
+      }
+
+      // Send the request to the platform sender function. This power command is
+      // the same for every govee appliance, so it is safe for an untested model
+      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
+      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 internalSpeedUpdate(value) {
+    // 0 is the slider following the fan being turned off, not a speed request
+    if (value === 0) {
+      return
+    }
+
+    reportUnsupportedControl(this.accessory, { control: 'fan speed', value })
+
+    // Put the slider back where it was, 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.hapChar.RotationSpeed, this.cacheSpeed)
+    }, 2000)
+    throw new this.hapErr(-70402)
+  }
+
+  externalUpdate(params) {
+    // 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)
+      this.accessory.log(`${platformLang.curState} [${this.cacheState}]`)
+    }
+
+    // Everything else is 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,
+      })
+    })
+  }
+}

package/lib/device/index.js

@@ -4,6 +4,7 @@ import deviceDehumidifierH7151 from './dehumidifier-H7151.js'
 import deviceDehumidifierH7152 from './dehumidifier-H7152.js'
 import deviceDiffuserH7161 from './diffuser-H7161.js'
 import deviceDiffuserH7162 from './diffuser-H7162.js'
+import deviceFanBasic from './fan-basic.js'
 import deviceFanH1310 from './fan-H1310.js'
 import deviceFanH1370 from './fan-H1370.js'
 import deviceFanH7100 from './fan-H7100.js'
@@ -73,6 +74,7 @@ export default {
   deviceDehumidifierH7152,
   deviceDiffuserH7161,
   deviceDiffuserH7162,
+  deviceFanBasic,
   deviceFanH1310,
   deviceFanH1370,
   deviceFanR1310: deviceFanH1310, // R1310 is the newer naming of the H1310

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,

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,7 +660,7 @@ 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'],
@@ -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.5",
   "description": "Homebridge plugin to integrate Govee devices into HomeKit.",
   "author": {
     "name": "bwp91",