Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
W

webbluetooth

> 编程语言
Open source

Node.js implementation of the Web Bluetooth Specification

198 stars0 likes0 views
WebsiteGitHub

About

Node.js implementation of the Web Bluetooth Specification

Node Web Bluetooth

Node.js implementation of the Web Bluetooth Specification

Licensing

This library is MIT licensed, however it relies on the SimpleBLE library which has a separate license with a confusing history...

SimpleBLE History

Since v0.7.0 a commercial license is required for any commercial usage, but is otherwise free to use for non-commercial purposes.

  • v0.6.1: MIT
  • v0.7.0: BSD3/GPLv3
  • v0.7.1: BSD3/GPLv3
  • v0.7.3: GPLv3
  • v0.8.1: GPLv3
  • v0.9.0+: BUSL-1.1

Note: v0.10.3 was the last to support MacOS Catalina, Big Sur and Monterey

Webbluetooth Library Versions

The default (latest) version of webbluetooth released on npm will always include the MIT version of SimpleBLE. However, if you want to use a newer version, others are available as follows and we will endeveuer to keep these up to date. Note that the license terms when using these are your responsibility.

  • v3.x.x webbluetooth@latest (default) - SimpleBLE v0.6.1 (MIT licensed)
  • v4.x.x webbluetooth@bsd-3 - SimpleBLE v0.7.1 (BSD-3-Clause)
  • v5.x.x [email protected] - SimpleBLE v0.8.1 (GPLv3 licensed)
  • v6.x.x [email protected] - latest SimpleBLE (BUSL-1.1 licensed)

Prerequisites

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

Installation

bash
$ 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:

OS x86 x64 arm64
Windows X X -
MacOS - X X
Linux (glibc) - X X

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:

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.

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:

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

Specification

The Web Bluetooth specification can be found here:

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

Implementation Status

Functions

  • getAdapters() - list available bluetooth adapters

new Bluetooth options

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

bluetooth

  • getAvailability()
  • 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.write
  • properties.writeWithoutResponse
  • 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

Prerequisites

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.

Cloning

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

Building

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

bash
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:

bash
yarn test

Issues· 0 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

TypeScript

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 18, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言