@homebridge-plugins/homebridge-govee 11.32.2-beta.31 → 11.32.2-beta.33

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)
@@ -47,6 +48,8 @@ All notable changes to `@homebridge-plugins/homebridge-govee` will be documented
 - 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 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
+- fix: stop the macOS bluetooth scan leaving its timer running once the device has been found
+- docs: say that macOS bluetooth support is new and ask for reports, rather than stating it works
 
 ## 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 on a Raspberry Pi, and has not been tested on Windows. macOS is newly supported from `v11.32.2` and has only been tried on a handful of devices so far - you will need to give the `node` binary running Homebridge permission under System Settings → Privacy & Security → Bluetooth, and please do report anything that does not work.
 
 ### Setup
 

package/lib/connection/ble.js

@@ -390,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)
         }),
@@ -400,6 +402,54 @@ 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
+      let scanTimeoutId
+      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
+        // The device is usually found in well under a second, so without this
+        // the timer stays live for the rest of its window and holds the event
+        // loop open. The two timeouts above clear theirs the same way.
+        clearTimeout(scanTimeoutId)
+        btClient.removeListener('discover', onDiscover)
+        btClient.stopScanningAsync().catch(() => {})
+        fn(value)
+      }
+      btClient.on('discover', onDiscover)
+      btClient.startScanningAsync([], true).catch(err => finish(reject, err))
+      scanTimeoutId = 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/package.json

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