Bluetooth Low Energy (BLE) library written with pure Node.js (no bindings) - baked by Bluez via DBus
Bluetooth Low Energy (BLE) library written with pure Node.js (no bindings) - baked by Bluez via DBus
yarn add node-ble
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.confwith the following content (customize with userid)
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()
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()
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()
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)
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()
When you have done you can disconnect and destroy the session.
javascript await device.disconnect() destroy()
const {createBluetooth} = require('node-ble') const {bluetooth, destroy} = createBluetooth()
| Method | Description | | --- | --- | |
Bluetooth bluetooth| |
void destroy()|
Bluetooth
| Method | Description | | --- | --- | |
Promise adapters()| List of available adapters | |
Promise defaultAdapter()| Get an available adapter | |
Promise getAdapter(String adapter)| Get a specific adapter (one of available in
adapters())|
Adapter
| Method | Description | | --- | --- | |
Promise getAddress()| The Bluetooth device address. | |
Promise getAddressType()| The Bluetooth Address Type. One of
publicor
random. | |
Promise getName()| The Bluetooth system name (pretty hostname). | |
Promise getAlias()| The Bluetooth friendly name. | |
Promise isPowered()| Adapter power status. | |
Promise isDiscovering()| Indicates that a device discovery procedure is active. | |
Promise startDiscovery()| Starts the device discovery session. | |
Promise stopDiscovery()| Cancel any previous StartDiscovery transaction. | |
Promise devices()| List of discovered Bluetooth Low Energy devices | |
Promise getDevice(String uuid)| Returns an available Bluetooth Low Energy (
waitDeviceis preferred)| |
Promise waitDevice(String uuid)| Returns a Bluetooth Low Energy device as soon as it is available | |
Promise toString()| User friendly adapter name |
Deviceextends
EventEmitter
| Method | Description | | --- | --- | |
Promise getName()| The Bluetooth remote name. | |
Promise getAddress()| The Bluetooth device address of the remote device. | |
Promise getAddressType()| The Bluetooth Address Type. One of
publicor
random. | |
Promise getAlias()| The name alias for the remote device. | |
Promise getRSSI()| Received Signal Strength Indicator of the remote device. | |
Promise isPaired()| Indicates if the remote device is paired. | |
Promise isConnected()| Indicates if the remote device is currently connected. | |
Promise pair()| Connects to the remote device, initiate pairing and then retrieve GATT primary services (needs a default agent to handle wizard).| |
Promise cancelPair()| This method can be used to cancel a pairing operation initiated by the Pair method. | |
Promise connect()| This is a generic method to connect any profiles the remote device supports that can be connected to and have been flagged as auto-connectable on our side. | |
Promise disconnect()| This method gracefully disconnects all connected profiles and then terminates low-level ACL connection. | |
Promise gatt()| Waits services resolving, then returns a connection to the remote Gatt Server |
Promise toString()| User friendly device name. |
| Event | Description | | --- | --- | |
connect| Connected to device | |
disconnect| Disconnected from device |
GattServer
| Method | Description | | --- | --- | |
Promise services()| List of available services | |
Promise getPrimaryService(String uuid)| Returns a specific Primary Service |
GattService
| Method | Description | | --- | --- | |
Promise isPrimary()| Indicates whether or not this GATT service is a primary service. | |
Promise getUUID()| 128-bit service UUID. | |
Promise characteristics()| List of available characteristic UUIDs. | |
Promise getCharacteristic(String uuid)| Returns a specific characteristic. | |
Promise toString()| User friendly service name. |
GattCharacteristicextends
EventEmitter
| Method | Description | | --- | --- | |
Promise getUUID()| 128-bit characteristic UUID. | |
Promise getFlags()| Defines how the characteristic value can be used. | |
Promise isNotifying()| True, if notifications or indications on this characteristic are currently enabled. | |
Promise readValue(Number offset = 0)| Issues a request to read the value of the characteristic and returns the value if the operation was successful. | |
Promise writeValue(Buffer buffer, Number | WriteValueOptions options = {})| Issues a request to write the value of the characteristic. Default options
{ offset: 0, type: 'reliable' }. | |
Promise startNotifications()| Starts a notification session from this characteristic if it supports value notifications or indications. | |
Promise stopNotifications()| This method will cancel any previous StartNotify transaction. | |
Promise toString()| User friendly characteristic name. |
| Event | Description | | --- | --- | | valuechanged | New value is notified. (invoke
startNotifications()to enable notifications)
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
async writeValue (value, optionsOrOffset = {})#20; Upgrades deps
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.confwith the following content (customize with userid)
yarn test
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.
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
```shell script
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
| 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 |