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

package/CHANGELOG.md

@@ -30,6 +30,7 @@ All notable changes to `@homebridge-plugins/homebridge-govee` will be documented
 - 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)
+- 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/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.27",
   "description": "Homebridge plugin to integrate Govee devices into HomeKit.",
   "author": {
     "name": "bwp91",