@homebridge-plugins/homebridge-govee 11.36.1-beta.9 → 11.37.0

package/CHANGELOG.md

@@ -2,7 +2,7 @@
 
 All notable changes to `@homebridge-plugins/homebridge-govee` will be documented in this file.
 
-## v11.36.1 (Pending Release)
+## v11.37.0 (2026-08-14)
 
 ### Changed
 
@@ -18,6 +18,19 @@ All notable changes to `@homebridge-plugins/homebridge-govee` will be documented
 - fix: only give the H1310 and R1310 two light tiles when each has a switch of its own to send (#1352)
 - fix: lead a thermo sensor's tile with its temperature, not its humidity, when shown as a thermostat (#1354)
 - docs(schema): describe what the thermo sensor extra switch setting actually does now (#1354)
+- feat: let a ceiling fan that can reverse be switched between forward and reverse from the fan tile (#1352)
+- fix: stop calling a ceiling fan's speed report unrecognised while the fan is off (#1352)
+- fix: read a ceiling fan's airflow direction from what the fan reports, so the tile follows the govee app (#1352)
+- fix: show each of a ceiling fan's two lights as on or off from what the fan reports (#1352)
+- fix: lead a ceiling fan's tile with the fan rather than one of its lights (#1352)
+- fix: read a ceiling fan's light from what it says about its lights, not from whether the fan has power (#1352)
+- fix: stop calling a ceiling fan's light status unrecognised on a handler that reads it (#1352)
+- fix: stop reporting govee's command receipts as messages the plugin did not understand (#1352)
+- fix: read whether a ceiling fan is turning from the fan itself, not from its lights (#1352)
+- fix: switch a ceiling fan on with its own switch, not with a command that turns its lights on (#1352)
+- fix: put a ceiling fan's shared brightness and colour on one light tile, as the fan has only one of each (#1352)
+- fix: switch a ceiling fan's light off instead of dimming both its lights to nothing (#1352)
+- chore(deps): dependency updates
 
 ## v11.36.0 (2026-08-11)
 

package/lib/device/fan-H1310.js

@@ -1,17 +1,116 @@
 import { hs2rgb } from '../utils/colour.js'
-import { generateRandomString, sleep } from '../utils/functions.js'
+import {
+  base64ToHex,
+  generateCodeFromHexValues,
+  generateRandomString,
+  getTwoItemPosition,
+  hexToTwoItems,
+  sleep,
+} from '../utils/functions.js'
+import platformLang from '../utils/lang-en.js'
 import deviceFanH1370 from './fan-H1370.js'
 
 /**
- * The two lights an H1310 has, and the api switch each one answers to. Govee
- * lists both against this device, and they are the only way to reach one light
- * without the other - `powerSwitch` is the whole unit, fan included.
+ * The two lights an H1310 has, the api switch each one answers to, and the bit
+ * each one sets in the `aa 42` status.
+ *
+ * Those switches are the only way to reach one light without the other -
+ * `powerSwitch` is the whole unit, fan included.
+ */
+/**
+ * ⚠️ The fan has ONE brightness and ONE colour, shared by both lights - the
+ * govee app offers a single set too. So only the main light carries them, and
+ * the background light is an on/off tile.
+ *
+ * Two sliders that secretly move together read as a fault, but the real cost
+ * was worse: HomeKit sends a brightness of 0 when a bulb is switched off, and
+ * the brightness command is device-wide, so switching one light off dimmed the
+ * pair to nothing (#1352).
  */
 const LIGHTS = [
-  { name: 'Main Light', instance: 'mainLightToggle' },
-  { name: 'Background Light', instance: 'backgroundLightToggle' },
+  { name: 'Main Light', instance: 'mainLightToggle', bit: 0x40, carriesSharedControls: true },
+  { name: 'Background Light', instance: 'backgroundLightToggle', bit: 0x20, carriesSharedControls: false },
 ]
 
+/**
+ * The two status frames carrying the lights. This fan sends both, every time,
+ * saying the same thing two different ways:
+ *
+ * - `aa 42 <mask>`  - one byte, bit 6 main, bit 5 background, bit 7 either
+ * - `aa 36 <main> <background>` - one byte each
+ *
+ * They agree in all 69 statuses posted on #1352:
+ *
+ * | `aa 36` | `aa 42` | lit                |
+ * |---------|---------|--------------------|
+ * | `01 01` | `e0`    | both               |
+ * | `01 00` | `c0`    | main only          |
+ * | `00 01` | `a0`    | background only    |
+ * | `00 00` | `00`    | neither            |
+ *
+ * ⚠️ `aa 36` is fan power on the H1370 and the lights here, which is why this
+ * handler has to claim the code rather than let the parent read it.
+ */
+const LIGHT_MASK_CODE = '42'
+const LIGHT_PAIR_CODE = '36'
+
+/** Set in that mask whenever either light is lit, whichever one it is. */
+const ANY_LIGHT_BIT = 0x80
+
+/**
+ * The speed frame, which also carries whether the fan is turning:
+ * `aa 31 <running> <speed> <direction>`.
+ */
+const FAN_CODE = '31'
+
+/** The api switches for the fan itself and for running it backwards. */
+const FAN_TOGGLE = 'fanToggle'
+const REVERSE_AIRFLOW = 'reverseAirflowToggle'
+
+/**
+ * Reads which lights are lit out of a status, from whichever of the two frames
+ * the fan sent, normalised to the `aa 42` mask.
+ *
+ * @param {string[]} commands base64 status codes from the fan
+ * @returns {number|undefined} the mask, or undefined if the fan said neither
+ */
+function lightMaskFrom(commands) {
+  let mask
+  ;(commands || []).forEach((command) => {
+    const hexParts = hexToTwoItems(base64ToHex(command))
+    if (getTwoItemPosition(hexParts, 1) !== 'aa') {
+      return
+    }
+    if (getTwoItemPosition(hexParts, 2) === LIGHT_MASK_CODE) {
+      mask = Number.parseInt(getTwoItemPosition(hexParts, 3), 16)
+      return
+    }
+    if (getTwoItemPosition(hexParts, 2) === LIGHT_PAIR_CODE) {
+      const main = getTwoItemPosition(hexParts, 3) === '01'
+      const background = getTwoItemPosition(hexParts, 4) === '01'
+      mask = (main ? 0x40 : 0) | (background ? 0x20 : 0) | (main || background ? ANY_LIGHT_BIT : 0)
+    }
+  })
+  return mask
+}
+
+/**
+ * Reads whether the fan is turning, from the third byte of its speed frame.
+ *
+ * @param {string[]} commands base64 status codes from the fan
+ * @returns {boolean|undefined} true if turning, or undefined if the fan did not say
+ */
+function fanIsRunningFrom(commands) {
+  let running
+  ;(commands || []).forEach((command) => {
+    const hexParts = hexToTwoItems(base64ToHex(command))
+    if (getTwoItemPosition(hexParts, 1) === 'aa' && getTwoItemPosition(hexParts, 2) === FAN_CODE) {
+      running = getTwoItemPosition(hexParts, 3) === '01'
+    }
+  })
+  return running
+}
+
 export default class GoveeFanH1310 extends deviceFanH1370 {
   constructor(platform, accessory) {
     super(platform, accessory)
@@ -20,10 +119,42 @@ export default class GoveeFanH1310 extends deviceFanH1370 {
     // ceiling-fan range. (speedSteps now comes from device-capabilities or the
     // device's OpenAPI fanSpeedMode; do not overwrite the superclass value here.)
 
+    // Both light frames are read here. `aa 36` especially has to be claimed:
+    // the parent reads it as fan power, so left to it the fan tile followed
+    // the lights - off whenever they were off, whatever the fan was doing
+    this.handledStatusCodes.add(LIGHT_MASK_CODE)
+    this.handledStatusCodes.add(LIGHT_PAIR_CODE)
+
+    // The fan has its own api switch, which is the only way to reach the fan
+    // without touching the lights. `33 36 ...`, which the parent sends for fan
+    // power, is the two lights on this model
+    this.canSendFanToggle = !!accessory.context.openApiCapabilities?.[FAN_TOGGLE]
+      && !!accessory.context.useOpenApiControl
+
     if (this.service.testCharacteristic(this.hapChar.SwingMode)) {
       this.service.removeCharacteristic(this.service.getCharacteristic(this.hapChar.SwingMode))
     }
 
+    // Airflow direction. HomeKit's fan already has somewhere to put this, so it
+    // goes on the tile the owner already has rather than adding another one.
+    //
+    // Gated on its own capability rather than on the lights below: a fan could
+    // reasonably have one and not the other, and a control that cannot be sent
+    // is worse than no control (#1352)
+    this.canReverseAirflow = !!accessory.context.openApiCapabilities?.[REVERSE_AIRFLOW]
+      && !!accessory.context.useOpenApiControl
+
+    if (this.canReverseAirflow) {
+      this.service
+        .getCharacteristic(this.hapChar.RotationDirection)
+        .onSet(async value => this.internalDirectionUpdate(value))
+      this.cacheDirection = this.service.getCharacteristic(this.hapChar.RotationDirection).value
+    } else if (this.service.testCharacteristic(this.hapChar.RotationDirection)) {
+      // Left over from a device that used to report the switch, or from a
+      // config that has since lost api access
+      this.service.removeCharacteristic(this.service.getCharacteristic(this.hapChar.RotationDirection))
+    }
+
     // Two tiles are only honest when each one has a switch of its own to send.
     // Those switches exist solely over the api, so without it both tiles would
     // fall back to the device-wide power switch - and either would take the fan
@@ -46,19 +177,227 @@ export default class GoveeFanH1310 extends deviceFanH1370 {
     }
 
     this.lightServices = {}
-    LIGHTS.forEach(({ name }) => {
+    LIGHTS.forEach(({ name, carriesSharedControls }) => {
       const service = this.accessory.getService(name)
         || this.accessory.addService(this.hapServ.Lightbulb, name, name)
       this.lightServices[name] = service
-      this.setupLightService(service, name)
+      this.setupLightService(service, name, carriesSharedControls)
+    })
+  }
+
+  /**
+   * Switching the fan on and off.
+   *
+   * The parent sends `33 36 01 01`, which on an H1370 is its fan. Here `aa 36`
+   * is the two lights, so that command turns both lights on and never touches
+   * the fan. The fan's own api switch is used instead where it can be sent,
+   * and otherwise the speed frame - `33 31 <running> <speed>` - which is the
+   * frame this fan reports its own running state in (#1352).
+   *
+   * @param {number} value 1 active, 0 inactive
+   */
+  async internalStateUpdate(value) {
+    try {
+      const newValue = value ? 'on' : 'off'
+      if (this.cacheState === newValue) {
+        return
+      }
+
+      if (this.canSendFanToggle) {
+        await this.platform.sendDeviceUpdate(this.accessory, {
+          cmd: 'openApi',
+          openApi: {
+            instance: FAN_TOGGLE,
+            capabilityType: 'devices.capabilities.toggle',
+            value: value ? 1 : 0,
+          },
+        })
+      } else {
+        // Keep the speed the fan already had, so switching it back on returns
+        // it to where its owner left it rather than to a speed of nothing
+        const speed = this.cacheSpeed || 1
+        await this.platform.sendDeviceUpdate(this.accessory, {
+          cmd: 'ptReal',
+          value: generateCodeFromHexValues([0x33, 0x31, value ? 0x01 : 0x00, speed]),
+        })
+      }
+
+      this.cacheState = newValue
+      this.accessory.log(`${platformLang.curState} [${newValue}]`)
+    } catch (err) {
+      this.failUpdate(err, () => {
+        this.service.updateCharacteristic(this.hapChar.Active, this.cacheState === 'on' ? 1 : 0)
+      })
+    }
+  }
+
+  /**
+   * HomeKit gives a fan two directions and Govee gives it one switch, so the
+   * two map onto each other directly. Which way round the fan physically turns
+   * for "reverse" is Govee's business and is not written down anywhere - if an
+   * owner reports the two being the wrong way round, swap them here.
+   *
+   * @param {number} value 0 clockwise, 1 counter-clockwise
+   */
+  async internalDirectionUpdate(value) {
+    try {
+      if (this.cacheDirection === value) {
+        return
+      }
+
+      await this.platform.sendDeviceUpdate(this.accessory, {
+        cmd: 'openApi',
+        openApi: {
+          instance: REVERSE_AIRFLOW,
+          capabilityType: 'devices.capabilities.toggle',
+          value: value === 1 ? 1 : 0,
+        },
+      })
+
+      this.cacheDirection = value
+      this.accessory.log(`${platformLang.curDirection} [${value === 1 ? 'upward' : 'downward'}]`)
+    } catch (err) {
+      this.failUpdate(err, () => {
+        this.service.updateCharacteristic(this.hapChar.RotationDirection, this.cacheDirection)
+      })
+    }
+  }
+
+  /**
+   * The device-wide on/off field is the whole unit having power here, not the
+   * light: a fan reporting `onOff` 1 has been seen with `aa 36 00` (fan off)
+   * and `aa 42 00` (both lights off) in the same status. Letting it speak for
+   * the light lit the light tile every time the fan was switched on (#1352).
+   *
+   * The `aa 42` mask is what this fan actually says about its lights, so read
+   * the single tile off the bit that is set whenever either one is lit.
+   *
+   * @param {object} params a parsed device update
+   * @returns {'on'|'off'|undefined} the light's state, or undefined if unsaid
+   */
+  readLightState(params) {
+    const mask = lightMaskFrom(params.commands)
+    if (mask === undefined) {
+      return undefined
+    }
+    return (mask & ANY_LIGHT_BIT) === ANY_LIGHT_BIT ? 'on' : 'off'
+  }
+
+  externalUpdate(params) {
+    super.externalUpdate(params)
+
+    // Whether the fan is turning. The parent cannot read this: on an H1370 it
+    // comes from `aa 36`, which here belongs to the lights. This fan says so in
+    // the third byte of its speed frame instead, and the api switch is read as
+    // a fallback for a device answering over the api rather than aws (#1352)
+    let running = fanIsRunningFrom(params.commands)
+    if (running === undefined && params.toggles?.[FAN_TOGGLE] !== undefined) {
+      running = !!params.toggles[FAN_TOGGLE]
+    }
+    if (running !== undefined) {
+      const newState = running ? 'on' : 'off'
+      if (this.cacheState !== newState) {
+        this.cacheState = newState
+        this.service.updateCharacteristic(this.hapChar.Active, running ? 1 : 0)
+        this.accessory.log(`${platformLang.curState} [${newState}]`)
+      }
+    }
+
+    // Each light's own on/off, read off the same mask
+    const mask = lightMaskFrom(params.commands)
+    if (mask !== undefined) {
+      LIGHTS.forEach(({ name, bit }) => {
+        const service = this.lightServices?.[name]
+        if (!service) {
+          return
+        }
+        const newValue = (mask & bit) === bit ? 'on' : 'off'
+        const cacheKey = `${name}:state`
+        if (this[cacheKey] !== newValue) {
+          this[cacheKey] = newValue
+          service.updateCharacteristic(this.hapChar.On, newValue === 'on')
+          this.accessory.log(`${name} ${newValue}`)
+        }
+      })
+    }
+
+    // The one shared brightness and colour, reported onto the one tile that
+    // carries them. The parent puts these on its single light, which the named
+    // tiles replaced
+    if (this.lightServices) {
+      LIGHTS.filter(light => light.carriesSharedControls).forEach(({ name }) => {
+        const service = this.lightServices[name]
+        if (params.brightness && this[`${name}:brightness`] !== params.brightness) {
+          this[`${name}:brightness`] = params.brightness
+          service.updateCharacteristic(this.hapChar.Brightness, params.brightness)
+        }
+        if (params.kelvin) {
+          const k = Math.min(Math.max(params.kelvin, 2700), 6500)
+          const mired = Math.min(Math.max(Math.round(1000000 / k), 154), 370)
+          if (this[`${name}:ct`] !== mired) {
+            this[`${name}:ct`] = mired
+            service.updateCharacteristic(this.hapChar.ColorTemperature, mired)
+          }
+        }
+      })
+    }
+
+    // Airflow direction is a separate capability from the lights, so it gets
+    // its own guard rather than sharing theirs
+    if (!this.canReverseAirflow) {
+      return
+    }
+
+    // The fan reports its direction as the fifth byte of its speed frame -
+    // `aa 31 <running> <speed> <direction>` - rather than as a status of its
+    // own. Captured on a real H1310 in #1352: flowing downward reported
+    // `aa 31 01 01 00` and upward `aa 31 01 01 01`, with nothing else in the
+    // status differing between the two.
+    let reported
+    ;(params.commands || []).forEach((command) => {
+      const hexParts = hexToTwoItems(base64ToHex(command))
+      if (getTwoItemPosition(hexParts, 1) === 'aa' && getTwoItemPosition(hexParts, 2) === '31') {
+        reported = getTwoItemPosition(hexParts, 5) === '01' ? 1 : 0
+      }
     })
+
+    // The api toggle is the only way to SEND a direction, so it is still read
+    // as a fallback for a device answering over the api rather than aws
+    if (reported === undefined && params.toggles?.[REVERSE_AIRFLOW] !== undefined) {
+      reported = params.toggles[REVERSE_AIRFLOW] ? 1 : 0
+    }
+
+    if (reported !== undefined && this.cacheDirection !== reported) {
+      this.cacheDirection = reported
+      this.service.updateCharacteristic(this.hapChar.RotationDirection, reported)
+      this.accessory.log(`${platformLang.curDirection} [${reported === 1 ? 'upward' : 'downward'}]`)
+    }
   }
 
-  setupLightService(service, name) {
+  setupLightService(service, name, carriesSharedControls) {
     service.getCharacteristic(this.hapChar.On).onSet(async (value) => {
       await this.internalLightStateUpdate(service, name, value)
     })
 
+    if (!carriesSharedControls) {
+      // An on/off tile. The brightness and colour live on the other light, as
+      // the fan has only one of each. Anything left over from a cached version
+      // that gave both tiles the full set has to go, or HomeKit keeps showing
+      // a slider that moves the other light too
+      const shared = [
+        this.hapChar.Brightness,
+        this.hapChar.Hue,
+        this.hapChar.Saturation,
+        this.hapChar.ColorTemperature,
+      ]
+      shared.forEach((characteristic) => {
+        if (service.testCharacteristic(characteristic)) {
+          service.removeCharacteristic(service.getCharacteristic(characteristic))
+        }
+      })
+      return
+    }
+
     service
       .getCharacteristic(this.hapChar.Brightness)
       .setProps({ minStep: 1 })
@@ -113,6 +452,15 @@ export default class GoveeFanH1310 extends deviceFanH1370 {
       return
     }
 
+    // HomeKit sends a brightness of 0 when a bulb is switched off, and the
+    // brightness command is device-wide - so obeying it dimmed BOTH lights to
+    // nothing. Switch this light off with its own switch instead, and leave
+    // the shared brightness where its owner had it (#1352)
+    if (value === 0) {
+      await this.internalLightStateUpdate(service, name, false)
+      return
+    }
+
     const cacheKey = `${name}:brightness`
     if (this[cacheKey] === value) {
       return

package/lib/device/fan-H1370.js

@@ -17,7 +17,7 @@ import GoveeDevice from './base.js'
 /*
   Codes below were decoded from a real device's AWS status reports in
   https://github.com/homebridge-plugins/homebridge-govee/issues/1307
-  Status aa 31 01 [speed] = fan speed (1 to the model's step count)
+  Status aa 31 [?] [speed] [direction] = fan speed and airflow direction
   Status aa 36 01 01 / aa 36 00 00 = fan power on/off
   The light reports through the standard state/brightness/kelvin fields
   (colour temperature only, 2700-6500K)
@@ -42,9 +42,20 @@ export default class GoveeFanH1370 extends GoveeDevice {
       }
     }
 
+    // Status codes a subclass reads for itself. Without this the parent still
+    // reaches its default branch and announces a code that was in fact handled,
+    // which is the same unrecognised-status noise this model was reported for
+    this.handledStatusCodes = new Set()
+
     // Add the fan service if it doesn't already exist
     this.service = this.accessory.getService(this.hapServ.Fanv2) || this.accessory.addService(this.hapServ.Fanv2)
 
+    // This accessory is a fan that happens to have lights on it, so the fan is
+    // what its tile should lead with. Without saying so the Home app picks for
+    // itself and lands on a light, leaving an owner tapping through to reach
+    // the fan they came for (#1352)
+    this.service.setPrimaryService(true)
+
     // Add the set handler to the fan on/off characteristic
     this.service
       .getCharacteristic(this.hapChar.Active)
@@ -281,11 +292,29 @@ export default class GoveeFanH1370 extends GoveeDevice {
     }
   }
 
+  /**
+   * Whether the light is lit, as this model reports it.
+   *
+   * On the H1370 the device-wide on/off field is the only word there is on the
+   * light, so it is taken at face value. A model that says so separately should
+   * override this rather than let that field speak for the light - see the
+   * H1310, where it stays on while both lights are off.
+   *
+   * @param {object} params a parsed device update
+   * @returns {'on'|'off'|undefined} the light's state, or undefined if unsaid
+   */
+  readLightState(params) {
+    return params.state
+  }
+
   externalUpdate(params) {
-    // The standard state/brightness/kelvin fields report the light
-    if (!this.hideLight) {
-      if (params.state && params.state !== this.cacheLightState) {
-        this.cacheLightState = params.state
+    // The standard state/brightness/kelvin fields report the light. A subclass
+    // that replaces the single light with named ones leaves lightService unset,
+    // and updating it would throw on every status the fan sends
+    if (!this.hideLight && this.lightService) {
+      const lightState = this.readLightState(params)
+      if (lightState && lightState !== this.cacheLightState) {
+        this.cacheLightState = lightState
         this.lightService.updateCharacteristic(this.hapChar.On, this.cacheLightState === 'on')
         this.accessory.log(`${platformLang.curLight} [${this.cacheLightState}]`)
       }
@@ -316,9 +345,24 @@ export default class GoveeFanH1370 extends GoveeDevice {
         return
       }
 
+      // A subclass that reads a code for itself owns it outright, so the parent
+      // must neither act on it nor call it unrecognised. The same code can mean
+      // different things on different fans - `aa 36` is fan power on an H1370
+      // and the two lights on an H1310 - so acting on it here would be wrong
+      if (this.handledStatusCodes.has(getTwoItemPosition(hexParts, 2))) {
+        return
+      }
+
       const deviceFunction = `${getTwoItemPosition(hexParts, 2)}${getTwoItemPosition(hexParts, 3)}`
 
       switch (deviceFunction) {
+        // aa 31 <?> <speed> <direction>. The third byte is not part of the
+        // code: an H1310 has been seen reporting both 00 and 01 for it with the
+        // fan running either way, so what it means is still unknown - but
+        // matching only 3101 announced every other status as unrecognised,
+        // which is the noise that sent this model's owner here (#1352).
+        // `aa 36` is the reliable word on whether the fan is running.
+        case '3100':
         case '3101': {
           // Fan speed
           const newSpeed = Number.parseInt(getTwoItemPosition(hexParts, 4), 16)

package/lib/platform.js

@@ -30,7 +30,7 @@ import {
 } from './utils/functions.js'
 import platformLang from './utils/lang-en.js'
 import { isFirstReport, logUnknownData } from './utils/report-unknown.js'
-import { parseDeviceUpdate } from './utils/response-parser.js'
+import { isCommandAcknowledgement, parseDeviceUpdate } from './utils/response-parser.js'
 
 const require = createRequire(import.meta.url)
 const plugin = require('../package.json')
@@ -1422,6 +1422,11 @@ export default class {
       } catch (err) {
         this.log.warn('[%s] %s %s.', accessory.displayName, platformLang.devNotUpdated, parseError(err))
       }
+    } else if (isCommandAcknowledgement(params)) {
+      // Govee answers a command with a receipt carrying nothing but whether it
+      // worked. There is no status in it to miss, so reporting it as a payload
+      // nobody understood buries the ones that are worth reading (#1352)
+      accessory.logDebug(`[${params.source}] ${platformLang.cmdAcknowledged} [${params.cmd}]`)
     } else {
       // Nothing in the payload was understood. This is the most useful thing a
       // user can send in when asking for a device or a function to be added, so

package/lib/utils/lang-en.js

@@ -65,6 +65,7 @@ export default {
   curOcc: 'current occupancy',
   curPM25: 'current PM2.5',
   curScene: 'current scene',
+  curDirection: 'current airflow direction',
   curSpeed: 'current speed',
   curState: 'current state',
   curSwing: 'current swing',
@@ -140,4 +141,5 @@ export default {
   syncStillRunning: 'skipping this sync as the previous one has not finished yet',
   viaAL: 'via adaptive lighting',
   statusCodes: 'device status codes',
+  cmdAcknowledged: 'command acknowledged',
 }

package/lib/utils/response-parser.js

@@ -47,6 +47,24 @@ function resolveOpenApiTempUnit(value, context) {
   return null
 }
 
+/**
+ * Whether a payload is only govee's receipt for a command we sent.
+ *
+ * These carry a command name and a `result` and nothing else - no status at
+ * all - so there is nothing in them to have failed to understand. Anything
+ * that names even one other field is a real payload and is not this.
+ *
+ * @param {object} params - Raw payload with source, cmd, state, etc.
+ * @returns {boolean} true if the payload is a bare acknowledgement
+ */
+export function isCommandAcknowledgement(params) {
+  if (!params?.cmd || !params.state || typeof params.state !== 'object') {
+    return false
+  }
+  const keys = Object.keys(params.state)
+  return keys.length > 0 && keys.every(key => key === 'result')
+}
+
 /**
  * Parses a raw device update payload into a standardised data object.
  * Handles different payload structures from AWS, LAN, OpenAPI, and legacy devices.

package/package.json

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