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

package/CHANGELOG.md

@@ -23,6 +23,8 @@ 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
 
 ## 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/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/utils/capabilities.js

@@ -0,0 +1,220 @@
+/**
+ * What a device can do, worked out from several sources rather than one table.
+ *
+ * Writing out all six hundred models by hand is a job nobody finishes, and it
+ * throws away the two things we already have: Govee's own API says what each
+ * device can do, and some behaviour depends on firmware rather than model. So
+ * instead of a table this asks a series of layers and takes the first answer:
+ *
+ *   1. user config      an explicit setting always wins
+ *   2. firmware         this model, at or above this firmware version
+ *   3. model            written down because someone worked it out
+ *   4. discovered       what this particular device reported it can do
+ *   5. family           what this kind of appliance usually has
+ *
+ * Most models never need an entry of their own. They are answered by what the
+ * device reported plus the family defaults, which is why this scales to models
+ * nobody has written down.
+ *
+ * ⚠️ Family defaults are deliberately generous. A control this plugin has
+ * offered for years may be in use by someone, and taking it away to tidy up
+ * would break a working setup. Only a model entry - written after someone
+ * confirmed it - is allowed to say a device does not have something.
+ */
+
+import { compareVersions } from './device-capabilities.js'
+
+/**
+ * What each kind of appliance usually offers.
+ *
+ * These are the fallback, so they describe the group rather than any one model.
+ * Where a group has historically been given a control, it stays here even if
+ * some members turn out not to have it - see the warning above.
+ */
+const familyControls = {
+  heater1: { swing: true, lock: true, light: false },
+  heater2: { swing: true, lock: true, light: true },
+  fan: { swing: true, lock: false, light: false },
+  humidifier: { swing: false, lock: false, light: false },
+  dehumidifier: { swing: false, lock: false, light: false },
+  purifier: { swing: false, lock: false, light: false },
+  iceMaker: { swing: false, lock: false, light: false },
+  diffuser: { swing: false, lock: false, light: false },
+}
+
+const emptyControls = {
+  swing: false,
+  lock: false,
+  light: false,
+  humiditySensor: false,
+  temperatureSensor: false,
+  modes: false,
+}
+
+/**
+ * Controls worked out for a particular model.
+ *
+ * Only add a model here once its controls are actually known. An entry is
+ * trusted over what the device reports, and it is the only thing allowed to
+ * take a control away.
+ */
+const modelControls = {
+  // Heaters. These match what Govee's own app offers for each model.
+  // Added new, so there is nobody whose setup could be broken by them
+  H7137: { swing: false, lock: false, light: false },
+  H713E: { swing: false, lock: false, light: false },
+
+  // Diffusers are power only, which is what the plugin already offers
+  H7161: { swing: false, lock: false, light: false },
+  H7162: { swing: false, lock: false, light: false },
+}
+
+/**
+ * Controls a model is believed NOT to have, which are still being offered.
+ *
+ * These are recorded rather than applied. Each has been offered for a long
+ * time, so an owner may be relying on it, and taking it away to match a
+ * capability list would break a working setup for the sake of tidiness. The
+ * evidence is written down here so nobody has to work it out twice, and so
+ * there is a list to check the next time an owner of one of these gets in
+ * touch.
+ *
+ * Move an entry into `modelControls` once an owner confirms the control really
+ * does nothing.
+ */
+const unconfirmedMissing = {
+  H713A: { swing: false },
+  H713B: { swing: false },
+  H713C: { swing: false },
+  H7135: { swing: false, light: false },
+}
+
+/**
+ * Controls that only appear at or above a firmware version. Same shape as the
+ * protocol overrides next door: a list per model, oldest rule first.
+ */
+const firmwareControls = {}
+
+/**
+ * What Govee's API calls a capability, and which control it means to us.
+ *
+ * These names come back per device, so they say what this particular unit can
+ * do rather than what its model generally can. That makes them the only source
+ * here that works for a model nobody has written down.
+ */
+const discoveryMap = {
+  oscillationToggle: 'swing',
+  lockToggle: 'lock',
+  nightlightToggle: 'light',
+  mainLightToggle: 'light',
+  backgroundLightToggle: 'light',
+  sensorHumidity: 'humiditySensor',
+  sensorTemperature: 'temperatureSensor',
+  workMode: 'modes',
+}
+
+/**
+ * Turn the capability list a device reported into controls.
+ *
+ * Only ever adds. A capability the device did not mention is left undecided so
+ * a later layer can answer, because the API not listing something is not proof
+ * the device cannot do it.
+ */
+function fromDiscovery(openApiCapabilities) {
+  const discovered = {}
+  Object.keys(openApiCapabilities || {}).forEach((instance) => {
+    const control = discoveryMap[instance]
+    if (control) {
+      discovered[control] = true
+    }
+  })
+  return discovered
+}
+
+/**
+ * Config settings that name a control directly, so an owner can turn something
+ * off that their device does not really have without waiting for a release.
+ */
+function fromConfig(deviceConf) {
+  const chosen = {}
+  if (deviceConf?.hideLight === true) {
+    chosen.light = false
+  }
+  if (deviceConf?.hideSwing === true) {
+    chosen.swing = false
+  }
+  return chosen
+}
+
+function firmwareLayer(model, firmware) {
+  if (!firmware) {
+    return {}
+  }
+  const applied = {}
+  const rules = [...(firmwareControls[model] || [])]
+    .sort((a, b) => compareVersions(a.minVersion, b.minVersion))
+  rules.forEach((rule) => {
+    if (compareVersions(firmware, rule.minVersion) >= 0) {
+      Object.assign(applied, rule.controls)
+    }
+  })
+  return applied
+}
+
+/**
+ * Work out what a device can do.
+ *
+ * @param {object} context describing the device
+ * @param {string} context.model the govee model, eg 'H7130'
+ * @param {string} [context.family] which set of defaults to fall back on
+ * @param {string} [context.firmware] the firmware version the device reported
+ * @param {object} [context.openApiCapabilities] what the api said it can do
+ * @param {object} [context.deviceConf] this device's settings
+ * @returns {{ controls: object, sources: object }} the controls, and which
+ *   layer decided each one - the second is for the log, so an unexpected answer
+ *   can be traced without guessing
+ */
+export function resolveControls(context = {}) {
+  const {
+    model,
+    family,
+    firmware,
+    openApiCapabilities,
+    deviceConf,
+  } = context
+
+  // Lowest priority first, so a later layer overwrites an earlier one
+  const layers = [
+    ['family', familyControls[family] || {}],
+    ['discovered', fromDiscovery(openApiCapabilities)],
+    ['model', modelControls[model] || {}],
+    ['firmware', firmwareLayer(model, firmware)],
+    ['config', fromConfig(deviceConf)],
+  ]
+
+  const controls = { ...emptyControls }
+  const sources = {}
+
+  layers.forEach(([name, values]) => {
+    Object.entries(values).forEach(([control, value]) => {
+      controls[control] = value
+      sources[control] = name
+    })
+  })
+
+  return { controls, sources }
+}
+
+/**
+ * A one-line summary of where each answer came from, for the debug log. Reading
+ * "swing from family" tells you nobody has confirmed it, which is a different
+ * situation from "swing from model".
+ */
+export function describeSources(sources) {
+  return Object.entries(sources)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([control, source]) => `${control} from ${source}`)
+    .join(', ') || 'nothing known'
+}
+
+export { familyControls, modelControls, unconfirmedMissing }

