@homebridge-plugins/homebridge-govee 11.32.0-beta.26 → 11.32.0-beta.28

package/CHANGELOG.md

@@ -17,7 +17,7 @@ All notable changes to `@homebridge-plugins/homebridge-govee` will be documented
 - 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)
+- 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)
@@ -26,10 +26,15 @@ All notable changes to `@homebridge-plugins/homebridge-govee` will be documented
 - 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)
-- docs(changelog): list every unreleased commit in the pending section
 - 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)
 
 ## v11.31.0 (2026-07-24)
 

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/platform.js

@@ -13,6 +13,7 @@ import lanClient from './connection/lan.js'
 import openApiClient from './connection/openapi.js'
 import deviceTypes from './device/index.js'
 import eveService from './fakegato/fakegato-history.js'
+import { BLE_UPDATE_TIMEOUT } from './utils/ble-protocol.js'
 import { buildCommand } from './utils/command-builder.js'
 import platformConsts from './utils/constants.js'
 import platformChars from './utils/custom-chars.js'
@@ -595,7 +596,10 @@ export default class {
         concurrency: 1,
         interval: this.config.bleControlInterval * 1000,
         intervalCap: 1,
-        timeout: 10000,
+        // Sized from the BLE stage timeouts so the two cannot drift apart. This
+        // is a backstop for a hung task, and must stay longer than the stages
+        // it wraps - see BLE_UPDATE_TIMEOUT.
+        timeout: BLE_UPDATE_TIMEOUT,
         throwOnTimeout: true,
       })
 

package/lib/utils/ble-protocol.js

