@homebridge-plugins/homebridge-govee 11.32.2-beta.31 → 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)

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

@@ -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,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/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.32",
   "description": "Homebridge plugin to integrate Govee devices into HomeKit.",
   "author": {
     "name": "bwp91",