@homebridge-plugins/homebridge-govee 11.32.0-beta.9 → 11.32.1

package/CHANGELOG.md

@@ -2,16 +2,53 @@
 
 All notable changes to `@homebridge-plugins/homebridge-govee` will be documented in this file.
 
-## v11.32.0 (Pending Release)
+## v11.32.1 (2026-08-02)
+
+### Changed
+
+- docs: add node 26 to the supported node versions
+- fix: read the H5106 monitor's temperature and humidity from the http device list too, so accounts whose aws channel never delivers still get readings (#1322)
+
+## v11.32.0 (2026-08-02)
 
 ### Changed
 
 - chore(github): use the shared homebridge action to deprecate past pre-releases
+- chore(github): allow the pre-release keep count to be set when running the deprecation workflow
 - feat(ui): hide or show a device in homekit from the my devices tab
 - chore(deps): dependency updates
 - style(ui): standardise the custom ui layout and sync the support tab with the readme
 - chore(deps): override help-me to v5 to clear the high brace-expansion security advisory from the aws-iot dependency chain
 - feat(ui): add a remove all devices action to the my devices tab (#1323)
+- feat: add support for the H5089 smart plug, exposing its outlet and built-in light as separate switches (#1323)
+- chore: declare the supports-hap transport keyword for the homebridge ui
+- feat: add support for the H60B3 uplighter as an rgb light (#1325)
+- feat: add support for the H5901 water timer through the govee openapi (#1324)
+- fix(fans): map rotation speed as a percentage on every fan model, so homekit stops showing speeds like 7% and the top of the slider means full power (#1326) (@cwhett)
+- chore: log what each device can do according to the govee openapi, in debug mode, to make working out new device support quicker
+- chore: decode the status codes a device reports into readable hex in debug mode, so support for new device features can be worked out from a normal log
+- feat: add the H5089 night light as a homekit light tile with on, off and brightness (#1323)
+- fix: send the H5089 night light commands as the newer ptIot type the plug listens for, instead of being silently ignored (#1323)
+- fix: also send the H5089 night light the command shape the supported govee purifiers use, since mirroring the plug's own status code was not enough on its own (#1323)
+- fix: stop sending a per-outlet value to the govee api, which rejected every press with a parameter out of range error on two-outlet plugs (#1323)
+- fix: hide the H5089 night light tile until its commands are worked out, rather than showing a control that does nothing (#1323)
+- feat: add support for the H3001 solar string lights as an rgb light (#1328)
+- fix(fans): rebuild the fan service once when it was cached under the old speed scale, so the top of the slider stops setting the slowest speed (#1326) (@cwhett)
+- fix: show the H5089 night light tile again, but refuse control commands, so it reports the real state instead of quietly ignoring taps (#1323)
+- fix(ice-makers): stop the home app showing an ice size of 0 when one has never been set (#1329) (@cwhett)
+- chore: add a test setup with tests for the shared helper functions
+- chore(github): run the build and tests in ci, on node 22, 24 and 26
+- chore: use the same lint setup across every plugin
+- chore: add a changelog:sync script to populate the pending section from the commits
+- chore(deps): refresh the lock file for the eslint config bump
+- fix(ble): size the update queue timeout from the connection stages, so a slow device still has time to send its command (#1328)
+- chore: count a repeated commit subject once when syncing the changelog
+- chore(github): check the changelog against the commits in ci
+- fix(openapi): report govee's own reason when it refuses a command, instead of the command appearing to succeed (#1324)
+- fix: report why a command failed instead of claiming no connection method was available (#1324)
+- fix(ble): use the segment-based colour command for the H617A, whose LEDs ignore the simple RGB colour commands (#1332)
+- feat: add support for the H1250 ceiling light pro as an rgb light (#1333)
+- fix: stop rescaling the H6022's aws brightness reports, which are already a percentage, so its brightness stops bouncing to a wrong value after every change
 
 ## v11.31.0 (2026-07-24)
 

package/README.md

@@ -27,7 +27,7 @@ Homebridge plugin to integrate Govee devices into HomeKit
 ### Prerequisites
 
 - To use this plugin, you will need to already have:
-  - [Node](https://nodejs.org): latest version of `v22` or `v24` - any other major version is not supported.
+  - [Node](https://nodejs.org): latest version of `v22`, `v24` or `v26` - any other major version is not supported.
   - [Homebridge](https://homebridge.io): `v1.6` or above - refer to link for more information and installation instructions.
   - For bluetooth connectivity, it may be necessary to install extra packages on your system, see [Bluetooth Control](https://github.com/homebridge-plugins/homebridge-govee/wiki/Bluetooth-Control). Bluetooth works best when using a Raspberry Pi, not been tested on Windows, and Mac devices are unsupported.
 

package/lib/connection/ble.js

@@ -3,7 +3,7 @@ import process from 'node:process'
 
 import btClient from '@stoprocent/noble'
 
-import { UUID } from '../utils/ble-protocol.js'
+import { BLE_STAGE_TIMEOUTS, UUID } from '../utils/ble-protocol.js'
 import { decodeAny } from '../utils/decode.js'
 import { base64ToHex, generateCodeFromHexValues, hexToTwoItems, sleep } from '../utils/functions.js'
 import platformLang from '../utils/lang-en.js'
@@ -15,8 +15,11 @@ process.env.NOBLE_REPORT_ALL_HCI_EVENTS = '1' // needed on Linux including Raspb
 
 const H5075_UUID = 'ec88'
 const H5101_UUID = '0001'
-const CONNECTION_TIMEOUT = 10000 // 10 seconds
-const WRITE_TIMEOUT = 5000 // 5 seconds
+
+const POWER_ON_TIMEOUT = BLE_STAGE_TIMEOUTS.powerOn
+const CONNECTION_TIMEOUT = BLE_STAGE_TIMEOUTS.connect
+const WRITE_TIMEOUT = BLE_STAGE_TIMEOUTS.write
+const SETTLE_DELAY = BLE_STAGE_TIMEOUTS.settle
 
 /*
   The necessary commands to send and functions are taken from and credit to:
@@ -169,7 +172,7 @@ export default class BLEConnection {
     }
   }
 
-  async waitForPowerOn(timeout = 5000) {
+  async waitForPowerOn(timeout = POWER_ON_TIMEOUT) {
     if (this.btState === 'poweredOn') {
       return true
     }
@@ -240,7 +243,7 @@ export default class BLEConnection {
       // Write without response then allow time for the BLE controller to transmit before disconnecting
       await this.writeWithTimeout(characteristic, finalBuffer, WRITE_TIMEOUT)
       accessory.logDebug('command sent successfully')
-      await sleep(100)
+      await sleep(SETTLE_DELAY)
     } catch (err) {
       accessory.logWarn(`BLE update failed: ${err.message}`)
       throw err

package/lib/connection/openapi.js

@@ -2,7 +2,7 @@ import axios from 'axios'
 import mqtt from 'mqtt'
 
 import { k2rgb } from '../utils/colour.js'
-import { parseError } from '../utils/functions.js'
+import { describeControlFailure, parseError } from '../utils/functions.js'
 
 const BASE_URL = 'https://openapi.api.govee.com'
 
@@ -500,7 +500,7 @@ export default class {
   async updateDevice(accessory, params) {
     const capability = this.buildCapabilityPayload(accessory, params)
 
-    await this.request({
+    const response = await this.request({
       method: 'post',
       path: '/router/api/v1/device/control',
       data: {
@@ -512,6 +512,18 @@ export default class {
         },
       },
     })
+
+    // Govee can accept the request and still refuse the command, reporting it
+    // only inside `capability.state`. Without this the plugin treated that as
+    // success and the device quietly ignored the command (#1324).
+    const refusal = describeControlFailure(response)
+    if (refusal) {
+      const error = new Error(refusal)
+      // Their wording is aimed at the user and describes the device's state, so
+      // log it on its own — a stack trace here suggests a fault in the plugin.
+      error.deviceRefusal = true
+      throw error
+    }
   }
 
   async connectMQTT() {

package/lib/device/fan-H1310.js

@@ -1,7 +1,9 @@
 import {
   base64ToHex,
+  fanSpeedToHkPercent,
   getTwoItemPosition,
   hexToTwoItems,
+  hkPercentToFanSpeed,
   parseError,
 } from '../utils/functions.js'
 import platformLang from '../utils/lang-en.js'
@@ -30,16 +32,20 @@ export default class {
       9: 'MwUAAwAAAAAAAAAAAAAAAAAAADU=', // auto mode
     }
     this.autoSpeed = 9
+    // Real speed steps, excluding auto - HomeKit percentages map onto these
+    this.speedSteps = 8
 
     // Remove any old original Fan services
     if (this.accessory.getService(this.hapServ.Fan)) {
       this.accessory.removeService(this.accessory.getService(this.hapServ.Fan))
     }
 
-    // Migrate old %-rotation speed to unitless
+    // Rebuild the fan service if it was cached under an older speed scale, as
+    // HomeKit keeps the old props until the service itself is replaced
     const existingService = this.accessory.getService(this.hapServ.Fanv2)
     if (existingService) {
-      if (existingService.getCharacteristic(this.hapChar.RotationSpeed).props.unit === 'percentage') {
+      const { props } = existingService.getCharacteristic(this.hapChar.RotationSpeed)
+      if (props.unit === 'percentage' || props.maxValue !== 100) {
         this.accessory.removeService(existingService)
       }
     }
@@ -57,7 +63,7 @@ export default class {
     this.service
       .getCharacteristic(this.hapChar.RotationSpeed)
       .setProps({
-        maxValue: this.autoSpeed,
+        maxValue: 100,
         minStep: 1,
         minValue: 0,
         unit: 'unitless',
@@ -115,6 +121,9 @@ export default class {
         return
       }
 
+      // HomeKit sends a percentage - map it onto this model's real speed steps
+      value = hkPercentToFanSpeed(value, this.speedSteps)
+
       // Don't continue if the new value is the same as before
       if (this.cacheSpeed === value) {
         return
@@ -142,7 +151,7 @@ export default class {
 
       // Throw a 'no response' error and set a timeout to revert this after 2 seconds
       setTimeout(() => {
-        this.service.updateCharacteristic(this.hapChar.RotationSpeed, this.cacheSpeed)
+        this.service.updateCharacteristic(this.hapChar.RotationSpeed, fanSpeedToHkPercent(this.cacheSpeed, this.speedSteps, this.autoSpeed))
       }, 2000)
       throw new this.hapErr(-70402)
     }
@@ -199,8 +208,9 @@ export default class {
       }
       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}]`)
+        const hkSpeed = fanSpeedToHkPercent(newSpeed, this.speedSteps, this.autoSpeed)
+        this.service.updateCharacteristic(this.hapChar.RotationSpeed, hkSpeed)
+        this.accessory.log(`${platformLang.curSpeed} [${newSpeed} -> ${hkSpeed}%]`)
       }
     }
 
@@ -237,10 +247,11 @@ export default class {
         case '0501': {
           // Fan speed
           const newSpeed = Number.parseInt(getTwoItemPosition(hexParts, 4), 16)
-          if (newSpeed >= 1 && newSpeed <= 8 && this.cacheSpeed !== newSpeed) {
+          if (newSpeed >= 1 && newSpeed <= this.speedSteps && this.cacheSpeed !== newSpeed) {
             this.cacheSpeed = newSpeed
-            this.service.updateCharacteristic(this.hapChar.RotationSpeed, this.cacheSpeed)
-            this.accessory.log(`${platformLang.curSpeed} [${this.cacheSpeed}]`)
+            const hkSpeed = fanSpeedToHkPercent(newSpeed, this.speedSteps, this.autoSpeed)
+            this.service.updateCharacteristic(this.hapChar.RotationSpeed, hkSpeed)
+            this.accessory.log(`${platformLang.curSpeed} [${newSpeed} -> ${hkSpeed}%]`)
           }
           break
         }
@@ -248,7 +259,8 @@ export default class {
           // 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)
+            // Cache auto so we can tell it apart from "user asked for max speed"
+            this.service.updateCharacteristic(this.hapChar.RotationSpeed, 100)
             this.accessory.log(`${platformLang.curSpeed} [auto]`)
           }
           break

package/lib/device/fan-H1370.js

@@ -1,9 +1,11 @@
 import {
   base64ToHex,
+  fanSpeedToHkPercent,
   generateCodeFromHexValues,
   generateRandomString,
   getTwoItemPosition,
   hexToTwoItems,
+  hkPercentToFanSpeed,
   parseError,
   sleep,
 } from '../utils/functions.js'
@@ -32,6 +34,16 @@ export default class {
     const deviceConf = platform.deviceConf[accessory.context.gvDeviceId]
     this.hideLight = deviceConf && deviceConf.hideLight
 
+    // Rebuild the fan service if it was cached under an older speed scale, as
+    // HomeKit keeps the old props until the service itself is replaced
+    const existingService = this.accessory.getService(this.hapServ.Fanv2)
+    if (existingService) {
+      const { props } = existingService.getCharacteristic(this.hapChar.RotationSpeed)
+      if (props.unit === 'percentage' || props.maxValue !== 100) {
+        this.accessory.removeService(existingService)
+      }
+    }
+
     // Add the fan service if it doesn't already exist
     this.service = this.accessory.getService(this.hapServ.Fanv2) || this.accessory.addService(this.hapServ.Fanv2)
 
@@ -41,11 +53,14 @@ export default class {
       .onSet(async value => this.internalStateUpdate(value))
     this.cacheState = this.service.getCharacteristic(this.hapChar.Active).value ? 'on' : 'off'
 
+    // Real speed steps - HomeKit percentages map onto these
+    this.speedSteps = 12
+
     // Add the set handler to the fan rotation speed characteristic
     this.service
       .getCharacteristic(this.hapChar.RotationSpeed)
       .setProps({
-        maxValue: 12,
+        maxValue: 100,
         minStep: 1,
         minValue: 0,
         unit: 'unitless',
@@ -140,6 +155,9 @@ export default class {
         return
       }
 
+      // HomeKit sends a percentage - map it onto this model's real speed steps
+      value = hkPercentToFanSpeed(value, this.speedSteps)
+
       // Don't continue if the new value is the same as before
       if (this.cacheSpeed === value) {
         return
@@ -162,7 +180,7 @@ export default class {
 
       // Throw a 'no response' error and set a timeout to revert this after 2 seconds
       setTimeout(() => {
-        this.service.updateCharacteristic(this.hapChar.RotationSpeed, this.cacheSpeed)
+        this.service.updateCharacteristic(this.hapChar.RotationSpeed, fanSpeedToHkPercent(this.cacheSpeed, this.speedSteps))
       }, 2000)
       throw new this.hapErr(-70402)
     }
@@ -320,10 +338,11 @@ export default class {
         case '3101': {
           // Fan speed
           const newSpeed = Number.parseInt(getTwoItemPosition(hexParts, 4), 16)
-          if (newSpeed >= 1 && newSpeed <= 12 && this.cacheSpeed !== newSpeed) {
+          if (newSpeed >= 1 && newSpeed <= this.speedSteps && this.cacheSpeed !== newSpeed) {
             this.cacheSpeed = newSpeed
-            this.service.updateCharacteristic(this.hapChar.RotationSpeed, this.cacheSpeed)
-            this.accessory.log(`${platformLang.curSpeed} [${this.cacheSpeed}]`)
+            const hkSpeed = fanSpeedToHkPercent(newSpeed, this.speedSteps)
+            this.service.updateCharacteristic(this.hapChar.RotationSpeed, hkSpeed)
+            this.accessory.log(`${platformLang.curSpeed} [${newSpeed} -> ${hkSpeed}%]`)
           }
           break
         }

package/lib/device/fan-H7100.js

@@ -1,7 +1,9 @@
 import {
   base64ToHex,
+  fanSpeedToHkPercent,
   getTwoItemPosition,
   hexToTwoItems,
+  hkPercentToFanSpeed,
   parseError,
 } from '../utils/functions.js'
 import platformLang from '../utils/lang-en.js'
@@ -30,16 +32,20 @@ export default class {
       9: 'MwUAAwAAAAAAAAAAAAAAAAAAADU=', // auto mode
     }
     this.autoSpeed = 9
+    // Real speed steps, excluding auto - HomeKit percentages map onto these
+    this.speedSteps = 8
 
     // Remove any old original Fan services
     if (this.accessory.getService(this.hapServ.Fan)) {
       this.accessory.removeService(this.accessory.getService(this.hapServ.Fan))
     }
 
-    // Migrate old %-rotation speed to unitless
+    // Rebuild the fan service if it was cached under an older speed scale, as
+    // HomeKit keeps the old props until the service itself is replaced
     const existingService = this.accessory.getService(this.hapServ.Fanv2)
     if (existingService) {
-      if (existingService.getCharacteristic(this.hapChar.RotationSpeed).props.unit === 'percentage') {
+      const { props } = existingService.getCharacteristic(this.hapChar.RotationSpeed)
+      if (props.unit === 'percentage' || props.maxValue !== 100) {
         this.accessory.removeService(existingService)
       }
     }
@@ -57,7 +63,7 @@ export default class {
     this.service
       .getCharacteristic(this.hapChar.RotationSpeed)
       .setProps({
-        maxValue: this.autoSpeed,
+        maxValue: 100,
         minStep: 1,
         minValue: 0,
         unit: 'unitless',
@@ -115,6 +121,9 @@ export default class {
         return
       }
 
+      // HomeKit sends a percentage - map it onto this model's real speed steps
+      value = hkPercentToFanSpeed(value, this.speedSteps)
+
       // Don't continue if the new value is the same as before
       if (this.cacheSpeed === value) {
         return
@@ -142,7 +151,7 @@ export default class {
 
       // Throw a 'no response' error and set a timeout to revert this after 2 seconds
       setTimeout(() => {
-        this.service.updateCharacteristic(this.hapChar.RotationSpeed, this.cacheSpeed)
+        this.service.updateCharacteristic(this.hapChar.RotationSpeed, fanSpeedToHkPercent(this.cacheSpeed, this.speedSteps, this.autoSpeed))
       }, 2000)
       throw new this.hapErr(-70402)
     }
@@ -199,8 +208,9 @@ export default class {
       }
       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}]`)
+        const hkSpeed = fanSpeedToHkPercent(newSpeed, this.speedSteps, this.autoSpeed)
+        this.service.updateCharacteristic(this.hapChar.RotationSpeed, hkSpeed)
+        this.accessory.log(`${platformLang.curSpeed} [${newSpeed} -> ${hkSpeed}%]`)
       }
     }
 
@@ -237,10 +247,11 @@ export default class {
         case '0501': {
           // Fan speed
           const newSpeed = Number.parseInt(getTwoItemPosition(hexParts, 4), 16)
-          if (newSpeed >= 1 && newSpeed <= 8 && this.cacheSpeed !== newSpeed) {
+          if (newSpeed >= 1 && newSpeed <= this.speedSteps && this.cacheSpeed !== newSpeed) {
             this.cacheSpeed = newSpeed
-            this.service.updateCharacteristic(this.hapChar.RotationSpeed, this.cacheSpeed)
-            this.accessory.log(`${platformLang.curSpeed} [${this.cacheSpeed}]`)
+            const hkSpeed = fanSpeedToHkPercent(newSpeed, this.speedSteps, this.autoSpeed)
+            this.service.updateCharacteristic(this.hapChar.RotationSpeed, hkSpeed)
+            this.accessory.log(`${platformLang.curSpeed} [${newSpeed} -> ${hkSpeed}%]`)
           }
           break
         }
@@ -248,7 +259,8 @@ export default class {
           // 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)
+            // Cache auto so we can tell it apart from "user asked for max speed"
+            this.service.updateCharacteristic(this.hapChar.RotationSpeed, 100)
             this.accessory.log(`${platformLang.curSpeed} [auto]`)
           }
           break

package/lib/device/fan-H7101.js

@@ -1,7 +1,9 @@
 import {
   base64ToHex,
+  fanSpeedToHkPercent,
   getTwoItemPosition,
   hexToTwoItems,
+  hkPercentToFanSpeed,
   parseError,
 } from '../utils/functions.js'
 import platformLang from '../utils/lang-en.js'
@@ -86,16 +88,20 @@ export default class {
       9: 'MwUAAwAAAAAAAAAAAAAAAAAAADU=', // auto mode
     }
     this.autoSpeed = 9
+    // Real speed steps, excluding auto - HomeKit percentages map onto these
+    this.speedSteps = 8
 
     // Remove any old original Fan services
     if (this.accessory.getService(this.hapServ.Fan)) {
       this.accessory.removeService(this.accessory.getService(this.hapServ.Fan))
     }
 
-    // Migrate old %-rotation speed to unitless
+    // Rebuild the fan service if it was cached under an older speed scale, as
+    // HomeKit keeps the old props until the service itself is replaced
     const existingService = this.accessory.getService(this.hapServ.Fanv2)
     if (existingService) {
-      if (existingService.getCharacteristic(this.hapChar.RotationSpeed).props.unit === 'percentage') {
+      const { props } = existingService.getCharacteristic(this.hapChar.RotationSpeed)
+      if (props.unit === 'percentage' || props.maxValue !== 100) {
         this.accessory.removeService(existingService)
       }
     }
@@ -113,7 +119,7 @@ export default class {
     this.service
       .getCharacteristic(this.hapChar.RotationSpeed)
       .setProps({
-        maxValue: this.autoSpeed,
+        maxValue: 100,
         minStep: 1,
         minValue: 0,
         unit: 'unitless',
@@ -171,6 +177,9 @@ export default class {
         return
       }
 
+      // HomeKit sends a percentage - map it onto this model's real speed steps
+      value = hkPercentToFanSpeed(value, this.speedSteps)
+
       // Don't continue if the new value is the same as before
       if (this.cacheSpeed === value) {
         return
@@ -198,7 +207,7 @@ export default class {
 
       // Throw a 'no response' error and set a timeout to revert this after 2 seconds
       setTimeout(() => {
-        this.service.updateCharacteristic(this.hapChar.RotationSpeed, this.cacheSpeed)
+        this.service.updateCharacteristic(this.hapChar.RotationSpeed, fanSpeedToHkPercent(this.cacheSpeed, this.speedSteps, this.autoSpeed))
       }, 2000)
       throw new this.hapErr(-70402)
     }
@@ -255,8 +264,9 @@ export default class {
       }
       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}]`)
+        const hkSpeed = fanSpeedToHkPercent(newSpeed, this.speedSteps, this.autoSpeed)
+        this.service.updateCharacteristic(this.hapChar.RotationSpeed, hkSpeed)
+        this.accessory.log(`${platformLang.curSpeed} [${newSpeed} -> ${hkSpeed}%]`)
       }
     }
 
@@ -293,10 +303,11 @@ export default class {
         case '0501': {
           // Fan speed
           const newSpeed = Number.parseInt(getTwoItemPosition(hexParts, 4), 16)
-          if (newSpeed >= 1 && newSpeed <= 8 && this.cacheSpeed !== newSpeed) {
+          if (newSpeed >= 1 && newSpeed <= this.speedSteps && this.cacheSpeed !== newSpeed) {
             this.cacheSpeed = newSpeed
-            this.service.updateCharacteristic(this.hapChar.RotationSpeed, this.cacheSpeed)
-            this.accessory.log(`${platformLang.curSpeed} [${this.cacheSpeed}]`)
+            const hkSpeed = fanSpeedToHkPercent(newSpeed, this.speedSteps, this.autoSpeed)
+            this.service.updateCharacteristic(this.hapChar.RotationSpeed, hkSpeed)
+            this.accessory.log(`${platformLang.curSpeed} [${newSpeed} -> ${hkSpeed}%]`)
           }
           break
         }
@@ -304,7 +315,8 @@ export default class {
           // 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)
+            // Cache auto so we can tell it apart from "user asked for max speed"
+            this.service.updateCharacteristic(this.hapChar.RotationSpeed, 100)
             this.accessory.log(`${platformLang.curSpeed} [auto]`)
           }
           break

package/lib/device/fan-H7102.js

@@ -1,7 +1,9 @@
 import {
   base64ToHex,
+  fanSpeedToHkPercent,
   getTwoItemPosition,
   hexToTwoItems,
+  hkPercentToFanSpeed,
   parseError,
 } from '../utils/functions.js'
 import platformLang from '../utils/lang-en.js'
@@ -30,16 +32,20 @@ export default class {
       9: 'MwUAAwAAAAAAAAAAAAAAAAAAADU=', // auto mode
     }
     this.autoSpeed = 9
+    // Real speed steps, excluding auto - HomeKit percentages map onto these
+    this.speedSteps = 8
 
     // Remove any old original Fan services
     if (this.accessory.getService(this.hapServ.Fan)) {
       this.accessory.removeService(this.accessory.getService(this.hapServ.Fan))
     }
 
-    // Migrate old %-rotation speed to unitless
+    // Rebuild the fan service if it was cached under an older speed scale, as
+    // HomeKit keeps the old props until the service itself is replaced
     const existingService = this.accessory.getService(this.hapServ.Fanv2)
     if (existingService) {
-      if (existingService.getCharacteristic(this.hapChar.RotationSpeed).props.unit === 'percentage') {
+      const { props } = existingService.getCharacteristic(this.hapChar.RotationSpeed)
+      if (props.unit === 'percentage' || props.maxValue !== 100) {
         this.accessory.removeService(existingService)
       }
     }
@@ -57,7 +63,7 @@ export default class {
     this.service
       .getCharacteristic(this.hapChar.RotationSpeed)
       .setProps({
-        maxValue: this.autoSpeed,
+        maxValue: 100,
         minStep: 1,
         minValue: 0,
         unit: 'unitless',
@@ -115,6 +121,9 @@ export default class {
         return
       }
 
+      // HomeKit sends a percentage - map it onto this model's real speed steps
+      value = hkPercentToFanSpeed(value, this.speedSteps)
+
       // Don't continue if the new value is the same as before
       if (this.cacheSpeed === value) {
         return
@@ -142,7 +151,7 @@ export default class {
 
       // Throw a 'no response' error and set a timeout to revert this after 2 seconds
       setTimeout(() => {
-        this.service.updateCharacteristic(this.hapChar.RotationSpeed, this.cacheSpeed)
+        this.service.updateCharacteristic(this.hapChar.RotationSpeed, fanSpeedToHkPercent(this.cacheSpeed, this.speedSteps, this.autoSpeed))
       }, 2000)
       throw new this.hapErr(-70402)
     }
@@ -199,8 +208,9 @@ export default class {
       }
       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}]`)
+        const hkSpeed = fanSpeedToHkPercent(newSpeed, this.speedSteps, this.autoSpeed)
+        this.service.updateCharacteristic(this.hapChar.RotationSpeed, hkSpeed)
+        this.accessory.log(`${platformLang.curSpeed} [${newSpeed} -> ${hkSpeed}%]`)
       }
     }
 
@@ -237,10 +247,11 @@ export default class {
         case '0501': {
           // Fan speed
           const newSpeed = Number.parseInt(getTwoItemPosition(hexParts, 4), 16)
-          if (newSpeed >= 1 && newSpeed <= 8 && this.cacheSpeed !== newSpeed) {
+          if (newSpeed >= 1 && newSpeed <= this.speedSteps && this.cacheSpeed !== newSpeed) {
             this.cacheSpeed = newSpeed
-            this.service.updateCharacteristic(this.hapChar.RotationSpeed, this.cacheSpeed)
-            this.accessory.log(`${platformLang.curSpeed} [${this.cacheSpeed}]`)
+            const hkSpeed = fanSpeedToHkPercent(newSpeed, this.speedSteps, this.autoSpeed)
+            this.service.updateCharacteristic(this.hapChar.RotationSpeed, hkSpeed)
+            this.accessory.log(`${platformLang.curSpeed} [${newSpeed} -> ${hkSpeed}%]`)
           }
           break
         }
@@ -248,7 +259,8 @@ export default class {
           // 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)
+            // Cache auto so we can tell it apart from "user asked for max speed"
+            this.service.updateCharacteristic(this.hapChar.RotationSpeed, 100)
             this.accessory.log(`${platformLang.curSpeed} [auto]`)
           }
           break