Node.js implementation of the Web Bluetooth Specification
Node.js > v10.20.0, which includes npm
.
$ npm install webbluetooth
See the examples or view the API documentation at:
https://thegecko.github.io/webbluetooth/
Binaries are built to support the following platforms:
- MacOS (x64 and arm64)
- Windows (x86 and x64)
- Linux (x64 glibc)
The module exports a default navigator.bluetooth
instance, the Bluetooth
class to allow you to instantiate your own bluetooth instances and the Bluetooth helper methods:
- bluetooth
- Bluetooth()
- BluetoothUUID.getService()
- BluetoothUUID.getCharacteristic()
- BluetoothUUID.getDescriptor()
- BluetoothUUID.canonicalUUID()
To use existing Web Bluetooth scripts, you can simply use the default bluetooth
instance in place of the navigator.bluetooth
object:
const bluetooth = require('webbluetooth').bluetooth;
const device = await bluetooth.requestDevice({
filters:[{ services:[ 'heart_rate' ] }]
});
const server = await device.gatt.connect();
...
The first device matching the filters will be returned.
You may want to create your own instance of the Bluetooth
class. For example, to inject a device chooser function or control the referring device:
const Bluetooth = require('webbluetooth').Bluetooth;
const deviceFound = (device, selectFn) => {
// If device can be automatically selected, do so by returning true
if (device.name === 'myName') return true;
// Otherwise store the selectFn somewhere and execute it later to select this device
};
const bluetooth = new Bluetooth({ deviceFound });
const device = await bluetooth.requestDevice({
filters:[{ services:[ 'heart_rate' ] }]
});
const server = await device.gatt.connect();
...
The Web Bluetooth specification can be found here:
https://webbluetoothcg.github.io/web-bluetooth/
- getAvailability() - unsupported in adapter
- referringDevice
- requestDevice()
- getDevices()
- RequestDeviceOptions.filter.name
- RequestDeviceOptions.filter.namePrefix
- RequestDeviceOptions.filter.services
- RequestDeviceOptions.filter.manufacturerData
- RequestDeviceOptions.filter.serviceData
- RequestDeviceOptions.acceptAllDevices
- RequestDeviceOptions.optionalServices
- RequestDeviceOptions.exclusionFilters
- RequestDeviceOptions.optionalManufacturerData - used in advertisements, unsupported in adapter
- id
- name
- gatt
- forget()
- watchAdvertisements() - unsupported in adapter
- watchingAdvertisements - unsupported in adapter
- device
- connected
- connect()
- disconnect()
- getPrimaryService()
- getPrimaryServices()
- uuid
- device
- isPrimary
- getCharacteristic()
- getCharacteristics()
- getIncludedService() - unsupported in adapter
- getIncludedServices() - unsupported in adapter
- uuid
- service
- value
- properties.broadcast - unsupported in adapter
- properties.read
- properties.writeWithoutResponse
- properties.write
- properties.notify
- properties.indicate
- properties.authenticatedSignedWrites - unsupported in adapter
- properties.reliableWrite - unsupported in adapter
- properties.writableAuxiliaries - unsupported in adapter
- getDescriptor()
- getDescriptors()
- readValue()
- writeValue()
- writeValueWithResponse()
- writeValueWithoutResponse()
- startNotifications()
- stopNotifications()
- uuid
- characteristic
- value
- readValue()
- writeValue()
- getService()
- getCharacteristic()
- getDescriptor()
- canonicalUUID()
- availabilitychanged - unsupported in adapter
- gattserverdisconnected
- advertisementreceived - unsupported in adapter
- serviceadded
- servicechanged - unsupported in adapter
- serviceremoved - unsupported in adapter
- characteristicvaluechanged
- Device selector hook
- Examples
- API Documentation
This repository uses a submodule to reference the SimpleBLE library. Clone it as follows:
git clone https://github.com/thegecko/webbluetooth
cd webbluetooth
git submodule update --init
To build the SimpleBLE module, bindings and TypeScriptsource, run:
yarn build:all
The tests are set up to use a BBC micro:bit in range with the following services available:
- Device Info Service (0000180a-0000-1000-8000-00805f9b34fb)
- LED Service (e95dd91d-251d-470a-a062-fa1922dfa9a8)
- Button Service (e95d9882-251d-470a-a062-fa1922dfa9a8)
Sample code and hex file for the v2 micro:bit can be found in the firmware folder.
To run the tests:
yarn test