Node.js implementation of the Web Bluetooth Specification
npm install webbluetooth
Node.js > v10.20.0, which includes npm.
``bash`
$ 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:
OS | x86 | x64 | arm64
--- | --- | --- | ---
Windows | X | X | -
MacOS | - | X | X
Linux (glibc) | - | X | X
To use existing Web Bluetooth scripts, you can simply use the default bluetooth instance in place of the navigator.bluetooth object:
`JavaScript
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:
`JavaScript
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/
callback function to allow the user to select a device
- [x] scanTime - The amount of seconds to scan for the device (default is 10)
- [x] allowAllDevices - Optional flag to automatically allow all devices
- [x] referringDevice - An optional referring device
- [x] adapterIndex - An optional index of bluetooth adapter to use (default is 0)$3
- [x] getAvailability()
- [x] referringDevice
- [x] requestDevice()
- [x] getDevices()
- [x] RequestDeviceOptions.filter.name
- [x] RequestDeviceOptions.filter.namePrefix
- [x] RequestDeviceOptions.filter.services
- [x] RequestDeviceOptions.filter.manufacturerData
- [x] RequestDeviceOptions.filter.serviceData
- [x] RequestDeviceOptions.acceptAllDevices
- [x] RequestDeviceOptions.optionalServices
- [ ] RequestDeviceOptions.exclusionFilters
- [ ] RequestDeviceOptions.optionalManufacturerData - used in advertisements, unsupported in adapter
$3
- [x] id
- [x] name
- [x] gatt
- [x] forget()
- [ ] watchAdvertisements() - unsupported in adapter
- [ ] watchingAdvertisements - unsupported in adapter
$3
- [x] device
- [x] connected
- [x] connect()
- [x] disconnect()
- [x] getPrimaryService()
- [x] getPrimaryServices()
$3
- [x] uuid
- [x] device
- [x] isPrimary
- [x] getCharacteristic()
- [x] getCharacteristics()
- [ ] getIncludedService() - unsupported in adapter
- [ ] getIncludedServices() - unsupported in adapter
$3
- [x] uuid
- [x] service
- [x] value
- [ ] properties.broadcast - unsupported in adapter
- [x] properties.read
- [x] properties.writeWithoutResponse
- [x] properties.write
- [x] properties.notify
- [x] properties.indicate
- [ ] properties.authenticatedSignedWrites - unsupported in adapter
- [ ] properties.reliableWrite - unsupported in adapter
- [ ] properties.writableAuxiliaries - unsupported in adapter
- [x] getDescriptor()
- [x] getDescriptors()
- [x] readValue()
- [x] writeValue()
- [x] writeValueWithResponse()
- [x] writeValueWithoutResponse()
- [x] startNotifications()
- [x] stopNotifications()
$3
- [x] uuid
- [x] characteristic
- [x] value
- [x] readValue()
- [x] writeValue()
$3
- [x] getService()
- [x] getCharacteristic()
- [x] getDescriptor()
- [x] canonicalUUID()
$3
#### Bluetooth
- [ ] availabilitychanged - unsupported in adapter
#### Bluetooth Device
- [x] gattserverdisconnected
- [ ] advertisementreceived - unsupported in adapter
#### Bluetooth Service
- [x] serviceadded
- [ ] servicechanged - unsupported in adapter
- [ ] serviceremoved - unsupported in adapter
#### Bluetooth Characteristic
- [x] characteristicvaluechanged
$3
- [x] Device selector hook
- [x] Examples
- [x] API Documentation
Development
$3
A valid cmake build system
#### Windows
- chocolatey
- cmake
`bash
choco install python visualstudio2019-workload-vctools -y
`If the automatic installation of VS Tools fails or pauses, open the installer GUI to resume installation.
$3
This repository uses a submodule to reference the SimpleBLE library. Clone it as follows:
bash
git clone https://github.com/thegecko/webbluetooth
cd webbluetooth
git submodule update --init
`$3
To build the SimpleBLE module, bindings and TypeScriptsource, run:
bash
yarn build:all
`$3
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:
bash
yarn test
``