@homebridge-plugins/homebridge-govee 11.36.1-beta.13 → 11.36.1-beta.15

package/CHANGELOG.md

@@ -22,6 +22,10 @@ All notable changes to `@homebridge-plugins/homebridge-govee` will be documented
 - 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)
 
 ## v11.36.0 (2026-08-11)
 

package/lib/device/fan-H1310.js

@@ -30,9 +30,29 @@ const LIGHTS = [
 /** The status frame carrying that mask: `aa 42 <mask>`. */
 const LIGHT_MASK_CODE = '42'
 
+/** Set in that mask whenever either light is lit, whichever one it is. */
+const ANY_LIGHT_BIT = 0x80
+
 /** The api switch that runs the fan backwards. */
 const REVERSE_AIRFLOW = 'reverseAirflowToggle'
 
+/**
+ * Reads the `aa 42 <mask>` light mask out of a status, if it is in there.
+ *
+ * @param {string[]} commands base64 status codes from the fan
+ * @returns {number|undefined} the mask, or undefined if the fan did not send one
+ */
+function lightMaskFrom(commands) {
+  let mask
+  ;(commands || []).forEach((command) => {
+    const hexParts = hexToTwoItems(base64ToHex(command))
+    if (getTwoItemPosition(hexParts, 1) === 'aa' && getTwoItemPosition(hexParts, 2) === LIGHT_MASK_CODE) {
+      mask = Number.parseInt(getTwoItemPosition(hexParts, 3), 16)
+    }
+  })
+  return mask
+}
+
 export default class GoveeFanH1310 extends deviceFanH1370 {
   constructor(platform, accessory) {
     super(platform, accessory)
@@ -41,6 +61,10 @@ 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.)
 
+    // This handler reads the light mask itself, so the parent should stop
+    // announcing it as a status nobody understood
+    this.handledStatusCodes.add(LIGHT_MASK_CODE)
+
     if (this.service.testCharacteristic(this.hapChar.SwingMode)) {
       this.service.removeCharacteristic(this.service.getCharacteristic(this.hapChar.SwingMode))
     }
@@ -127,16 +151,32 @@ export default class GoveeFanH1310 extends deviceFanH1370 {
     }
   }
 
+  /**
+   * 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)
 
     // Each light's own on/off, read off the same mask
-    ;(params.commands || []).forEach((command) => {
-      const hexParts = hexToTwoItems(base64ToHex(command))
-      if (getTwoItemPosition(hexParts, 1) !== 'aa' || getTwoItemPosition(hexParts, 2) !== LIGHT_MASK_CODE) {
-        return
-      }
-      const mask = Number.parseInt(getTwoItemPosition(hexParts, 3), 16)
+    const mask = lightMaskFrom(params.commands)
+    if (mask !== undefined) {
       LIGHTS.forEach(({ name, bit }) => {
         const service = this.lightServices?.[name]
         if (!service) {
@@ -150,7 +190,28 @@ export default class GoveeFanH1310 extends deviceFanH1370 {
           this.accessory.log(`${name} ${newValue}`)
         }
       })
-    })
+    }
+
+    // The fan has one brightness and one colour shared between both lights, so
+    // a reading of either belongs on both tiles. The parent puts these on its
+    // single light, which the named tiles replaced
+    if (this.lightServices) {
+      LIGHTS.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

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 [running] [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}]`)
       }
@@ -319,11 +348,12 @@ export default class GoveeFanH1370 extends GoveeDevice {
       const deviceFunction = `${getTwoItemPosition(hexParts, 2)}${getTwoItemPosition(hexParts, 3)}`
 
       switch (deviceFunction) {
-        // aa 31 <running> <speed>. The third byte is the fan's running flag,
-        // not part of the code - a stopped fan reports 3100 and still names the
-        // speed it will return to. Reading only 3101 meant that every status
-        // sent while the fan was off was announced as unrecognised, which is
-        // the noise that sent this model's owner to the issue tracker (#1352)
+        // 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
@@ -355,6 +385,9 @@ export default class GoveeFanH1370 extends GoveeDevice {
           break
         }
         default:
+          if (this.handledStatusCodes.has(getTwoItemPosition(hexParts, 2))) {
+            break
+          }
           logUnknownData(this.accessory, {
             kind: 'status',
             source: params.source,

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

@@ -141,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.13",
+  "version": "11.36.1-beta.15",
   "description": "Homebridge plugin to integrate Govee devices into HomeKit.",
   "author": {
     "name": "bwp91",