Package Exports
- node-ble
- node-ble/src/index.js
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (node-ble) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
node-ble
Bluetooth Low Energy (BLE) library written with pure Node.js (no bindings) - baked by Bluez via DBus
Documentation
Pre-requisites
This library works on many architectures supported by Linux. However Windows and Mac OS are not supported.
It leverages the bluez
driver, a component supported by the following platforms and distributions https://www.bluez.org/about.
node-ble has been tested on the following operating systems:
- Raspbian
- Ubuntu
- Debian
Install
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 /etc/dbus-1/system.d/node-ble.conf
, configured with the current user id (Note: You may need to manually change the user id).
echo '<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
"http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
<busconfig>
<policy user="__USERID__">
<allow own="org.bluez"/>
<allow send_destination="org.bluez"/>
<allow send_interface="org.bluez.GattCharacteristic1"/>
<allow send_interface="org.bluez.GattDescriptor1"/>
<allow send_interface="org.freedesktop.DBus.ObjectManager"/>
<allow send_interface="org.freedesktop.DBus.Properties"/>
</policy>
</busconfig>' | sed "s/__USERID__/$(id -un)/" | sudo tee /etc/dbus-1/system.d/node-ble.conf > /dev/null
STEP 1: Get Adapter
To start a Bluetooth Low Energy (BLE) connection you need a Bluetooth adapter instance.
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.
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.
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')
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.
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
async writeValue (value, optionsOrOffset = {})
#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()
andwriteValueWithResponse
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
andgetAdvertisingData
functions onDevice
#67; AddsgetServiceData
functions onDevice
; Improves pre-requisite doc section #68 - 1.12 - Upgrades deps and actions; Fixes memory leak #75; Improved docs with copy-and-paste configuration scripts.
- 1.13 - Upgrades deps; Fixes race condition #77
Contributors
- chrvadala (author)
- pascalopitz
- lupol
- altaircunhajr
- derwehr
- mxc42
- tuxedoxt
- raffone17
- gmacario
- ianchanning
- nmasse-itix
References
- https://git.kernel.org/pub/scm/bluetooth/bluez.git/tree/doc/adapter-api.txt?h=5.64
- https://git.kernel.org/pub/scm/bluetooth/bluez.git/tree/doc/device-api.txt?h=5.64
- https://git.kernel.org/pub/scm/bluetooth/bluez.git/tree/doc/gatt-api.txt?h=5.64
- 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 |
inxi --bluetooth -z | Bluetooth device info |