Bluetooth Low Energy (BLE) library written with pure Node.js (no bindings) - baked by Bluez via DBus
npm install node-bleBluetooth Low Energy (BLE) library written with pure Node.js (no bindings) - baked by Bluez via DBus
It leverages the bluez driver, a component supported by the following platforms and distributions
node-ble has been tested on the following operating systems:
- Raspbian
- Ubuntu
- Debian
sh
npm install node-ble
`Quick start guide
Provide permissions
In order to allow a connection with the DBus daemon, you have to set up right permissions.Execute the following command, in order to create the file
, configured with the current user id (Note: You may need to manually change the user id).`sh
echo ' "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
`STEP 1: Get Adapter
To start a Bluetooth Low Energy (BLE) connection you need a Bluetooth adapter instance.javascript
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 the adapter instance in order to get a remote Bluetooth device, then connect and interact with the GATT (Generic Attribute Profile) server.javascript
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.
javascript
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.
javascript
const service2 = await gattServer.getPrimaryService('uuid')
const characteristic2 = await service2.getCharacteristic('uuid')
characteristic2.on('valuechanged', buffer => {
console.log(buffer)
})
await characteristic2.startNotifications()
`STEP 5: Disconnect
When you have done you can stop notifications, disconnect and destroy the session.
javascript
await characteristic2.stopNotifications()
await device.disconnect()
destroy()
`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 #20; Upgrades deps
- 1.6 - Upgrades deps and removes some dependencies; migrates to npm; improves gh-actions
- 1.7 - Fixes compatibility issue #30; Adds JSdoc; Deprecates NodeJS 10 and 12; Upgrades deps;
- 1.8 - Upgrades deps and gh-actions os; Adds Bluetooth.activeAdapters() func #45;
- 1.9 - Upgrades deps; Adds writeValueWithoutResponse() and writeValueWithResponse methods #47; Improves typescript definition #48
- 1.10 - Upgrades deps and gh-actions; Fixes memory leak #37; Makes MAC Address case insensitive
- 1.11 - Upgrades deps; Fixes doc #69; Adds getManufacturerData and getAdvertisingData functions on Device #67; Adds getServiceData functions on Device`; Improves pre-requisite doc section #68