macOS Fixes

Audit remaining address-only paths
Add id-based BLE lookups
Add manufacturer MAC fallback
Broaden discovery filters safely
Add macOS/id-only regressions

Author: donavanbecker

package.json

@@ -46,6 +46,7 @@
     "test": "vitest run",
     "test:watch": "vitest watch",
     "test-coverage": "npm run test -- --coverage",
+    "ble:scan": "node tmp-switchbot-scan.mjs",
     "docs": "typedoc",
     "lint-docs": "typedoc --emit none --treatWarningsAsErrors"
   },

src/ble.ts

@@ -11,7 +11,7 @@ import { EventEmitter } from 'node:events'
 
 import { BLENotAvailableError, DeviceNotFoundError } from './errors.js'
 import { BLE_COMMAND_TIMEOUT, BLE_CONNECT_TIMEOUT, BLE_NOTIFY_CHARACTERISTIC_UUID, BLE_SCAN_TIMEOUT, BLE_SERVICE_UUID, BLE_WRITE_CHARACTERISTIC_UUID, DEVICE_MODEL_MAP } from './settings.js'
-import { Logger, normalizeMAC, withTimeout } from './utils/index.js'
+import { Logger, macToDeviceId, normalizeMAC, withTimeout, extractMacFromManufacturerData } from './utils/index.js'
 
 /**
  * BLE Scanner for discovering SwitchBot devices
@@ -124,8 +124,14 @@ export class BLEScanner extends EventEmitter {
       }
 
       for (const serviceDataItem of advertisement.serviceData) {
-        // SwitchBot service UUID
-        if (serviceDataItem.uuid !== 'fd3d' && serviceDataItem.uuid !== '0000fd3d-0000-1000-8000-00805f9b34fb') {
+        // SwitchBot service UUID (current: fd3d, legacy: 000d)
+        const uuid = typeof serviceDataItem.uuid === 'string' ? serviceDataItem.uuid.toLowerCase() : ''
+        const isSwitchBotUUID = uuid === 'fd3d' || 
+                               uuid === '0000fd3d-0000-1000-8000-00805f9b34fb' ||
+                               uuid === '000d' ||
+                               uuid === '0000000d-0000-1000-8000-00805f9b34fb'
+        
+        if (!isSwitchBotUUID) {
           continue
         }
 
@@ -135,17 +141,37 @@ export class BLEScanner extends EventEmitter {
           continue
         }
 
-        const mac = normalizeMAC(address)
+        let normalizedAddress = typeof address === 'string' && address.length > 0 ? normalizeMAC(address) : undefined
+
+        // Fallback to manufacturer data MAC if service data address is empty
+        if (!normalizedAddress) {
+          const manufacturerMac = extractMacFromManufacturerData(peripheral.advertisement.manufacturerData)
+          if (manufacturerMac) {
+            normalizedAddress = manufacturerMac
+          }
+        }
+
+        const fallbackId = typeof peripheral.id === 'string' && peripheral.id.length > 0
+          ? peripheral.id
+          : (normalizedAddress ? macToDeviceId(normalizedAddress) : undefined)
+
+        if (!fallbackId) {
+          this.logger.debug('Skipping BLE discovery with no address and no peripheral id')
+          continue
+        }
+
         const advertisement: BLEAdvertisement = {
-          id: peripheral.id,
-          address: mac,
+          id: fallbackId,
+          address: normalizedAddress,
+          isAddressable: normalizedAddress !== undefined,
           rssi,
           serviceData,
         }
 
-        this.discoveredDevices.set(mac, advertisement)
+        const discoveryKey = normalizedAddress ?? `id:${fallbackId}`
+        this.discoveredDevices.set(discoveryKey, advertisement)
         this.emit('discover', advertisement)
-        this.logger.debug(`Discovered ${serviceData.modelName} at ${mac}`)
+        this.logger.debug(`Discovered ${serviceData.modelName} at ${normalizedAddress ?? fallbackId}`)
       }
     } catch (error) {
       this.logger.error('Error handling discovery', error)
@@ -247,10 +273,21 @@ export class BLEScanner extends EventEmitter {
   }
 
   /**
-   * Get discovered device by MAC
+   * Get discovered device by MAC or BLE ID
    */
