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

package/CHANGELOG.md

@@ -2,11 +2,19 @@
 
 All notable changes to `@homebridge-plugins/homebridge-govee` will be documented in this file.
 
-## v11.34.1 (Pending Release)
+## 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
+
+## v11.34.1 (2026-08-06)
 
 ### Changed
 
 - fix: log unrecognised device status at debug, not as a warning per frame (#1341, #1342)
+- chore(deps): dependency updates
 
 ## v11.34.0 (2026-08-05)
 

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/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-beta.0",
+  "version": "11.34.2-beta.0",
   "description": "Homebridge plugin to integrate Govee devices into HomeKit.",
   "author": {
     "name": "bwp91",
@@ -76,7 +76,7 @@
     "@stoprocent/noble": "^2.7.1"
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^9.2.0",
+    "@antfu/eslint-config": "^9.3.0",
     "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   },