@@ -61,3 +61,35 @@ export const UUID = {
 
 // Total BLE packet size
 export const PACKET_SIZE = 20
+
+// Timeouts for the individual stages of a single BLE updateDevice() call.
+// They live here, rather than beside the code that uses them, so the platform
+// can size its queue from them without importing the BLE client — that client
+// pulls in a native module which is not present on every install.
+export const BLE_STAGE_TIMEOUTS = {
+  powerOn: 5000,
+  connect: 10000,
+  write: 5000,
+  settle: 100, // let the controller transmit before disconnecting
+
+  // Discovering services, and the disconnect on the way out, have no timeout of
+  // their own, so leave them room in the total.
+  untimedStages: 3000,
+
+  // Headroom on top, so that a stage which times out reports its own error
+  // instead of being cut short by the queue's much vaguer one.
+  queueHeadroom: 2000,
+}
+
+/**
+ * The longest a single BLE updateDevice() call can legitimately take.
+ *
+ * The platform queue sizes its own timeout from this. It is meant as a backstop
+ * for a task that has hung, not a second deadline racing the stage timeouts.
+ * Both used to be a flat 10 seconds, which meant the queue killed a connection
+ * attempt at the exact moment that attempt gave up — and a light that connected
+ * slowly never got as far as sending its command at all (#1328).
+ */
+export const BLE_UPDATE_TIMEOUT = Object
+  .values(BLE_STAGE_TIMEOUTS)
+  .reduce((total, stage) => total + stage, 0)

package/lib/utils/ble-timeouts.test.js

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest'
+
+import { BLE_STAGE_TIMEOUTS, BLE_UPDATE_TIMEOUT } from './ble-protocol.js'
+
+/**
+ * The bug these guard against (#1328): the BLE connect timeout and the platform
+ * queue timeout were both a flat 10000ms. The queue therefore killed a task at
+ * the exact moment the connect gave up, and any light that connected slowly had
+ * nothing left of the budget for discovering services and writing its command.
+ */
+describe('bLE timeout budget', () => {
+  it('leaves room for every stage of an update', () => {
+    const stages = BLE_STAGE_TIMEOUTS.powerOn
+      + BLE_STAGE_TIMEOUTS.connect
+      + BLE_STAGE_TIMEOUTS.untimedStages
+      + BLE_STAGE_TIMEOUTS.write
+      + BLE_STAGE_TIMEOUTS.settle
+
+    expect(BLE_UPDATE_TIMEOUT).toBeGreaterThan(stages)
+  })
+
+  it('is not simply the connect timeout, which is what caused #1328', () => {
+    expect(BLE_UPDATE_TIMEOUT).not.toBe(BLE_STAGE_TIMEOUTS.connect)
+  })
+
+  it('still has time left after the slowest possible connect', () => {
+    // A connect that only just succeeds must leave enough behind to discover
+    // services and send the command - otherwise a slow device is
+    // indistinguishable from an unreachable one.
+    const afterSlowestConnect = BLE_UPDATE_TIMEOUT
+      - BLE_STAGE_TIMEOUTS.powerOn
+      - BLE_STAGE_TIMEOUTS.connect
+
+    expect(afterSlowestConnect).toBeGreaterThanOrEqual(
+      BLE_STAGE_TIMEOUTS.untimedStages + BLE_STAGE_TIMEOUTS.write + BLE_STAGE_TIMEOUTS.settle,
+    )
+  })
+
+  it('keeps every stage timeout positive', () => {
+    Object.entries(BLE_STAGE_TIMEOUTS).forEach(([stage, ms]) => {
+      expect(ms, stage).toBeGreaterThan(0)
+    })
+  })
+})

package/lib/utils/functions.test.js

@@ -0,0 +1,179 @@
+import { Buffer } from 'node:buffer'
+
+import { describe, expect, it } from 'vitest'
+
+import {
+  base64ToHex,
+  cenToFar,
+  fanSpeedToHkPercent,
+  farToCen,
+  generateCodeFromHexValues,
+  getTwoItemPosition,
+  hasProperty,
+  hexToBase64,
+  hexToDecimal,
+  hexToTwoItems,
+  hkPercentToFanSpeed,
+  nearestHalf,
+  parseDeviceId,
+  parseError,
+} from './functions.js'
+
+/**
+ * The fan speed mapping is the one worth pinning hardest. Before #1310/#1326
+ * the plugin sent the raw HomeKit percentage as a speed, so a slider at 100%
+ * asked an 8-step fan for speed 100, and the Home app displayed speeds like
+ * "7%". These tests cover the round trip on both step counts we ship.
+ */
+describe('fan speed mapping', () => {
+  it('maps the top of the slider to the fastest speed', () => {
+    expect(hkPercentToFanSpeed(100, 8)).toBe(8)
+    expect(hkPercentToFanSpeed(100, 12)).toBe(12)
+  })
+
+  it('never returns speed 0, which would mean "off" to the device', () => {
+    // HomeKit sends 0 when the fan is switched off. Speed 0 is not a valid
+    // speed, so the mapping clamps to the slowest instead.
+    expect(hkPercentToFanSpeed(0, 8)).toBe(1)
+    expect(hkPercentToFanSpeed(1, 8)).toBe(1)
+  })
+
+  it('never exceeds the number of steps the model has', () => {
+    expect(hkPercentToFanSpeed(150, 8)).toBe(8)
+  })
+
+  it('round trips every speed on an 8 step model', () => {
+    for (let speed = 1; speed <= 8; speed++) {
+      expect(hkPercentToFanSpeed(fanSpeedToHkPercent(speed, 8), 8)).toBe(speed)
+    }
+  })
+
+  it('round trips every speed on a 12 step model', () => {
+    for (let speed = 1; speed <= 12; speed++) {
+      expect(hkPercentToFanSpeed(fanSpeedToHkPercent(speed, 12), 12)).toBe(speed)
+    }
+  })
+
+  it('reports a stopped fan as 0 percent', () => {
+    expect(fanSpeedToHkPercent(0, 8)).toBe(0)
+    expect(fanSpeedToHkPercent(undefined, 8)).toBe(0)
+  })
+
+  it('shows auto mode at the top of the slider', () => {
+    // Chosen so the two paths disagree: without the auto case, speed 5 of 8
+    // would map to 63%. An auto speed that happens to sit above the step count
+    // would return 100 either way and would not prove the branch runs.
+    expect(fanSpeedToHkPercent(5, 8, 5)).toBe(100)
+    expect(fanSpeedToHkPercent(5, 8, undefined)).toBe(63)
+  })
+
+  it('does not treat auto as special when the model has no auto speed', () => {
+    expect(fanSpeedToHkPercent(4, 8, undefined)).toBe(50)
+  })
+})
+
+describe('parseDeviceId', () => {
+  it('uppercases and strips punctuation the api does not use', () => {
+    expect(parseDeviceId('ab:cd:ef')).toBe('AB:CD:EF')
+    expect(parseDeviceId('ab cd-ef')).toBe('ABCDEF')
+  })
+
+  it('keeps the separators govee device ids actually contain', () => {
+    // Colons and underscores are meaningful in a Govee device id, so the
+    // cleaner must not strip them along with the rest.
+    expect(parseDeviceId('AB:CD_EF')).toBe('AB:CD_EF')
+  })
+
+  it('accepts a non-string id without throwing', () => {
+    expect(parseDeviceId(123456)).toBe('123456')
+  })
+})
+
+describe('hex helpers', () => {
+  it('splits a hex string into byte pairs', () => {
+    expect(hexToTwoItems('aabbcc')).toEqual(['aa', 'bb', 'cc'])
+  })
+
+  it('reads a byte by its 1-based position, as the device handlers do', () => {
+    // Callers index from 1 because they are reading a protocol spec, not an
+    // array. Getting this off by one silently misreads every payload.
+    const parts = hexToTwoItems('aa1b0164')
+    expect(getTwoItemPosition(parts, 1)).toBe('aa')
+    expect(getTwoItemPosition(parts, 2)).toBe('1b')
+    expect(getTwoItemPosition(parts, 4)).toBe('64')
+  })
+
+  it('converts hex to decimal', () => {
+    expect(hexToDecimal('64')).toBe(100)
+    expect(hexToDecimal('ff')).toBe(255)
+  })
+
+  it('round trips base64 and hex', () => {
+    const hex = '330501000000000000000000000000000000000037'
+    expect(base64ToHex(hexToBase64(hex))).toBe(hex)
+  })
+})
+
+describe('generateCodeFromHexValues', () => {
+  it('builds a 20 byte packet', () => {
+    // Every Govee BLE/IoT command is exactly 20 bytes: 19 of payload plus a
+    // trailing XOR checksum.
+    const packet = Buffer.from(generateCodeFromHexValues(['0x33', '0x05', '0x01']), 'base64')
+    expect(packet).toHaveLength(20)
+  })
+
+  it('ends with an xor checksum over the first 19 bytes', () => {
+    const packet = Buffer.from(generateCodeFromHexValues(['0x33', '0x05', '0x01']), 'base64')
+    let expected = 0
+    for (let i = 0; i < 19; i++) {
+      expected ^= packet[i]
+    }
+    expect(packet[19]).toBe(expected)
+  })
+
+  it('pads short commands with zeroes rather than leaving them short', () => {
+    const packet = Buffer.from(generateCodeFromHexValues(['0x33', '0x01']), 'base64')
+    expect(packet.subarray(2, 19).every(b => b === 0)).toBe(true)
+  })
+})
+
+describe('temperature conversion', () => {
+  it('converts celsius to fahrenheit to one decimal place', () => {
+    expect(cenToFar(0)).toBe(32)
+    expect(cenToFar(100)).toBe(212)
+    expect(cenToFar(21.5)).toBe(70.7)
+  })
+
+  it('converts fahrenheit to whole celsius', () => {
+    expect(farToCen(32)).toBe(0)
+    expect(farToCen(212)).toBe(100)
+  })
+
+  it('rounds to the nearest half', () => {
+    expect(nearestHalf(21.24)).toBe(21)
+    expect(nearestHalf(21.26)).toBe(21.5)
+    expect(nearestHalf(21.75)).toBe(22)
+  })
+})
+
+describe('misc helpers', () => {
+  it('detects own properties only', () => {
+    expect(hasProperty({ a: 1 }, 'a')).toBe(true)
+    expect(hasProperty({}, 'toString')).toBe(false)
+  })
+
+  it('appends the first stack frame to an error message', () => {
+    const err = new Error('boom')
+    err.stack = 'Error: boom\n    at thing (/a.js:1:1)'
+    expect(parseError(err)).toContain('boom')
+    expect(parseError(err)).toContain('at thing')
+  })
+
+  it('can be told to hide the stack for expected errors', () => {
+    // Some errors are routine (a device being offline) and their stack is
+    // noise in the log, so callers pass them in hideStack.
+    const err = new Error('offline')
+    err.stack = 'Error: offline\n    at thing (/a.js:1:1)'
+    expect(parseError(err, ['offline'])).toBe('offline')
+  })
+})

package/package.json

@@ -2,7 +2,7 @@
   "name": "@homebridge-plugins/homebridge-govee",
   "alias": "Govee",
   "type": "module",
-  "version": "11.32.0-beta.26",
+  "version": "11.32.0-beta.28",
   "description": "Homebridge plugin to integrate Govee devices into HomeKit.",
   "author": {
     "name": "bwp91",
@@ -49,12 +49,16 @@
   "main": "lib/index.js",
   "engines": {
     "homebridge": "^1.6.0 || ^2.0.0",
-    "node": "^22.12.0 || ^24.0.0"
+    "node": "^22.12.0 || ^24.0.0 || ^26.0.0"
   },
   "scripts": {
     "lint": "eslint . --max-warnings=0",
     "lint:fix": "npm run lint -- --fix",
-    "postinstall": "patch-package"
+    "postinstall": "patch-package",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test-coverage": "npm run test -- --coverage",
+    "changelog:sync": "node .github/scripts/sync-changelog.mjs"
   },
   "dependencies": {
     "@homebridge/plugin-ui-utils": "^2.2.5",
@@ -72,7 +76,9 @@
     "@stoprocent/noble": "^2.5.9"
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^9.2.0"
+    "@antfu/eslint-config": "^9.2.0",
+    "@vitest/coverage-v8": "^4.1.10",
+    "vitest": "^4.1.10"
   },
   "allowScripts": {
     "@stoprocent/bluetooth-hci-socket@2.2.6": true,