@homebridge-plugins/homebridge-govee 11.34.1 → 11.34.2-beta.1

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to `@homebridge-plugins/homebridge-govee` will be documented in this file.
 
+## v11.34.2 (Pending Release)
+
+### Changed
+
+- feat: control the H1250 zones with the device's own frame, as govee ignores its toggles (#1343) (@Principe1218)
+- fix: explain in the log when zone tiles are missing because aws credentials are not set
+- fix: restore debug logging when the plugin runs in a child bridge
+
 ## v11.34.1 (2026-08-06)
 
 ### Changed

package/lib/device/light.js

@@ -6,14 +6,43 @@ import {
 } from '../utils/colour.js'
 import platformConsts from '../utils/constants.js'
 import {
+  base64ToHex,
   generateRandomString,
+  getTwoItemPosition,
   hasProperty,
+  hexToTwoItems,
   parseError,
   sleep,
 } from '../utils/functions.js'
 import platformLang from '../utils/lang-en.js'
 import GoveeDevice from './base.js'
 
+/**
+ * The zone state of a light that reports both of its zones in one frame, as
+ * `aa 30 <main> <background>`.
+ *
+ * Reported under the same capability instances the OpenAPI uses, so zone state
+ * reads the same whichever connection carried it. This frame arrives unprompted
+ * whenever the zones change, including from the Govee app or the wall switch,
+ * which is how the tiles stay right rather than only echoing our own writes -
+ * all the toggles could ever manage on these models (#1333).
+ *
+ * @param {string[]} [commands] the base64 frames from the payload
+ * @returns {object} the zones found, keyed by capability instance
+ */
+function readZoneFrame(commands = []) {
+  const zones = {}
+  commands.forEach((command) => {
+    const hexParts = hexToTwoItems(base64ToHex(command))
+    if (`${getTwoItemPosition(hexParts, 1)}${getTwoItemPosition(hexParts, 2)}` !== 'aa30') {
+      return
+    }
+    zones.mainLightToggle = getTwoItemPosition(hexParts, 3) === '01'
+    zones.backgroundLightToggle = getTwoItemPosition(hexParts, 4) === '01'
+  })
+  return zones
+}
+
 export default class extends GoveeDevice {
   constructor(platform, accessory) {
     super(platform, accessory)
@@ -199,30 +228,51 @@ export default class extends GoveeDevice {
     // Some lights (e.g. the H1270 Ceiling Light Ultra) have two independently
     // controllable zones - a main/bottom panel and a background/top light. Govee
     // exposes these as OpenAPI toggle capabilities, so add a switch for each zone
-    // the device reports. These are only controllable via the OpenAPI connection.
+    // the device reports, controlled over the OpenAPI connection.
+    //
+    // The models in `zoneLightModels` advertise those same capabilities but the
+    // cloud never delivers them, so they are driven by a raw frame over AWS
+    // instead. That is the only difference - the tiles, their state and the way
+    // a failure is undone are the same either way (#1333)
     this.zoneServices = {}
     this.zoneCache = {}
+    this.hasRawZones = platformConsts.zoneLightModels.includes(accessory.context.gvModel)
     const zoneToggleDefs = [
-      { instance: 'mainLightToggle', name: 'Main Light' },
-      { instance: 'backgroundLightToggle', name: 'Background Light' },
+      { instance: 'mainLightToggle', zone: 'main', name: 'Main Light' },
+      { instance: 'backgroundLightToggle', zone: 'background', name: 'Background Light' },
     ]
     const openApiCaps = accessory.context.openApiCapabilities || {}
-    zoneToggleDefs.forEach(({ instance, name }) => {
+    zoneToggleDefs.forEach(({ instance, zone, name }) => {
       const existingService = this.accessory.getService(name)
-      if (accessory.context.useOpenApiControl && openApiCaps[instance]) {
+
+      // The raw frame goes over AWS, which needs Govee account credentials
+      // rather than just an API key
+      const isControllable = this.hasRawZones
+        ? accessory.context.useAwsControl
+        : accessory.context.useOpenApiControl && openApiCaps[instance]
+
+      if (isControllable) {
         const service = existingService
           || this.accessory.addService(this.hapServ.Switch, name, instance)
         service
           .getCharacteristic(this.hapChar.On)
-          .onSet(async value => this.internalZoneUpdate(instance, name, value))
+          .onSet(async value => this.internalZoneUpdate(instance, zone, name, value))
         this.zoneServices[instance] = service
         this.zoneCache[instance] = service.getCharacteristic(this.hapChar.On).value ? 1 : 0
       } else if (existingService) {
-        // Capability no longer available (or OpenAPI disabled) so remove the switch
+        // Capability no longer available (or the connection it needs is off) so
+        // remove the switch
         this.accessory.removeService(existingService)
       }
     })
 
+    // Withholding the tiles without AWS is deliberate - tiles that swallow taps
+    // are worse than none - but silence would leave the owner with no idea the
+    // zones exist or what is missing, so say so once at startup
+    if (this.hasRawZones && !accessory.context.useAwsControl) {
+      this.accessory.log(platformLang.zoneNeedsAws)
+    }
+
     // Output the customised options to the log
     const useAwsControl = accessory.context.useAwsControl ? 'enabled' : 'disabled'
     const useBleControl = accessory.context.useBleControl ? 'enabled' : 'disabled'
@@ -274,7 +324,7 @@ export default class extends GoveeDevice {
     }
   }
 
-  async internalZoneUpdate(instance, name, value) {
+  async internalZoneUpdate(instance, zone, name, value) {
     const service = this.zoneServices[instance]
     try {
       const newValue = value ? 1 : 0
@@ -284,15 +334,26 @@ export default class extends GoveeDevice {
         return
       }
 
-      // These toggles are only controllable via the OpenAPI (cloud) connection
-      await this.platform.sendDeviceUpdate(this.accessory, {
-        cmd: 'openApi',
-        openApi: {
-          instance,
-          capabilityType: 'devices.capabilities.toggle',
-          value: newValue,
-        },
-      })
+      if (this.hasRawZones) {
+        // This model's toggles are accepted and ignored, so send the frame the
+        // device itself uses. The command builder leaves lanParams off, so this
+        // one skips LAN - which the device ignores - and goes over AWS
+        await this.platform.sendDeviceUpdate(this.accessory, {
+          cmd: 'zoneState',
+          zone,
+          value: newValue === 1,
+        })
+      } else {
+        // These toggles are only controllable via the OpenAPI (cloud) connection
+        await this.platform.sendDeviceUpdate(this.accessory, {
+          cmd: 'openApi',
+          openApi: {
+            instance,
+            capabilityType: 'devices.capabilities.toggle',
+            value: newValue,
+          },
+        })
+      }
 
       // Cache the new state and log
       this.zoneCache[instance] = newValue
@@ -663,11 +724,13 @@ export default class extends GoveeDevice {
       }
     }
 
-    // Update any independently-controllable light zones (e.g. main/background)
-    if (params.toggles) {
+    // Update any independently-controllable light zones (e.g. main/background),
+    // read from the device's own frame where the toggles report nothing
+    const zoneToggles = this.hasRawZones ? readZoneFrame(params.commands) : params.toggles
+    if (zoneToggles) {
       Object.entries(this.zoneServices).forEach(([instance, service]) => {
-        if (hasProperty(params.toggles, instance)) {
-          const newValue = params.toggles[instance] ? 1 : 0
+        if (hasProperty(zoneToggles, instance)) {
+          const newValue = zoneToggles[instance] ? 1 : 0
           if (this.zoneCache[instance] !== newValue) {
             this.zoneCache[instance] = newValue
             service.updateCharacteristic(this.hapChar.On, newValue === 1)

package/lib/platform.js

@@ -55,7 +55,6 @@ export default class {
     try {
       this.api = api
       this.log = log
-      this.isBeta = process.argv.includes('-D')
 
       // Configuration objects for accessories
       this.deviceConf = {}
@@ -111,14 +110,16 @@ export default class {
       // Log that the plugin initialisation has been successful
       this.log('%s.', platformLang.initialised)
 
-      // Sort out some logging functions
-      if (this.isBeta) {
-        this.log.debug = this.log
-        this.log.debugWarn = this.log.warn
-      } else {
-        this.log.debug = () => {}
-        this.log.debugWarn = () => {}
-      }
+      // Homebridge already decides whether debug lines are shown, and it gets it
+      // right in a child bridge too. This used to work it out for itself by
+      // looking for `-D` in the plugin's own process arguments, which a child
+      // bridge does not receive unless that bridge has its own debug setting
+      // turned on - so debug logging silently disappeared for anyone running the
+      // plugin in a child bridge with debug enabled globally.
+      //
+      // `debugWarn` has no equivalent on Homebridge's logger, so it goes out as
+      // a debug line too rather than being invented here.
+      this.log.debugWarn = (...args) => this.log.debug(...args)
 
       // Require any libraries that the plugin uses
       this.cusChar = new platformChars(this.api)
@@ -663,22 +664,21 @@ export default class {
   }
 
   applyAccessoryLogging(accessory) {
-    if (this.isBeta) {
-      accessory.log = msg => this.log('[%s] %s.', accessory.displayName, msg)
-      accessory.logWarn = msg => this.log.warn('[%s] %s.', accessory.displayName, msg)
-      accessory.logDebug = msg => this.log('[%s] %s.', accessory.displayName, msg)
-      accessory.logDebugWarn = msg => this.log.warn('[%s] %s.', accessory.displayName, msg)
-    } else {
-      if (this.config.disableDeviceLogging) {
-        accessory.log = () => {}
-        accessory.logWarn = () => {}
-      } else {
-        accessory.log = msg => this.log('[%s] %s.', accessory.displayName, msg)
-        accessory.logWarn = msg => this.log.warn('[%s] %s.', accessory.displayName, msg)
-      }
-      accessory.logDebug = () => {}
-      accessory.logDebugWarn = () => {}
+    // Debug lines always go to Homebridge's debug logger, which prints them only
+    // when debug is on - so there is nothing to decide here. Working it out from
+    // the process arguments instead is what lost debug logging entirely for
+    // anyone running the plugin in a child bridge.
+    accessory.logDebug = msg => this.log.debug('[%s] %s.', accessory.displayName, msg)
+    accessory.logDebugWarn = accessory.logDebug
+
+    if (this.config.disableDeviceLogging) {
+      accessory.log = () => {}
+      accessory.logWarn = () => {}
+      return
     }
+
+    accessory.log = msg => this.log('[%s] %s.', accessory.displayName, msg)
+    accessory.logWarn = msg => this.log.warn('[%s] %s.', accessory.displayName, msg)
   }
 
   initialiseDevice(device) {

package/lib/utils/command-builder.js

@@ -1,7 +1,7 @@
 import { CMD } from './ble-protocol.js'
 import { k2rgb } from './colour.js'
 import { getDeviceCapabilities } from './device-capabilities.js'
-import { base64ToHex } from './functions.js'
+import { base64ToHex, generateCodeFromHexValues } from './functions.js'
 
 /**
  * Builds connection-specific command params from a high-level device command.
@@ -26,6 +26,8 @@ export function buildCommand(params, context) {
       return buildPtRealCommand(params)
     case 'openApi':
       return buildOpenApiCommand(params)
+    case 'zoneState':
+      return buildZoneStateCommand(params)
     case 'brightness':
       return buildBrightnessCommand(params, context)
     case 'color':
@@ -117,6 +119,32 @@ function buildOpenApiCommand(params) {
   }
 }
 
+// A two-zone light reports its zones as `aa 30 <main> <background>` and takes
+// `33 30 <zone> <state>` to set one of them, where zone 00 is the main panel
+// and 01 the background ring (#1333)
+const ZONE_BYTE = { main: 0x00, background: 0x01 }
+
+function buildZoneStateCommand(params) {
+  const zone = ZONE_BYTE[params.zone]
+  if (zone === undefined) {
+    // Falling back to the main panel would switch the wrong light, which is far
+    // harder to notice than an outright failure
+    throw new Error(`Unknown light zone [${params.zone}] for ${params.cmd}`)
+  }
+
+  // Deliberately no lanParams. This model ignores `ptReal` over LAN, and LAN is
+  // fire-and-forget UDP, so sending it there would resolve and count as done -
+  // the command would never be retried over AWS. Leaving lanParams off lets the
+  // existing guard skip LAN for this one command, and every other command on
+  // the device carries on taking the faster local path.
+  return {
+    awsParams: {
+      cmd: 'ptReal',
+      data: { command: [generateCodeFromHexValues([0x33, 0x30, zone, params.value ? 0x01 : 0x00])] },
+    },
+  }
+}
+
 function buildBrightnessCommand(params, context) {
   const caps = getDeviceCapabilities(context.gvModel, context.firmware)
   return {

package/lib/utils/constants.js

@@ -714,6 +714,20 @@ export default {
     ],
   },
 
+  // Two-zone lights whose zones Govee lists but never routes. Not a device type
+  // of its own - these stay in `models.rgb` like any other light, and only the
+  // way their zones are driven differs.
+  //
+  // Govee advertises `mainLightToggle` and `backgroundLightToggle` for these,
+  // and its cloud answers `{"status":"success"}` to both, but the command never
+  // reaches the device. Nothing reports a failure, so the plugin cannot tell -
+  // the tiles simply do nothing. The models here take the raw frame the device
+  // itself reports its zones with instead (#1333).
+  //
+  // The H1270 is deliberately absent. It advertises the same capabilities, but
+  // nobody has confirmed it shares the fault, so it stays on the toggle path.
+  zoneLightModels: ['H1250'],
+
   matterModels: [
     'H1401',
     'H14C0',

package/lib/utils/lang-en.js

@@ -113,6 +113,7 @@ export default {
   noExtFunc: 'no externalUpdate function to process incoming update',
   notAWSConn: 'not connected to AWS',
   notAWSSent: 'not using AWS connection as',
+  zoneNeedsAws: 'this light has separately switchable zones, but the zone tiles need your Govee account username and password in the plugin settings - an API key alone is not enough for them',
   notBLESent: 'not using BLE connection as',
   notLANSent: 'not using LAN connection as',
   noOpenssl: 'See https://github.com/homebridge-plugins/homebridge-govee/wiki/OpenSSL for more info about installing OpenSSL',

package/package.json

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