@homebridge-plugins/homebridge-govee 11.34.2-beta.8 → 11.35.0

package/CHANGELOG.md

@@ -2,7 +2,7 @@
 
 All notable changes to `@homebridge-plugins/homebridge-govee` will be documented in this file.
 
-## v11.34.2 (Pending Release)
+## v11.35.0 (2026-08-09)
 
 ### Changed
 
@@ -19,10 +19,13 @@ All notable changes to `@homebridge-plugins/homebridge-govee` will be documented
 - fix: apply the openapi disable and refresh settings instead of asking for them to be removed
 - fix: say once when a bluetooth reading arrives for an unknown device, not on every broadcast
 - fix: reject a refresh time so large it would make the plugin poll every millisecond
-- fix(H5054): don't let a slow leak warning block other sensors (#1348)
-- fix: mark sensor batteries low at the configured threshold
+- fix(H5054): don't let a slow leak warning block other sensors (#1348) (@danieloleary)
+- fix: mark sensor batteries low at the configured threshold (#1349) (@danieloleary)
 - feat: show whether the kettle is heating, keeping warm or idle (#1337)
 - 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

@@ -1,6 +1,7 @@
 import platformConsts from './constants.js'
 import { getDeviceCapabilities } from './device-capabilities.js'
 import { hasProperty } from './functions.js'
+import platformLang from './lang-en.js'
 
 /**
  * Fills in everything a handler needs to know about a device before it is
@@ -69,9 +70,38 @@ export function applyDeviceContext(platform, accessory, device, deviceConf, join
     accessory.context.useLanControl = true
   }
 
-  // If the device is LAN-only, then sync the display name with the label in the configuration
-  if (device.isLanOnly) {
-    accessory.displayName = device.deviceName
+  // Keep the name in step with Govee - or, for a LAN-only device, with the
+  // 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. A name HAP complains about
+  // (brackets, say) could then not be cleared without deleting the cached
+  // accessory and losing its room and automations (#1344).
+  //
+  // ⚠️ 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)
+
+    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)
+    if (hapChar && infoService) {
+      infoService.updateCharacteristic(hapChar.Name, device.deviceName)
+      infoService.updateCharacteristic(hapChar.ConfiguredName, device.deviceName)
+    }
   }
 
   // See if we have extra HTTP client info for this device

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',
@@ -82,6 +86,7 @@ export default {
   devNotRet: 'skipping sync as device status not retrievable',
   devNotUpdated: 'could not be updated as',
   devRemove: 'has been removed from Homebridge',
+  devRenamed: 'has been renamed to',
   disableClient: 'disabling client as',
   disabledInConfig: 'disabled in config',
   disabling: 'Disabling plugin',

package/lib/utils/validation.js

@@ -11,7 +11,23 @@ export function isHt5075(hex) { // Govee H5072/H5075
   return hex.includes(h5075_uuid_rev) && hex.length === 16
 }
 
-export const isHt5101 = hex => hex.includes(h5101_uuid_rev) // Govee H5100/H5101/H5102
+// Govee H5100/H5101/H5102
+//
+// ⚠️ The length check matters as much as the marker. `0100` is only four hex
+// digits, and plenty of Govee broadcasts happen to contain it - a light sending
+// `4388ec00020100` did, which claimed the broadcast for the H5101 decoder, and
+// that decoder reads sixteen characters and threw on fourteen (#1350). The
+// throw surfaced as `error processing discovered peripheral` on every broadcast
+// from a light that was working perfectly well.
+//
+// This is `>=` rather than the `===` its siblings use, deliberately: the
+// decoder only ever reads the first sixteen characters, so anything at least
+// that long decodes correctly today. Pinning an exact length would reject a
+// longer payload from an H5111 or H5220 - both documented as sharing this
+// format - and there is no sample of either to check that against.
+export function isHt5101(hex) {
+  return hex.includes(h5101_uuid_rev) && hex.length >= 16
+}
 
 export function isHt5179(hex) { // Govee H5179
   return hex.includes(h5179_uuid_rev) && hex.length === 22

package/package.json

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