# @abandonware/noble 中文文档

规范地址：https://npmcn.com/package/%40abandonware/noble/

版本：1\.9\.2-26
npm 元数据更新时间：2025-02-09T22:23:34.861Z
中文译文更新时间：2026-11-05T19:20:10.608Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40abandonware/noble
原文对照：https://npmcn.com/package/%40abandonware/noble/?lang=original
源码仓库：https://github.com/abandonware/noble

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.4 MB，131 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=16
- 运行依赖：4 个
- 首次发布：2018-12-19T16:44:43.198Z
- 最新版本发布：2025-02-09T22:23:34.637Z
- 近 30 天下载量：40306（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：25（近 12 个月 0 个）

## 中文简介

A Node.js BLE(蓝牙低能)中央图书馆.

## 安装

```sh
npm install @abandonware/noble
```

也可以使用：`pnpm add @abandonware/noble`、`yarn add @abandonware/noble`、`bun add @abandonware/noble`

## README

# ![noble](https://npmcn.com/package/%40abandonware/noble/assets/noble-logo.png)

[![npm version](https://badgen.net/npm/v/@abandonware/noble)](https://www.npmjs.com/package/@abandonware/noble) [![npm downloads](https://badgen.net/npm/dt/@abandonware/noble)](https://www.npmjs.com/package/@abandonware/noble) [![Build Status](https://travis-ci.org/abandonware/noble.svg?branch=master)](https://travis-ci.org/abandonware/noble) [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/abandonware/noble?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![OpenCollective](https://opencollective.com/noble/backers/badge.svg)](https://npmcn.com/package/%40abandonware/noble/#readme-backers) [![OpenCollective](https://opencollective.com/noble/sponsors/badge.svg)](https://npmcn.com/package/%40abandonware/noble/#readme-sponsors)

一个Node.js BLE(蓝牙低能)中央模块.

想要执行一个外围? 检查出来 [布尔诺](https://github.com/abandonware/bleno)。 。 。 .

**说明:** macOS / Mac OS X,Linux,FreeBSD和Windows是目前唯一被支持的OS.

## 文档

-   [快速启动示例](https://npmcn.com/package/%40abandonware/noble/#readme-quick-start-example)
-   [安装](https://npmcn.com/package/%40abandonware/noble/#readme-installation)
-   [API 文件](https://npmcn.com/package/%40abandonware/noble/#readme-api-docs)
-   [高级用途](https://npmcn.com/package/%40abandonware/noble/#readme-advanced-usage)
-   [常见问题](https://npmcn.com/package/%40abandonware/noble/#readme-common-problems)

## 快速启动示例

```javascript
// Read the battery level of the first found peripheral exposing the Battery Level characteristic

const noble = require('@abandonware/noble');

noble.on('stateChange', async (state) => {
  if (state === 'poweredOn') {
    await noble.startScanningAsync(['180f'], false);
  }
});

noble.on('discover', async (peripheral) => {
  await noble.stopScanningAsync();
  await peripheral.connectAsync();
  const {characteristics} = await peripheral.discoverSomeServicesAndCharacteristicsAsync(['180f'], ['2a19']);
  const batteryLevel = (await characteristics[0].readAsync())[0];

  console.log(`${peripheral.address} (${peripheral.advertisement.localName}): ${batteryLevel}%`);

  await peripheral.disconnectAsync();
  process.exit(0);
});
```

## 使用高贵的 BLE5 扩展特性

```javascript
const noble = require('@abandonware/noble/with-custom-binding')({extended: true});

```

## 安装

-   [先决条件](https://npmcn.com/package/%40abandonware/noble/#readme-prerequisites)
    -   [操作系统X](https://npmcn.com/package/%40abandonware/noble/#readme-os-x)
    -   [链接](https://npmcn.com/package/%40abandonware/noble/#readme-linux)
        -   [乌本图、德比安、拉斯比安](https://npmcn.com/package/%40abandonware/noble/#readme-ubuntu-debian-raspbian)
        -   [Fedora 和其他基于 RPM 的分布](https://npmcn.com/package/%40abandonware/noble/#readme-fedora-and-other-rpm-based-distributions)
        -   [爱迪生情报](https://npmcn.com/package/%40abandonware/noble/#readme-intel-edison)
    -   [免费BSD](https://npmcn.com/package/%40abandonware/noble/#readme-freebsd)
    -   [窗口](https://npmcn.com/package/%40abandonware/noble/#readme-windows)
    -   [夹克](https://npmcn.com/package/%40abandonware/noble/#readme-docker)
-   [安装和使用软件包](https://npmcn.com/package/%40abandonware/noble/#readme-installing-and-using-the-package)

### 先决条件

#### 操作系统X

-   安装 [X代码](https://itunes.apple.com/ca/app/xcode/id497799835?mt=12)
-   在更新的OSX上,允许蓝牙访问终端应用程序:"系统首选项"QQ"安全与隐私"QQ"蓝牙"-". 添加终端应用程序(参见 [沙箱终端](https://npmcn.com/package/%40abandonware/noble/#readme-sandboxed-terminal)(中文(简体) )

#### 链接

-   3.6或以上内核版本
-   `libbluetooth-dev` 需要安装。 关于具体分发的指示,见下文.
-   设置必要的权限 运行没有sudo, [参见本节](https://npmcn.com/package/%40abandonware/noble/#readme-running-without-rootsudo-linux-specific)。所有分销(Raspbian、Ubuntu、Fedora等)都需要这样做。 如果运行时没有sudo, 就不会出任何错误, 但不会发生任何事 .

##### 乌本图、德比安、拉斯比安

见 [以上通用 Linux 注释](https://npmcn.com/package/%40abandonware/noble/#readme-linux) 先说.

```sh
sudo apt-get install bluetooth bluez libbluetooth-dev libudev-dev
```

确保 `node` 交给你了 `PATH`如果不是,一些选项:

-   共线 `nodejs` 改为 `node`数字 : `sudo ln -s /usr/bin/nodejs /usr/bin/node`
-   [使用节点源码包安装节点.js](https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions)

如果你在Raspberry Pi上无法连接到 BLE 设备,你应该禁用 `pnat` 插件 。 在底部添加下行 `/etc/bluetooth/main.conf`数字 :

```
DisablePlugins=pnat
```

然后重新启动系统.

见 [· OpenWonderLabs/家用桥接接接器](https://github.com/OpenWonderLabs/homebridge-switchbot/issues/425#issuecomment-1190864279)。 。 。 .

##### Fedora 和其他基于 RPM 的分布

见 [以上通用 Linux 注释](https://npmcn.com/package/%40abandonware/noble/#readme-linux) 先说.

```sh
sudo yum install bluez bluez-libs bluez-libs-devel
```

##### 爱迪生情报

见 [以上通用 Linux 注释](https://npmcn.com/package/%40abandonware/noble/#readme-linux) 先说.

见 [为 Bluetooth LE (Smart) 开发配置信息爱迪生](http://rexstjohn.com/configure-intel-edison-for-bluetooth-le-smart-development/)。 。 。 .

#### 免费BSD

确保您有 GNU Make :

```sh
sudo pkg install gmake
```

禁用默认蓝牙堆栈的自动加载 [无怀疑.conf](https://gist.github.com/myfreeweb/44f4f3e791a057bc4f3619a166a03b87) 输入 `/usr/local/etc/devd/no-ubt.conf` 并重新启动devd(`sudo service devd restart`) (中文(简体) ).

卸载 `ng_ubt` 如果已装入内核模块 :

```sh
sudo kldunload ng_ubt
```

请确认您已读取和写入权限 `/dev/usb/*` 与您的蓝牙适配器对应的设备.

#### 窗口

[windows 的节点- gyp 要求](https://github.com/TooTallNate/node-gyp#installation)

使用 Microsoft 安装所需的工具和配置 [窗口建设工具](https://github.com/felixrieseberg/windows-build-tools) 从高级的 PowerShell 或 cmd.exe (以管理员身份运行) .

```cmd
npm install --global --production windows-build-tools
```

[节点-蓝牙-hci-socket 先决条件](https://npmcn.com/package/%40abandonware/noble/#readme-windows)

-   相容蓝牙 5.0 Zephyr HCI-USB适配器(需要将 BLUETOOTH HCI SOCKET USB VID 和 BLUETOOTH HCI SOCKET USB PID 添加到进程内)
-   兼容蓝牙 4.0 USB 适配器
-   [温USB](https://msdn.microsoft.com/en-ca/library/windows/hardware/ff540196\(v=vs.85\).aspx) 蓝牙 4. 0 USB 适配器的驱动程序设置,使用 [Zadig 工具](http://zadig.akeo.ie/)

见 [@don (英语)](https://github.com/don)设置指南 [蓝牙 LE 有节点.js和Windows上的Noble](https://www.youtube.com/watch?v=mL9B8wuEdms&feature=youtu.be&t=1m46s)

#### 夹克

确保你的容器运行 `--network=host` 选项和所有特定环境的前提都经过核查.

### 安装和使用软件包

```sh
npm install @abandonware/noble
```

在 Windows OS 中,将您的自定义 hci- usb dongle 添加到进程内

```sh
set BLUETOOTH_HCI_SOCKET_USB_VID=xxx
set BLUETOOTH_HCI_SOCKET_USB_PID=xxx
```

```javascript
const noble = require('@abandonware/noble');
```

## API 文件

所有操作都有两种API的变体,一种是等待回调,一种是返回承诺(注意: `Async` 后缀).

此外,还有与每项行动相适应的事件(以及一些全球事件).

例如,对于周边的"发现服务"操作:

-   有一个 `discoverServices` 需要召回的方法 :
    
    ```javascript
    peripheral.discoverServices((error, services) => {
      // callback - handle error and services
    });
    ```
    
-   有一个 `discoverServicesAsync` 返回承诺的方法 :
    
    ```javascript
    try {
      const services = await peripheral.discoverServicesAsync();
      // handle services
    } catch (e) {
      // handle error
    }
    ```
    
-   有一个 `servicesDiscover` 发现服务后释放出的事件 :
    
    ```javascript
    peripheral.once('servicesDiscover', (services) => {
      // handle services
    });
    ```
    

API 结构 :

-   [扫描和发现](https://npmcn.com/package/%40abandonware/noble/#readme-scanning-and-discovery)
    -   [_事件: 适应器状态已更改_](https://npmcn.com/package/%40abandonware/noble/#readme-event-adapter-state-changed)
    -   [开始扫描](https://npmcn.com/package/%40abandonware/noble/#readme-start-scanning)
    -   [_事件: 开始扫描_](https://npmcn.com/package/%40abandonware/noble/#readme-event-scanning-started)
    -   [停止扫描](https://npmcn.com/package/%40abandonware/noble/#readme-stop-scanning)
    -   [_事件: 扫描已停止_](https://npmcn.com/package/%40abandonware/noble/#readme-event-scanning-stopped)
    -   [_事件:发现地外_](https://npmcn.com/package/%40abandonware/noble/#readme-event-peripheral-discovered)
    -   [_事件:提出警告_](https://npmcn.com/package/%40abandonware/noble/#readme-event-warning-raised)
-   [重置设备](https://npmcn.com/package/%40abandonware/noble/#readme-reset-device)
-   [周边](https://npmcn.com/package/%40abandonware/noble/#readme-peripheral)
    -   [连接](https://npmcn.com/package/%40abandonware/noble/#readme-connect)
    -   [_事件:已连接_](https://npmcn.com/package/%40abandonware/noble/#readme-event-connected)
    -   [取消待定的连接](https://npmcn.com/package/%40abandonware/noble/#readme-cancel-a-pending-connection)
    -   [断开连接](https://npmcn.com/package/%40abandonware/noble/#readme-disconnect)
    -   [_事件: 断开_](https://npmcn.com/package/%40abandonware/noble/#readme-event-disconnected)
    -   [更新 RSSI](https://npmcn.com/package/%40abandonware/noble/#readme-update-rssi)
    -   [_活动:更新RSSI_](https://npmcn.com/package/%40abandonware/noble/#readme-event-rssi-updated)
    -   [发现服务](https://npmcn.com/package/%40abandonware/noble/#readme-discover-services)
    -   [发现所有服务和特点](https://npmcn.com/package/%40abandonware/noble/#readme-discover-all-services-and-characteristics)
    -   [发现一些服务和特点](https://npmcn.com/package/%40abandonware/noble/#readme-discover-some-services-and-characteristics)
    -   [_事件:发现的服务_](https://npmcn.com/package/%40abandonware/noble/#readme-event-services-discovered)
    -   [读取手柄](https://npmcn.com/package/%40abandonware/noble/#readme-read-handle)
    -   [_事件: 处理已读_](https://npmcn.com/package/%40abandonware/noble/#readme-event-handle-read)
    -   [写手柄](https://npmcn.com/package/%40abandonware/noble/#readme-write-handle)
    -   [_事件: 处理已写入_](https://npmcn.com/package/%40abandonware/noble/#readme-event-handle-written)
-   [服务](https://npmcn.com/package/%40abandonware/noble/#readme-service)
    -   [发现包括的服务](https://npmcn.com/package/%40abandonware/noble/#readme-discover-included-services)
    -   [_事件:发现的服务包含在内_](https://npmcn.com/package/%40abandonware/noble/#readme-event-included-services-discovered)
    -   [发现特性](https://npmcn.com/package/%40abandonware/noble/#readme-discover-characteristics)
    -   [_事件: 发现的特征_](https://npmcn.com/package/%40abandonware/noble/#readme-event-characteristics-discovered)
-   [特征](https://npmcn.com/package/%40abandonware/noble/#readme-characteristic)
    -   [读取](https://npmcn.com/package/%40abandonware/noble/#readme-read)
    -   [_事件: 数据已读取_](https://npmcn.com/package/%40abandonware/noble/#readme-event-data-read)
    -   [写入](https://npmcn.com/package/%40abandonware/noble/#readme-write)
    -   [_事件: 数据已写入_](https://npmcn.com/package/%40abandonware/noble/#readme-event-data-written)
    -   [广播](https://npmcn.com/package/%40abandonware/noble/#readme-broadcast)
    -   [_事件:发送广播_](https://npmcn.com/package/%40abandonware/noble/#readme-event-broadcast-sent)
    -   [订阅](https://npmcn.com/package/%40abandonware/noble/#readme-subscribe)
    -   [_事件:收到通知_](https://npmcn.com/package/%40abandonware/noble/#readme-event-notification-received)
    -   [取消订阅](https://npmcn.com/package/%40abandonware/noble/#readme-unsubscribe)
    -   [发现描述符](https://npmcn.com/package/%40abandonware/noble/#readme-discover-descriptors)
    -   [_事件:发现描述符_](https://npmcn.com/package/%40abandonware/noble/#readme-event-descriptors-discovered)
-   [说明](https://npmcn.com/package/%40abandonware/noble/#readme-descriptor)
    -   [读取值](https://npmcn.com/package/%40abandonware/noble/#readme-read-value)
    -   [_事件: 数值已读_](https://npmcn.com/package/%40abandonware/noble/#readme-event-value-read)
    -   [写入值](https://npmcn.com/package/%40abandonware/noble/#readme-write-value)
    -   [_事件: 写入值_](https://npmcn.com/package/%40abandonware/noble/#readme-event-value-written)

### 扫描和发现

#### _事件: 适应器状态已更改_

```javascript
noble.on('stateChange', callback(state));
```

`state` 可以是:

-   `unknown`
-   `resetting`
-   `unsupported`
-   `unauthorized`
-   `poweredOff`
-   `poweredOn`

#### 开始扫描

```javascript
noble.startScanning(); // any service UUID, no duplicates


noble.startScanning([], true); // any service UUID, allow duplicates


var serviceUUIDs = ['<service UUID 1>', ...]; // default: [] => all
var allowDuplicates = falseOrTrue; // default: false

noble.startScanning(serviceUUIDs, allowDuplicates[, callback(error)]); // particular UUIDs
```

**注:** `noble.state` 必须是 `poweredOn` 在扫描开始前. `noble.on('stateChange', callback(state));` 可用于收听州变事件.

#### _事件: 开始扫描_

```javascript
noble.on('scanStart', callback);
```

活动于下列时间发布:

-   扫描开始
-   另一个应用程序允许扫描
-   另一个应用程序更改了扫描设置

#### 停止扫描

```javascript
noble.stopScanning();
```

#### _事件: 扫描已停止_

```javascript
noble.on('scanStop', callback);
```

活动于下列时间发布:

-   扫描已停止
-   另一个应用程序停止扫描

#### _事件:发现地外_

```javascript
noble.on('discover', callback(peripheral));
```

-   `peripheral`数字 :
    
    ```javascript
    {
      id: '<id>',
      address: '<BT address'>, // Bluetooth Address of device, or 'unknown' if not known
      addressType: '<BT address type>', // Bluetooth Address type (public, random), or 'unknown' if not known
      connectable: trueOrFalseOrUndefined, // true or false, or undefined if not known
      advertisement: {
        localName: '<name>',
        txPowerLevel: someInteger,
        serviceUuids: ['<service UUID>', ...],
        serviceSolicitationUuid: ['<service solicitation UUID>', ...],
        manufacturerData: someBuffer, // a Buffer
        serviceData: [
            {
                uuid: '<service UUID>',
                data: someBuffer // a Buffer
            },
            // ...
        ]
      },
      rssi: integerValue,
      mtu: integerValue // MTU will be null, until device is connected and hci-socket is used
    };
    ```
    

**说明:** 在 macOS 上, 如果设备之前没有连接, 地址将被设置为 “ ” .

#### _事件:提出警告_

```javascript
noble.on('warning', callback(message));
```

### 重置设备

```javascript
noble.reset()
```

### 周边

#### 连接

```javascript
peripheral.connect([callback(error)]);
```

有的蓝牙设备没有无缝连接,可能是因为蓝牙设备固件或内核. 在连接 API 之前, 请用 al. reset () API 重置设备 .

#### _事件:已连接_

```javascript
peripheral.once('connect', callback);
```

#### 取消待定的连接

```javascript
peripheral.cancelConnect();
// Will emit a 'connect' event with error
```

#### 断开连接

```javascript
peripheral.disconnect([callback(error)]);
```

#### _事件: 断开_

```javascript
peripheral.once('disconnect', callback);
```

#### 更新 RSSI

```javascript
peripheral.updateRssi([callback(error, rssi)]);
```

#### _活动:更新RSSI_

```javascript
peripheral.once('rssiUpdate', callback(rssi));
```

#### 发现服务

```javascript
peripheral.discoverServices(); // any service UUID

var serviceUUIDs = ['<service UUID 1>', ...];
peripheral.discoverServices(serviceUUIDs[, callback(error, services)]); // particular UUIDs
```

#### 发现所有服务和特点

```javascript
peripheral.discoverAllServicesAndCharacteristics([callback(error, services, characteristics)]);
```

#### 发现一些服务和特点

```javascript
var serviceUUIDs = ['<service UUID 1>', ...];
var characteristicUUIDs = ['<characteristic UUID 1>', ...];
peripheral.discoverSomeServicesAndCharacteristics(serviceUUIDs, characteristicUUIDs, [callback(error, services, characteristics));
```

#### _事件:发现的服务_

```javascript
peripheral.once('servicesDiscover', callback(services));
```

#### 读取手柄

```javascript
peripheral.readHandle(handle, callback(error, data));
```

#### _事件: 处理已读_

```javascript
peripheral.once('handleRead<handle>', callback(data)); // data is a Buffer
```

`<handle>` 是手柄标识符.

#### 写手柄

```javascript
peripheral.writeHandle(handle, data, withoutResponse, callback(error));
```

#### _事件: 处理已写入_

```javascript
peripheral.once('handleWrite<handle>', callback());
```

`<handle>` 是手柄标识符.

### 服务

#### 发现包括的服务

```javascript
service.discoverIncludedServices(); // any service UUID

var serviceUUIDs = ['<service UUID 1>', ...];
service.discoverIncludedServices(serviceUUIDs[, callback(error, includedServiceUuids)]); // particular UUIDs
```

#### _事件:发现的服务包含在内_

```javascript
service.once('includedServicesDiscover', callback(includedServiceUuids));
```

#### 发现特性

```javascript
service.discoverCharacteristics() // any characteristic UUID

var characteristicUUIDs = ['<characteristic UUID 1>', ...];
service.discoverCharacteristics(characteristicUUIDs[, callback(error, characteristics)]); // particular UUIDs
```

#### _事件: 发现的特征_

```javascript
service.once('characteristicsDiscover', callback(characteristics));
```

-   `characteristics`
    
    ```javascript
    {
      uuid: '<uuid>',
      properties: ['...'] // 'broadcast', 'read', 'writeWithoutResponse', 'write', 'notify', 'indicate', 'authenticatedSignedWrites', 'extendedProperties'
    };
    ```
    

### 特征

#### 读取

```javascript
characteristic.read([callback(error, data)]);
```

#### _事件: 数据已读取_

```javascript
characteristic.on('data', callback(data, isNotification));

characteristic.once('read', callback(data, isNotification)); // legacy
```

当:

-   特征读取完成,结果 `characteristic.read(...)`
-   特征值在启用之后,通过通知或提示通过外围更新 `characteristic.notify(true[, callback(error)])`

**说明:** `isNotification` 事件参数值 `undefined` 取决于平台。 参数是 **已贬值** 在1.8.1版本之后,在macOS High Sierra上和后来不支持.

#### 写入

```javascript
characteristic.write(data, withoutResponse[, callback(error)]); // data is a Buffer, withoutResponse is true|false
```

-   `withoutResponse`数字 :
    -   `false`: 发送一个带有“ 写” 特性属性的写请求
    -   `true`: 发送写入命令, 使用“ 写入无回复” 特性属性

#### _事件: 数据已写入_

```javascript
characteristic.once('write', withoutResponse, callback());
```

特性书写完成后即予公布,结果 `characteristic.write(...)`。 。 。 .

#### 广播

```javascript
characteristic.broadcast(broadcast[, callback(error)]); // broadcast is true|false
```

#### _事件:发送广播_

```javascript
characteristic.once('broadcast', callback(state));
```

特性广播状态发生变化时,因 `characteristic.broadcast(...)`。 。 。 .

#### 订阅

```javascript
characteristic.subscribe([callback(error)]);
```

订阅于一特征.

触发器 `data` 当外围发送通知或指示时的事件。 用于具有"通知"或"暗示"属性的特性.

#### _事件:收到通知_

```javascript
characteristic.once('notify', callback(state));
```

特性通知状态发生变化时,因 `characteristic.notify(...)`。 。 。 .

#### 取消订阅

```javascript
characteristic.unsubscribe([callback(error)]);
```

不订阅从特征.

用于具有“ 通知” 或“ 输入” 属性的特性

#### 发现描述符

```javascript
characteristic.discoverDescriptors([callback(error, descriptors)]);
```

#### _事件:发现描述符_

```javascript
characteristic.once('descriptorsDiscover', callback(descriptors));
```

-   `descriptors`数字 :
    
    ```javascript
    [
      {
        uuid: '<uuid>'
      },
      // ...
    ]
    ```
    

### 说明

#### 读取值

```javascript
descriptor.readValue([callback(error, data)]);
```

#### _事件: 数值已读_

```javascript
descriptor.once('valueRead', data); // data is a Buffer
```

#### 写入值

```javascript
descriptor.writeValue(data[, callback(error)]); // data is a Buffer
```

#### _事件: 写入值_

```javascript
descriptor.once('valueWrite');
```

## 高级用途

### 覆盖默认绑定

默认情况下,贵族会根据您的平台选择合适的蓝牙设备绑定. 您可以使用 `with-bindings` 模块.

```javascript
var noble = require('@abandonware/noble/with-bindings')(require('./my-custom-bindings'));
```

### 无 root/ sudo 运行( 特定 Linux)

运行以下命令 :

```sh
sudo setcap cap_net_raw+eip $(eval readlink -f `which node`)
```

这允许 `node` 二进制 `cap_net_raw` 权限,因此可以开始/停止BLE广告.

**说明:** 上述命令要求 `setcap` 将安装. 其安装方式如下:

-   时间: `sudo apt-get install libcap2-bin`
-   y: `su -c \'yum install libcap2-bin\'`

### 多个适配器( Linux 特定)

`hci0` 默认使用.

要覆盖,请设置 `NOBLE_HCI_DEVICE_ID` 环境变量到接口编号.

例如,指明 `hci1`数字 :

```sh
sudo NOBLE_HCI_DEVICE_ID=1 node <your file>.js
```

如果您在一个设置中使用了多个 SCI 设备, 您可以通过在代码中自行初始化来运行两种具有不同绑定配置的 高贵 :

```
const HCIBindings = require('@abandonware/noble/lib/hci-socket/bindings');
const Noble = require('@abandonware/noble/lib/noble');

const params = {
  deviceId: 0,
  userChannel: true,
  extended: false //ble5 extended features
};

const noble = new Noble(new HCIBindings(params));
```

### 报告所有HCI事件(具体为Linux)

默认情况下,贵族既会等待广告数据,也会为每个蓝牙地址扫描响应数据. 如果设备不使用扫描响应,则 `NOBLE_REPORT_ALL_HCI_EVENTS` 环境变量可用于绕过.

```sh
sudo NOBLE_REPORT_ALL_HCI_EVENTS=1 node <your file>.js
```

### bleno 兼容性( 特定 Linux )

默认情况下,只要收到关贸总协定请求的电文,贵族就会以出错回应. 如果你打算和贵族一起使用布尔诺语 `NOBLE_MULTI_ROLE` 环境变量可用于绕过此行为.

**说明:** 这需要蓝牙4.1适配器.

```sh
sudo NOBLE_MULTI_ROLE=1 node <your file>.js
```

## 常见问题

### 最大同时连接

此限制由蓝牙适配器硬件及其固件所强制.

| 平台 |  |
| :-- | --- |
| OS X 10.11 (El Capitan) (法语) | 6个 |
| Linux/ Windows - 适应器依赖 | 5 (基于CSR的适配器) |

### 沙箱终端

在较新版本的OSX上,终端应用被沙盒所设置,默认不允许蓝牙连接. 如果你运行一个尝试访问它的脚本, 你会得到一个 `Abort trap: 6` 错误.

要启用蓝牙, 请访问“ 系统首选项 ” QQ“ 安全和隐私 ” “ 蓝牙 ” - > 将终端添加到允许的应用程序中 .

### 特定适应者的已知问题

一些BLE适配器在扫描时无法连接到外围(下面的例子). 您在尝试连接时会收到以下信息 :

Sena UD-100(剑桥硅电台,Ltd Bluetooth Dongle(HCI模式)): `Error: Command disallowed`

Intel Dual Band Wireless-AC 7260 (Intel Corporation Wireless 7260 (rev 73)): 互联网档案馆的存檔,存档日期2013-12-20 `Error: Connection Rejected due to Limited Resources (0xd)`

在试图连接之前你必须停止扫描,以便解决这个问题.

## 备份

支持我们每月捐款,帮助我们继续活动。 \[[成为后卫](https://opencollective.com/noble#backer)\[ . \]

[![](https://opencollective.com/noble/backer/0/avatar.svg)](https://opencollective.com/noble/backer/0/website) [![](https://opencollective.com/noble/backer/1/avatar.svg)](https://opencollective.com/noble/backer/1/website) [![](https://opencollective.com/noble/backer/2/avatar.svg)](https://opencollective.com/noble/backer/2/website) [![](https://opencollective.com/noble/backer/3/avatar.svg)](https://opencollective.com/noble/backer/3/website) [![](https://opencollective.com/noble/backer/4/avatar.svg)](https://opencollective.com/noble/backer/4/website) [![](https://opencollective.com/noble/backer/5/avatar.svg)](https://opencollective.com/noble/backer/5/website) [![](https://opencollective.com/noble/backer/6/avatar.svg)](https://opencollective.com/noble/backer/6/website) [![](https://opencollective.com/noble/backer/7/avatar.svg)](https://opencollective.com/noble/backer/7/website) [![](https://opencollective.com/noble/backer/8/avatar.svg)](https://opencollective.com/noble/backer/8/website) [![](https://opencollective.com/noble/backer/9/avatar.svg)](https://opencollective.com/noble/backer/9/website) [![](https://opencollective.com/noble/backer/10/avatar.svg)](https://opencollective.com/noble/backer/10/website) [![](https://opencollective.com/noble/backer/11/avatar.svg)](https://opencollective.com/noble/backer/11/website) [![](https://opencollective.com/noble/backer/12/avatar.svg)](https://opencollective.com/noble/backer/12/website) [![](https://opencollective.com/noble/backer/13/avatar.svg)](https://opencollective.com/noble/backer/13/website) [![](https://opencollective.com/noble/backer/14/avatar.svg)](https://opencollective.com/noble/backer/14/website) [![](https://opencollective.com/noble/backer/15/avatar.svg)](https://opencollective.com/noble/backer/15/website) [![](https://opencollective.com/noble/backer/16/avatar.svg)](https://opencollective.com/noble/backer/16/website) [![](https://opencollective.com/noble/backer/17/avatar.svg)](https://opencollective.com/noble/backer/17/website) [![](https://opencollective.com/noble/backer/18/avatar.svg)](https://opencollective.com/noble/backer/18/website) [![](https://opencollective.com/noble/backer/19/avatar.svg)](https://opencollective.com/noble/backer/19/website) [![](https://opencollective.com/noble/backer/20/avatar.svg)](https://opencollective.com/noble/backer/20/website) [![](https://opencollective.com/noble/backer/21/avatar.svg)](https://opencollective.com/noble/backer/21/website) [![](https://opencollective.com/noble/backer/22/avatar.svg)](https://opencollective.com/noble/backer/22/website) [![](https://opencollective.com/noble/backer/23/avatar.svg)](https://opencollective.com/noble/backer/23/website) [![](https://opencollective.com/noble/backer/24/avatar.svg)](https://opencollective.com/noble/backer/24/website) [![](https://opencollective.com/noble/backer/25/avatar.svg)](https://opencollective.com/noble/backer/25/website) [![](https://opencollective.com/noble/backer/26/avatar.svg)](https://opencollective.com/noble/backer/26/website) [![](https://opencollective.com/noble/backer/27/avatar.svg)](https://opencollective.com/noble/backer/27/website) [![](https://opencollective.com/noble/backer/28/avatar.svg)](https://opencollective.com/noble/backer/28/website) [![](https://opencollective.com/noble/backer/29/avatar.svg)](https://opencollective.com/noble/backer/29/website)

## 发起人

成为赞助商,在Github上的我们读取的README上获得你的标志,并链接到你的网站。 \[[成为提案国](https://opencollective.com/noble#sponsor)\[ . \]

[![](https://opencollective.com/noble/sponsor/0/avatar.svg)](https://opencollective.com/noble/sponsor/0/website) [![](https://opencollective.com/noble/sponsor/1/avatar.svg)](https://opencollective.com/noble/sponsor/1/website) [![](https://opencollective.com/noble/sponsor/2/avatar.svg)](https://opencollective.com/noble/sponsor/2/website) [![](https://opencollective.com/noble/sponsor/3/avatar.svg)](https://opencollective.com/noble/sponsor/3/website) [![](https://opencollective.com/noble/sponsor/4/avatar.svg)](https://opencollective.com/noble/sponsor/4/website) [![](https://opencollective.com/noble/sponsor/5/avatar.svg)](https://opencollective.com/noble/sponsor/5/website) [![](https://opencollective.com/noble/sponsor/6/avatar.svg)](https://opencollective.com/noble/sponsor/6/website) [![](https://opencollective.com/noble/sponsor/7/avatar.svg)](https://opencollective.com/noble/sponsor/7/website) [![](https://opencollective.com/noble/sponsor/8/avatar.svg)](https://opencollective.com/noble/sponsor/8/website) [![](https://opencollective.com/noble/sponsor/9/avatar.svg)](https://opencollective.com/noble/sponsor/9/website) [![](https://opencollective.com/noble/sponsor/10/avatar.svg)](https://opencollective.com/noble/sponsor/10/website) [![](https://opencollective.com/noble/sponsor/11/avatar.svg)](https://opencollective.com/noble/sponsor/11/website) [![](https://opencollective.com/noble/sponsor/12/avatar.svg)](https://opencollective.com/noble/sponsor/12/website) [![](https://opencollective.com/noble/sponsor/13/avatar.svg)](https://opencollective.com/noble/sponsor/13/website) [![](https://opencollective.com/noble/sponsor/14/avatar.svg)](https://opencollective.com/noble/sponsor/14/website) [![](https://opencollective.com/noble/sponsor/15/avatar.svg)](https://opencollective.com/noble/sponsor/15/website) [![](https://opencollective.com/noble/sponsor/16/avatar.svg)](https://opencollective.com/noble/sponsor/16/website) [![](https://opencollective.com/noble/sponsor/17/avatar.svg)](https://opencollective.com/noble/sponsor/17/website) [![](https://opencollective.com/noble/sponsor/18/avatar.svg)](https://opencollective.com/noble/sponsor/18/website) [![](https://opencollective.com/noble/sponsor/19/avatar.svg)](https://opencollective.com/noble/sponsor/19/website) [![](https://opencollective.com/noble/sponsor/20/avatar.svg)](https://opencollective.com/noble/sponsor/20/website) [![](https://opencollective.com/noble/sponsor/21/avatar.svg)](https://opencollective.com/noble/sponsor/21/website) [![](https://opencollective.com/noble/sponsor/22/avatar.svg)](https://opencollective.com/noble/sponsor/22/website) [![](https://opencollective.com/noble/sponsor/23/avatar.svg)](https://opencollective.com/noble/sponsor/23/website) [![](https://opencollective.com/noble/sponsor/24/avatar.svg)](https://opencollective.com/noble/sponsor/24/website) [![](https://opencollective.com/noble/sponsor/25/avatar.svg)](https://opencollective.com/noble/sponsor/25/website) [![](https://opencollective.com/noble/sponsor/26/avatar.svg)](https://opencollective.com/noble/sponsor/26/website) [![](https://opencollective.com/noble/sponsor/27/avatar.svg)](https://opencollective.com/noble/sponsor/27/website) [![](https://opencollective.com/noble/sponsor/28/avatar.svg)](https://opencollective.com/noble/sponsor/28/website) [![](https://opencollective.com/noble/sponsor/29/avatar.svg)](https://opencollective.com/noble/sponsor/29/website)

## 有用链接

-   [蓝牙开发门户](http://developer.bluetooth.org/)
    -   [关贸总协定规格](https://www.bluetooth.com/specifications/gatt/)
-   [蓝牙:ATT和关贸总协定](http://epx.com.br/artigos/bluetooth_gatt.php)

## 许可证

版权(C)2015 Sandep Mistry [sandep.mistry@gmail.com (英语)](mailto:sandeep.mistry@gmail.com)

特此准许任何人免费获得本软件和相关文件文件("软件")的副本,不受限制地在软件中进行交易,包括不受限制地享有软件的使用、复制、修改、合并、出版、分发、分版和(或)销售的权利,并允许软件获得者这样做,但须符合下列条件: 1

上述版权通知和许可通知应载入软件的所有副本或大部分.

软件是提供的"AS IS", 没有任何种类的恐惧, 释放或被卷入, 包括但不限制在 危机的保障, 证明一个特定的目的和无关。 任何索赔、索赔或其他负债,无论是合同、交易或其他行为,产生于、产生于或涉及软件或软件的使用或其他交易的行为,都不得作为担保.

[![Analytics](https://ga-beacon.appspot.com/UA-56089547-1/sandeepmistry/noble?pixel)](https://github.com/igrigorik/ga-beacon)

## 常见问题

### @abandonware/noble 是什么？

A Node\.js BLE\(蓝牙低能\)中央图书馆\.

### 如何安装 @abandonware/noble？

在项目目录运行 npm install @abandonware/noble，或使用 pnpm add / yarn add / bun add。

### @abandonware/noble 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @abandonware/noble 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @abandonware/noble 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=16。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @abandonware/noble 可以商用吗？

@abandonware/noble 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @abandonware/noble 的下载量有多少？

根据 npm 官方下载统计，@abandonware/noble 在 2026/10/05 – 2026/11/03 这 30 天内被下载 40,306 次，日均约 1,344 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @abandonware/noble 还在维护吗？

最新版本 1\.9\.2-26 发布于 2025/02/10（1\.7 年前）；至今共发布 25 个版本，其中过去 12 个月发布了 0 个；首次发布于 2018/12/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。