@stoprocent/noble 2.4.1 → 2.5.0

package/lib/dbus/uuid.js

@@ -0,0 +1,62 @@
+const BLUETOOTH_BASE_SUFFIX = '-0000-1000-8000-00805f9b34fb';
+
+function normalizeUuid (uuid) {
+  if (!uuid) return uuid;
+  const lower = String(uuid).toLowerCase();
+  if (lower.length === 36 && lower.endsWith(BLUETOOTH_BASE_SUFFIX)) {
+    const head = lower.slice(0, 8);
+    if (head.startsWith('0000')) {
+      return head.slice(4);
+    }
+    return head;
+  }
+  return lower.replace(/-/g, '');
+}
+
+function expandUuid (uuid) {
+  if (!uuid) return uuid;
+  const lower = String(uuid).toLowerCase().replace(/-/g, '');
+  if (lower.length === 4) {
+    return `0000${lower}-0000-1000-8000-00805f9b34fb`;
+  }
+  if (lower.length === 8) {
+    return `${lower}-0000-1000-8000-00805f9b34fb`;
+  }
+  if (lower.length === 32) {
+    return `${lower.slice(0, 8)}-${lower.slice(8, 12)}-${lower.slice(12, 16)}-${lower.slice(16, 20)}-${lower.slice(20)}`;
+  }
+  return lower;
+}
+
+function addressToId (address) {
+  return address.replace(/:/g, '').toLowerCase();
+}
+
+function idToAddress (id) {
+  return id.match(/.{1,2}/g).join(':').toUpperCase();
+}
+
+function devicePathToAddress (path) {
+  const m = path.match(/dev_([0-9A-Fa-f_]+)$/);
+  if (!m) return null;
+  return m[1].replace(/_/g, ':').toUpperCase();
+}
+
+function deviceIdFromPath (path) {
+  const address = devicePathToAddress(path);
+  return address ? addressToId(address) : null;
+}
+
+function devicePathFromAddress (adapterPath, address) {
+  return `${adapterPath}/dev_${address.toUpperCase().replace(/:/g, '_')}`;
+}
+
+module.exports = {
+  normalizeUuid,
+  expandUuid,
+  addressToId,
+  idToAddress,
+  devicePathToAddress,
+  deviceIdFromPath,
+  devicePathFromAddress
+};

package/lib/resolve-bindings.js

