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 表示不超时

异常:

• 连接超时
• 连接失败

返回值:

类型Promise<Peer>

说明返回 Peer 对象的 Promise

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

贡献者: alee

上一页BT(蓝牙)

下一页从机(Peripheral)