node-ble

Bluetooth Low Energy (BLE) library written with pure Node.js (no bindings) - baked by Bluez via DBus

Setup

yarn add node-ble

Example

Provide permissions

In order to allow a connection with the DBus daemon, you have to set up right permissions.

Create the file

/etc/dbus-1/system.d/node-ble.conf

STEP 1: Get Adapter

To start a Bluetooth Low Energy (BLE) connection you need a Bluetooth adapter.

const {createBluetooth} = require('node-ble')
const {bluetooth, destroy} = createBluetooth()
const adapter = await bluetooth.defaultAdapter()

STEP 2: Start discovering

In order to find a Bluetooth Low Energy device out, you have to start a discovery operation.

javascript
if (! await adapter.isDiscovering())
  await adapter.startDiscovery()

STEP 3: Get a device, Connect and Get GATT Server

Use an adapter to get a remote Bluetooth device, then connect to it and bind to the GATT (Generic Attribute Profile) server.

const device = await adapter.waitDevice('00:00:00:00:00:00')
await device.connect()
const gattServer = await device.gatt()

STEP 4a: Read and write a characteristic.

const service1 = await gattServer.getPrimaryService('uuid')
const characteristic1 = await service1.getCharacteristic('uuid')
await characteristic1.writeValue(Buffer.from("Hello world"))
const buffer = await characteristic1.readValue()
console.log(buffer)

STEP 4b: Subscribe to a characteristic.

const service2 = await gattServer.getPrimaryService('uuid')
const characteristic2 = await service2.getCharacteristic('uuid')
await characteristic2.startNotifications()
characteristic2.on('valuechanged', buffer => {
  console.log(buffer)
})
await characteristic2.stopNotifications()

STEP 5: Disconnect

When you have done you can disconnect and destroy the session.

javascript
await device.disconnect()
destroy()

Reference

const {createBluetooth} = require('node-ble')
const {bluetooth, destroy} = createBluetooth()

| Method | Description | | --- | --- | |

Bluetooth bluetooth

void destroy()

Bluetooth

| Method | Description | | --- | --- | |

Promise adapters()

Promise defaultAdapter()

Promise getAdapter(String adapter)

adapters()

Adapter

| Method | Description | | --- | --- | |

Promise getAddress()

Promise getAddressType()

public

random

Promise getName()

Promise getAlias()

Promise isPowered()

Promise isDiscovering()

Promise startDiscovery()

Promise stopDiscovery()

Promise devices()

Promise getDevice(String uuid)

waitDevice

Promise waitDevice(String uuid)

Promise toString()

Device

extends

EventEmitter

| Method | Description | | --- | --- | |

Promise getName()

Promise getAddress()

Promise getAddressType()

public

random

Promise getAlias()

Promise getRSSI()

Promise isPaired()

Promise isConnected()

Promise pair()

Promise cancelPair()

Promise connect()

Promise disconnect()

Promise gatt()

Promise toString()

| Event | Description | | --- | --- | |

connect

disconnect

GattServer

| Method | Description | | --- | --- | |

Promise services()

Promise getPrimaryService(String uuid)

GattService

| Method | Description | | --- | --- | |

Promise isPrimary()

Promise getUUID()

Promise characteristics()

Promise getCharacteristic(String uuid)

Promise toString()

GattCharacteristic

extends

EventEmitter

| Method | Description | | --- | --- | |

Promise getUUID()

Promise getFlags()

Promise isNotifying()

Promise readValue(Number offset = 0)

Promise writeValue(Buffer buffer, Number | WriteValueOptions options = {})

{ offset: 0, type: 'reliable' }

Promise startNotifications()

Promise stopNotifications()

Promise toString()

| Event | Description | | --- | --- | | valuechanged | New value is notified. (invoke

startNotifications()

Compatibility

This library works on many architectures supported by Linux. It leverages on Bluez driver, a component supported by the following platforms and distributions https://www.bluez.org/about

Node-ble has been tested on the following environment: - Raspbian GNU/Linux 10 (buster) - Ubuntu 18.04.4 LTS - Ubuntu 20.04 LTS

Changelog

• 0.x - Beta version
• 1.0 - First official version
• 1.1 - Migrates to gh-workflows
• 1.2 - Upgrades deps
• 1.3 - Adds typescript definitions #10
• 1.4 - Upgrades deps
• 1.5 - Adds write options configuration

  async writeValue (value, optionsOrOffset = {})

  #20; Upgrades deps

Contributors

• chrvadala (author)
• pascalopitz
• lupol

Run tests

In order to run test suite you have to set up right DBus permissions.

Create the file

/etc/dbus-1/system.d/node-ble-test.conf

Unit tests

yarn test

End to end (e2e) tests

The end to end test will try to connect to a real bluetooth device and read some characteristics. To do that, you need two different devices.

Device 1

shell script
wget https://git.kernel.org/pub/scm/bluetooth/bluez.git/plain/test/example-advertisement
wget https://git.kernel.org/pub/scm/bluetooth/bluez.git/plain/test/example-gatt-server
python example-advertisement
python example-gatt-server
hcitool dev #this command shows bluetooth mac address

Device 2

```shell script

.env

TESTDEVICE=00:00:00:00:00:00 TESTSERVICE=12345678-1234-5678-1234-56789abcdef0 TESTCHARACTERISTIC=12345678-1234-5678-1234-56789abcdef1 TESTNOTIFYSERVICE=0000180d-0000-1000-8000-00805f9b34fb TESTNOTIFY_CHARACTERISTIC=00002a37-0000-1000-8000-00805f9b34fb ```

shell script
yarn test:e2e

References

• https://git.kernel.org/pub/scm/bluetooth/bluez.git/tree/doc/adapter-api.txt
• https://git.kernel.org/pub/scm/bluetooth/bluez.git/tree/doc/device-api.txt
• https://git.kernel.org/pub/scm/bluetooth/bluez.git/tree/doc/gatt-api.txt
• https://webbluetoothcg.github.io/web-bluetooth - method signatures follow, when possible, WebBluetooth standards
• https://developers.google.com/web/updates/2015/07/interact-with-ble-devices-on-the-web - method signatures follow, when possible, WebBluetooth standards

Similar libraries

• https://github.com/noble/noble
• https://github.com/abandonware/noble (noble fork)
• https://www.npmjs.com/package/node-web-bluetooth

Useful commands

| Command | Description | | --- | --- | | rm -r /var/lib/bluetooth/* | Clean Bluetooth cache | | hciconfig -a | Adapter info | | hcitool dev | Adapter info (through Bluez) | | d-feet | DBus debugging tool | | nvram bluetoothHostControllerSwitchBehavior=never | Only on Parallels |