@homebridge-plugins/homebridge-govee 11.32.2-beta.11 → 11.32.2-beta.13

package/CHANGELOG.md

@@ -23,6 +23,11 @@ All notable changes to `@homebridge-plugins/homebridge-govee` will be documented
 - fix: stop shipping the test files to npm, since they are only needed in the repository
 - fix: refuse to send a bluetooth command too long to fit in a packet, rather than sending a longer one the device quietly ignores
 - test: record what every supported model turns into, so a change can be shown to have altered nothing
+- feat: work out what an appliance can do from what the device itself reports, so a model nobody has written down still gets the right controls
+- feat: offer oscillation and the child lock on any appliance that reports having them, driven through govee's api rather than needing that model's command codes
+- refactor: point three more models at a shared handler instead of a near-copy of the same file, keeping each one's behaviour exactly as it was
+- fix: give the H7124 the air quality handling the H7123 already had, so a poor reading is named properly and stops being logged over and over (#1261)
+- refactor: point the H7151 and H7111 at the handlers they were byte-for-byte copies of
 
 ## v11.32.1 (2026-08-02)
 

package/lib/device/appliance-basic.js

@@ -1,3 +1,4 @@
+import { describeSources, resolveControls } from '../utils/capabilities.js'
 import { base64ToHex, getTwoItemPosition, hexToTwoItems, parseError } from '../utils/functions.js'
 import platformLang from '../utils/lang-en.js'
 import { logUnknownData, reportUnsupportedControl } from '../utils/report-unknown.js'
@@ -31,13 +32,26 @@ class ApplianceBasic {
     this.accessory = accessory
     this.config = config
 
+    // Work out what this particular device can do, rather than what its model
+    // generally can - for a model nobody has written down, what the device
+    // itself reported is all there is to go on
+    const resolved = resolveControls({
+      model: accessory.context.gvModel,
+      family: config.family,
+      firmware: accessory.context.firmware,
+      openApiCapabilities: accessory.context.openApiCapabilities,
+      deviceConf: platform.deviceConf?.[accessory.context.gvDeviceId],
+    })
+    this.controls = resolved.controls
+    this.cacheToggles = {}
+    this.discoveredControls = []
+
     // 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]
+    // Where the device says it has that sensor, use the better tile; otherwise
+    // fall back to the plain one, which needs nothing extra.
+    const hasSensor = config.richControl && this.controls[config.richControl]
     const serviceName = (config.richService && hasSensor) ? config.richService : config.service
     this.usingRichService = serviceName === config.richService
 
@@ -94,10 +108,78 @@ class ApplianceBasic {
       this.cacheVariable = this.service.getCharacteristic(this.variableChar).value
     }
 
+    // A control the device told us about can be driven through Govee's own api
+    // by name, without knowing this model's command bytes. So unlike the
+    // settings above, these work rather than asking to be reported.
+    this.addDiscoveredToggle('swing', 'SwingMode', 'oscillationToggle')
+    this.addDiscoveredToggle('lock', 'LockPhysicalControls', 'lockToggle')
+
     // 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`)
+    this.accessory.logDebug(`controls: ${describeSources(resolved.sources)}`)
+
+    const working = ['on and off', ...this.discoveredControls]
+    this.accessory.log(`${working.join(', ')} ${working.length > 1 ? 'are' : 'is'} supported for this model, the ${config.variableLabel || 'other settings'} are not known yet`)
+  }
+
+  /**
+   * Offer a control the device said it has, driven through Govee's api by the
+   * name the device gave it.
+   *
+   * This is the one place a model nobody has tested gets something that really
+   * works beyond power: the api takes the capability name, so the command bytes
+   * for this model never have to be known.
+   */
+  addDiscoveredToggle(control, characteristic, instance) {
+    const char = this.hapChar[characteristic]
+
+    // The device has to have named this capability itself. Knowing the model
+    // usually has a turning head is not enough - the api is driven by the name
+    // the device reported, so without it there is nothing to send, and the
+    // switch would fail every time it was touched.
+    const reported = !!this.accessory.context.openApiCapabilities?.[instance]
+
+    if (!reported || !this.controls[control] || !char) {
+      if (this.service.testCharacteristic?.(char)) {
+        this.service.removeCharacteristic(this.service.getCharacteristic(char))
+      }
+      return
+    }
+
+    this.service
+      .getCharacteristic(char)
+      .onSet(async value => this.internalToggleUpdate(control, char, instance, value))
+    this.cacheToggles[control] = this.service.getCharacteristic(char).value
+
+    this.discoveredControls.push(control === 'swing' ? 'oscillation' : 'the child lock')
+  }
+
+  async internalToggleUpdate(control, characteristic, instance, value) {
+    const previous = this.cacheToggles[control]
+    try {
+      if (previous === value) {
+        return
+      }
+
+      await this.platform.sendDeviceUpdate(this.accessory, {
+        cmd: 'openApi',
+        openApi: {
+          instance,
+          capabilityType: 'devices.capabilities.toggle',
+          value: value ? 1 : 0,
+        },
+      })
+
+      this.cacheToggles[control] = value
+      this.accessory.log(`current ${control} [${value ? 'on' : 'off'}]`)
+    } catch (err) {
+      this.accessory.logWarn(`${platformLang.devNotUpdated} ${parseError(err)}`)
+      setTimeout(() => {
+        this.service.updateCharacteristic(characteristic, previous)
+      }, 2000)
+      throw new this.hapErr(-70402)
+    }
   }
 
   async internalStateUpdate(value) {
@@ -229,6 +311,7 @@ export function makeBasicAppliance(config) {
 
 // Fan-shaped appliances: a speed slider that is not worked out yet
 export const deviceFanBasic = makeBasicAppliance({
+  family: 'fan',
   service: 'Fanv2',
   variableChar: 'RotationSpeed',
   variableLabel: 'fan speed',
@@ -236,6 +319,7 @@ export const deviceFanBasic = makeBasicAppliance({
 
 // Ice makers reuse the fan tile, with the slider standing in for ice size
 export const deviceIceMakerBasic = makeBasicAppliance({
+  family: 'iceMaker',
   service: 'Fanv2',
   variableChar: 'RotationSpeed',
   variableLabel: 'ice size',
@@ -245,11 +329,12 @@ export const deviceIceMakerBasic = makeBasicAppliance({
 // 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({
+  family: 'humidifier',
   service: 'Fan',
   variableChar: 'RotationSpeed',
   variableLabel: 'mist level',
   richService: 'HumidifierDehumidifier',
-  richCapability: 'sensorHumidity',
+  richControl: 'humiditySensor',
   richVariableChar: 'RelativeHumidityHumidifierThreshold',
   richReadingChar: 'CurrentRelativeHumidity',
   currentStateChar: 'CurrentHumidifierDehumidifierState',
@@ -258,11 +343,12 @@ export const deviceHumidifierBasic = makeBasicAppliance({
 })
 
 export const deviceDehumidifierBasic = makeBasicAppliance({
+  family: 'dehumidifier',
   service: 'Fan',
   variableChar: 'RotationSpeed',
   variableLabel: 'fan speed',
   richService: 'HumidifierDehumidifier',
-  richCapability: 'sensorHumidity',
+  richControl: 'humiditySensor',
   richVariableChar: 'RelativeHumidityDehumidifierThreshold',
   richReadingChar: 'CurrentRelativeHumidity',
   currentStateChar: 'CurrentHumidifierDehumidifierState',
@@ -271,6 +357,7 @@ export const deviceDehumidifierBasic = makeBasicAppliance({
 })
 
 export const devicePurifierBasic = makeBasicAppliance({
+  family: 'purifier',
   service: 'AirPurifier',
   variableChar: 'RotationSpeed',
   variableLabel: 'fan speed',

package/lib/device/dehumidifier-H7150.js

@@ -8,7 +8,7 @@ import platformLang from '../utils/lang-en.js'
 import { logUnknownData } from '../utils/report-unknown.js'
 
 /*
-  H7150
+  H7150 and H7151
   {
     "mode": {
       "options": [
@@ -32,7 +32,7 @@ import { logUnknownData } from '../utils/report-unknown.js'
     }
   }
  */
-export default class {
+export default class GoveeDehumidifierH7150 {
   constructor(platform, accessory) {
     // Set up variables from the platform
     this.hapChar = platform.api.hap.Characteristic

package/lib/device/fan-H7100.js

@@ -1,3 +1,4 @@
+import { getDeviceCapabilities } from '../utils/device-capabilities.js'
 import {
   base64ToHex,
   fanSpeedToHkPercent,
@@ -9,7 +10,7 @@ import {
 import platformLang from '../utils/lang-en.js'
 import { logUnknownData } from '../utils/report-unknown.js'
 
-export default class {
+export default class GoveeFanH7100 {
   constructor(platform, accessory) {
     // Set up variables from the platform
     this.hapChar = platform.api.hap.Characteristic
@@ -20,6 +21,10 @@ export default class {
     // Set up variables from the accessory
     this.accessory = accessory
 
+    // Which of the models on this handler have a confirmed meaning for the
+    // oscillation status message
+    this.readsSwingStatus = getDeviceCapabilities(accessory.context.gvModel).readsSwingStatus
+
     // Codes etc
     this.speedCodes = {
       1: 'MwUBAQAAAAAAAAAAAAAAAAAAADY=',
@@ -267,7 +272,18 @@ export default class {
           break
         }
         case '1f01': {
-          // Swing Mode
+          // Not every model on this handler is known to mean oscillation by
+          // this message, so one that has not been confirmed falls through and
+          // reports it instead - which is how it gets confirmed
+          if (!this.readsSwingStatus) {
+            logUnknownData(this.accessory, {
+              kind: 'scene',
+              source: params.source,
+              raw: command,
+              hex: hexString,
+            })
+            break
+          }
           const newSwing = getTwoItemPosition(hexParts, 4) === '01' ? 'on' : 'off'
           if (this.cacheSwing !== newSwing) {
             this.cacheSwing = newSwing

package/lib/device/fan-H7101.js

@@ -10,7 +10,7 @@ import platformLang from '../utils/lang-en.js'
 import { logUnknownData } from '../utils/report-unknown.js'
 
 /*
-  H7101
+  H7101 and H7111
   {
     "mode": {
       "options": [
@@ -53,6 +53,7 @@ import { logUnknownData } from '../utils/report-unknown.js'
 
   // NOTES
   H7101 -> Sleep, Nature, Turbo, Custom, Auto
+  H7111 -> Sleep, Nature, Custom, Auto (no turbo)
 
   sleep
   [31/10/2022, 20:52:08] [Govee] [Device1] [AWS] receiving update {"source":"AWS","result":1,"commands":["qgUFAAAAAAAAAAAAAAAAAAAAAKo=","qgUABQAAAAAAAAAAAAAAAAAAAKo="]}.
@@ -65,7 +66,7 @@ import { logUnknownData } from '../utils/report-unknown.js'
   [31/10/2022, 20:52:43] [Govee] [Device1] new scene code: [qgUABgAAAAAAAAAAAAAAAAAAAKk=] [aa050006000000000000000000000000000000a9].
 */
 
-export default class {
+export default class GoveeFanH7101 {
   constructor(platform, accessory) {
     // Set up variables from the platform
     this.hapChar = platform.api.hap.Characteristic
@@ -318,7 +319,7 @@ export default class {
             this.cacheSpeed = this.autoSpeed
             // Cache auto so we can tell it apart from "user asked for max speed"
             this.service.updateCharacteristic(this.hapChar.RotationSpeed, 100)
-            this.accessory.log(`${platformLang.curSpeed} [auto]`)
+            this.accessory.log(`${platformLang.curSpeed} [auto -> 100%]`)
           }
           break
         }

package/lib/device/heater1a.js

@@ -1,4 +1,4 @@
-import { getHeaterFeatures } from '../utils/appliance-capabilities.js'
+import { describeSources, resolveControls } from '../utils/capabilities.js'
 import {
   base64ToHex,
   farToCen,
@@ -94,7 +94,15 @@ export default class {
 
     // Only offer the controls this model actually has, so a heater without a
     // turning head does not get an oscillation switch that does nothing
-    this.features = getHeaterFeatures(this.accessory.context.gvModel)
+    const resolved = resolveControls({
+      model: this.accessory.context.gvModel,
+      family: 'heater1',
+      firmware: this.accessory.context.firmware,
+      openApiCapabilities: this.accessory.context.openApiCapabilities,
+      deviceConf: platform.deviceConf?.[this.accessory.context.gvDeviceId],
+    })
+    this.features = resolved.controls
+    this.accessory.logDebug(`controls: ${describeSources(resolved.sources)}`)
 
     // Add the set handler to the heater swing mode characteristic (for oscillation)
     if (this.features.swing) {

package/lib/device/ice-maker-H8121.js

@@ -2,7 +2,7 @@ import { base64ToHex, getTwoItemPosition, hexToTwoItems, parseError } from '../u
 import platformLang from '../utils/lang-en.js'
 import { logUnknownData } from '../utils/report-unknown.js'
 
-export default class {
+export default class GoveeIceMakerH8121 {
   constructor(platform, accessory) {
     // Set up variables from the platform
     this.hapChar = platform.api.hap.Characteristic
@@ -14,7 +14,7 @@ export default class {
     this.accessory = accessory
 
     // Ice size codes: small=1, medium=2, large=3, matching the OpenAPI workMode
-    // values. Unlike the H8120, the H8121's BLE size byte runs in the SAME
+    // values. Unlike the H8120, this generation's BLE size byte runs in the SAME
     // direction as workMode (small=0x05 01 .. large=0x05 03), so the two paths
     // agree here and no inversion is needed.
     this.sizeCodes = {
@@ -89,7 +89,7 @@ export default class {
       } else {
         // Turn off. The OpenAPI workMode=0 path is authoritative; the BLE frame
         // mirrors the H8120 ice-maker-off command (33 19 00) as a best effort
-        // and is pending confirmation from an H8121 owner.
+        // and is pending confirmation from an owner of either model.
         await this.platform.sendDeviceUpdate(this.accessory, {
           cmd: 'ptReal',
           value: 'MxkAAAAAAAAAAAAAAAAAAAAAACo=',

package/lib/device/index.js

@@ -7,16 +7,13 @@ import {
 } from './appliance-basic.js'
 import deviceCoolerSingle from './cooler-single.js'
 import deviceDehumidifierH7150 from './dehumidifier-H7150.js'
-import deviceDehumidifierH7151 from './dehumidifier-H7151.js'
 import deviceDehumidifierH7152 from './dehumidifier-H7152.js'
 import deviceDiffuserH7161 from './diffuser-H7161.js'
-import deviceFanH1310 from './fan-H1310.js'
 import deviceFanH1370 from './fan-H1370.js'
 import deviceFanH7100 from './fan-H7100.js'
 import deviceFanH7101 from './fan-H7101.js'
 import deviceFanH7105 from './fan-H7105.js'
 import deviceFanH7107 from './fan-H7107.js'
-import deviceFanH7111 from './fan-H7111.js'
 import deviceHeater1A from './heater1a.js'
 import deviceHeater1B from './heater1b.js'
 import deviceHeater2 from './heater2.js'
@@ -28,7 +25,6 @@ import deviceHumidifierH7143 from './humidifier-H7143.js'
 import deviceHumidifierH7160 from './humidifier-H7160.js'
 import deviceIceMakerH7172 from './ice-maker-H7172.js'
 import deviceIceMakerH8121 from './ice-maker-H8121.js'
-import deviceIceMakerH8122 from './ice-maker-H8122.js'
 import deviceKettle from './kettle.js'
 import deviceLightSwitch from './light-switch.js'
 import deviceLight from './light.js'
@@ -36,15 +32,12 @@ import deviceOutletDouble from './outlet-double.js'
 import deviceOutletSingle from './outlet-single.js'
 import deviceOutletTriple from './outlet-triple.js'
 import devicePurifierH7120 from './purifier-H7120.js'
-import devicePurifierH7121 from './purifier-H7121.js'
 import devicePurifierH7122 from './purifier-H7122.js'
 import devicePurifierH7123 from './purifier-H7123.js'
-import devicePurifierH7124 from './purifier-H7124.js'
 import devicePurifierH7126 from './purifier-H7126.js'
 import devicePurifierSingle from './purifier-single.js'
-import deviceSensorButton from './sensor-button.js'
+import deviceSensorBasic from './sensor-basic.js'
 import deviceSensorCO2 from './sensor-co2.js'
-import deviceSensorContact from './sensor-contact.js'
 import deviceSensorLeak from './sensor-leak.js'
 import deviceSensorMonitor from './sensor-monitor.js'
 import deviceSensorPresence from './sensor-presence.js'
@@ -62,22 +55,22 @@ import deviceValveSingle from './valve-single.js'
 export default {
   deviceCoolerSingle,
   deviceDehumidifierH7150,
-  deviceDehumidifierH7151,
+  deviceDehumidifierH7151: deviceDehumidifierH7150, // identical to the H7150
   deviceDehumidifierH7152,
   deviceDiffuserH7161,
   deviceDiffuserH7162: deviceDiffuserH7161, // identical to the H7161
   deviceDehumidifierBasic,
   deviceFanBasic,
-  deviceFanH1310,
+  deviceFanH1310: deviceFanH7100, // same fan, minus a confirmed swing status message
   deviceFanH1370,
-  deviceFanR1310: deviceFanH1310, // R1310 is the newer naming of the H1310
+  deviceFanR1310: deviceFanH7100, // R1310 is the newer naming of the H1310
   deviceFanH7100,
   deviceFanH7102: deviceFanH7100, // identical to the H7100
   deviceFanH7106: deviceFanH7100, // identical to the H7100
   deviceFanH7101,
   deviceFanH7105,
   deviceFanH7107,
-  deviceFanH7111,
+  deviceFanH7111: deviceFanH7101, // same fan without the turbo mode, which is not sent
   deviceHeaterSingle,
   deviceHeater1A,
   deviceHeater1B,
@@ -98,7 +91,7 @@ export default {
   deviceIceMakerH717D: deviceIceMakerH7172, // identical to the H7172
   deviceIceMakerH8120: deviceIceMakerH7172, // identical to the H7172
   deviceIceMakerH8121,
-  deviceIceMakerH8122,
+  deviceIceMakerH8122: deviceIceMakerH8121, // identical to the H8121
   deviceKettle,
   deviceLight,
   deviceLightSwitch,
@@ -107,19 +100,20 @@ export default {
   deviceOutletTriple,
   devicePurifierBasic,
   devicePurifierH7120,
-  devicePurifierH7121,
+  devicePurifierH7121: devicePurifierH7120, // identical apart from its sleep mode value, which is not sent
   devicePurifierH7122,
   devicePurifierH7123,
-  devicePurifierH7124,
+  devicePurifierH7124: devicePurifierH7123, // same device; this also gives it the #1261 air quality fix
   devicePurifierH7126,
   devicePurifierH7127: devicePurifierH7126, // identical to the H7126
   devicePurifierH7128: devicePurifierH7126, // identical to the H7126
   devicePurifierH7129: devicePurifierH7126, // identical to the H7126
   devicePurifierH712C: devicePurifierH7126, // identical to the H7126
   devicePurifierSingle,
-  deviceSensorButton,
+  deviceSensorBasic,
+  deviceSensorButton: deviceSensorBasic, // nothing decoded yet, so it reports instead
   deviceSensorCO2,
-  deviceSensorContact,
+  deviceSensorContact: deviceSensorBasic, // nothing decoded yet, so it reports instead
   deviceSensorLeak,
   deviceSensorMonitor,
   deviceSensorPresence,

package/lib/device/purifier-H7120.js

@@ -8,32 +8,15 @@ import platformLang from '../utils/lang-en.js'
 import { logUnknownData } from '../utils/report-unknown.js'
 
 /*
-  H7120
-  {
-    "mode": {
-      "options": [
-        {
-          "name": "Low",
-          "value": 1
-        },
-        {
-          "name": "Medium",
-          "value": 2
-        },
-        {
-          "name": "High",
-          "value": 3
-        },
-        {
-          "name": "Sleep mode",
-          "value": 5
-        }
-      ]
-    }
-  }
+  The modes these purifiers report over the api. Low, medium and high are the
+  gear speeds the plugin drives; sleep is listed for reference and is the one
+  place the two models differ, so it must not be sent as a shared value.
+
+  H7120: Low 1, Medium 2, High 3, "Sleep mode" 5
+  H7121: Low 1, Medium 2, High 3, "Sleep" 16
  */
 
-export default class {
+export default class GoveePurifierH7120 {
   constructor(platform, accessory) {
     // Set up variables from the platform
     this.cusChar = platform.cusChar

package/lib/device/purifier-H7123.js

@@ -10,7 +10,7 @@ import platformLang from '../utils/lang-en.js'
 import { logUnknownData } from '../utils/report-unknown.js'
 
 /*
-  H7123
+  H7123 and H7124
   {
     "mode": {
       "options": [
@@ -39,7 +39,7 @@ import { logUnknownData } from '../utils/report-unknown.js'
   }
  */
 
-export default class {
+export default class GoveePurifierH7123 {
   constructor(platform, accessory) {
     // Set up variables from the platform
     this.cusChar = platform.cusChar

package/lib/device/{sensor-button.js → sensor-basic.js}

@@ -1,7 +1,14 @@
 import platformLang from '../utils/lang-en.js'
 import { logUnknownData } from '../utils/report-unknown.js'
 
-export default class {
+/**
+ * A sensor whose broadcasts are not decoded yet.
+ *
+ * It offers no tile, because a tile that never updates is worse than none. What
+ * it does is report every message it receives in one copy-paste line, so an
+ * owner can send in exactly what is needed to finish the model off.
+ */
+export default class GoveeSensorBasic {
   constructor(platform, accessory) {
     // Set up variables from the platform
     this.hapChar = platform.api.hap.Characteristic