# @abandonware/bleno 中文文档

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

版本：0\.6\.2
npm 元数据更新时间：2025-02-05T18:29:36.328Z
中文译文更新时间：2026-11-06T01:08:27.416Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：458 kB，84 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=16
- 运行依赖：3 个
- 首次发布：2019-07-23T17:24:50.042Z
- 最新版本发布：2025-02-05T18:29:36.095Z
- 近 30 天下载量：7447（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 0 个）

## 中文简介

用于实施BLE(蓝牙低能)外围的节点.js模块

## 安装

```sh
npm install @abandonware/bleno
```

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

## README

# 布尔诺

[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/sandeepmistry/bleno?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

用于实施BLE(蓝牙低能)外围的Node.js模块.

需要BLE中央模块吗? 见 [贵族](https://github.com/abandonware/noble)。 。 。 .

**说明:** 从0.6 Bleno版本开始,基于ES6类,只支持Node.js 14.x和更高. 对于更古老版本的Node.js使用bleno 0.5.x.

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

## 先决条件

### 操作系统X

-   通过安装 XCode 命令行工具 `xcode-select --install`
-   10.9 或以后时间

### 链接

-   3.6或以上内核版本
-   `libbluetooth-dev`
-   `bluetoothd` 禁用,如果安装了 BlueZ 5.14 或以后安装。 使用 `sudo hciconfig hci0 up` 以在停止或失效后使蓝牙适配器启动 `bluetoothd`。 。 。 .
    -   `System V`数字 :
        -   `sudo service bluetooth stop` (一次)
        -   `sudo update-rc.d bluetooth remove` (坚持重启)
    -   `systemd`
        -   `sudo systemctl stop bluetooth` (一次)
        -   `sudo systemctl disable bluetooth` (坚持重启)

如果你在用的话 [贵族](https://github.com/sandeepmistry/noble) _财务报告和审定财务报表_ 同时 Bleno,连接的 BLE 设备可能无法从 BLE 适配器取回服务列表. 看看高贵的 [关于bleno相容性的文档](https://github.com/sandeepmistry/noble#bleno-compatibility)

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

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

确保 `node` 在你的路上,如果没有,一些选择:

-   符号链接 `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)

#### Fedora/ 基于其他RPM

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

#### 爱迪生情报

见 [为 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)
    -   Py 2.7
    -   视觉工作室( E)[快递](https://www.visualstudio.com/en-us/products/visual-studio-express-vs.aspx)(中文(简体) )
-   [节点-蓝牙-hci-socket 先决条件](https://github.com/sandeepmistry/node-bluetooth-hci-socket#windows)
    -   兼容蓝牙 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/)

## 安装

```sh
npm install bleno@npm:@abandonware/bleno
```

## 使用量

```javascript
var bleno = require('bleno');
```

见 [示例文件夹](https://github.com/sandeepmistry/bleno/blob/master/examples) 代码示例.

### 行动

#### 广告

##### 开始广告

注: `bleno.state` 必须是 `poweredOn` 在广告开始前. `bleno.on('stateChange', callback(state));` 可用于状态更改事件.

```javascript
var name = 'name';
var serviceUuids = ['fffffffffffffffffffffffffffffff0']

bleno.startAdvertising(name, serviceUuids[, callback(error)]);
```

**说明:**: 对UUID的名称和服务有限制

-   名称
    -   最大 26 字节
-   服务UUUID
    -   1 128 位服务 UUID
    -   1 128位服务 UUID + 2 16位服务 UUID
    -   7 16 位服务 UUID

##### 开始广告iBeacon

```javascript
var uuid = 'e2c56db5dffb48d2b060d0f5a71096e0';
var major = 0; // 0x0000 - 0xffff
var minor = 0; // 0x0000 - 0xffff
var measuredPower = -59; // -128 - 127

bleno.startAdvertisingIBeacon(uuid, major, minor, measuredPower[, callback(error)]);
```

**注释:**数字 :

-   操作系统X:
    -   在iBeacon模式下, 您的外围无法连接 !

##### 开始使用 EIR 数据进行广告(**仅限 Linux**(中文(简体) )

```javascript
var scanData = Buffer.alloc(...); // maximum 31 bytes
var advertisementData = Buffer.alloc(...); // maximum 31 bytes

bleno.startAdvertisingWithEIRData(advertisementData[, scanData, callback(error)]);
```

-   EIR 格式一节 [蓝牙核心规格](https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=229737) 数据格式.

##### 停止广告

```javascript
bleno.stopAdvertising([callback]);
```

#### 设置服务

设置周边可用的初级服务.

```javascript
var services = [
   ... // see PrimaryService for data type
];

bleno.setServices(services[, callback(error)]);
```

#### 断开客户端

```javascript
bleno.disconnect(); // Linux only
```

#### 更新 RSSI

```javascript
bleno.updateRssi([callback(error, rssi)]); // not available in OS X 10.9
```

### 小学

```javascript
var PrimaryService = bleno.PrimaryService;

var primaryService = new PrimaryService({
    uuid: 'fffffffffffffffffffffffffffffff0', // or 'fff0' for 16-bit
    characteristics: [
        // see Characteristic for data type
    ]
});
```

### 特征

```javascript
var Characteristic = bleno.Characteristic;

var characteristic = new Characteristic({
    uuid: 'fffffffffffffffffffffffffffffff1', // or 'fff1' for 16-bit
    properties: [ ... ], // can be a combination of 'read', 'write', 'writeWithoutResponse', 'notify', 'indicate'
    secure: [ ... ], // enable security for properties, can be a combination of 'read', 'write', 'writeWithoutResponse', 'notify', 'indicate'
    value: null, // optional static value, must be of type Buffer - for read only characteristics
    descriptors: [
        // see Descriptor for data type
    ],
    onReadRequest: null, // optional read request handler, function(offset, callback) { ... }
    onWriteRequest: null, // optional write request handler, function(data, offset, withoutResponse, callback) { ...}
    onSubscribe: null, // optional notify/indicate subscribe handler, function(maxValueSize, updateValueCallback) { ...}
    onUnsubscribe: null, // optional notify/indicate unsubscribe handler, function() { ...}
    onNotify: null, // optional notify sent handler, function() { ...}
    onIndicate: null // optional indicate confirmation received handler, function() { ...}
});
```

#### 结果代码

-   特征. RESULT SUCCESS
-   特征. RESULT INVALID OFFSET
-   特征. RESULT INVALID ATRIBUTE LENGTH
-   特征. RESULT UNLIKELY 错误

#### 读取请求

可以通过构建器选项指定已读请求处理器, 或者通过扩展“ 读取请求” 的特性和压倒性来指定 .

处理器的参数为

-   `offset` (0x000- 0xffff) (中文(简体) )
-   `callback`

`callback` 必须使用结果和数据(类型) `Buffer`) -可以是同音.

```javascript
var result = Characteristic.RESULT_SUCCESS;
var data = Buffer.alloc( ... );

callback(result, data);
```

#### 写请求

可以通过构建器选项或扩展特性和之上的 Write Request 指定写入请求处理器 .

处理器的参数为

-   `data` (压力)
-   `offset` (0x000- 0xffff) (中文(简体) )
-   `withoutResponse` (真伪)
-   `callback`。 。 。 .

`callback` 必须使用结果代码调用 - 可以是同源代码.

```javascript
var result = Characteristic.RESULT_SUCCESS;

callback(result);
```

#### 通知订阅

可以通过构建器选项或通过扩展特性和主控程序指定通知用户处理器.

处理器的参数为

-   `maxValueSize` (最大数据大小)
-   `updateValueCallback` (值改变时召回)

#### 通知未订阅

可以通过构建器选项或扩展特性和对用户的压倒性来指定通知未订阅的处理器.

#### 通知数值变化

打电话 `updateValueCallback` 调用( 请参见 Notify 订阅), 带有类型参数 `Buffer`

可通过建构器选项或通过扩展特性和压倒性通知方式指定已发送处理器.

### 说明

```javascript
var Descriptor = bleno.Descriptor;

var descriptor = new Descriptor({
    uuid: '2901',
    value: 'value' // static value, must be of type Buffer or string if set
});
```

### 活动

#### 适应器状态变化

```javascript
state = <"unknown" | "resetting" | "unsupported" | "unauthorized" | "poweredOff" | "poweredOn">

bleno.on('stateChange', callback(state));
```

#### 广告开始

```javascript
bleno.on('advertisingStart', callback(error));

bleno.on('advertisingStartError', callback(error));
```

#### 广告停止

```javascript
bleno.on('advertisingStop', callback);
```

#### 服务设置

```javascript
bleno.on('servicesSet', callback(error));

bleno.on('servicesSetError', callback(error));
```

#### 接受

```javascript
bleno.on('accept', callback(clientAddress)); // not available on OS X 10.9
```

#### 断开连接

```javascript
bleno.on('disconnect', callback(clientAddress)); // Linux only
```

#### RSSI 更新

```javascript
bleno.on('rssiUpdate', callback(rssi)); // not available on OS X 10.9
```

### 在 Linux 上运行

**说明:** 确定你也检查过 [Linux 先决条件](https://npmcn.com/package/%40abandonware/bleno/#readme-linux)

#### 无根/ sudo 运行

运行以下命令 :

```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\'`

#### 多个适配器

`hci0` 默认使用以推翻设置 `BLENO_HCI_DEVICE_ID` 环境变量到接口编号.

示例,指定 `hci1`数字 :

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

#### 设置自定义设备名称

默认 bleno 使用主机名(`require('os').hostname()`)作为设备名(0x2a00)字符isic的值,以匹配OS X的行为.

自定义设备名称可以通过设置 `BLENO_DEVICE_NAME` 环境变量 :

```sh
sudo BLENO_DEVICE_NAME="custom device name" node <your file>.js
```

或者说

```js
process.env['BLENO_DEVICE_NAME'] = 'custom device name';
```

#### 设置广告间距

bleno默认使用100ms的广告间隔.

设置自定义广告间隔可以指定 `BLENO_ADVERTISING_INTERVAL` 环境变量,以毫秒计:

```sh
sudo BLENO_ADVERTISING_INTERVAL=500 node <your file>.js
```

广告间隔必须在20至10 s(10,000 ms)之间.

## 有用工具/链接

-   工具
    -   浅蓝色为 [iOS系统](https://itunes.apple.com/us/app/lightblue/id557428110)编号 :[操作系统X](https://itunes.apple.com/us/app/lightblue/id639944780)
    -   [nRF 主控制面板(BLE)](https://play.google.com/store/apps/details?id=no.nordicsemi.android.mcp&hl=en) 用于 Android 的
    -   [支架](http://linux.die.net/man/1/hcitool) 财务报告和审定财务报表 `gatttool` 以 [蓝色Z](http://www.bluez.org/) 用于 Linux

## 许可证

版权(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/bleno?pixel)](https://github.com/igrigorik/ga-beacon)

## 常见问题

### @abandonware/bleno 是什么？

用于实施BLE\(蓝牙低能\)外围的节点\.js模块

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

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

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

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

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

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

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

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

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

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

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

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

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

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