@homebridge-plugins/homebridge-govee 11.32.2-beta.1 → 11.32.2-beta.3

package/CHANGELOG.md

@@ -8,6 +8,8 @@ All notable changes to `@homebridge-plugins/homebridge-govee` will be documented
 
 - fix: implement the H7107's oscillation toggle, which threw a not-implemented error when tapped (#1334)
 - fix: also send the H7107's oscillation command as the multiSync frame the fan itself uses, since the first shape only turned it off sometimes (#1334)
+- fix: send the H7107's oscillation-off command without the swing-range bytes, matching the zero-tailed frame the fan echoes back (#1334)
+- feat: add support for the H8121 and H8122 ice makers, with ice size derived from the govee app (pending owner confirmation)
 
 ## v11.32.1 (2026-08-02)
 

package/lib/device/fan-H7107.js

@@ -210,12 +210,15 @@ export default class {
         return
       }
 
-      // The AWS code mirrors the device's own `aa1d..` oscillation report,
-      // carrying over the extra bytes from the last report seen (#1334).
-      // Mirroring a status code is not guaranteed on every model, so the
-      // documented OpenAPI oscillation toggle is also sent when the device
-      // advertises it
-      const tailBytes = this.cacheSwingCode
+      // The AWS code mirrors the device's own `aa1d..` oscillation report.
+      // Turning ON carries over the swing-range bytes from the last report
+      // seen, which hardware-confirmed works. Turning OFF must NOT carry
+      // them: the fan answered a parameterised off command by echoing back a
+      // zero-tailed `331d00..` frame while continuing to oscillate — its own
+      // way of showing the shape it expects (#1334). Mirroring a status code
+      // is not guaranteed on every model, so the documented OpenAPI
+      // oscillation toggle is also sent when the device advertises it
+      const tailBytes = value && this.cacheSwingCode
         ? this.cacheSwingCode.slice(6, 14).match(/.{1,2}/g).map(byte => Number.parseInt(byte, 16))
         : []
       await this.platform.sendDeviceUpdate(this.accessory, {

package/lib/device/ice-maker-H8121.js

@@ -0,0 +1,222 @@
+import { base64ToHex, getTwoItemPosition, hexToTwoItems, parseError } from '../utils/functions.js'
+import platformLang from '../utils/lang-en.js'
+
+export default class {
+  constructor(platform, accessory) {
+    // Set up variables from the platform
+    this.hapChar = platform.api.hap.Characteristic
+    this.hapErr = platform.api.hap.HapStatusError
+    this.hapServ = platform.api.hap.Service
+    this.platform = platform
+
+    // Set up variables from the accessory
+    this.accessory = accessory
+
+    // Ice size codes: small=1, medium=2, large=3, matching the OpenAPI workMode
+    // values. Unlike the H8120, the H8121's BLE size byte runs in the SAME
+    // direction as workMode (small=0x05 01 .. large=0x05 03) - taken from the
+    // app's ModeActionParserH8121, so the two paths agree here.
+    this.sizeCodes = {
+      1: 'MwUBAAAAAAAAAAAAAAAAAAAAADc=', // small  -> 33 05 01
+      2: 'MwUCAAAAAAAAAAAAAAAAAAAAADQ=', // medium -> 33 05 02
+      3: 'MwUDAAAAAAAAAAAAAAAAAAAAADU=', // large  -> 33 05 03
+    }
+
+    this.sizeLabels = {
+      1: 'small',
+      2: 'medium',
+      3: 'large',
+    }
+
+    // Remove old switch service if migrating
+    if (this.accessory.getService(this.hapServ.Switch)) {
+      this.accessory.removeService(this.accessory.getService(this.hapServ.Switch))
+    }
+
+    // Add the fan service for ice size control
+    this.service = this.accessory.getService(this.hapServ.Fanv2)
+      || this.accessory.addService(this.hapServ.Fanv2)
+
+    // Add the set handler to the on/off characteristic
+    this.service.getCharacteristic(this.hapChar.Active).onSet(async (value) => {
+      await this.internalStateUpdate(value)
+    })
+    this.cacheState = this.service.getCharacteristic(this.hapChar.Active).value === 1 ? 'on' : 'off'
+
+    // Add the set handler to the rotation speed characteristic (ice size)
+    this.service
+      .getCharacteristic(this.hapChar.RotationSpeed)
+      .setProps({
+        maxValue: 3,
+        minStep: 1,
+        minValue: 0,
+        unit: 'unitless',
+      })
+      .onSet(async value => this.internalSizeUpdate(value))
+    this.cacheSize = this.service.getCharacteristic(this.hapChar.RotationSpeed).value || 2
+
+    // Keep the characteristic in step with the cache. Without this an accessory
+    // that has never had a size set reports Active=1 with RotationSpeed=0, which
+    // is contradictory and which the Home app renders as "0".
+    if (this.service.getCharacteristic(this.hapChar.RotationSpeed).value !== this.cacheSize) {
+      this.service.updateCharacteristic(this.hapChar.RotationSpeed, this.cacheSize)
+    }
+
+    // Output the customised options to the log
+    const opts = JSON.stringify({})
+    platform.log('[%s] %s %s.', accessory.displayName, platformLang.devInitOpts, opts)
+  }
+
+  async internalStateUpdate(value) {
+    try {
+      const newState = value ? 'on' : 'off'
+
+      // Don't continue if the new value is the same as before
+      if (newState === this.cacheState) {
+        return
+      }
+
+      if (value) {
+        // Turn on with current cached ice size
+        await this.platform.sendDeviceUpdate(this.accessory, {
+          cmd: 'ptReal',
+          value: this.sizeCodes[this.cacheSize],
+          openApi: this.accessory.context.openApiCapabilities?.workMode
+            ? { instance: 'workMode', capabilityType: 'devices.capabilities.work_mode', value: { workMode: this.cacheSize, modeValue: 0 } }
+            : undefined,
+        })
+      } else {
+        // Turn off. The OpenAPI workMode=0 path is authoritative; the BLE frame
+        // mirrors the H8120 ice-maker-off command (33 19 00) as a best effort
+        // and is pending confirmation from an H8121 owner.
+        await this.platform.sendDeviceUpdate(this.accessory, {
+          cmd: 'ptReal',
+          value: 'MxkAAAAAAAAAAAAAAAAAAAAAACo=',
+          openApi: this.accessory.context.openApiCapabilities?.workMode
+            ? { instance: 'workMode', capabilityType: 'devices.capabilities.work_mode', value: { workMode: 0, modeValue: 0 } }
+            : undefined,
+        })
+      }
+
+      // Cache the new state and log if appropriate
+      if (this.cacheState !== newState) {
+        this.cacheState = newState
+        this.accessory.log(`${platformLang.curState} [${this.cacheState}]`)
+      }
+    } catch (err) {
+      // Catch any errors during the process
+      this.accessory.logWarn(`${platformLang.devNotUpdated} ${parseError(err)}`)
+
+      // Throw a 'no response' error and set a timeout to revert this after 2 seconds
+      setTimeout(() => {
+        this.service.updateCharacteristic(this.hapChar.Active, this.cacheState === 'on' ? 1 : 0)
+      }, 2000)
+      throw new this.hapErr(-70402)
+    }
+  }
+
+  async internalSizeUpdate(value) {
+    try {
+      // 0 is not a valid ice size. Put the slider back, otherwise HomeKit keeps 0
+      // while the device carries on at cacheSize - and that 0 is what gets written
+      // to the accessory cache, so it returns on the next restart. Deferred for the
+      // same reason as the error reverts below: an immediate update would be
+      // overwritten by the value HomeKit is currently writing.
+      if (value === 0) {
+        setTimeout(() => {
+          this.service.updateCharacteristic(this.hapChar.RotationSpeed, this.cacheSize)
+        }, 1000)
+        return
+      }
+
+      // Don't continue if the new value is the same as before
+      if (value === this.cacheSize) {
+        return
+      }
+
+      await this.platform.sendDeviceUpdate(this.accessory, {
+        cmd: 'ptReal',
+        value: this.sizeCodes[value],
+        openApi: this.accessory.context.openApiCapabilities?.workMode
+          ? { instance: 'workMode', capabilityType: 'devices.capabilities.work_mode', value: { workMode: value, modeValue: 0 } }
+          : undefined,
+      })
+
+      // Cache the new state and log if appropriate
+      this.cacheSize = value
+      this.cacheState = 'on'
+      this.service.updateCharacteristic(this.hapChar.Active, 1)
+      this.accessory.log(`${platformLang.curSpeed} [${this.sizeLabels[value]}]`)
+    } catch (err) {
+      // Catch any errors during the process
+      this.accessory.logWarn(`${platformLang.devNotUpdated} ${parseError(err)}`)
+
+      // Throw a 'no response' error and set a timeout to revert this after 2 seconds
+      setTimeout(() => {
+        this.service.updateCharacteristic(this.hapChar.RotationSpeed, this.cacheSize)
+      }, 2000)
+      throw new this.hapErr(-70402)
+    }
+  }
+
+  externalUpdate(params) {
+    // Handle OpenAPI workMode
+    if (params.workMode) {
+      const mode = params.workMode.workMode
+      if (mode > 0 && mode <= 3) {
+        if (this.cacheState !== 'on') {
+          this.cacheState = 'on'
+          this.service.updateCharacteristic(this.hapChar.Active, 1)
+          this.accessory.log(`${platformLang.curState} [on]`)
+        }
+        if (this.cacheSize !== mode) {
+          this.cacheSize = mode
+          this.service.updateCharacteristic(this.hapChar.RotationSpeed, this.cacheSize)
+          this.accessory.log(`${platformLang.curSpeed} [${this.sizeLabels[this.cacheSize]}]`)
+        }
+      } else if (mode === 0) {
+        if (this.cacheState !== 'off') {
+          this.cacheState = 'off'
+          this.service.updateCharacteristic(this.hapChar.Active, 0)
+          this.accessory.log(`${platformLang.curState} [off]`)
+        }
+      }
+    }
+
+    // Check for some other scene/mode change
+    (params.commands || []).forEach((command) => {
+      const hexString = base64ToHex(command)
+      const hexParts = hexToTwoItems(hexString)
+
+      // Return now if not a device query update code
+      if (getTwoItemPosition(hexParts, 1) !== 'aa') {
+        return
+      }
+
+      const deviceFunction = `${getTwoItemPosition(hexParts, 1)}${getTwoItemPosition(hexParts, 2)}`
+
+      switch (deviceFunction) {
+        case 'aa19': {
+          // On/Off
+          const newState = getTwoItemPosition(hexParts, 3) === '01' ? 'on' : 'off'
+          if (this.cacheState !== newState) {
+            this.cacheState = newState
+            this.service.updateCharacteristic(this.hapChar.Active, this.cacheState === 'on' ? 1 : 0)
+            this.accessory.log(`${platformLang.curState} [${this.cacheState}]`)
+          }
+          break
+        }
+        case 'aa05': {
+          // Ice size report. Left undecoded for now: the OpenAPI workMode report
+          // above is the authoritative source of the current size, so decoding
+          // the BLE echo would only risk a mismatch. This case exists to stop a
+          // routine status report being logged as an unrecognised scene code.
+          break
+        }
+        default:
+          this.accessory.logWarn(`${platformLang.newScene}: [${command}] [${hexString}]`)
+          break
+      }
+    })
+  }
+}

package/lib/device/ice-maker-H8122.js

@@ -0,0 +1,222 @@
+import { base64ToHex, getTwoItemPosition, hexToTwoItems, parseError } from '../utils/functions.js'
+import platformLang from '../utils/lang-en.js'
+
+export default class {
+  constructor(platform, accessory) {
+    // Set up variables from the platform
+    this.hapChar = platform.api.hap.Characteristic
+    this.hapErr = platform.api.hap.HapStatusError
+    this.hapServ = platform.api.hap.Service
+    this.platform = platform
+
+    // Set up variables from the accessory
+    this.accessory = accessory
+
+    // Ice size codes: small=1, medium=2, large=3, matching the OpenAPI workMode
+    // values. Unlike the H8120, the H8122's BLE size byte runs in the SAME
+    // direction as workMode (small=0x05 01 .. large=0x05 03) - taken from the
+    // app's ModeActionParserH8122, so the two paths agree here.
+    this.sizeCodes = {
+      1: 'MwUBAAAAAAAAAAAAAAAAAAAAADc=', // small  -> 33 05 01
+      2: 'MwUCAAAAAAAAAAAAAAAAAAAAADQ=', // medium -> 33 05 02
+      3: 'MwUDAAAAAAAAAAAAAAAAAAAAADU=', // large  -> 33 05 03
+    }
+
+    this.sizeLabels = {
+      1: 'small',
+      2: 'medium',
+      3: 'large',
+    }
+
+    // Remove old switch service if migrating
+    if (this.accessory.getService(this.hapServ.Switch)) {
+      this.accessory.removeService(this.accessory.getService(this.hapServ.Switch))
+    }
+
+    // Add the fan service for ice size control
+    this.service = this.accessory.getService(this.hapServ.Fanv2)
+      || this.accessory.addService(this.hapServ.Fanv2)
+
+    // Add the set handler to the on/off characteristic
+    this.service.getCharacteristic(this.hapChar.Active).onSet(async (value) => {
+      await this.internalStateUpdate(value)
+    })
+    this.cacheState = this.service.getCharacteristic(this.hapChar.Active).value === 1 ? 'on' : 'off'
+
+    // Add the set handler to the rotation speed characteristic (ice size)
+    this.service
+      .getCharacteristic(this.hapChar.RotationSpeed)
+      .setProps({
+        maxValue: 3,
+        minStep: 1,
+        minValue: 0,
+        unit: 'unitless',
+      })
+      .onSet(async value => this.internalSizeUpdate(value))
+    this.cacheSize = this.service.getCharacteristic(this.hapChar.RotationSpeed).value || 2
+
+    // Keep the characteristic in step with the cache. Without this an accessory
+    // that has never had a size set reports Active=1 with RotationSpeed=0, which
+    // is contradictory and which the Home app renders as "0".
+    if (this.service.getCharacteristic(this.hapChar.RotationSpeed).value !== this.cacheSize) {
+      this.service.updateCharacteristic(this.hapChar.RotationSpeed, this.cacheSize)
+    }
+
+    // Output the customised options to the log
+    const opts = JSON.stringify({})
+    platform.log('[%s] %s %s.', accessory.displayName, platformLang.devInitOpts, opts)
+  }
+
+  async internalStateUpdate(value) {
+    try {
+      const newState = value ? 'on' : 'off'
+
+      // Don't continue if the new value is the same as before
+      if (newState === this.cacheState) {
+        return
+      }
+
+      if (value) {
+        // Turn on with current cached ice size
+        await this.platform.sendDeviceUpdate(this.accessory, {
+          cmd: 'ptReal',
+          value: this.sizeCodes[this.cacheSize],
+          openApi: this.accessory.context.openApiCapabilities?.workMode
+            ? { instance: 'workMode', capabilityType: 'devices.capabilities.work_mode', value: { workMode: this.cacheSize, modeValue: 0 } }
+            : undefined,
+        })
+      } else {
+        // Turn off. The OpenAPI workMode=0 path is authoritative; the BLE frame
+        // mirrors the H8120 ice-maker-off command (33 19 00) as a best effort
+        // and is pending confirmation from an H8122 owner.
+        await this.platform.sendDeviceUpdate(this.accessory, {
+          cmd: 'ptReal',
+          value: 'MxkAAAAAAAAAAAAAAAAAAAAAACo=',
+          openApi: this.accessory.context.openApiCapabilities?.workMode
+            ? { instance: 'workMode', capabilityType: 'devices.capabilities.work_mode', value: { workMode: 0, modeValue: 0 } }
+            : undefined,
+        })
+      }
+
+      // Cache the new state and log if appropriate
+      if (this.cacheState !== newState) {
+        this.cacheState = newState
+        this.accessory.log(`${platformLang.curState} [${this.cacheState}]`)
+      }
+    } catch (err) {
+      // Catch any errors during the process
+      this.accessory.logWarn(`${platformLang.devNotUpdated} ${parseError(err)}`)
+
+      // Throw a 'no response' error and set a timeout to revert this after 2 seconds
+      setTimeout(() => {
+        this.service.updateCharacteristic(this.hapChar.Active, this.cacheState === 'on' ? 1 : 0)
+      }, 2000)
+      throw new this.hapErr(-70402)
+    }
+  }
+
+  async internalSizeUpdate(value) {
+    try {
+      // 0 is not a valid ice size. Put the slider back, otherwise HomeKit keeps 0
+      // while the device carries on at cacheSize - and that 0 is what gets written
+      // to the accessory cache, so it returns on the next restart. Deferred for the
+      // same reason as the error reverts below: an immediate update would be
+      // overwritten by the value HomeKit is currently writing.
+      if (value === 0) {
+        setTimeout(() => {
+          this.service.updateCharacteristic(this.hapChar.RotationSpeed, this.cacheSize)
+        }, 1000)
+        return
+      }
+
+      // Don't continue if the new value is the same as before
+      if (value === this.cacheSize) {
+        return
+      }
+
+      await this.platform.sendDeviceUpdate(this.accessory, {
+        cmd: 'ptReal',
+        value: this.sizeCodes[value],
+        openApi: this.accessory.context.openApiCapabilities?.workMode
+          ? { instance: 'workMode', capabilityType: 'devices.capabilities.work_mode', value: { workMode: value, modeValue: 0 } }
+          : undefined,
+      })
+
+      // Cache the new state and log if appropriate
+      this.cacheSize = value
+      this.cacheState = 'on'
+      this.service.updateCharacteristic(this.hapChar.Active, 1)
+      this.accessory.log(`${platformLang.curSpeed} [${this.sizeLabels[value]}]`)
+    } catch (err) {
+      // Catch any errors during the process
+      this.accessory.logWarn(`${platformLang.devNotUpdated} ${parseError(err)}`)
+
+      // Throw a 'no response' error and set a timeout to revert this after 2 seconds
+      setTimeout(() => {
+        this.service.updateCharacteristic(this.hapChar.RotationSpeed, this.cacheSize)
+      }, 2000)
+      throw new this.hapErr(-70402)
+    }
+  }
+
+  externalUpdate(params) {
+    // Handle OpenAPI workMode
+    if (params.workMode) {
+      const mode = params.workMode.workMode
+      if (mode > 0 && mode <= 3) {
+        if (this.cacheState !== 'on') {
+          this.cacheState = 'on'
+          this.service.updateCharacteristic(this.hapChar.Active, 1)
+          this.accessory.log(`${platformLang.curState} [on]`)
+        }
+        if (this.cacheSize !== mode) {
+          this.cacheSize = mode
+          this.service.updateCharacteristic(this.hapChar.RotationSpeed, this.cacheSize)
+          this.accessory.log(`${platformLang.curSpeed} [${this.sizeLabels[this.cacheSize]}]`)
+        }
+      } else if (mode === 0) {
+        if (this.cacheState !== 'off') {
+          this.cacheState = 'off'
+          this.service.updateCharacteristic(this.hapChar.Active, 0)
+          this.accessory.log(`${platformLang.curState} [off]`)
+        }
+      }
+    }
+
+    // Check for some other scene/mode change
+    (params.commands || []).forEach((command) => {
+      const hexString = base64ToHex(command)
+      const hexParts = hexToTwoItems(hexString)
+
+      // Return now if not a device query update code
+      if (getTwoItemPosition(hexParts, 1) !== 'aa') {
+        return
+      }
+
+      const deviceFunction = `${getTwoItemPosition(hexParts, 1)}${getTwoItemPosition(hexParts, 2)}`
+
+      switch (deviceFunction) {
+        case 'aa19': {
+          // On/Off
+          const newState = getTwoItemPosition(hexParts, 3) === '01' ? 'on' : 'off'
+          if (this.cacheState !== newState) {
+            this.cacheState = newState
+            this.service.updateCharacteristic(this.hapChar.Active, this.cacheState === 'on' ? 1 : 0)
+            this.accessory.log(`${platformLang.curState} [${this.cacheState}]`)
+          }
+          break
+        }
+        case 'aa05': {
+          // Ice size report. Left undecoded for now: the OpenAPI workMode report
+          // above is the authoritative source of the current size, so decoding
+          // the BLE echo would only risk a mismatch. This case exists to stop a
+          // routine status report being logged as an unrecognised scene code.
+          break
+        }
+        default:
+          this.accessory.logWarn(`${platformLang.newScene}: [${command}] [${hexString}]`)
+          break
+      }
+    })
+  }
+}

package/lib/device/index.js

@@ -30,6 +30,8 @@ import deviceHumidifierH7160 from './humidifier-H7160.js'
 import deviceIceMakerH717D from './ice-maker-H717D.js'
 import deviceIceMakerH7172 from './ice-maker-H7172.js'
 import deviceIceMakerH8120 from './ice-maker-H8120.js'
+import deviceIceMakerH8121 from './ice-maker-H8121.js'
+import deviceIceMakerH8122 from './ice-maker-H8122.js'
 import deviceKettle from './kettle.js'
 import deviceLightSwitch from './light-switch.js'
 import deviceLight from './light.js'
@@ -98,6 +100,8 @@ export default {
   deviceIceMakerH7172,
   deviceIceMakerH717D,
   deviceIceMakerH8120,
+  deviceIceMakerH8121,
+  deviceIceMakerH8122,
   deviceKettle,
   deviceLight,
   deviceLightSwitch,

package/lib/utils/constants.js

@@ -555,7 +555,7 @@ export default {
     humidifier: ['H7140', 'H7141', 'H7142', 'H7143', 'H7145', 'H7147', 'H7148', 'H7149', 'H714E', 'H7160'],
     purifier: ['H7120', 'H7121', 'H7122', 'H7123', 'H7124', 'H7126', 'H7127', 'H7128', 'H7129', 'H712C'],
     diffuser: ['H7161', 'H7162'],
-    iceMaker: ['H7172', 'H717D', 'H8120'],
+    iceMaker: ['H7172', 'H717D', 'H8120', 'H8121', 'H8122'],
     sensorButton: ['H5122'],
     sensorContact: ['H5123'],
     sensorPresence: ['H5127'],

package/package.json

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