package/lib/utils/device-capabilities.js

@@ -80,7 +80,7 @@ const firmwareOverrides = {
  * newer than `b`, negative if older, and zero if they match. Missing parts
  * count as zero, so "1.03" and "1.03.00" are equal.
  */
-function compareVersions(a, b) {
+export function compareVersions(a, b) {
   const aParts = String(a).split('.')
   const bParts = String(b).split('.')
   for (let i = 0; i < Math.max(aParts.length, bParts.length); i += 1) {

package/package.json

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

package/lib/utils/appliance-capabilities.js

@@ -1,45 +0,0 @@
-/**
- * What each appliance model can actually do.
- *
- * Appliance handlers are shared between models, which historically meant every
- * model in a group was given every control the group could offer - so a heater
- * without a turning head still got an oscillation switch that did nothing. This
- * map lets a shared handler offer only the controls a model really has, without
- * needing a separate file per model.
- *
- * A model that is not listed keeps the handler's full set of controls, so
- * adding an entry is opt-in and nothing changes for a model until it is
- * described here.
- */
-
-/**
- * Heaters.
- *
- * ⚠️ Several models already in the plugin are believed not to have oscillation
- * (the H713A, H713B, H713C and H7135), but they have been offered it for a long
- * time. They are deliberately NOT restricted here: if any owner is using that
- * control today, taking it away would break a working setup for the sake of
- * tidiness. Restrict them only once an owner has confirmed the control does
- * nothing. New models are added with their real capabilities from the start,
- * where there is nobody to break.
- */
-const heaterFeatures = {
-  // Power and mode only - no turning head, no night light
-  H7137: { swing: false, lock: false },
-  H713E: { swing: false, lock: false },
-}
-
-const heaterDefaults = {
-  swing: true,
-  lock: true,
-}
-
-/**
- * Get the controls a heater model should offer.
- *
- * @param {string} model the govee model, eg 'H7130'
- * @returns {{ swing: boolean, lock: boolean }} the controls to offer
- */
-export function getHeaterFeatures(model) {
-  return { ...heaterDefaults, ...(heaterFeatures[model] || {}) }
-}