-  getDevice(mac: string): BLEAdvertisement | undefined {
-    return this.discoveredDevices.get(normalizeMAC(mac))
+  getDevice(mac: string, bleId?: string): BLEAdvertisement | undefined {
+    // Try MAC lookup first
+    const byMac = this.discoveredDevices.get(normalizeMAC(mac))
+    if (byMac) {
+      return byMac
+    }
+
+    // Fall back to ID-based lookup
+    if (bleId) {
+      return this.discoveredDevices.get(`id:${bleId}`)
+    }
+
+    return undefined
   }
 
   /**
@@ -263,11 +300,11 @@ export class BLEScanner extends EventEmitter {
   /**
    * Wait for specific device
    */
-  async waitForDevice(mac: string, timeoutMs = BLE_SCAN_TIMEOUT): Promise<BLEAdvertisement> {
+  async waitForDevice(mac: string, timeoutMs = BLE_SCAN_TIMEOUT, bleId?: string): Promise<BLEAdvertisement> {
     const normalizedMac = normalizeMAC(mac)
 
-    // Check if already discovered
-    const existing = this.discoveredDevices.get(normalizedMac)
+    // Check if already discovered (try MAC first, then ID)
+    const existing = this.discoveredDevices.get(normalizedMac) || (bleId ? this.discoveredDevices.get(`id:${bleId}`) : undefined)
     if (existing) {
       return existing
     }
@@ -276,7 +313,10 @@ export class BLEScanner extends EventEmitter {
     return withTimeout(
       new Promise<BLEAdvertisement>((resolve) => {
         const handler = (advertisement: BLEAdvertisement) => {
-          if (normalizeMAC(advertisement.address) === normalizedMac) {
+          // Match by address (if available) or by ID
+          const matches = (advertisement.address && normalizeMAC(advertisement.address) === normalizedMac) ||
+                         (bleId && advertisement.id === bleId)
+          if (matches) {
             this.off('discover', handler)
             resolve(advertisement)
           }
@@ -368,9 +408,20 @@ export class BLEConnection {
 
     this.logger.info(`Connecting to ${mac}`)
 
-    // Find peripheral
+    // Find peripheral (by address or ID)
     const peripherals = await this.noble.peripherals || []
-    const peripheral = peripherals.find((p: any) => normalizeMAC(p.address) === normalizedMac)
+    let peripheral: any
+
+    // Try to find by normalized MAC first
+    if (mac.startsWith('id:')) {
+      // ID-based lookup: extract the ID and find by peripheral.id
+      const bleId = mac.substring(3)
+      // Look through peripherals to find matching ID
+      peripheral = peripherals.find((p: any) => p.id === bleId)
+    } else {
+      // MAC-based lookup
+      peripheral = peripherals.find((p: any) => p.address && normalizeMAC(p.address) === normalizedMac)
+    }
 
     if (!peripheral) {
       throw new DeviceNotFoundError(mac)

src/devices/base.ts

@@ -46,6 +46,26 @@ export abstract class SwitchBotDevice extends EventEmitter {
   protected enableCircuitBreaker: boolean
   protected enableRetry: boolean
 
+  private defineCompatibilityProperties(): void {
+    const properties: Array<'id' | 'name' | 'deviceType' | 'mac' | 'activeConnection'> = ['id', 'name', 'deviceType', 'mac', 'activeConnection']
+
+    for (const property of properties) {
+      Object.defineProperty(this, property, {
+        enumerable: true,
+        configurable: true,
+        get: () => {
+          const value = this.info[property]
+
+          if ((property === 'id' || property === 'mac') && typeof value === 'string' && value.length === 0) {
+            return undefined
+          }
+
+          return value
+        },
+      })
+    }
+  }
+
   constructor(
     protected info: DeviceInfo,
     options: {
@@ -63,6 +83,8 @@ export abstract class SwitchBotDevice extends EventEmitter {
   ) {
     super()
 
+    this.defineCompatibilityProperties()
+
     this.logger = new Logger(`${info.deviceType}:${info.id}`, options.logLevel)
     this.bleConnection = options.bleConnection
     this.apiClient = options.apiClient
@@ -105,8 +127,8 @@ export abstract class SwitchBotDevice extends EventEmitter {
   /**
    * Get device ID (property accessor for convenience)
    */
-  get id(): string {
-    return this.info.id
+  get id(): string | undefined {
+    return this.info.id.length > 0 ? this.info.id : undefined
   }
 
   /**
@@ -141,14 +163,14 @@ export abstract class SwitchBotDevice extends EventEmitter {
    * Get MAC address (if available)
    */
   getMAC(): string | undefined {
-    return this.info.mac
+    return this.info.mac && this.info.mac.length > 0 ? this.info.mac : undefined
   }
 
   /**
    * Get MAC address (property accessor for convenience)
    */
   get mac(): string | undefined {
-    return this.info.mac
+    return this.info.mac && this.info.mac.length > 0 ? this.info.mac : undefined
   }
 
   /**
@@ -215,7 +237,8 @@ export abstract class SwitchBotDevice extends EventEmitter {
       const buffer = Buffer.isBuffer(command) ? command : Buffer.from(command)
 
       const startTime = Date.now()
-      await this.bleConnection!.write(this.info.mac!, buffer)
+      const mac = this.info.mac ?? `id:${this.info.bleId}`
+      await this.bleConnection!.write(mac, buffer)
       const latencyMs = Date.now() - startTime
 
       // Record success
@@ -474,7 +497,7 @@ export abstract class SwitchBotDevice extends EventEmitter {
     try {
       this.logger.debug('Reading BLE status')
       const startTime = Date.now()
-      const data = await this.bleConnection!.read(this.info.mac!)
+      const data = await this.bleConnection!.read(this.info.mac ?? `id:${this.info.bleId}`)
       const latencyMs = Date.now() - startTime
 
       if (this.enableConnectionIntelligence) {

src/devices/wo-hand.ts

@@ -119,10 +119,11 @@ export class WoHand extends SwitchBotDevice implements BotCommands {
       this.logger.debug('Sending password-protected command', { action })
 
       // Send command via BLE
-      await this.bleConnection!.write(this.info.mac!, command)
+      const mac = this.info.mac ?? `id:${this.info.bleId}`
+      await this.bleConnection!.write(mac, command)
 
       // Read response
-      const responseBuffer = await this.bleConnection!.read(this.info.mac!)
+      const responseBuffer = await this.bleConnection!.read(mac)
 
       // Parse and validate response
       parseBotBleResponse(responseBuffer)

src/switchbot.ts

@@ -40,7 +40,7 @@ import { WoSensorTHPro } from './devices/wo-sensor-th-pro.js'
 import { WoSensorTH } from './devices/wo-sensor-th.js'
 import { WoStrip } from './devices/wo-strip.js'
 import { BLE_SUPPORTED, DEFAULTS, DEVICE_CLASS_MAP } from './settings.js'
-import { Logger } from './utils/index.js'
+import { Logger, macToDeviceId } from './utils/index.js'
 
 /**
  * Device class constructor type
@@ -241,15 +241,23 @@ export class SwitchBot extends EventEmitter {
    * Handle BLE device discovery
    */
   private handleBLEDiscovery(advertisement: any): void {
-    const { address, serviceData, rssi } = advertisement
+    const { id: advertisementId, address, serviceData, rssi } = advertisement
     const deviceType = serviceData.modelName
+    const mac = typeof address === 'string' && address.length > 0 ? address : undefined
+    const deviceId = mac ? macToDeviceId(mac) : advertisementId
+
+    if (!deviceId) {
+      this.logger.warn(`Skipping ${deviceType} BLE discovery: no address or advertisement id`)
+      return
+    }
 
     // Create device info
     const info = {
-      id: address.replace(/:/g, '').toUpperCase(),
+      id: deviceId,
       name: deviceType,
       deviceType,
-      mac: address,
+      mac,
+      bleId: advertisementId,
       connectionTypes: ['ble'] as any,
       activeConnection: undefined,
       battery: serviceData.battery,
@@ -262,7 +270,7 @@ export class SwitchBot extends EventEmitter {
     if (device) {
       // Update existing device info
       device.updateInfo({
-        mac: address,
+        mac: mac ?? device.getInfo().mac,
         connectionTypes: [...new Set([...device.getInfo().connectionTypes, 'ble' as ConnectionType])],
         battery: serviceData.battery,
         rssi,

src/types/ble.ts

@@ -192,7 +192,8 @@ export interface RelaySwitchServiceData extends BLEServiceData {
  */
 export interface BLEAdvertisement {
   id: string
-  address: string
+  address?: string
+  isAddressable: boolean
   rssi: number
   serviceData: BLEServiceData
 }

src/types/index.ts

@@ -85,6 +85,8 @@ export interface DeviceInfo {
   model?: string
   /** MAC address (for BLE devices) */
   mac?: string
+  /** BLE peripheral/advertisement ID (for ID-based lookups on macOS) */
+  bleId?: string
   /** Available connection types */
   connectionTypes: ConnectionType[]
   /** Current active connection type */

src/utils/index.ts

@@ -71,6 +71,37 @@ export function macToDeviceId(mac: string): string {
   return mac.replace(COLON_REGEX, '').toUpperCase()
 }
 
+/**
+ * Extract MAC address from manufacturer data (SwitchBot: company ID 0x0969)
+ * Bytes: [2 bytes company ID (69 09)] + [6 bytes MAC] + ...
+ */
+export function extractMacFromManufacturerData(manufacturerDataHex?: unknown): string | undefined {
+  if (!manufacturerDataHex || typeof manufacturerDataHex !== 'string') {
+    return undefined
+  }
+
+  // Check if hex string starts with 6909 (SwitchBot company ID in little-endian)
+  if (!manufacturerDataHex.startsWith('6909')) {
+    return undefined
+  }
+
+  // Extract 6 bytes (12 hex chars) starting at position 4 (after company ID)
+  const macHex = manufacturerDataHex.substring(4, 16)
+  if (macHex.length !== 12) {
+    return undefined
+  }
+
+  // Convert to MAC address format: XX:XX:XX:XX:XX:XX
+  return [
+    macHex.substring(0, 2),
+    macHex.substring(2, 4),
+    macHex.substring(4, 6),
+    macHex.substring(6, 8),
+    macHex.substring(8, 10),
+    macHex.substring(10, 12),
+  ].join(':').toUpperCase()
+}
+
 /**
  * Delay utility
  */

test/devices.test.ts

@@ -76,6 +76,40 @@ describe('device Base Functionality', () => {
       expect(retrievedInfo.mac).toBe('AA:BB:CC:DD:EE:FF')
       expect(retrievedInfo.battery).toBe(95)
     })
+
+    it('should expose enumerable compatibility properties', () => {
+      const info: DeviceInfo = {
+        id: 'compat-bot-1',
+        name: 'Compat Bot',
+        deviceType: 'WoHand',
+        connectionTypes: ['ble'] as ConnectionType[],
+        mac: 'AA:11:22:33:44:55',
+      }
+
+      const bot = new WoHand(info)
+
+      expect(bot.id).toBe('compat-bot-1')
+      expect(bot.name).toBe('Compat Bot')
+      expect(bot.deviceType).toBe('WoHand')
+      expect(bot.mac).toBe('AA:11:22:33:44:55')
+      expect(Object.keys(bot)).toContain('id')
+    })
+
+    it('should normalize empty compatibility id/mac getters to undefined', () => {
+      const info: DeviceInfo = {
+        id: '',
+        name: 'Compat Empty Bot',
+        deviceType: 'WoHand',
+        connectionTypes: ['ble'] as ConnectionType[],
+        mac: '',
+      }
+
+      const bot = new WoHand(info)
+
+      expect(bot.id).toBeUndefined()
+      expect(bot.getMAC()).toBeUndefined()
+      expect(bot.mac).toBeUndefined()
+    })
   })
 
   describe('woCurtain', () => {