主机
约 4561 字大约 15 分钟
2026-03-19
central 对象
函数 setScanParam central侧
原型: setScanParam (options:object)
设置 BLE 扫描参数(Central 角色)
在 Central 模式下开始扫描前配置扫描参数,包括扫描类型、间隔、窗口等。
示例:
import * as bt from 'bt'
bt.setScanParam({
scan_type: 0, // 0: 被动扫描, 1: 主动扫描
own_addr_type: 0, // 0: 公共地址, 1: 随机地址
scan_filter_policy: 0, // 0: 接受所有, 1: 只接受白名单
scan_interval: 0x50, // 扫描间隔 (0x0004 ~ 0x4000)
scan_window: 0x40, // 扫描窗口 (0x0004 ~ 0x4000)
scan_duplicate: 0 // 0: 不重复, 1: 重复
})参数:
options
类型object (详见下方类型定义)
参数说明扫描参数对象
options 类型定义:
{ scan_type?: number, // 扫描类型:0 被动扫描,1 主动扫描,默认 0 own_addr_type?: number, // 自身地址类型:0 公共地址,1 随机地址,默认 0 scan_filter_policy?: number, // 扫描过滤策略,默认 0 scan_interval?: number, // 扫描间隔,默认 0x50 scan_window?: number, // 扫描窗口,默认 0x40 scan_duplicate?: number // 重复扫描策略,默认 0 }
异常:
- 设置扫描参数失败
- BLE 4.2 不支持
返回值:
类型undefined
函数 startScan central侧
原型: startScan (duration:number=4294967295)
开始扫描 BLE 设备(Central 角色)
作为 Central 开始扫描周围的 BLE 设备,扫描结果通过 'scan-res' 事件返回。
示例:
import * as bt from 'bt'
// 监听扫描结果
bt.on('scan-res', (device) => {
console.log('发现设备:', device.addr, 'RSSI:', device.rssi)
})
// 开始扫描,持续 10 秒
bt.startScan(10)
// 无限扫描
bt.startScan()参数:
duration
类型number
默认值4294967295
参数说明扫描持续时间(秒),默认为无限
异常:
- 开始扫描失败
- BLE 4.2 不支持
返回值:
类型undefined
函数 stopScan central侧
原型: stopScan ()
停止扫描 BLE 设备(Central 角色)
作为 Central 停止扫描周围的 BLE 设备。
示例:
import * as bt from 'bt'
bt.stopScan()异常:
- BLE 4.2 不支持
返回值:
类型boolean
说明是否成功停止
函数 isScanning central侧
原型: isScanning ()
检查是否正在扫描(Central 角色)
检查 Central 是否正在扫描 BLE 设备。
示例:
import * as bt from 'bt'
if (bt.isScanning()) {
console.log('正在扫描中...')
}返回值:
类型boolean
说明是否正在扫描
函数 connect central侧
原型: connect (addr:string)
连接到 BLE 设备(Central 角色)
作为 Central 连接到指定的 BLE 设备。
示例:
import * as bt from 'bt'
// 连接到指定 MAC 地址的设备
bt.connect('AA:BB:CC:DD:EE:FF')
// 使用 JS 侧封装的 Promise API
const peer = await bt.central.connect('AA:BB:CC:DD:EE:FF', 5000)参数:
addr
类型string
参数说明目标设备的 MAC 地址,格式为 "xx:xx:xx:xx:xx:xx"
异常:
- 未初始化 Central 模式
- MAC 地址格式无效
- 连接失败
返回值:
类型undefined
函数 disconnect central侧
原型: disconnect (conn_id:number)
断开与 BLE 设备的连接(Central 角色)
作为 Central 断开与指定 BLE 设备的连接。
示例:
import * as bt from 'bt'
// 断开指定连接 ID 的设备
bt.disconnect(connId)参数:
conn_id
类型number
参数说明连接 ID
异常:
- 未初始化 Central 模式
- 断开连接失败
返回值:
类型undefined
函数 requestMTU central侧
原型: requestMTU (conn_id:number)
请求更新 MTU (Maximum Transmission Unit)(Central 角色)
作为 Central 向连接的设备请求更新 MTU 大小。
示例:
import * as bt from 'bt'
bt.requestMTU(connId)
// 等待 MTU 更新完成
bt.once('cfg-mtu', (status, connId, mtu) => {
console.log('MTU 更新为:', mtu)
})参数:
conn_id
类型number
参数说明连接 ID
异常:
- 未初始化 Central 模式
返回值:
类型undefined
函数 search central侧
原型: search (conn_id:number)
搜索 BLE 设备的服务和特征(Central 角色)
作为 Central 在已连接的设备上搜索所有 GATT 服务和特征。 搜索结果通过 'search-res' 和 'search-cmpl' 事件返回。
示例:
import * as bt from 'bt'
bt.on('search-res', (connId, service) => {
console.log('发现服务:', service.uuid)
console.log('特征列表:', service.chars)
})
bt.on('search-cmpl', (status, connId) => {
console.log('搜索完成')
})
bt.search(connId)参数:
conn_id
类型number
参数说明连接 ID
异常:
- 未初始化 Central 模式
返回值:
类型undefined
函数 read central侧
原型: read (conn_id:number, handle:number)
读取特征值(Central 角色)
作为 Central 从已连接设备的指定特征读取数据。 读取结果通过 'read-char' 事件返回。
示例:
import * as bt from 'bt'
bt.on('read-char', (status, handle, data) => {
if (status === 0) {
console.log('读取成功:', data)
}
})
bt.read(connId, charHandle)参数:
conn_id
类型number
参数说明连接 ID
handle
类型number
参数说明特征句柄
异常:
- 未初始化 Central 模式
- 读取失败
返回值:
类型undefined
函数 write central侧
原型: write (conn_id:number, handle:number, data:ArrayBuffer, rsp:boolean=false)
写入特征值(Central 角色)
作为 Central 向已连接设备的指定特征写入数据。 写入结果通过 'write-char' 事件返回。
示例:
import * as bt from 'bt'
bt.on('write-char', (status, handle, offset) => {
if (status === 0) {
console.log('写入成功')
}
})
// 写入数据(不需要响应)
bt.write(connId, handle, new Uint8Array([0x01, 0x02]))
// 写入数据(需要响应)
bt.write(connId, handle, new Uint8Array([0x01, 0x02]), true)参数:
conn_id
类型number
参数说明连接 ID
handle
类型number
参数说明特征句柄
data
类型ArrayBuffer
参数说明要写入的数据
rsp
类型boolean
默认值false
参数说明是否需要响应
异常:
- 未初始化 Central 模式
- 数据格式无效
- 写入失败
返回值:
类型undefined
函数 subscribe central侧
原型: subscribe (conn_id:number, handle:number, type:number=1)
订阅特征值通知(Central 角色)
作为 Central 订阅指定特征的通知或指示。订阅成功后,设备会主动推送数据变化。 订阅结果通过 'write-desc' 事件返回。
示例:
import * as bt from 'bt'
bt.on('write-desc', (status, handle, offset) => {
if (status === 0) {
console.log('订阅成功')
}
})
// 订阅通知 (type=1)
bt.subscribe(connId, cccdHandle, 1)
// 订阅指示 (type=2)
bt.subscribe(connId, cccdHandle, 2)参数:
conn_id
类型number
参数说明连接 ID
handle
类型number
参数说明CCCD (Client Characteristic Configuration Descriptor) 句柄
type
类型number
默认值1
参数说明订阅类型:1 通知 (Notification),2 指示 (Indication)
异常:
- 未初始化 Central 模式
- 订阅类型无效
- 订阅失败
返回值:
类型undefined
Central 类
Central 类提供了 BLE 主机模式的完整功能,包括:
- 扫描参数设置和扫描控制
- 设备连接和断开
- 服务搜索
- 特征读写和订阅
bt 模块已预创建了一个 Central 实例,通过 bt.central 或 bt.cent 访问,无需手动创建。
import {cent} as bt from 'bt'
cent.init()事件
Central 类继承自 EventEmitter,支持以下事件:
| 事件 | 参数 | 说明 |
|---|---|---|
connect | (connid, addr) | 连接到设备时触发 |
disconnect | (connid, addr) | 与设备断开连接时触发 |
close | (connid, addr, reason) | 连接关闭时触发,reason 为断开原因码 |
示例:
import * as bt from 'bt'
// 初始化 Central(使用预创建的实例)
bt.central.init()
// 开始扫描
bt.setScanParam({ scan_type: 0, scan_interval: 0x50, scan_window: 0x40 })
bt.startScan()
// 发现设备后连接
bt.on('scan-res', async (device) => {
if (device.addr === 'AA:BB:CC:DD:EE:FF') {
bt.stopScan()
// 连接设备
const peer = await bt.central.connect(device.addr, 5000)
console.log('已连接到:', peer.addr)
// 搜索服务
await peer.search()
// 读取特征值
const data = await peer['2a37'].read()
console.log('心率:', new Uint8Array(data)[0])
// 订阅通知
await peer['2a37'].subscribe()
peer['2a37'].on('notify', (data) => {
console.log('收到通知:', data)
})
}
})方法 init
原型: init ()
初始化 Central 模式
初始化 BLE Central (主机) 模式,注册事件回调。
示例:
import * as bt from 'bt'
bt.central.init()返回值:
类型undefined
方法 connect
原型: connect (addr:string, timeout:number=0)
连接到 BLE 设备
连接到指定 MAC 地址的 BLE 设备,返回 Promise 包装的 Peer 对象。
示例:
import * as bt from 'bt'
bt.central.init()
const peer = await bt.central.connect('AA:BB:CC:DD:EE:FF', 5000)
console.log('已连接到:', peer.addr)参数:
addr
类型string
参数说明目标设备的 MAC 地址
timeout
类型number
默认值0
参数说明连接超时时间(毫秒),0 表示不超时
异常:
- 连接超时
- 连接失败
返回值:
Peer 类
Peer 类,表示已连接的 BLE 设备
Peer 类继承自 EventEmitter,表示 Central 连接到的远程 BLE 设备。 通过 Peer 对象可以搜索服务、读写 PeripheralCharacteristic、设置 MTU 等。
事件
Peer 类继承自 EventEmitter,支持以下事件:
| 事件 | 参数 | 说明 |
|---|---|---|
search | (service) | 发现服务时触发,service 包含 uuid 和 chars |
search-cmpl | (status) | 服务搜索完成时触发,status 为 0 表示成功 |
cfg-mtu | (status, mtu) | MTU 配置完成时触发,mtu 为协商后的 MTU 大小 |
示例:
import * as bt from 'bt'
bt.central.init()
const peer = await bt.central.connect('AA:BB:CC:DD:EE:FF', 5000)
// 搜索服务
await peer.search()
// 读取特征值
const data = await peer['2a37'].read()
// 设置 MTU
const mtu = await peer.setMTU(185)
// 断开连接
peer.disconnect()方法 search
原型: search ()
Peer 类的方法:search
在已连接的 BLE 设备上搜索所有 GATT 服务和特征。
示例:
const peer = await bt.central.connect('AA:BB:CC:DD:EE:FF')
await peer.search()返回值:
类型Promise<undefined>
说明搜索完成时 resolve
方法 setMTU
原型: setMTU (mtu:number)
Peer 类的方法:setMTU
请求更新与设备的 MTU 大小。
示例:
const peer = await bt.central.connect('AA:BB:CC:DD:EE:FF')
const mtu = await peer.setMTU(185)参数:
mtu
类型number
参数说明请求的 MTU 大小
返回值:
类型Promise<number>
说明返回实际 MTU 大小的 Promise
方法 disconnect
原型: disconnect ()
Peer 类的方法:disconnect
断开与 BLE 设备的连接。
示例:
const peer = await bt.central.connect('AA:BB:CC:DD:EE:FF')
peer.disconnect()返回值:
类型undefined
方法 search
原型: search ()
Peer 类的方法:search
在已连接的 BLE 设备上搜索所有 GATT 服务和特征。
示例:
const peer = await bt.central.connect('AA:BB:CC:DD:EE:FF')
await peer.search()返回值:
类型Promise<undefined>
说明搜索完成时 resolve
方法 setMTU
原型: setMTU (mtu:number)
Peer 类的方法:setMTU
请求更新与设备的 MTU 大小。
示例:
const peer = await bt.central.connect('AA:BB:CC:DD:EE:FF')
const mtu = await peer.setMTU(185)参数:
mtu
类型number
参数说明请求的 MTU 大小
返回值:
类型Promise<number>
说明返回实际 MTU 大小的 Promise
方法 disconnect
原型: disconnect ()
Peer 类的方法:disconnect
断开与 BLE 设备的连接。
示例:
const peer = await bt.central.connect('AA:BB:CC:DD:EE:FF')
peer.disconnect()返回值:
类型undefined
PeripheralCharacteristic 类
PeripheralCharacteristic 类(Central 侧),表示远程设备的 GATT 特征
PeripheralCharacteristic 类继承自 EventEmitter,表示 Central 连接到的远程设备中的 GATT 特征。 支持读取、写入和订阅通知等操作。
事件
PeripheralCharacteristic 类继承自 EventEmitter,支持以下事件:
| 事件 | 参数 | 说明 |
|---|---|---|
read-char | (status, data) | 读取特征值完成时触发,data 为 ArrayBuffer |
write-char | (status, offset) | 写入特征值完成时触发 |
subscribe | (status) | 订阅/取消订阅完成时触发,status 为 0 表示成功 |
示例:
import * as bt from 'bt'
bt.central.init()
const peer = await bt.central.connect('AA:BB:CC:DD:EE:FF', 5000)
await peer.search()
// 访问特征(通过 UUID)
const char = peer['2a37']
// 读取特征值
const data = await char.read()
// 写入特征值
await char.write(new Uint8Array([0x01, 0x02]))
// 订阅通知
await char.subscribe()
char.on('notify', (data) => {
console.log('收到通知:', data)
})方法 write
原型: write (data:ArrayBuffer, rsp:boolean=false)
Characteristic 类的方法:write(Central 侧)
向远程设备的特征写入数据。
示例:
const char = peer['2a37']
await char.write(new Uint8Array([0x01, 0x02]))参数:
data
类型ArrayBuffer
参数说明要写入的数据
rsp
类型boolean
默认值false
参数说明是否需要响应
返回值:
类型Promise<undefined>
说明写入完成时 resolve
方法 read
原型: read ()
Characteristic 类的方法:read(Central 侧)
从远程设备的特征读取数据。
示例:
const char = peer['2a37']
const data = await char.read()返回值:
类型Promise<ArrayBuffer>
说明读取到的数据
方法 subscribe
原型: subscribe ()
Characteristic 类的方法:subscribe(Central 侧)
订阅远程设备特征的通知或指示。
示例:
const char = peer['2a37']
await char.subscribe()
char.on('notify', (data) => {
console.log('收到通知:', data)
})返回值:
类型Promise<undefined>
说明订阅完成时 resolve
方法 write
原型: write (data:ArrayBuffer, rsp:boolean=false)
PeripheralCharacteristic 类的方法:write(Central 侧)
向远程设备的特征写入数据。
示例:
const char = peer['2a37']
await char.write(new Uint8Array([0x01, 0x02]))参数:
data
类型ArrayBuffer
参数说明要写入的数据
rsp
类型boolean
默认值false
参数说明是否需要响应
返回值:
类型Promise<undefined>
说明写入完成时 resolve
方法 read
原型: read ()
PeripheralCharacteristic 类的方法:read(Central 侧)
从远程设备的特征读取数据。
示例:
const char = peer['2a37']
const data = await char.read()返回值:
类型Promise<ArrayBuffer>
说明读取到的数据
方法 subscribe
原型: subscribe ()
PeripheralCharacteristic 类的方法:subscribe(Central 侧)
订阅远程设备特征的通知或指示。
示例:
const char = peer['2a37']
await char.subscribe()
char.on('notify', (data) => {
console.log('收到通知:', data)
})返回值:
类型Promise<undefined>
说明订阅完成时 resolve
