@homebridge-plugins/homebridge-govee 11.32.2-beta.30 → 11.32.2-beta.32

package/CHANGELOG.md

@@ -7,6 +7,7 @@ All notable changes to `@homebridge-plugins/homebridge-govee` will be documented
 ### Changed
 
 - fix: stop shipping the test files to npm, since they are only needed in the repository
+- fix: BLE device control on macOS by resolving peripherals via advertised name (#1336) (@Perafan18)
 - fix: implement the H7107's oscillation toggle, which threw a not-implemented error when tapped (#1334)
 - fix: also send the H7107's oscillation command as the multiSync frame the fan itself uses, since the first shape only turned it off sometimes (#1334)
 - fix: send the H7107's oscillation-off command without the swing-range bytes, matching the zero-tailed frame the fan echoes back (#1334)
@@ -45,7 +46,8 @@ All notable changes to `@homebridge-plugins/homebridge-govee` will be documented
 - feat: add the H5161 power strip and give the H7184 kitchen composter an on and off switch
 - feat: recognise three more sensors, which report what they send, and say plainly in the log why a sensor has no tile yet
 - feat: add ble encryption for the H3001 solar string lights, which silently ignore unencrypted frames (#1328) (@dominick-han)
-- fix: mention an unrecognised bluetooth broadcast once, and only when the device is on your own account, since a scan also hears the neighbours
+- fix: mention an unrecognised bluetooth broadcast once, and only for one of your own sensors, since a scan also hears your lights and the neighbours
+- fix: say "device(s)" in the connection summary, since the count is often one
 
 ## v11.32.1 (2026-08-02)
 

package/README.md

@@ -29,7 +29,7 @@ Homebridge plugin to integrate Govee devices into HomeKit
 - To use this plugin, you will need to already have:
   - [Node](https://nodejs.org): latest version of `v22`, `v24` or `v26` - any other major version is not supported.
   - [Homebridge](https://homebridge.io): `v1.6` or above - refer to link for more information and installation instructions.
-  - For bluetooth connectivity, it may be necessary to install extra packages on your system, see [Bluetooth Control](https://github.com/homebridge-plugins/homebridge-govee/wiki/Bluetooth-Control). Bluetooth works best when using a Raspberry Pi, not been tested on Windows, and Mac devices are unsupported.
+  - For bluetooth connectivity, it may be necessary to install extra packages on your system, see [Bluetooth Control](https://github.com/homebridge-plugins/homebridge-govee/wiki/Bluetooth-Control). Bluetooth works best when using a Raspberry Pi, and has not been tested on Windows. On macOS, the plugin resolves BLE devices via their advertised name (macOS does not expose bluetooth MAC addresses), and the `node` binary running Homebridge needs Bluetooth permission in System Settings → Privacy & Security → Bluetooth.
 
 ### Setup
 

package/lib/connection/ble.js

@@ -147,11 +147,12 @@ export default class BLEConnection {
               raw,
             })}`
 
-            // Bluetooth is a broadcast medium, so this scan hears every Govee
-            // device in range - including a neighbour's, which is not something
-            // the owner can do anything about. Only a device on this account is
-            // worth putting in front of them.
-            if (this.platform.hasBleDevice(address)) {
+            // Only one of this account's own sensors is worth putting in front
+            // of someone: that is the case where the plugin should be reading
+            // the broadcast and cannot. A light of theirs broadcasts just as
+            // often but is driven over aws/lan/ble, and an address that is not
+            // on the account at all may belong to a neighbour.
+            if (this.platform.hasBleSensor(address)) {
               this.log.warn(line)
             } else {
               this.log.debug(line)
@@ -389,7 +390,9 @@ export default class BLEConnection {
     let timeoutId
     try {
       return await Promise.race([
-        btClient.connectAsync(address),
+        process.platform === 'darwin'
+          ? this.connectByNameDarwin(address, timeout)
+          : btClient.connectAsync(address),
         new Promise((_, reject) => {
           timeoutId = setTimeout(() => reject(new Error('Connection timeout')), timeout)
         }),
@@ -399,6 +402,49 @@ export default class BLEConnection {
     }
   }
 
+  // macOS: CoreBluetooth never exposes MAC addresses, so connect-by-address can
+  // never resolve. Govee devices advertise a local name whose suffix is the last
+  // two bytes of their MAC (e.g. Govee_H617A_325A for ...:32:5A), so scan and
+  // match on that instead, then connect to the discovered peripheral directly.
+  async connectByNameDarwin(address, timeout) {
+    const suffix = address.replace(/:/g, '').slice(-4).toLowerCase()
+    this.darwinPeripheralCache = this.darwinPeripheralCache ?? new Map()
+    const cached = this.darwinPeripheralCache.get(suffix)
+    if (cached) {
+      try {
+        await cached.connectAsync()
+        return cached
+      } catch (err) {
+        this.darwinPeripheralCache.delete(suffix)
+        this.log.debug('[BLE] cached peripheral for %s failed (%s), rescanning.', suffix, err.message)
+      }
+    }
+    const peripheral = await new Promise((resolve, reject) => {
+      let done = false
+      function onDiscover(p) {
+        const name = (p.advertisement?.localName ?? '').toLowerCase()
+        if (name.endsWith(suffix) && (name.startsWith('govee') || name.startsWith('ihoment'))) {
+          finish(resolve, p)
+        }
+      }
+      function finish(fn, value) {
+        if (done) {
+          return
+        }
+        done = true
+        btClient.removeListener('discover', onDiscover)
+        btClient.stopScanningAsync().catch(() => {})
+        fn(value)
+      }
+      btClient.on('discover', onDiscover)
+      btClient.startScanningAsync([], true).catch(err => finish(reject, err))
+      setTimeout(() => finish(reject, new Error(`no peripheral advertising name suffix ${suffix} found in scan`)), Math.max(timeout - 1000, 4000))
+    })
+    this.darwinPeripheralCache.set(suffix, peripheral)
+    await peripheral.connectAsync()
+    return peripheral
+  }
+
   async writeWithTimeout(characteristic, buffer, timeout) {
     let timeoutId
     try {

package/lib/platform.js

@@ -566,18 +566,18 @@ export default class {
 
     // Real-time channels
     if (this.awsClient) {
-      realtime.push(`AWS IoT MQTT (${awsCount} devices)`)
+      realtime.push(`AWS IoT MQTT (${awsCount} device(s))`)
     }
     if (this.openApiClient?.mqttConnected) {
-      realtime.push(`OpenAPI MQTT (${openApiCount} devices)`)
+      realtime.push(`OpenAPI MQTT (${openApiCount} device(s))`)
     }
     if (this.lanClient && lanCount > 0) {
-      realtime.push(`LAN UDP (${lanCount} devices)`)
+      realtime.push(`LAN UDP (${lanCount} device(s))`)
     }
 
     // Polling intervals
     if (this.refreshAWSInterval) {
-      polling.push(`AWS every 60s (${awsCount} devices)`)
+      polling.push(`AWS every 60s (${awsCount} device(s))`)
     }
     if (this.refreshHTTPInterval) {
       polling.push(`HTTP every ${this.config.httpRefreshTime}s (sensors)`)
@@ -1061,19 +1061,31 @@ export default class {
   }
 
   /**
-   * Whether a bluetooth address belongs to one of this account's devices.
+   * Whether a bluetooth address belongs to one of this account's sensors.
    *
-   * Bluetooth is a broadcast medium: a scan hears every Govee device in range,
-   * including a neighbour's. Without this the plugin cannot tell the two apart,
-   * and asking someone to report a device that is not theirs is noise.
+   * An undecodable broadcast is only worth putting in front of someone when it
+   * came from a sensor of theirs, because a sensor is the one kind of device
+   * whose readings arrive this way and so the one kind the plugin is failing.
+   * The two cases this deliberately leaves quiet:
+   *
+   * - a light or appliance of theirs, which also broadcasts constantly but is
+   *   controlled over aws/lan/ble and has nothing to gain from being decoded
+   * - an address that is not on this account at all, which may be a neighbour's
+   *   device and is not something the owner can act on
    */
-  hasBleDevice(address) {
+  hasBleSensor(address) {
     if (!address) {
       return false
     }
     const wanted = String(address).toLowerCase()
+    // Any list named sensor* counts, so a new sensor type is covered on the day
+    // it is added rather than needing this list updated too
+    const sensorModels = Object.keys(platformConsts.models)
+      .filter(key => key.startsWith('sensor'))
+      .flatMap(key => platformConsts.models[key])
     return [...devicesInHB.values()].some(
-      accessory => String(accessory.context.bleAddress || '').toLowerCase() === wanted,
+      accessory => String(accessory.context.bleAddress || '').toLowerCase() === wanted
+        && sensorModels.includes(accessory.context.gvModel),
     )
   }
 

package/package.json

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