README
THIS REPOSITORY IS NO LONGER MAINTAINED
Looking for an alternative? Please have a look at node-ble.
If you are interested in maintaining this repository (and taking ownership of it), please reach out to me here.
Web Bluetooth API and interactive device picker for node.js, using the awesome noble package
Installation
npm install node-web-bluetooth
This will automatically install noble. Depending on your system environment and the tools installed, noble may or may not work out of the box. Please visit https://github.com/abandonware/noble on how to install all the prerequisites for noble.
Usage
const Bluetooth = require('node-web-bluetooth');
async function connect() {
const device = await Bluetooth.requestDevice({
filters: [
{services: ['heart_rate']}
]
});
const server = await device.gatt.connect();
const service = await server.getPrimaryService('heart_rate');
const char = await service.getCharacteristic('heart_rate_measurement');
await char.startNotifications();
char.on('characteristicvaluechanged', (data) => {
// parse heart-rate data here
});
...
await char.stopNotifications();
await server.disconnect();
}
connect();
Programmatically selecting a device
By default, Bluetooth.requestDevice
shows an interactive list
with all the discovered devices it has found. To programmatically
control the selected device, you can pass in an instance of the RequestDeviceDelegate
class.
const Bluetooth = require('node-web-bluetooth');
class SelectFirstFoundDevice extends Bluetooth.RequestDeviceDelegate {
// Select first device found
onAddDevice(device) {
this.resolve(device);
}
onUpdateDevice(device) {
// Called whenever new advertisement data was received
// for the device
}
// Time-out when device hasn't been found in 20 secs
onStartScan() {
this._timer = setTimeout(() => {
this.reject(new Error('No device found'));
}, 20000);
}
onStopScan() {
if (this._timer) clearTimeout(this._timer);
}
}
async function connect() {
const device = await Bluetooth.requestDevice({
filters: [
{services: ['heart_rate']}
],
delegate: new SelectFirstFoundDevice()
});
...
}
connect();
Customizing the interactive device picker
The header-text and the formatting of the interactive device picker are customizable. To fully customize it, derive a class from it and override its methods.
const Bluetooth = require('node-web-bluetooth');
const device = Bluetooth.requestDevice({
delegate: new Bluetooth.InteractiveRequestDeviceDelegate({
header: 'Set your custom header text here',
format: (device) => `${device.id} - ${device.name}`
})
});
compatibility navigator.bluetooth
In order to achieve full code compatibility with browser code, navigator.bluetooth
is injected into the global scope.
In case the navigator
object already existed, it is
extended with the bluetooth
object. Causing this to work:
require('node-web-bluetooth');
navigator.bluetooth.requestDevice({
...
});
Supported APIs
- Bluetooth.requestDevice()
- Bluetooth.getAvailability()
- Bluetooth.availabilitychanged
Bluetooth.referringDevice(not relevant)- BluetoothDevice.id
- BluetoothDevice.name
- BluetoothDevice.gatt
- BluetoothDevice.uuids
- BluetoothDevice.gattserverdisconnected
- BluetoothDevice.watchAdvertisements()
- BluetoothDevice.advertisementreceived()
- BluetoothRemoteGATTServer.device
- BluetoothRemoteGATTServer.connected
- BluetoothRemoteGATTServer.connect()
- BluetoothRemoteGATTServer.disconnect()
- BluetoothRemoteGATTServer.getPrimaryService()
- BluetoothRemoteGATTServer.getPrimaryServices()
- BluetoothRemoteGATTService.uuid
- BluetoothRemoteGATTService.isPrimary
- BluetoothRemoteGATTService.device
- BluetoothRemoteGATTService.getCharacteristic()
- BluetoothRemoteGATTService.getCharacteristics()
- BluetoothRemoteGATTService.getIncludedService()
- BluetoothRemoteGATTService.getIncludedServices()
- BluetoothRemoteGATTService.serviceadded
- BluetoothRemoteGATTService.servicechanged
- BluetoothRemoteGATTService.serviceremoved
- BluetoothRemoteGATTCharacteristic.service
- BluetoothRemoteGATTCharacteristic.uuid
- BluetoothRemoteGATTCharacteristic.properties
- BluetoothRemoteGATTCharacteristic.value
- BluetoothRemoteGATTCharacteristic.getDescriptor()
- BluetoothRemoteGATTCharacteristic.getDescriptors()
- BluetoothRemoteGATTCharacteristic.readValue()
- BluetoothRemoteGATTCharacteristic.writeValue()
- BluetoothRemoteGATTCharacteristic.writeValueWithResponse()
- BluetoothRemoteGATTCharacteristic.writeValueWithoutResponse()
- BluetoothRemoteGATTCharacteristic.startNotifications()
- BluetoothRemoteGATTCharacteristic.stopNotifications()
- BluetoothRemoteGATTCharacteristic.characteristicvaluechanged
- BluetoothRemoteGATTDescriptor.characteristic
- BluetoothRemoteGATTDescriptor.uuid
- BluetoothRemoteGATTDescriptor.value
- BluetoothRemoteGATTDescriptor.readValue
- BluetoothRemoteGATTDescriptor.writeValue
- Translate characteric names to UUIDs
- Translate descriptor names to UUIDs
Known issues
Due to an implementation restriction in noble, calling BluetoothRemoteGATTService.getCharacteristic(s)
multiple times doesn't work correctly. If you need to obtain multiple characterstics, then do it using a
single call to BluetoothRemoteGATTService.getCharacteristics
.
Resources
- https://webbluetoothcg.github.io/web-bluetooth
- https://github.com/WebBluetoothCG/demos
- https://developer.mozilla.org/en-US/docs/Web/API/Web_Bluetooth_API