Node Web Bluetooth

Node.js implementation of the Web Bluetooth Specification

Prerequisites

Node.js > v10.20.0, which includes npm.

Installation

$ npm install webbluetooth

Getting Started

See the examples or view the API documentation at:

https://thegecko.github.io/webbluetooth/

Supported Platforms

Binaries are built to support the following platforms:

Usage

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()

Using the default bluetooth instance

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.

Creating your own bluetooth instances

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();
...

Specification

The Web Bluetooth specification can be found here:

https://webbluetoothcg.github.io/web-bluetooth/

Implementation Status

Functions

• <input checked="" disabled="" type="checkbox"> getAdapters() - list available bluetooth adapters

new Bluetooth options

• <input checked="" disabled="" type="checkbox"> deviceFound - A device found callback function to allow the user to select a device
• <input checked="" disabled="" type="checkbox"> scanTime - The amount of seconds to scan for the device (default is 10)
• <input checked="" disabled="" type="checkbox"> allowAllDevices - Optional flag to automatically allow all devices
• <input checked="" disabled="" type="checkbox"> referringDevice - An optional referring device
• <input checked="" disabled="" type="checkbox"> adapterIndex - An optional index of bluetooth adapter to use (default is 0)

bluetooth

• <input checked="" disabled="" type="checkbox"> getAvailability()
• <input checked="" disabled="" type="checkbox"> referringDevice
• <input checked="" disabled="" type="checkbox"> requestDevice()
• <input checked="" disabled="" type="checkbox"> getDevices()
• <input checked="" disabled="" type="checkbox"> RequestDeviceOptions.filter.name
• <input checked="" disabled="" type="checkbox"> RequestDeviceOptions.filter.namePrefix
• <input checked="" disabled="" type="checkbox"> RequestDeviceOptions.filter.services
• <input checked="" disabled="" type="checkbox"> RequestDeviceOptions.filter.manufacturerData
• <input checked="" disabled="" type="checkbox"> RequestDeviceOptions.filter.serviceData
• <input checked="" disabled="" type="checkbox"> RequestDeviceOptions.acceptAllDevices
• <input checked="" disabled="" type="checkbox"> RequestDeviceOptions.optionalServices
• <input disabled="" type="checkbox"> RequestDeviceOptions.exclusionFilters
• <input disabled="" type="checkbox"> RequestDeviceOptions.optionalManufacturerData - used in advertisements, unsupported in adapter

BluetoothDevice

• <input checked="" disabled="" type="checkbox"> id
• <input checked="" disabled="" type="checkbox"> name
• <input checked="" disabled="" type="checkbox"> gatt
• <input checked="" disabled="" type="checkbox"> forget()
• <input disabled="" type="checkbox"> watchAdvertisements() - unsupported in adapter
• <input disabled="" type="checkbox"> watchingAdvertisements - unsupported in adapter

BluetoothRemoteGATTServer

• <input checked="" disabled="" type="checkbox"> device
• <input checked="" disabled="" type="checkbox"> connected
• <input checked="" disabled="" type="checkbox"> connect()
• <input checked="" disabled="" type="checkbox"> disconnect()
• <input checked="" disabled="" type="checkbox"> getPrimaryService()
• <input checked="" disabled="" type="checkbox"> getPrimaryServices()

BluetoothRemoteGATTService

• <input checked="" disabled="" type="checkbox"> uuid
• <input checked="" disabled="" type="checkbox"> device
• <input checked="" disabled="" type="checkbox"> isPrimary
• <input checked="" disabled="" type="checkbox"> getCharacteristic()
• <input checked="" disabled="" type="checkbox"> getCharacteristics()
• <input disabled="" type="checkbox"> getIncludedService() - unsupported in adapter
• <input disabled="" type="checkbox"> getIncludedServices() - unsupported in adapter

BluetoothRemoteGATTCharacteristic

