Skip to content

thegecko/webbluetooth

This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Folders and files

NameName
Last commit message
Last commit date

Latest commit

5812d7f · Jun 4, 2023
Jun 1, 2023
Nov 3, 2019
Mar 27, 2023
May 27, 2023
Jun 4, 2023
Jun 4, 2023
May 27, 2023
Dec 23, 2022
Jun 7, 2022
Dec 29, 2022
Dec 23, 2022
Jun 1, 2023
Jun 1, 2023
May 7, 2023
Dec 3, 2017
May 27, 2023
Dec 3, 2017
Jun 1, 2023
Dec 23, 2022
Jun 7, 2022
Jun 1, 2023

Repository files navigation

Node Web Bluetooth

Node.js implementation of the Web Bluetooth Specification

Build Status npm Licence MIT

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/

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:

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

  • 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

BluetoothDevice

  • id
  • name
  • gatt
  • forget()
  • watchAdvertisements() - unsupported in adapter
  • watchingAdvertisements - unsupported in adapter

BluetoothRemoteGATTServer

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

BluetoothRemoteGATTService

  • uuid
  • device
  • isPrimary
  • getCharacteristic()
  • getCharacteristics()
  • getIncludedService() - unsupported in adapter
  • getIncludedServices() - unsupported in adapter

BluetoothRemoteGATTCharacteristic

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

BluetoothRemoteGATTDescriptor

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

BluetoothUUID

  • getService()
  • getCharacteristic()
  • getDescriptor()
  • canonicalUUID()

Events

Bluetooth

  • availabilitychanged - unsupported in adapter

Bluetooth Device

  • gattserverdisconnected
  • advertisementreceived - unsupported in adapter

Bluetooth Service

  • serviceadded
  • servicechanged - unsupported in adapter
  • serviceremoved - unsupported in adapter

Bluetooth Characteristic

  • characteristicvaluechanged

Other

  • Device selector hook
  • Examples
  • 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)

Firmware for this hardware including the services can be found here: https://microbit.org/get-started/user-guide/firmware/

To run the tests:

yarn test