@homebridge-plugins/homebridge-govee 11.34.2-beta.11 → 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/device-context.js

@@ -74,17 +74,27 @@ export function applyDeviceContext(platform, accessory, device, deviceConf, join
   // label in the configuration.
   //
   // ⚠️ This used to run for LAN-only devices only, so every other device kept
-  // whatever name it was discovered under, forever. Renaming in the Govee app
-  // did nothing, and a name HAP complains about (brackets, say) could not be
-  // cleared without deleting the cached accessory and losing its room and
-  // automations (#1344).
+  // whatever name it was discovered under, forever. A name HAP complains about
+  // (brackets, say) could then not be cleared without deleting the cached
+  // accessory and losing its room and automations (#1344).
   //
-  // The AccessoryInformation characteristics are set alongside displayName
-  // because addAccessory sets all three, and HAP's own warning reads the
-  // characteristic rather than the display name.
+  // ⚠️ This does NOT rename anything in the Home app. HomeKit fixes the name a
+  // user sees when the accessory is first added, and a rename made there never
+  // comes back to us either. What this fixes is the name Homebridge itself
+  // shows and, through the Name characteristic, the HAP warning.
+  //
+  // `updateDisplayName` is the supported way to do it - assigning to
+  // `displayName` sets only Homebridge's copy and leaves the HAP accessory
+  // behind. It arrived in Homebridge v1.10.0, and this plugin still supports
+  // ^1.6.0, hence the check.
   if (device.deviceName && accessory.displayName !== device.deviceName) {
     platform.log('[%s] %s [%s].', accessory.displayName, platformLang.devRenamed, device.deviceName)
-    accessory.displayName = device.deviceName
+
+    if (typeof accessory.updateDisplayName === 'function') {
+      accessory.updateDisplayName(device.deviceName)
+    } else {
+      accessory.displayName = device.deviceName
+    }
 
     const hapChar = platform.api?.hap?.Characteristic
     const infoService = accessory.getService?.(platform.api?.hap?.Service?.AccessoryInformation)

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.11",
+  "version": "11.34.2-beta.13",
   "description": "Homebridge plugin to integrate Govee devices into HomeKit.",
   "author": {
     "name": "bwp91",