• <input checked="" disabled="" type="checkbox"> uuid
• <input checked="" disabled="" type="checkbox"> service
• <input checked="" disabled="" type="checkbox"> value
• <input disabled="" type="checkbox"> properties.broadcast - unsupported in adapter
• <input checked="" disabled="" type="checkbox"> properties.read
• <input checked="" disabled="" type="checkbox"> properties.writeWithoutResponse
• <input checked="" disabled="" type="checkbox"> properties.write
• <input checked="" disabled="" type="checkbox"> properties.notify
• <input checked="" disabled="" type="checkbox"> properties.indicate
• <input disabled="" type="checkbox"> properties.authenticatedSignedWrites - unsupported in adapter
• <input disabled="" type="checkbox"> properties.reliableWrite - unsupported in adapter
• <input disabled="" type="checkbox"> properties.writableAuxiliaries - unsupported in adapter
• <input checked="" disabled="" type="checkbox"> getDescriptor()
• <input checked="" disabled="" type="checkbox"> getDescriptors()
• <input checked="" disabled="" type="checkbox"> readValue()
• <input checked="" disabled="" type="checkbox"> writeValue()
• <input checked="" disabled="" type="checkbox"> writeValueWithResponse()
• <input checked="" disabled="" type="checkbox"> writeValueWithoutResponse()
• <input checked="" disabled="" type="checkbox"> startNotifications()
• <input checked="" disabled="" type="checkbox"> stopNotifications()

BluetoothRemoteGATTDescriptor

• <input checked="" disabled="" type="checkbox"> uuid
• <input checked="" disabled="" type="checkbox"> characteristic
• <input checked="" disabled="" type="checkbox"> value
• <input checked="" disabled="" type="checkbox"> readValue()
• <input checked="" disabled="" type="checkbox"> writeValue()

BluetoothUUID

• <input checked="" disabled="" type="checkbox"> getService()
• <input checked="" disabled="" type="checkbox"> getCharacteristic()
• <input checked="" disabled="" type="checkbox"> getDescriptor()
• <input checked="" disabled="" type="checkbox"> canonicalUUID()

Events

Bluetooth

• <input disabled="" type="checkbox"> availabilitychanged - unsupported in adapter

Bluetooth Device

• <input checked="" disabled="" type="checkbox"> gattserverdisconnected
• <input disabled="" type="checkbox"> advertisementreceived - unsupported in adapter

Bluetooth Service

• <input checked="" disabled="" type="checkbox"> serviceadded
• <input disabled="" type="checkbox"> servicechanged - unsupported in adapter
• <input disabled="" type="checkbox"> serviceremoved - unsupported in adapter

Bluetooth Characteristic

• <input checked="" disabled="" type="checkbox"> characteristicvaluechanged

Other

• <input checked="" disabled="" type="checkbox"> Device selector hook
• <input checked="" disabled="" type="checkbox"> Examples
• <input checked="" disabled="" type="checkbox"> API Documentation

Development

Cloning

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

Building

To build the SimpleBLE module, bindings and TypeScriptsource, run:

yarn build:all

Testing

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

Changelog

[3.3.2] - 2025-03-08

Fixed

• Fixed connecting to multiple devices - 299 (Rob Moran)

Added

• Added ability to list and select bluetooth adapter - 189 (Ingo Fischer)
• Added Linux arm64 support - 309 (Rob Moran)
• Added prebuild binaries to npm package - 309 (Rob Moran)
• Exposed MTU in _adData - 300 (Rob Moran)

[3.2.1] - 2024-02-12

Fixed

• Fixed having separate notifications for characteristics 109 (Daníel Grétarsson)
• Updated multiple dependant packages including cmakejs and prebuild

[3.1.0] - 2023-08-22

Fixed

• Fixed write without response - 91 (Rob Moran)

[3.0.3] - 2023-06-01

Added

• Added prebuild for Arm-based MacOS - 55 (Rob Moran)

[3.0.2] - 2023-06-01

Changed

• Backend changed from noble to use SimpleBLE v0.6.1 - 46 (Alex Shaw)
• TypeScript adapter added to use SimpleBLE - 46 (Rob Moran)