百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
W

webbluetooth

> 编程语言
开源

Node.js 实现 Web 蓝牙规范

198 stars0 点赞0 次浏览
访问官网GitHub

工具介绍

Node.js 实现 Web 蓝牙规范

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 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

TypeScript

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月18日
分类编程语言
定价开源

> 相关工具

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