@homebridge-plugins/homebridge-govee 11.24.0 → 11.25.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to `@homebridge-plugins/homebridge-govee` will be documented in this file.
 
+## v11.25.0 (2026-07-12)
+
+### Changes
+
+- fix: parse water leak detection from the openapi response (#1276) (#1312) (@dev-d)
+- feat: add support for the Edison Bulb H14C0 (#1302) (@starrlord)
+- feat: add support for the H1270 ceiling light with independent zone control (#1306) (@x86txt)
+- fix: H7111 HomeKit rotation speed percentage mapping (#1310) (@u2jrmw)
+- fix: clamp H7123 air quality to HomeKit range (#1261)
+- fix: hide matter devices when ignoreMatter is enabled (#1287)
+- feat: add H70C5 to the matter exclusion list (#1300)
+- fix: clearer error when Govee login returns no token
+- chore: update actions/checkout to v7
+- chore: dependency updates
+- fix: show temperature on the HomeKit tile for sensors
+- feat: add support for new light models
+- chore: allow install scripts for native BLE/USB dependencies
+
 ## v11.24.0 (2026-05-31)
 
 ### Changes

package/eslint.config.js

@@ -35,7 +35,6 @@ export default antfu(
       'style/brace-style': ['error', '1tbs', { allowSingleLine: true }],
       'style/quote-props': ['error', 'consistent-as-needed'],
       'test/no-only-tests': 'error',
-      'unicorn/no-useless-spread': 'error',
       'unused-imports/no-unused-vars': ['error', { caughtErrors: 'none' }],
     },
     typescript: false,

package/lib/connection/http.js

@@ -59,7 +59,7 @@ export default class {
 
       // Check to see we got a response
       if (!res.data) {
-        throw new Error(platformLang.noToken)
+        throw new Error(`${platformLang.noToken} (HTTP ${res.status})`)
       }
 
       // Handle 2FA requirement (status 454)
@@ -104,7 +104,7 @@ export default class {
             return await this.login()
           }
         }
-        throw new Error(res.data.message || platformLang.noToken)
+        throw new Error(res.data.message || `${platformLang.noToken} (HTTP ${res.status})`)
       }
 
       // Make the token available in other functions

package/lib/connection/openapi.js

@@ -92,6 +92,8 @@ function getCapabilitiesFromPayload(data) {
 function getCapabilityValue(capability) {
   if (capability?.state && Object.hasOwn(capability.state, 'value')) {
     return capability.state.value
+  } else if (capability?.state && Array.isArray(capability.state)) {
+    return capability.state[0].value
   }
   return capability?.value
 }
@@ -560,6 +562,9 @@ export default class {
           message.capabilities.forEach((capability) => {
             const value = getCapabilityValue(capability)
             switch (capability?.instance) {
+              case 'bodyAppearedEvent':
+                normalized.leakDetected = !(Number(value) - 1)
+                break
               case 'online':
                 normalized.online = !!value
                 break

package/lib/device/fan-H7111.js

@@ -118,7 +118,7 @@ export default class {
     this.service
       .getCharacteristic(this.hapChar.RotationSpeed)
       .setProps({
-        maxValue: this.autoSpeed,
+        maxValue: 100,
         minStep: 1,
         minValue: 0,
         unit: 'unitless',
@@ -176,6 +176,13 @@ export default class {
         return
       }
 
+      // HomeKit sends percentages
+      if (value >= 100) {
+        value = this.autoSpeed
+      } else if (value > 8) {
+        value = Math.max(1, Math.min(8, Math.round(value * 8 / 100)))
+      }
+
       // Don't continue if the new value is the same as before
       if (this.cacheSpeed === value) {
         return
@@ -258,10 +265,14 @@ export default class {
       } else {
         newSpeed = params.workMode.modeValue
       }
-      if (Number.isFinite(newSpeed) && newSpeed >= 1 && newSpeed <= this.autoSpeed && this.cacheSpeed !== newSpeed) {
-        this.cacheSpeed = newSpeed
-        this.service.updateCharacteristic(this.hapChar.RotationSpeed, this.cacheSpeed)
-        this.accessory.log(`${platformLang.curSpeed} [${this.cacheSpeed}]`)
+      if (Number.isFinite(newSpeed) && newSpeed >= 1 && newSpeed <= this.autoSpeed) {
+        const hkSpeed = newSpeed === this.autoSpeed ? 100 : Math.round((newSpeed / 8) * 100)
+
+        if (this.cacheSpeed !== hkSpeed) {
+          this.cacheSpeed = hkSpeed
+          this.service.updateCharacteristic(this.hapChar.RotationSpeed, hkSpeed)
+          this.accessory.log(`${platformLang.curSpeed} [${newSpeed} -> ${hkSpeed}%]`)
+        }
       }
     }
 
@@ -276,7 +287,7 @@ export default class {
     }
 
     // Check for some other scene/mode change
-    (params.commands || []).forEach((command) => {
+    ;(params.commands || []).forEach((command) => {
       const hexString = base64ToHex(command)
       const hexParts = hexToTwoItems(hexString)
 
@@ -298,19 +309,21 @@ export default class {
         case '0501': {
           // Fan speed
           const newSpeed = Number.parseInt(getTwoItemPosition(hexParts, 4), 16)
-          if (newSpeed >= 1 && newSpeed <= 8 && this.cacheSpeed !== newSpeed) {
-            this.cacheSpeed = newSpeed
-            this.service.updateCharacteristic(this.hapChar.RotationSpeed, this.cacheSpeed)
-            this.accessory.log(`${platformLang.curSpeed} [${this.cacheSpeed}]`)
+          if (newSpeed >= 1 && newSpeed <= 8) {
+            const hkSpeed = Math.round((newSpeed / 8) * 100)
+
+            this.cacheSpeed = hkSpeed
+            this.service.updateCharacteristic(this.hapChar.RotationSpeed, hkSpeed)
+            this.accessory.log(`${platformLang.curSpeed} [${newSpeed} -> ${hkSpeed}%]`)
           }
           break
         }
         case '0500': {
           // Mode change (auto = 0x03)
           if (getTwoItemPosition(hexParts, 4) === '03' && this.cacheSpeed !== this.autoSpeed) {
-            this.cacheSpeed = this.autoSpeed
-            this.service.updateCharacteristic(this.hapChar.RotationSpeed, this.cacheSpeed)
-            this.accessory.log(`${platformLang.curSpeed} [auto]`)
+            this.cacheSpeed = 100
+            this.service.updateCharacteristic(this.hapChar.RotationSpeed, 100)
+            this.accessory.log(`${platformLang.curSpeed} [auto -> 100%]`)
           }
           break
         }

package/lib/device/light.js

@@ -198,6 +198,33 @@ export default class {
       this.accessory.context.adaptiveLighting = true
     }
 
+    // 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.
+    this.zoneServices = {}
+    this.zoneCache = {}
+    const zoneToggleDefs = [
+      { instance: 'mainLightToggle', name: 'Main Light' },
+      { instance: 'backgroundLightToggle', name: 'Background Light' },
+    ]
+    const openApiCaps = accessory.context.openApiCapabilities || {}
+    zoneToggleDefs.forEach(({ instance, name }) => {
+      const existingService = this.accessory.getService(name)
+      if (accessory.context.useOpenApiControl && openApiCaps[instance]) {
+        const service = existingService
+          || this.accessory.addService(this.hapServ.Switch, name, instance)
+        service
+          .getCharacteristic(this.hapChar.On)
+          .onSet(async value => this.internalZoneUpdate(instance, 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
+        this.accessory.removeService(existingService)
+      }
+    })
+
     // Output the customised options to the log
     const useAwsControl = accessory.context.useAwsControl ? 'enabled' : 'disabled'
     const useBleControl = accessory.context.useBleControl ? 'enabled' : 'disabled'
@@ -249,6 +276,43 @@ export default class {
     }
   }
 
+  async internalZoneUpdate(instance, name, value) {
+    const service = this.zoneServices[instance]
+    try {
+      const newValue = value ? 1 : 0
+
+      // Don't continue if the new value is the same as before
+      if (this.zoneCache[instance] === newValue) {
+        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,
+        },
+      })
+
+      // Cache the new state and log
+      this.zoneCache[instance] = newValue
+      this.accessory.log(`[${name}] ${platformLang.curState} [${value ? 'on' : 'off'}]`)
+    } catch (err) {
+      // Catch any errors during the process
+      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.On, this.zoneCache[instance] === 1)
+        }
+      }, 2000)
+      throw new this.hapErr(-70402)
+    }
+  }
+
   async internalBrightnessUpdate(value) {
     try {
       // This acts like a debounce function when endlessly sliding the brightness scale
@@ -613,5 +677,19 @@ export default class {
         }
       }
     }
+
+    // Update any independently-controllable light zones (e.g. main/background)
+    if (params.toggles) {
+      Object.entries(this.zoneServices).forEach(([instance, service]) => {
+        if (hasProperty(params.toggles, instance)) {
+          const newValue = params.toggles[instance] ? 1 : 0
+          if (this.zoneCache[instance] !== newValue) {
+            this.zoneCache[instance] = newValue
+            service.updateCharacteristic(this.hapChar.On, newValue === 1)
+            this.accessory.log(`[${service.displayName}] ${platformLang.curState} [${newValue === 1 ? 'on' : 'off'}]`)
+          }
+        }
+      })
+    }
   }
 }

package/lib/device/purifier-H7123.js

@@ -74,10 +74,11 @@ export default class {
     }
 
     this.airValue2Label = {
+      0: 'unknown',
       1: 'excellent',
       2: 'good',
       3: 'moderate',
-      4: 'poor',
+      5: 'poor',
     }
 
     // Add the purifier service if it doesn't already exist
@@ -469,13 +470,19 @@ export default class {
         }
         case 'aa19': {
           // Check air quality reading (i.e. 1=green, 2=blue, 3=yellow, 4=red)
-          // Cache will be in {1, 2, 3, 5} which relates to Govee {1, 2, 3, 4}
+          // Govee reports 1-4 (excellent→poor); HomeKit AirQuality accepts 0-5.
+          // Map Govee's 'poor' (and any higher/unexpected reading) to HomeKit's
+          // Poor (5), and treat anything invalid as Unknown (0), so HomeKit is
+          // never sent an out-of-range value (#1261).
           let newQual = Number.parseInt(getTwoItemPosition(hexParts, 5), 16)
-          if (newQual === 4) {
+          if (!Number.isInteger(newQual) || newQual < 1) {
+            newQual = 0
+          } else if (newQual >= 4) {
             newQual = 5
           }
 
           if (newQual !== this.cacheAir) {
+            this.cacheAir = newQual
             this.airService.updateCharacteristic(this.hapChar.AirQuality, newQual)
             this.accessory.log(`${platformLang.curAirQual} [${this.airValue2Label[newQual]}]`)
           }

package/lib/device/sensor-monitor.js

@@ -29,6 +29,8 @@ export default class {
     // Add the temperature service if it doesn't already exist
     this.tempService = this.accessory.getService(this.hapServ.TemperatureSensor)
       || this.accessory.addService(this.hapServ.TemperatureSensor)
+    // Mark it as the primary service so the HomeKit tile shows the temperature
+    this.tempService.setPrimaryService(true)
     this.cacheTemp = this.tempService.getCharacteristic(this.hapChar.CurrentTemperature).value
     this.updateCache()
 

package/lib/device/sensor-thermo.js

@@ -33,6 +33,8 @@ export default class {
     // Add the temperature service if it doesn't already exist
     this.tempService = this.accessory.getService(this.hapServ.TemperatureSensor)
       || this.accessory.addService(this.hapServ.TemperatureSensor)
+    // Mark it as the primary service so the HomeKit tile shows the temperature
+    this.tempService.setPrimaryService(true)
     this.cacheTemp = this.tempService.getCharacteristic(this.hapChar.CurrentTemperature).value
 
     // Add the battery service if it doesn't already exist

package/lib/platform.js

@@ -718,12 +718,16 @@ export default class {
 
       // Check for redundant Homebridge accessories
       devicesInHB.forEach((accessory) => {
-        // If the accessory doesn't exist in Govee then remove it
+        // If the accessory doesn't exist in Govee then remove it. Also remove it
+        // if it is now being ignored, or if it is a matter model and the user has
+        // enabled ignoreMatter (otherwise the cached accessory lingers even though
+        // the device is skipped during setup) (#1287).
         if (
           (!httpDevices.some(el => el.device === accessory.context.gvDeviceId)
             && !lanDevices.some(el => el.device === accessory.context.gvDeviceId)
             && !openApiDevices.some(el => el.device === accessory.context.gvDeviceId))
           || this.ignoredDevices.includes(accessory.context.gvDeviceId)
+          || (this.config.ignoreMatter && platformConsts.matterModels.includes(accessory.context.gvModel))
         ) {
           this.removeAccessory(accessory)
         }

package/lib/utils/constants.js

@@ -128,7 +128,9 @@ export default {
 
   models: {
     rgb: [
+      'H1270', // Ceiling Light Ultra
       'H1401',
+      'H14C0', // https://github.com/homebridge-plugins/homebridge-govee/issues/1301
       'H1630',
       'H16B0', // https://github.com/homebridge-plugins/homebridge-govee/issues/1278
       'H16C0', // https://github.com/homebridge-plugins/homebridge-govee/issues/1286
@@ -391,6 +393,7 @@ export default {
       'H7024',
       'H7025',
       'H7026',
+      'H7027', // https://github.com/homebridge-plugins/homebridge-govee/issues/1305
       'H7028',
       'H7029',
       'H702A',
@@ -406,6 +409,7 @@ export default {
       'H703B',
       'H7041',
       'H7042',
+      'H7046', // https://github.com/homebridge-plugins/homebridge-govee/issues/1297
       'H7050',
       'H7051',
       'H7052',
@@ -469,6 +473,7 @@ export default {
       'H801C',
       'H8022',
       'H8025',
+      'H802A', // https://github.com/homebridge-plugins/homebridge-govee/issues/1295
       'H805A',
       'H805B',
       'H805C',
@@ -558,6 +563,7 @@ export default {
 
   matterModels: [
     'H1401',
+    'H14C0',
     'H3200',
     'H5085',
     'H600B',
@@ -590,6 +596,7 @@ export default {
     'H7075',
     'H7094',
     'H70C4',
+    'H70C5',
     'H8015',
   ],
 

package/lib/utils/lang-en.js

@@ -113,7 +113,7 @@ export default {
   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',
-  noToken: 'no data received from Govee server whilst obtaining token',
+  noToken: 'could not obtain an account token from Govee - the account may need attention in the Govee Home app (e.g. an email verification code or accepting updated terms), or it may be served by a region this plugin does not support. If you only use Bluetooth or LAN control then this cloud login is not required',
   twoFARequired: '2FA verification required - a code has been sent to your email, please add it to the "code" field in your plugin config and restart Homebridge',
   twoFACodeInvalid: '2FA verification code was provided but login still failed - please check the code is correct and has not expired',
   noTokenExists: 'no account token has been retrieved',

package/lib/utils/response-parser.js

@@ -77,6 +77,11 @@ export function parseDeviceUpdate(params, context) {
   // LEAK DETECTED
   if (hasProperty(params, 'leakDetected')) {
     data.leakDetected = params.leakDetected
+  } else if (params?.state?.leakDetected) {
+    data.leakDetected = params.state.leakDetected
+  }
+  if (params?.state && hasProperty(params.state, 'online')) {
+    data.online = params.state.online
   }
 
   // CURRENT TEMPERATURE

package/package.json

@@ -2,7 +2,7 @@
   "name": "@homebridge-plugins/homebridge-govee",
   "alias": "Govee",
   "type": "module",
-  "version": "11.24.0",
+  "version": "11.25.0",
   "description": "Homebridge plugin to integrate Govee devices into HomeKit.",
   "author": {
     "name": "bwp91",
@@ -56,21 +56,27 @@
     "postinstall": "patch-package"
   },
   "dependencies": {
-    "@homebridge/plugin-ui-utils": "^2.2.4",
+    "@homebridge/plugin-ui-utils": "^2.2.5",
     "aws-iot-device-sdk": "^2.2.16",
-    "axios": "^1.16.1",
-    "mqtt": "^5.12.1",
+    "axios": "^1.18.1",
+    "mqtt": "^5.15.2",
     "node-persist": "^4.0.4",
     "node-rsa": "^2.0.0",
-    "p-queue": "^9.3.0",
+    "p-queue": "^9.3.1",
     "patch-package": "^8.0.1",
     "pem": "^1.14.8"
   },
   "optionalDependencies": {
     "@stoprocent/bluetooth-hci-socket": "^2.2.6",
-    "@stoprocent/noble": "^2.5.3"
+    "@stoprocent/noble": "^2.5.5"
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^9.0.0"
+    "@antfu/eslint-config": "^9.1.0"
+  },
+  "allowScripts": {
+    "@stoprocent/bluetooth-hci-socket@2.2.6": true,
+    "@stoprocent/noble@2.5.5": true,
+    "usb@2.18.0": true,
+    "@serialport/bindings-cpp@12.0.1": true
   }
 }