webbluetooth

Node Web Bluetooth

Node.js implementation of the Web Bluetooth Specification

Prerequisites

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

Installation

$ npm install webbluetooth

Getting Started

See the examples or view the API documentation at:

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

Usage

The module exports a default navigator.bluetooth instance, the Bluetooth class to allow you to instantiate your own bluetooth instances and some helper methods:

• bluetooth
• Bluetooth()
• getCanonicalUUID()
• getServiceUUID()
• getCharacteristicUUID()
• getDescriptorUUID()

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

bluetooth

• referringDevice - specification unstable
• getAvailability() - specification unstable
• requestDevice()
• getDevices()
• RequestDeviceOptions.name
• RequestDeviceOptions.namePrefix
• RequestDeviceOptions.services
• RequestDeviceOptions.optionalServices
• RequestDeviceOptions.acceptAllDevices
• RequestDeviceOptions.manufacturerData - specification unstable
• RequestDeviceOptions.serviceData - specification unstable

BluetoothDevice

• id
• name
• gatt
• forget
• watchingAdvertisements - specification unstable
• watchAdvertisements() - specification unstable
• unwatchAdvertisements() - specification unstable

BluetoothRemoteGATTServer

• connected
• device
• connect()
• disconnect()
• getPrimaryService()
• getPrimaryServices()

BluetoothRemoteGATTService

• device
• uuid
• isPrimary
• getCharacteristic()
• getCharacteristics()
• getIncludedService()
• getIncludedServices()

BluetoothRemoteGATTCharacteristic

• service
• uuid
• properties
• value
• getDescriptor()
• getDescriptors()
• readValue()
• writeValue()
• writeValueWithResponse()
• writeValueWithoutResponse()
• startNotifications()
• stopNotifications()

BluetoothRemoteGATTDescriptor

• characteristic
• uuid
• value
• readValue()
• writeValue()

Events

Bluetooth

• availabilitychanged

Bluetooth Device

• gattserverdisconnected
• advertisementreceived - specification unstable

Bluetooth Service

• serviceadded
• servicechanged - unsupported in noble
• serviceremoved - unsupported in noble

Bluetooth Characteristic

• characteristicvaluechanged

Other

• Device selector hook
• Lookups for known services, characteristics and descriptors
• Canonical UUID helper
• Examples
• API Documentation