@homebridge-plugins/homebridge-govee 11.34.2-beta.12 → 11.34.2-beta.13

package/CHANGELOG.md

@@ -25,6 +25,7 @@ All notable changes to `@homebridge-plugins/homebridge-govee` will be documented
 - fix: give the H5106 a battery service, so its low battery setting does something
 - fix: stop a light's broadcast being mistaken for an h5101 sensor reading
 - fix: follow a device renamed in the govee app, instead of keeping its first name forever (#1344)
+- fix: say why the bluetooth adapter would not start, rather than only that it timed out (#1344)
 
 ## v11.34.1 (2026-08-06)
 

package/lib/connection/ble.js

@@ -4,7 +4,7 @@ import process from 'node:process'
 import btClient from '@stoprocent/noble'
 
 import { buildHandshake, isHandshakeFrame, parseHandshakeResponse, V2Session } from '../utils/ble-crypto.js'
-import { BLE_STAGE_TIMEOUTS, UUID } from '../utils/ble-protocol.js'
+import { BLE_STAGE_TIMEOUTS, describeAdapterState, UUID } from '../utils/ble-protocol.js'
 import { decodeAny } from '../utils/decode.js'
 import { getDeviceCapabilities } from '../utils/device-capabilities.js'
 import { base64ToHex, generateCodeFromHexValues, hexToTwoItems, sleep } from '../utils/functions.js'
@@ -42,6 +42,9 @@ export default class BLEConnection {
     this.scanTimeoutId = null
     this.isShuttingDown = false
 
+    // The power-on failure is said once, not every few minutes - see waitForPowerOn
+    this.powerOnReported = false
+
     // Store event handler references for cleanup
     this.eventHandlers = {
       stateChange: null,
@@ -64,6 +67,11 @@ export default class BLEConnection {
         this.btState = state
         this.log.debug('[BLE] adapter state changed to: %s.', state)
 
+        // Someone has acted on it, so a later failure is worth saying again
+        if (state === 'poweredOn') {
+          this.powerOnReported = false
+        }
+
         // If adapter loses power while operations are in progress, clean up
         if (state !== 'poweredOn') {
           this.handleAdapterPowerLoss()
@@ -224,7 +232,21 @@ export default class BLEConnection {
       await btClient.waitForPoweredOnAsync(timeout)
       return true
     } catch (err) {
-      this.log.warn('[BLE] failed to power on adapter: %s.', err.message)
+      // Say what to do about it, from the state noble reported, rather than
+      // repeating its "timed out" message for every possible cause (#1344).
+      const advice = describeAdapterState(this.btState, platformLang)
+      const message = advice
+        ? `${advice} [${this.btState}]`
+        : err.message
+
+      // The retry runs every few minutes, so say it once and then keep quiet -
+      // nothing changes until someone acts on it
+      if (this.powerOnReported) {
+        this.log.debug('[BLE] failed to power on adapter: %s.', message)
+      } else {
+        this.powerOnReported = true
+        this.log.warn('[BLE] failed to power on adapter: %s.', message)
+      }
       return false
     }
   }

package/lib/utils/ble-protocol.js

@@ -101,3 +101,31 @@ export const BLE_STAGE_TIMEOUTS = {
 export const BLE_UPDATE_TIMEOUT = Object
   .values(BLE_STAGE_TIMEOUTS)
   .reduce((total, stage) => total + stage, 0)
+
+/**
+ * What a noble adapter state means for the person reading the log.
+ *
+ * ⚠️ The plugin used to report only noble's own message — "Timeout waiting for
+ * Noble to be powered on" — for every one of these. That reads as a stuck
+ * adapter no matter which it is, and the three real causes need completely
+ * different fixes: a blocked radio, a missing capability, or no adapter at all.
+ * Working out which cost a reporter four days of back-and-forth (#1344), and it
+ * was knowable from the state noble had already reported.
+ *
+ * Returns undefined when the state does not point at a specific cause, so the
+ * caller can fall back to noble's own wording.
+ */
+export function describeAdapterState(state, lang) {
+  switch (state) {
+    case 'poweredOff':
+      return lang.blePowerBlocked
+    case 'unauthorized':
+      return lang.blePowerUnauthorized
+    case 'unsupported':
+      return lang.blePowerNoAdapter
+    case 'unknown':
+      return lang.blePowerUnknown
+    default:
+      return undefined
+  }
+}

package/lib/utils/lang-en.js

@@ -25,6 +25,10 @@ export default {
   bleScanNoStart: 'could not start sync as',
   bleScanNoStop: 'could not stop sync as',
   bleScanUnknown: 'reading received for unknown accessory',
+  blePowerBlocked: 'the bluetooth adapter is switched off or blocked - check `rfkill list`, and `sudo rfkill unblock bluetooth` if it is blocked',
+  blePowerNoAdapter: 'no bluetooth adapter was found - check the adapter exists and the bluetooth service is running',
+  blePowerUnauthorized: 'not allowed to use the bluetooth adapter - node needs raw network access, which a node upgrade wipes: `sudo setcap cap_net_raw+eip $(readlink -f $(which node))`, then fully restart homebridge',
+  blePowerUnknown: 'the bluetooth adapter never reported its state - check the bluetooth service is running',
   bleStart: 'scanning started',
   bleStop: 'scanning stopped',
   bleTimeout: 'BLE took too long',

package/package.json

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