@homebridge-plugins/homebridge-govee 11.34.2-beta.3 → 11.34.2-beta.5

package/CHANGELOG.md

@@ -12,7 +12,9 @@ All notable changes to `@homebridge-plugins/homebridge-govee` will be documented
 - fix: turn adaptive lighting off when a colour is chosen outside HomeKit
 - fix: send a colour change when only the saturation moves, on every night light
 - fix: listen for saturation on the main light too, not only hue
-  fix: accept 20-byte H5106 status frames (#1345) (@danieloleary)
+- fix: accept 20-byte H5106 status frames (#1345) (@danieloleary)
+- fix: stop rescaling the H1250's brightness, since it already counts to 100 over AWS (#1347) (@Principe1218)
+- feat: give the H1250's zones independent color and brightness (#1346) (@Principe1218)
 - fix: stop a lan scan that cannot reach the network from crashing the bridge
 - fix: apply the openapi disable and refresh settings instead of asking for them to be removed
 - fix: say once when a bluetooth reading arrives for an unknown device, not on every broadcast

package/lib/device/light.js

@@ -43,6 +43,75 @@ function readZoneFrame(commands = []) {
   return zones
 }
 
+/**
+ * The brightness and color a two-zone light reports for every one of its
+ * light segments, as `aa a5 <page>` followed by four groups of
+ * `<level> <r> <g> <b>`.
+ *
+ * Pages run from 01 and each covers four light segments, so page N describes
+ * segments (N-1)*4 upward. A light whose segment count is not a multiple of
+ * four pads the last page with zeroes, and those are skipped rather than
+ * reported as black segments that do not exist (#1333).
+ *
+ * @param {string[]} [commands] the base64 frames from the payload
+ * @returns {object} what each light segment reported, keyed by segment number
+ */
+function readLightSegmentFrames(commands = []) {
+  const lightSegments = {}
+  commands.forEach((command) => {
+    const hexParts = hexToTwoItems(base64ToHex(command))
+    if (`${getTwoItemPosition(hexParts, 1)}${getTwoItemPosition(hexParts, 2)}` !== 'aaa5') {
+      return
+    }
+    const page = Number.parseInt(getTwoItemPosition(hexParts, 3), 16)
+    for (let group = 0; group < 4; group += 1) {
+      const at = 4 + (group * 4)
+      const level = Number.parseInt(getTwoItemPosition(hexParts, at), 16)
+      const r = Number.parseInt(getTwoItemPosition(hexParts, at + 1), 16)
+      const g = Number.parseInt(getTwoItemPosition(hexParts, at + 2), 16)
+      const b = Number.parseInt(getTwoItemPosition(hexParts, at + 3), 16)
+      if (level === 0 && r === 0 && g === 0 && b === 0) {
+        continue
+      }
+      lightSegments[((page - 1) * 4) + group] = { level, r, g, b }
+    }
+  })
+  return lightSegments
+}
+
+/**
+ * The two zones a light of this kind has. Fixed, unlike which light segments
+ * each one owns, which varies by model - see `zoneLightModels` in constants.js.
+ */
+const ZONE_DEFS = [
+  { instance: 'mainLightToggle', zone: 'main', name: 'Main Light' },
+  { instance: 'backgroundLightToggle', zone: 'background', name: 'Background Light' },
+]
+
+/**
+ * Real HAP's AdaptiveLightingController adds these three characteristics to
+ * the service it attaches to. When adaptive lighting has just been switched
+ * off, only these need to go - the whole Lightbulb service used to be thrown
+ * away and rebuilt here, which does hide the icon but presents Home with what
+ * looks like a different light, and an owner can lose that light's room and
+ * its automations as a result.
+ *
+ * @param {object} service the HAP service to remove the characteristics from
+ * @param {object} hapChar the platform's Characteristic lookup
+ */
+function clearAdaptiveLightingCharacteristics(service, hapChar) {
+  [
+    'SupportedCharacteristicValueTransitionConfiguration',
+    'CharacteristicValueTransitionControl',
+    'CharacteristicValueActiveTransitionCount',
+  ].forEach((charName) => {
+    const char = hapChar[charName]
+    if (char && service.testCharacteristic(char)) {
+      service.removeCharacteristic(service.getCharacteristic(char))
+    }
+  })
+}
+
 export default class extends GoveeDevice {
   constructor(platform, accessory) {
     super(platform, accessory)
@@ -78,16 +147,7 @@ export default class extends GoveeDevice {
     // the icon but presents Home with what looks like a different light, and an
     // owner can lose that light's room and its automations as a result.
     if ((this.colourSafeMode || this.alShift === -1) && this.accessory.context.adaptiveLighting) {
-      [
-        'SupportedCharacteristicValueTransitionConfiguration',
-        'CharacteristicValueTransitionControl',
-        'CharacteristicValueActiveTransitionCount',
-      ].forEach((charName) => {
-        const char = this.hapChar[charName]
-        if (char && this.service.testCharacteristic(char)) {
-          this.service.removeCharacteristic(this.service.getCharacteristic(char))
-        }
-      })
+      clearAdaptiveLightingCharacteristics(this.service, this.hapChar)
       this.accessory.context.adaptiveLighting = false
     }
 
@@ -247,41 +307,153 @@ 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, controlled over the OpenAPI connection.
+    // exposes these as OpenAPI toggle capabilities, so add a lightbulb for each
+    // zone 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)
+    // instead - and only those models can address a zone's brightness and
+    // color, since the raw frame reaches light segments the OpenAPI toggle
+    // capabilities never could. Either way the tile itself, its state and how
+    // a failure is undone are the same (#1333)
     this.zoneServices = {}
     this.zoneCache = {}
-    this.hasRawZones = platformConsts.zoneLightModels.includes(accessory.context.gvModel)
-    const zoneToggleDefs = [
-      { instance: 'mainLightToggle', zone: 'main', name: 'Main Light' },
-      { instance: 'backgroundLightToggle', zone: 'background', name: 'Background Light' },
-    ]
+    // "light segments" to avoid any confusion with the unrelated
+    // segmented/segmentedTwo/segmentedThree/segmentedFour config options
+    // elsewhere in this file, which name a captured scene or BLE code
+    this.zoneLightSegments = platformConsts.zoneLightModels[accessory.context.gvModel]
+    this.hasRawZones = Boolean(this.zoneLightSegments)
+    this.zoneBrightCache = {}
+    this.zoneColourCache = {}
+    this.zoneMiredCache = {}
+    this.zoneKelvinCache = {}
+    this.zoneUpdateKey = {}
+    this.zoneAlControllers = {}
     const openApiCaps = accessory.context.openApiCapabilities || {}
-    zoneToggleDefs.forEach(({ instance, zone, name }) => {
-      const existingService = this.accessory.getService(name)
+    ZONE_DEFS.forEach(({ instance, zone, name }) => {
+      // A real HAP Service has no `.type` - only `.UUID`, `.subtype` and
+      // `.displayName` - so getServiceById is the correct way to ask "does this
+      // zone's lightbulb already exist", matching by type AND subtype rather
+      // than by name. Falling back to a name lookup only when that comes up
+      // empty catches a service under this name that ISN'T this lightbulb,
+      // which can only be the tile's previous Switch, since HomeKit cannot
+      // change a service's type in place
+      const existingLightbulb = this.accessory.getServiceById(this.hapServ.Lightbulb, instance)
+      let existingService = existingLightbulb || this.accessory.getService(name)
 
       // The raw frame goes over AWS, which needs Govee account credentials
-      // rather than just an API key
+      // rather than just an API key. For raw-zone models, also require this
+      // particular zone to have a measured light segment layout - a model
+      // whose config only defines one of its two zones should not offer a
+      // tile for the other one, since every raw-zone handler indexes
+      // zoneLightSegments[zone] and would throw at tap time on a real device
+      // rather than at startup
       const isControllable = this.hasRawZones
-        ? accessory.context.useAwsControl
+        ? accessory.context.useAwsControl && Boolean(this.zoneLightSegments[zone])
         : accessory.context.useOpenApiControl && openApiCaps[instance]
 
       if (isControllable) {
+        // That name-matched fallback is stale (the old Switch) whenever it
+        // isn't the lightbulb itself - clear it out before the lightbulb can
+        // take the name, otherwise the tile is stuck with On and nothing
+        // else, and no amount of adding characteristics will fix it
+        if (existingService && existingService !== existingLightbulb) {
+          this.accessory.removeService(existingService)
+          existingService = undefined
+        }
+
         const service = existingService
-          || this.accessory.addService(this.hapServ.Switch, name, instance)
+          || this.accessory.addService(this.hapServ.Lightbulb, name, instance)
         service
           .getCharacteristic(this.hapChar.On)
           .onSet(async value => this.internalZoneUpdate(instance, zone, name, value))
+
+        // Only the raw-frame models can address a zone's brightness and color.
+        // The models whose toggles work have on/off and nothing else, so giving
+        // them sliders would be a control that silently does nothing - which is
+        // the bug this whole path exists to avoid (#1333)
+        if (this.hasRawZones) {
+          // Adaptive lighting characteristics are added to a service by real
+          // HAP's AdaptiveLightingController when it attaches, not by this
+          // file, so they can only be sitting on a zone service left over from
+          // an earlier boot that had a controller here. Zones have no
+          // equivalent of `accessory.context.adaptiveLighting` above - that
+          // flag exists purely to remember, for the MAIN light, that this
+          // block already ran once so it does not repeat needlessly. A zone's
+          // controller is fully re-derived from colourSafeMode/alShift on
+          // every boot regardless (see below), so there is nothing to
+          // remember here: checking those two directly is enough to know
+          // whether this boot's controller state has changed from the last
+          if (this.colourSafeMode || this.alShift === -1) {
+            clearAdaptiveLightingCharacteristics(service, this.hapChar)
+          }
+
+          service
+            .getCharacteristic(this.hapChar.Brightness)
+            .setProps({ minStep: this.brightStep })
+            .onSet(async value => this.internalZoneBrightnessUpdate(instance, zone, name, value))
+          service
+            .getCharacteristic(this.hapChar.Hue)
+            .onSet(async value => this.internalZoneColourUpdate(instance, zone, name, value))
+          service.getCharacteristic(this.hapChar.Saturation)
+          this.zoneBrightCache[instance] = service.getCharacteristic(this.hapChar.Brightness).value
+
+          // Seed this now, not just on the first write or status report. An
+          // unseeded cache would make externalUpdate's "did this change
+          // elsewhere" check treat the very first report after every restart
+          // as an external change - switching adaptive lighting off before
+          // anything has actually changed
+          const seedHue = service.getCharacteristic(this.hapChar.Hue).value
+          const seedSat = service.getCharacteristic(this.hapChar.Saturation).value
+          const [seedR, seedG, seedB] = hs2rgb(seedHue, seedSat)
+          this.zoneColourCache[instance] = {
+            r: seedR,
+            g: seedG,
+            b: seedB,
+            hue: seedHue,
+            sat: seedSat,
+          }
+
+          // Adaptive lighting needs Brightness and ColorTemperature on the same
+          // service, so a zone that is to have it needs its own color
+          // temperature control. The zone only takes rgb on the wire, so a
+          // temperature is converted on the way out - the same thing the
+          // bluetooth path already does for every other light
+          if (this.colourSafeMode) {
+            if (service.testCharacteristic(this.hapChar.ColorTemperature)) {
+              service.removeCharacteristic(service.getCharacteristic(this.hapChar.ColorTemperature))
+            }
+            this.zoneMiredCache[instance] = 0
+            this.zoneKelvinCache[instance] = 0
+          } else {
+            service
+              .getCharacteristic(this.hapChar.ColorTemperature)
+              .onSet(async value => this.internalZoneCTUpdate(instance, zone, name, value))
+            this.zoneMiredCache[instance] = service.getCharacteristic(this.hapChar.ColorTemperature).value
+
+            // Seeded the same way as the mired cache above, so the first real
+            // adaptive lighting tick after a restart is compared against what
+            // was actually last sent, not against nothing
+            const seedMired = this.zoneMiredCache[instance]
+            const seedKelvin = Math.round(1000000 / seedMired / 100) * 100
+            this.zoneKelvinCache[instance] = Math.min(Math.max(seedKelvin, this.minKelvin), this.maxKelvin)
+
+            // One controller per zone. The id is derived from the service, so
+            // these sit alongside the main light's rather than clashing with it
+            if (this.alShift !== -1) {
+              this.zoneAlControllers[instance] = new platform.api.hap.AdaptiveLightingController(service, {
+                customTemperatureAdjustment: this.alShift,
+              })
+              this.accessory.configureController(this.zoneAlControllers[instance])
+            }
+          }
+        }
+
         this.zoneServices[instance] = service
         this.zoneCache[instance] = service.getCharacteristic(this.hapChar.On).value ? 1 : 0
       } else if (existingService) {
         // Capability no longer available (or the connection it needs is off) so
-        // remove the switch
+        // remove the tile
         this.accessory.removeService(existingService)
       }
     })
@@ -392,6 +564,193 @@ export default class extends GoveeDevice {
     }
   }
 
+  /**
+   * Sets one zone's brightness in response to a HomeKit write.
+   *
+   * @param {string} instance the capability instance, eg 'mainLightToggle'
+   * @param {string} zone the key into `this.zoneLightSegments`, eg 'main'
+   * @param {string} name the tile's display name, for logging
+   * @param {number} value 0-100
+   */
+  async internalZoneBrightnessUpdate(instance, zone, name, value) {
+    const service = this.zoneServices[instance]
+    try {
+      // HomeKit writes once per position of the slider, so without this a single
+      // drag becomes a burst of frames. Same debounce the main light uses
+      const updateKey = generateRandomString(5)
+      this.zoneUpdateKey[instance] = updateKey
+      await sleep(350)
+      if (updateKey !== this.zoneUpdateKey[instance]) {
+        return
+      }
+
+      // Don't continue if the new value is the same as before
+      if (this.zoneBrightCache[instance] === value) {
+        return
+      }
+
+      await this.platform.sendDeviceUpdate(this.accessory, {
+        cmd: 'zoneBrightness',
+        lightSegments: this.zoneLightSegments[zone],
+        value,
+      })
+
+      this.zoneBrightCache[instance] = value
+      this.accessory.log(`[${name}] ${platformLang.curBright} [${value}%]`)
+    } catch (err) {
+      this.accessory.logWarn(`[${name}] ${platformLang.devNotUpdated} ${parseError(err)}`)
+
+      // Throw a 'no response' error and revert this after 2 seconds
+      setTimeout(() => {
+        if (service) {
+          service.updateCharacteristic(this.hapChar.Brightness, this.zoneBrightCache[instance])
+        }
+      }, 2000)
+      throw new this.hapErr(-70402)
+    }
+  }
+
+  /**
+   * Sets one zone's color in response to a HomeKit hue write. Saturation is
+   * read from the tile itself, since HomeKit sends hue and saturation as
+   * separate writes.
+   *
+   * @param {string} instance the capability instance, eg 'mainLightToggle'
+   * @param {string} zone the key into `this.zoneLightSegments`, eg 'main'
+   * @param {string} name the tile's display name, for logging
+   * @param {number} value hue, 0-360
+   */
+  async internalZoneColourUpdate(instance, zone, name, value) {
+    const service = this.zoneServices[instance]
+    try {
+      // Same debounce as the main light's colour wheel
+      const updateKey = generateRandomString(5)
+      this.zoneUpdateKey[instance] = updateKey
+      await sleep(300)
+      if (updateKey !== this.zoneUpdateKey[instance]) {
+        return
+      }
+
+      // Dropping the cct to its lowest mimics native adaptive lighting, and
+      // HAP asks for it on any service carrying both hue/saturation and color
+      // temperature. The main light does the same
+      if (!this.colourSafeMode) {
+        service.updateCharacteristic(this.hapChar.ColorTemperature, 140)
+      }
+
+      // Hue and saturation arrive as separate writes, so the other half comes
+      // from this tile's own characteristic - not the main light's
+      const currentSat = service.getCharacteristic(this.hapChar.Saturation).value
+      const [r, g, b] = hs2rgb(value, currentSat)
+
+      // Don't continue if the new value is the same as before
+      const cached = this.zoneColourCache[instance]
+      if (cached && cached.r === r && cached.g === g && cached.b === b) {
+        return
+      }
+
+      await this.platform.sendDeviceUpdate(this.accessory, {
+        cmd: 'zoneColour',
+        lightSegments: this.zoneLightSegments[zone],
+        value: { r, g, b },
+      })
+
+      this.zoneColourCache[instance] = {
+        r,
+        g,
+        b,
+        hue: value,
+        sat: currentSat,
+      }
+      this.accessory.log(`[${name}] ${platformLang.curColour} [rgb ${r} ${g} ${b}]`)
+    } catch (err) {
+      this.accessory.logWarn(`[${name}] ${platformLang.devNotUpdated} ${parseError(err)}`)
+
+      // Throw a 'no response' error and revert this after 2 seconds
+      setTimeout(() => {
+        const previous = this.zoneColourCache[instance]
+        if (service && previous) {
+          service.updateCharacteristic(this.hapChar.Hue, previous.hue)
+          service.updateCharacteristic(this.hapChar.Saturation, previous.sat)
+        }
+      }, 2000)
+      throw new this.hapErr(-70402)
+    }
+  }
+
+  /**
+   * Sets one zone's color temperature. Adaptive lighting calls this on its own
+   * schedule; a HomeKit write reaches it the same way.
+   *
+   * @param {string} instance the capability instance, eg 'mainLightToggle'
+   * @param {string} zone the key into `this.zoneLightSegments`, eg 'main'
+   * @param {string} name the tile's display name, for logging
+   * @param {number} value mireds
+   */
+  async internalZoneCTUpdate(instance, zone, name, value) {
+    const service = this.zoneServices[instance]
+    try {
+      // Adaptive lighting writes here every sixty seconds, so this is debounced
+      // exactly as the main light's color temperature is
+      const updateKey = generateRandomString(5)
+      this.zoneUpdateKey[instance] = updateKey
+      await sleep(300)
+      if (updateKey !== this.zoneUpdateKey[instance]) {
+        return
+      }
+
+      // Convert mired to kelvin to nearest 100, the same rounding the main
+      // light uses. Adaptive lighting nudges mired by fractional amounts far
+      // more often than the rounded kelvin actually changes, so comparing the
+      // rounded value below - not raw mired - is what keeps a real command
+      // from going out on almost every adaptive lighting tick
+      const kelvin = Math.round(1000000 / value / 100) * 100
+      const k = Math.min(Math.max(kelvin, this.minKelvin), this.maxKelvin)
+
+      // Don't continue if the rounded kelvin is the same as before
+      if (this.zoneKelvinCache[instance] === k) {
+        return
+      }
+
+      // Updating hue/sat to the corresponding values mimics native adaptive
+      // lighting - the main light's own color temperature handler does the same
+      const [hue, sat] = m2hs(value)
+      service.updateCharacteristic(this.hapChar.Hue, hue)
+      service.updateCharacteristic(this.hapChar.Saturation, sat)
+
+      // The zone frame carries rgb and nothing else, so the temperature is
+      // converted here - the same conversion the bluetooth path uses
+      const [r, g, b] = k2rgb(k)
+
+      await this.platform.sendDeviceUpdate(this.accessory, {
+        cmd: 'zoneColour',
+        lightSegments: this.zoneLightSegments[zone],
+        value: { r, g, b },
+      })
+
+      this.zoneKelvinCache[instance] = k
+      this.zoneMiredCache[instance] = value
+      this.zoneColourCache[instance] = {
+        r,
+        g,
+        b,
+        hue,
+        sat,
+      }
+      this.accessory.log(`[${name}] ${platformLang.curColour} [${k}K / ${value}M]`)
+    } catch (err) {
+      this.accessory.logWarn(`[${name}] ${platformLang.devNotUpdated} ${parseError(err)}`)
+
+      // Throw a 'no response' error and revert this after 2 seconds
+      setTimeout(() => {
+        if (service) {
+          service.updateCharacteristic(this.hapChar.ColorTemperature, this.zoneMiredCache[instance])
+        }
+      }, 2000)
+      throw new this.hapErr(-70402)
+    }
+  }
+
   async internalBrightnessUpdate(value) {
     try {
       // This acts like a debounce function when endlessly sliding the brightness scale
@@ -762,5 +1121,68 @@ export default class extends GoveeDevice {
         }
       })
     }
+
+    // The same status carries every light segment's brightness and color, so a
+    // change made in the Govee app, on a remote or at the wall reaches the
+    // zone tiles too - not just our own writes echoing back
+    if (this.hasRawZones) {
+      const lightSegments = readLightSegmentFrames(params.commands)
+      ZONE_DEFS.forEach(({ instance, zone, name }) => {
+        const service = this.zoneServices[instance]
+        if (!service) {
+          return
+        }
+
+        // Every light segment in a zone normally holds the same value. Where
+        // they differ - someone has colored segments individually in the
+        // Govee app - the first is what the tile shows, because HomeKit has
+        // one value per characteristic and this zone has sixteen segments
+        const first = this.zoneLightSegments[zone].find(index => lightSegments[index])
+        const reported = first === undefined ? undefined : lightSegments[first]
+        if (!reported) {
+          return
+        }
+
+        if (this.zoneBrightCache[instance] !== reported.level) {
+          this.zoneBrightCache[instance] = reported.level
+          service.updateCharacteristic(this.hapChar.Brightness, reported.level)
+          this.accessory.log(`[${name}] ${platformLang.curBright} [${reported.level}%]`)
+        }
+
+        const cached = this.zoneColourCache[instance]
+        if (!cached || cached.r !== reported.r || cached.g !== reported.g || cached.b !== reported.b) {
+          const [hue, sat] = rgb2hs(reported.r, reported.g, reported.b)
+
+          // A zone repeating our own command back can drift by a unit or two
+          // through the conversions on the way out and back. Beyond that
+          // drift, somebody else set this color
+          const changedElsewhere = !cached
+            || Math.abs(reported.r - cached.r) > 5
+            || Math.abs(reported.g - cached.g) > 5
+            || Math.abs(reported.b - cached.b) > 5
+
+          this.zoneColourCache[instance] = {
+            r: reported.r,
+            g: reported.g,
+            b: reported.b,
+            hue,
+            sat,
+          }
+          service.updateCharacteristic(this.hapChar.Hue, hue)
+          service.updateCharacteristic(this.hapChar.Saturation, sat)
+          this.accessory.log(`[${name}] ${platformLang.curColour} [rgb ${reported.r} ${reported.g} ${reported.b}]`)
+
+          // Somebody chose this color in the Govee app, on a remote or at the
+          // wall. Homebridge catches HomeKit's own writes, but nothing sees
+          // these - so this zone's adaptive lighting would carry on and move
+          // it back off that color within minutes (#1333)
+          const controller = this.zoneAlControllers[instance]
+          if (changedElsewhere && controller?.isAdaptiveLightingActive?.()) {
+            controller.disableAdaptiveLighting()
+            this.accessory.log(`[${name}] ${platformLang.alDisabled}`)
+          }
+        }
+      })
+    }
   }
 }

package/lib/utils/command-builder.js

@@ -28,6 +28,10 @@ export function buildCommand(params, context) {
       return buildOpenApiCommand(params)
     case 'zoneState':
       return buildZoneStateCommand(params)
+    case 'zoneColour':
+      return buildZoneColourCommand(params)
+    case 'zoneBrightness':
+      return buildZoneBrightnessCommand(params)
     case 'brightness':
       return buildBrightnessCommand(params, context)
     case 'color':
@@ -145,6 +149,123 @@ function buildZoneStateCommand(params) {
   }
 }
 
+/**
+ * A zone is addressed by a bitmask over the light's individually-addressable
+ * segments, three bytes wide, least significant byte first. Called "light
+ * segments" throughout, distinct from the unrelated `segmented`/`segmentedTwo`/
+ * etc. config options elsewhere in this plugin, which name a captured scene or
+ * BLE code and have nothing to do with per-segment addressing.
+ *
+ * Two bytes is what every other model in the plugin uses, and is exactly why
+ * nothing ever reached the H1250's main panel - that light has seventeen light
+ * segments and the seventeenth bit lives in the third byte (#1333).
+ *
+ * @param {number[]} lightSegments the light segment indices to address (0-23)
+ * @returns {number[]} a 3-byte mask, least significant byte first
+ */
+function lightSegmentMask(lightSegments) {
+  const mask = [0x00, 0x00, 0x00]
+  if (!lightSegments.length) {
+    throw new Error('No light segments given for a zone command')
+  }
+  lightSegments.forEach((lightSegment) => {
+    if (!Number.isInteger(lightSegment) || lightSegment < 0 || lightSegment > 23) {
+      // Past 23 the mask array silently grows a fourth byte, which shifts every
+      // byte after it and still checksums cleanly - a wrong frame the device
+      // accepts is far harder to spot than an outright failure
+      throw new Error(`Light segment [${lightSegment}] is outside the three-byte mask`)
+    }
+    mask[Math.floor(lightSegment / 8)] |= 1 << (lightSegment % 8)
+  })
+  return mask
+}
+
+/**
+ * Builds the `ptReal` frame that sets color on one or more zones of an H1250.
+ *
+ * Color pads to put the mask at bytes 12-14. Brightness puts it straight after
+ * the level, at bytes 5-7. The two layouts really do differ - assuming
+ * brightness matched color is what made every early attempt at it fail.
+ *
+ * @param {object} params the command params
+ * @param {object} params.value
+ * @param {number} params.value.r 0-255
+ * @param {number} params.value.g 0-255
+ * @param {number} params.value.b 0-255
+ * @param {number[]} params.lightSegments the light segment indices to address
+ * @returns {{ awsParams: object }} the AWS-only command params
+ */
+function buildZoneColourCommand(params) {
+  if (!params.value || !params.lightSegments) {
+    throw new Error(`Missing value or light segments for ${params.cmd}`)
+  }
+  const { r, g, b } = params.value
+  return {
+    // AWS only, for the same reason as buildZoneStateCommand
+    awsParams: {
+      cmd: 'ptReal',
+      data: {
+        command: [generateCodeFromHexValues([
+          0x33,
+          0x05,
+          0x15,
+          0x01,
+          r,
+          g,
+          b,
+          0x00,
+          0x00,
+          0x00,
+          0x00,
+          0x00,
+          ...lightSegmentMask(params.lightSegments),
+        ])],
+      },
+    },
+  }
+}
+
+/**
+ * The frame that sets a zone's brightness.
+ *
+ * Sent as-is, with no 0-254 scaling like `buildBrightnessCommand` applies for
+ * the whole-device AWS command - this is deliberate, not an oversight. The zone
+ * frame's level byte is already 0-100, the same scale HomeKit uses.
+ *
+ * @param {object} params
+ * @param {number[]} params.lightSegments the light segment indices to set
+ * @param {number} params.value 0-100, the same scale HomeKit uses
+ * @returns {{ awsParams: object }} the raw frame to send over AWS -
+ *   for the same reason as `buildZoneColourCommand`, this device does not
+ *   get a LAN path
+ */
+function buildZoneBrightnessCommand(params) {
+  if (params.value === undefined || !params.lightSegments) {
+    throw new Error(`Missing value or light segments for ${params.cmd}`)
+  }
+  if (!Number.isInteger(params.value) || params.value < 0 || params.value > 100) {
+    // Out of range the byte silently wraps - 300 becomes 44 - and the frame
+    // still checksums cleanly, so the light takes a brightness nobody asked
+    // for rather than the command failing outright
+    throw new Error(`Brightness [${params.value}] is outside 0-100 for ${params.cmd}`)
+  }
+  return {
+    awsParams: {
+      cmd: 'ptReal',
+      data: {
+        command: [generateCodeFromHexValues([
+          0x33,
+          0x05,
+          0x15,
+          0x02,
+          params.value,
+          ...lightSegmentMask(params.lightSegments),
+        ])],
+      },
+    },
+  }
+}
+
 function buildBrightnessCommand(params, context) {
   const caps = getDeviceCapabilities(context.gvModel, context.firmware)
   return {

package/lib/utils/constants.js

@@ -742,7 +742,24 @@ export default {
   //
   // 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'],
+  /**
+   * Which light segments make up each zone of a two-zone light. Called "light
+   * segments" to avoid any confusion with the unrelated `segmented`/
+   * `segmentedTwo`/`segmentedThree`/`segmentedFour` config options above,
+   * which name a captured scene or BLE code.
+   *
+   * How many light segments a light has can be read back from its own report,
+   * but which segments belong to which zone cannot - nothing in the frame says
+   * so. The H1250's split was established by changing one zone at a time and
+   * watching which segments moved, so this is configuration, and a new model
+   * should be measured rather than assumed to share the layout (#1333).
+   */
+  zoneLightModels: {
+    H1250: {
+      main: [16],
+      background: Array.from({ length: 16 }, (_, index) => index),
+    },
+  },
 
   matterModels: [
     'H1401',

package/lib/utils/device-capabilities.js

@@ -80,6 +80,12 @@ const modelOverrides = {
   H1401: { awsBrightnessNoScale: true },
   H6008: { awsBrightnessNoScale: true },
   H6022: { awsBrightnessNoScale: true },
+
+  // H1250: proven live on hardware 2026-08-08 - a HomeKit write of 100 sent
+  // val:254 and came out visibly dimmer than the Govee app's own 100%, then the
+  // AWS echo of {"brightness":100} was rescaled down to 39%, matching every
+  // step of a slider drag exactly (98->39, 69->27, 42->17, 97->38, 43->17)
+  H1250: { awsBrightnessNoScale: true },
 }
 
 /**

package/lib/utils/dispatch.js

@@ -23,12 +23,19 @@ import platformConsts from './constants.js'
  *              out still gets power rather than being left unsupported
  * - `choose`   for the few lists where the answer depends on the device or the
  *              owner's settings
- * - `awsPolling` these devices need their status asking for over AWS
+ * - `awsPolling` these devices need their status asking for over AWS. Either a
+ *   boolean for every model in the list, or a function of the same args as
+ *   `choose`, for a list where only some models need it.
  */
 const routes = [
   {
     list: 'rgb',
     choose: ({ deviceConf }) => (deviceConf.showAs === 'switch' ? 'deviceLightSwitch' : 'deviceLight'),
+    // A light segment layout means this model's zone data only ever arrives
+    // in reply to a full AWS status request - LAN never carries it. Every
+    // other light gets everything it needs from LAN polling, so only these
+    // need the extra AWS traffic
+    awsPolling: ({ device }) => Boolean(platformConsts.zoneLightModels[device.model]),
   },
   { list: 'switchSingle', choose: chooseSingleSwitch },
   {
@@ -149,11 +156,15 @@ export function resolveDeviceType(device, deviceConf = {}, cachedContext = undef
     return { skip: chosen.skip, list: route.list }
   }
 
+  const awsPolling = typeof route.awsPolling === 'function'
+    ? route.awsPolling({ device, deviceConf, cachedContext })
+    : !!route.awsPolling
+
   return {
     list: route.list,
     handlerKey: chosen.handler,
     handler: deviceTypes[chosen.handler],
-    awsPolling: !!route.awsPolling,
+    awsPolling,
     externalCategory: chosen.externalCategory,
   }
 }

package/package.json

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