@@ -6,6 +6,8 @@ function loadBindings (bindingType = null, options = {}) {
   switch (bindingType) {
     case 'hci':
       return new (require('./hci-socket/bindings'))(options);
+    case 'dbus':
+      return new (require('./dbus/bindings'))(options);
     case 'mac':
       return new (require('./mac/bindings'))(options);
     case 'win':
@@ -17,7 +19,7 @@ function loadBindings (bindingType = null, options = {}) {
 
 function getWindowsBindings () {
   const ver = os.release().split('.').map((str) => parseInt(str, 10));
-  const isWin10WithBLE = 
+  const isWin10WithBLE =
     ver[0] > 10 ||
     (ver[0] === 10 && ver[1] > 0) ||
     (ver[0] === 10 && ver[1] === 0 && ver[2] >= 15063);
@@ -26,6 +28,10 @@ function getWindowsBindings () {
 
 function getDefaultBindings (options = {}) {
   const platform = os.platform();
+  const requested = (process.env.NOBLE_BINDINGS || '').toLowerCase();
+  if (requested === 'dbus' || requested === 'hci' || requested === 'mac' || requested === 'win') {
+    return loadBindings(requested, options);
+  }
   if (
     platform === 'linux' ||
     platform === 'freebsd' ||
@@ -44,7 +50,7 @@ function getDefaultBindings (options = {}) {
 }
 
 module.exports = function (bindingType = 'default', options = {}) {
-  const bindings = bindingType === 'default' 
+  const bindings = bindingType === 'default'
     ? getDefaultBindings(options)
     : loadBindings(bindingType, options);
   return new Noble(bindings);

package/package.json

@@ -6,7 +6,7 @@
   "license": "MIT",
   "name": "@stoprocent/noble",
   "description": "A Node.js BLE (Bluetooth Low Energy) central library.",
-  "version": "2.4.1",
+  "version": "2.5.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/stoprocent/noble.git"

package/test/lib/dbus/bindings.test.js

@@ -0,0 +1,412 @@
+const { EventEmitter } = require('events');
+
+// ---- dbus-next mock ----
+// Provides an in-memory BlueZ object tree we can mutate per-test.
+
+class Variant {
+  constructor (signature, value) {
+    this.signature = signature;
+    this.value = value;
+  }
+}
+
+const mockState = {
+  managedObjects: {},
+  ifaceCalls: [],
+  proxies: new Map(), // path -> proxy
+  rootProxy: null,
+  systemBusListeners: []
+};
+const state = mockState;
+
+function v (signature, value) {
+  return new Variant(signature, value);
+}
+
+// Wrap a plain props dict to look like dbus-next's variant-wrapped output
+function wrapDict (obj) {
+  const out = {};
+  for (const [k, val] of Object.entries(obj)) {
+    out[k] = val instanceof Variant ? val : v('v', val);
+  }
+  return out;
+}
+
+function makeIfaceEmitter (extras = {}) {
+  const e = new EventEmitter();
+  Object.assign(e, extras);
+  return e;
+}
+
+function makeProxy (path) {
+  if (state.proxies.has(path)) return state.proxies.get(path);
+
+  const propsIface = makeIfaceEmitter();
+  const interfaces = { 'org.freedesktop.DBus.Properties': propsIface };
+
+  const ifacesAt = state.managedObjects[path] || {};
+  for (const ifaceName of Object.keys(ifacesAt)) {
+    if (interfaces[ifaceName]) continue;
+    interfaces[ifaceName] = makeIfaceEmitter();
+  }
+
+  const recordedCall = (ifaceName, method) => (...args) => {
+    state.ifaceCalls.push({ path, iface: ifaceName, method, args });
+    return Promise.resolve();
+  };
+
+  if (interfaces['org.bluez.Adapter1']) {
+    Object.assign(interfaces['org.bluez.Adapter1'], {
+      SetDiscoveryFilter: recordedCall('org.bluez.Adapter1', 'SetDiscoveryFilter'),
+      StartDiscovery: recordedCall('org.bluez.Adapter1', 'StartDiscovery'),
+      StopDiscovery: recordedCall('org.bluez.Adapter1', 'StopDiscovery')
+    });
+  }
+  if (interfaces['org.bluez.Device1']) {
+    Object.assign(interfaces['org.bluez.Device1'], {
+      Connect: recordedCall('org.bluez.Device1', 'Connect'),
+      Disconnect: recordedCall('org.bluez.Device1', 'Disconnect')
+    });
+  }
+  if (interfaces['org.bluez.GattCharacteristic1']) {
+    Object.assign(interfaces['org.bluez.GattCharacteristic1'], {
+      ReadValue: jest.fn().mockResolvedValue(Buffer.from([0x01, 0x02])),
+      WriteValue: jest.fn().mockResolvedValue(undefined),
+      StartNotify: jest.fn().mockResolvedValue(undefined),
+      StopNotify: jest.fn().mockResolvedValue(undefined)
+    });
+  }
+  if (interfaces['org.bluez.GattDescriptor1']) {
+    Object.assign(interfaces['org.bluez.GattDescriptor1'], {
+      ReadValue: jest.fn().mockResolvedValue(Buffer.from([0x09])),
+      WriteValue: jest.fn().mockResolvedValue(undefined)
+    });
+  }
+
+  if (path === '/') {
+    interfaces['org.freedesktop.DBus.ObjectManager'] = makeIfaceEmitter({
+      GetManagedObjects: jest.fn().mockImplementation(async () => {
+        const out = {};
+        for (const [p, ifs] of Object.entries(state.managedObjects)) {
+          out[p] = {};
+          for (const [iname, props] of Object.entries(ifs)) {
+            out[p][iname] = wrapDict(props);
+          }
+        }
+        return out;
+      })
+    });
+  }
+
+  const proxy = {
+    path,
+    interfaces,
+    getInterface: name => {
+      if (!interfaces[name]) interfaces[name] = makeIfaceEmitter();
+      return interfaces[name];
+    }
+  };
+  state.proxies.set(path, proxy);
+  if (path === '/') state.rootProxy = proxy;
+  return proxy;
+}
+
+const mockBus = {
+  getProxyObject: jest.fn().mockImplementation(async (_service, path) => makeProxy(path)),
+  disconnect: jest.fn()
+};
+
+const mockDbus = {
+  systemBus: jest.fn().mockReturnValue(mockBus),
+  Variant
+};
+
+jest.mock('dbus-next', () => mockDbus, { virtual: true });
+
+// ---- Tests ----
+
+const DbusBindings = require('../../../lib/dbus/bindings');
+
+function resetState (objects = {}) {
+  state.managedObjects = objects;
+  state.ifaceCalls = [];
+  state.proxies.clear();
+  state.rootProxy = null;
+}
+
+function adapterTree (extra = {}) {
+  return {
+    '/org/bluez': { 'org.freedesktop.DBus.ObjectManager': {} },
+    '/org/bluez/hci0': {
+      'org.bluez.Adapter1': {
+        Address: '00:11:22:33:44:55',
+        Powered: true,
+        Discovering: false
+      }
+    },
+    ...extra
+  };
+}
+
+async function flush () {
+  // Allow microtasks (init promise chain) to settle.
+  await new Promise(resolve => setImmediate(resolve));
+  await new Promise(resolve => setImmediate(resolve));
+}
+
+describe('dbus/bindings', () => {
+  beforeEach(() => {
+    resetState(adapterTree());
+  });
+
+  test('start() emits stateChange("poweredOn") and addressChange', async () => {
+    const bindings = new DbusBindings();
+    const states = [];
+    const addresses = [];
+    bindings.on('stateChange', s => states.push(s));
+    bindings.on('addressChange', a => addresses.push(a));
+
+    bindings.start();
+    await flush();
+
+    expect(states).toContain('poweredOn');
+    expect(addresses).toContain('00:11:22:33:44:55');
+  });
+
+  test('emits stateChange("poweredOff") when adapter is unpowered', async () => {
+    resetState(adapterTree({
+      '/org/bluez/hci0': {
+        'org.bluez.Adapter1': { Address: 'AA:BB:CC:DD:EE:FF', Powered: false }
+      }
+    }));
+    const bindings = new DbusBindings();
+    const states = [];
+    bindings.on('stateChange', s => states.push(s));
+
+    bindings.start();
+    await flush();
+
+    expect(states).toContain('poweredOff');
+  });
+
+  test('emits unsupported when no adapter is found', async () => {
+    resetState({ '/org/bluez': { 'org.freedesktop.DBus.ObjectManager': {} } });
+    const bindings = new DbusBindings();
+    const states = [];
+    const warnings = [];
+    bindings.on('stateChange', s => states.push(s));
+    bindings.on('warning', w => warnings.push(w));
+
+    bindings.start();
+    await flush();
+
+    expect(states).toContain('unsupported');
+    expect(warnings.some(w => /No BlueZ adapter/.test(w))).toBe(true);
+  });
+
+  test('startScanning calls SetDiscoveryFilter + StartDiscovery and emits scanStart', async () => {
+    const bindings = new DbusBindings();
+    const scanStarts = [];
+    bindings.on('scanStart', () => scanStarts.push(true));
+
+    bindings.start();
+    await flush();
+
+    bindings.startScanning(['180d'], false);
+    await flush();
+
+    const calls = state.ifaceCalls.filter(c => c.path === '/org/bluez/hci0');
+    expect(calls.map(c => c.method)).toEqual(
+      expect.arrayContaining(['SetDiscoveryFilter', 'StartDiscovery'])
+    );
+    expect(scanStarts.length).toBe(1);
+  });
+
+  test('stopScanning calls StopDiscovery and emits scanStop', async () => {
+    const bindings = new DbusBindings();
+    const scanStops = [];
+    bindings.on('scanStop', () => scanStops.push(true));
+
+    bindings.start();
+    await flush();
+    bindings.startScanning([], false);
+    await flush();
+    bindings.stopScanning();
+    await flush();
+
+    const stopCall = state.ifaceCalls.find(c => c.method === 'StopDiscovery');
+    expect(stopCall).toBeDefined();
+    expect(scanStops.length).toBe(1);
+  });
+
+  test('InterfacesAdded for a Device1 emits discover with parsed advertisement', async () => {
+    const bindings = new DbusBindings();
+    const discoveries = [];
+    bindings.on('discover', (...args) => discoveries.push(args));
+
+    bindings.start();
+    await flush();
+
+    const om = state.rootProxy.getInterface('org.freedesktop.DBus.ObjectManager');
+    om.emit('InterfacesAdded', '/org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF', {
+      'org.bluez.Device1': wrapDict({
+        Address: 'AA:BB:CC:DD:EE:FF',
+        AddressType: 'public',
+        Name: 'Test Device',
+        RSSI: -42,
+        UUIDs: ['0000180d-0000-1000-8000-00805f9b34fb']
+      })
+    });
+    await flush();
+
+    expect(discoveries.length).toBe(1);
+    const [id, address, addressType, connectable, advertisement, rssi] = discoveries[0];
+    expect(id).toBe('aabbccddeeff');
+    expect(address).toBe('AA:BB:CC:DD:EE:FF');
+    expect(addressType).toBe('public');
+    expect(connectable).toBe(true);
+    expect(rssi).toBe(-42);
+    expect(advertisement.localName).toBe('Test Device');
+    expect(advertisement.serviceUuids).toEqual(['180d']);
+  });
+
+  test('discoverServices/Characteristics/Descriptors walk the cached object tree', async () => {
+    const tree = adapterTree({
+      '/org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF': {
+        'org.bluez.Device1': { Address: 'AA:BB:CC:DD:EE:FF', AddressType: 'public', Connected: false }
+      },
+      '/org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF/service0001': {
+        'org.bluez.GattService1': { UUID: '0000180d-0000-1000-8000-00805f9b34fb', Primary: true }
+      },
+      '/org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF/service0001/char0002': {
+        'org.bluez.GattCharacteristic1': {
+          UUID: '00002a37-0000-1000-8000-00805f9b34fb',
+          Flags: ['read', 'notify']
+        }
+      },
+      '/org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF/service0001/char0002/desc0003': {
+        'org.bluez.GattDescriptor1': { UUID: '00002902-0000-1000-8000-00805f9b34fb' }
+      }
+    });
+    resetState(tree);
+
+    const bindings = new DbusBindings();
+    bindings.start();
+    await flush();
+
+    const services = [];
+    const chars = [];
+    const descs = [];
+    bindings.on('servicesDiscover', (...a) => services.push(a));
+    bindings.on('characteristicsDiscover', (...a) => chars.push(a));
+    bindings.on('descriptorsDiscover', (...a) => descs.push(a));
+
+    bindings.discoverServices('aabbccddeeff', []);
+    bindings.discoverCharacteristics('aabbccddeeff', '180d', []);
+    bindings.discoverDescriptors('aabbccddeeff', '180d', '2a37');
+
+    expect(services[0]).toEqual(['aabbccddeeff', ['180d']]);
+    expect(chars[0][0]).toBe('aabbccddeeff');
+    expect(chars[0][1]).toBe('180d');
+    expect(chars[0][2]).toEqual([{ uuid: '2a37', properties: ['read', 'notify'] }]);
+    expect(descs[0][0]).toBe('aabbccddeeff');
+    expect(descs[0][3]).toEqual(['2902']);
+  });
+
+  test('read emits "read" with the characteristic value', async () => {
+    const tree = adapterTree({
+      '/org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF': {
+        'org.bluez.Device1': { Address: 'AA:BB:CC:DD:EE:FF', AddressType: 'public' }
+      },
+      '/org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF/service0001': {
+        'org.bluez.GattService1': { UUID: '0000180d-0000-1000-8000-00805f9b34fb' }
+      },
+      '/org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF/service0001/char0002': {
+        'org.bluez.GattCharacteristic1': {
+          UUID: '00002a37-0000-1000-8000-00805f9b34fb',
+          Flags: ['read']
+        }
+      }
+    });
+    resetState(tree);
+
+    const bindings = new DbusBindings();
+    bindings.start();
+    await flush();
+
+    const reads = [];
+    bindings.on('read', (...a) => reads.push(a));
+
+    bindings.read('aabbccddeeff', '180d', '2a37');
+    await flush();
+
+    expect(reads.length).toBe(1);
+    expect(reads[0][0]).toBe('aabbccddeeff');
+    expect(reads[0][1]).toBe('180d');
+    expect(reads[0][2]).toBe('2a37');
+    expect(Buffer.isBuffer(reads[0][3])).toBe(true);
+    expect(reads[0][4]).toBe(false); // not a notification
+  });
+
+  test('notify(true) calls StartNotify and forwards value updates as notifications', async () => {
+    const charPath = '/org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF/service0001/char0002';
+    const tree = adapterTree({
+      '/org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF': {
+        'org.bluez.Device1': { Address: 'AA:BB:CC:DD:EE:FF', AddressType: 'public' }
+      },
+      '/org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF/service0001': {
+        'org.bluez.GattService1': { UUID: '0000180d-0000-1000-8000-00805f9b34fb' }
+      },
+      [charPath]: {
+        'org.bluez.GattCharacteristic1': {
+          UUID: '00002a37-0000-1000-8000-00805f9b34fb',
+          Flags: ['notify']
+        }
+      }
+    });
+    resetState(tree);
+
+    const bindings = new DbusBindings();
+    bindings.start();
+    await flush();
+
+    const notifies = [];
+    const reads = [];
+    bindings.on('notify', (...a) => notifies.push(a));
+    bindings.on('read', (...a) => reads.push(a));
+
+    bindings.notify('aabbccddeeff', '180d', '2a37', true);
+    await flush();
+
+    const proxy = state.proxies.get(charPath);
+    expect(proxy.interfaces['org.bluez.GattCharacteristic1'].StartNotify).toHaveBeenCalled();
+    expect(notifies[0]).toEqual(['aabbccddeeff', '180d', '2a37', true]);
+
+    // Simulate BlueZ pushing a notification
+    proxy.interfaces['org.freedesktop.DBus.Properties'].emit(
+      'PropertiesChanged',
+      'org.bluez.GattCharacteristic1',
+      wrapDict({ Value: Buffer.from([0xaa]) }),
+      []
+    );
+
+    expect(reads.length).toBe(1);
+    expect(reads[0][4]).toBe(true); // isNotification
+    expect(reads[0][3].equals(Buffer.from([0xaa]))).toBe(true);
+  });
+
+  test('readHandle is unsupported and emits an error', () => {
+    const bindings = new DbusBindings();
+    const events = [];
+    bindings.on('handleRead', (...a) => events.push(a));
+    bindings.readHandle('aabbccddeeff', 0x42);
+    expect(events.length).toBe(1);
+    expect(events[0][3]).toBeInstanceOf(Error);
+    expect(events[0][3].message).toMatch(/not supported/);
+  });
+
+  test('addressToId normalizes a MAC into a noble peripheral id', () => {
+    const bindings = new DbusBindings();
+    expect(bindings.addressToId('AA:BB:CC:DD:EE:FF')).toBe('aabbccddeeff');
+  });
+});

package/test/lib/dbus/uuid.test.js

@@ -0,0 +1,78 @@
+const {
+  normalizeUuid,
+  expandUuid,
+  addressToId,
+  idToAddress,
+  devicePathToAddress,
+  deviceIdFromPath,
+  devicePathFromAddress
+} = require('../../../lib/dbus/uuid');
+
+describe('dbus/uuid', () => {
+  describe('normalizeUuid', () => {
+    test('shortens 16-bit Bluetooth base UUIDs', () => {
+      expect(normalizeUuid('00002a37-0000-1000-8000-00805f9b34fb')).toBe('2a37');
+    });
+
+    test('shortens 32-bit Bluetooth base UUIDs', () => {
+      expect(normalizeUuid('1234abcd-0000-1000-8000-00805f9b34fb')).toBe('1234abcd');
+    });
+
+    test('strips dashes for non-base 128-bit UUIDs', () => {
+      expect(normalizeUuid('6E400001-B5A3-F393-E0A9-E50E24DCCA9E'))
+        .toBe('6e400001b5a3f393e0a9e50e24dcca9e');
+    });
+
+    test('returns falsy values unchanged', () => {
+      expect(normalizeUuid(undefined)).toBeUndefined();
+      expect(normalizeUuid(null)).toBeNull();
+      expect(normalizeUuid('')).toBe('');
+    });
+  });
+
+  describe('expandUuid', () => {
+    test('expands 16-bit short form', () => {
+      expect(expandUuid('2a37')).toBe('00002a37-0000-1000-8000-00805f9b34fb');
+    });
+
+    test('expands 32-bit short form', () => {
+      expect(expandUuid('1234abcd')).toBe('1234abcd-0000-1000-8000-00805f9b34fb');
+    });
+
+    test('expands no-dash 128-bit form', () => {
+      expect(expandUuid('6e400001b5a3f393e0a9e50e24dcca9e'))
+        .toBe('6e400001-b5a3-f393-e0a9-e50e24dcca9e');
+    });
+  });
+
+  describe('addressToId / idToAddress', () => {
+    test('addressToId strips colons and lowercases', () => {
+      expect(addressToId('AA:BB:CC:DD:EE:FF')).toBe('aabbccddeeff');
+    });
+
+    test('idToAddress reverses the transformation', () => {
+      expect(idToAddress('aabbccddeeff')).toBe('AA:BB:CC:DD:EE:FF');
+    });
+  });
+
+  describe('devicePathToAddress / deviceIdFromPath', () => {
+    test('parses BlueZ device path', () => {
+      expect(devicePathToAddress('/org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF'))
+        .toBe('AA:BB:CC:DD:EE:FF');
+      expect(deviceIdFromPath('/org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF'))
+        .toBe('aabbccddeeff');
+    });
+
+    test('returns null for non-device paths', () => {
+      expect(devicePathToAddress('/org/bluez/hci0')).toBeNull();
+      expect(deviceIdFromPath('/org/bluez/hci0')).toBeNull();
+    });
+  });
+
+  describe('devicePathFromAddress', () => {
+    test('builds the BlueZ device path', () => {
+      expect(devicePathFromAddress('/org/bluez/hci0', 'aa:bb:cc:dd:ee:ff'))
+        .toBe('/org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF');
+    });
+  });
+});