peripheral 对象

函数 setAdvName peripheral侧

原型: setAdvName (name:string)

设置广播设备名称（Peripheral 角色）

作为 Peripheral 设置 BLE 设备在广播时显示的名称。

示例：

import * as bt from 'bt'

bt.peripheral.init()
bt.setAdvName('MyBLEDevice')
bt.startAdv()

参数:

• name

  类型string

  参数说明设备名称

异常:

• 未初始化 Peripheral 模式
• 设置名称失败

返回值:

类型undefined

---

函数 setAdvData peripheral侧

原型: setAdvData (data:ArrayBuffer)

设置原始广播数据（Peripheral 角色）

作为 Peripheral 设置 BLE 广播的原始数据包内容。

示例：

import * as bt from 'bt'

// 设置自定义广播数据
const advData = new Uint8Array([
  0x02, 0x01, 0x06,  // 广播标志
  0x03, 0x03, 0xAA, 0xFE  // 16-bit UUID
])
bt.setAdvData(advData.buffer)

参数:

• data

  类型ArrayBuffer

  参数说明原始广播数据

异常:

• 未初始化 Peripheral 模式
• 设置广播数据失败

返回值:

类型undefined

---

函数 startAdv peripheral侧

原型: startAdv (options:object)

开始 BLE 广播（Peripheral 角色）

作为 Peripheral 开始发送 BLE 广播包，让其他设备可以发现并连接。

示例：

import * as bt from 'bt'

// 使用默认参数开始广播
bt.startAdv()

// 自定义广播参数
bt.startAdv({
  min: 0xA0,           // 最小广播间隔
  max: 0xB0,           // 最大广播间隔
  type: 0,             // 广播类型
  own_addr_type: 0,    // 自身地址类型
  channel_map: 0x07,   // 广播通道映射
  adv_filter_policy: 0 // 广播过滤策略
})

参数:

• options

  类型object (详见下方类型定义)

  参数说明可选的广播参数

  options 类型定义：

  {
      min?: number,           // 最小广播间隔，默认 0xA0
      max?: number,           // 最大广播间隔，默认 0xB0
      type?: number,          // 广播类型，默认 0
      own_addr_type?: number, // 自身地址类型，默认 0
      channel_map?: number,   // 广播通道映射，默认 0x07
      adv_filter_policy?: number // 广播过滤策略，默认 0
  }

异常:

• 未初始化 Peripheral 模式
• 开始广播失败

返回值:

类型undefined

---

函数 stopAdv peripheral侧

原型: stopAdv ()

停止 BLE 广播（Peripheral 角色）

作为 Peripheral 停止发送 BLE 广播包。

示例：

import * as bt from 'bt'

bt.stopAdv()

异常:

• 未初始化 Peripheral 模式
• 停止广播失败

返回值:

类型undefined

---

函数 addService peripheral侧

原型: addService (uuid:string, num_handles:number)

添加 GATT 服务（Peripheral 角色）

作为 Peripheral 添加一个 GATT 服务。服务创建成功后会自动启动。

示例：

import * as bt from 'bt'

// 添加一个心率服务 (0x180D)
const serviceHandle = bt.addService('180D', 10)
console.log('服务句柄:', serviceHandle)

参数:

• uuid

  类型string

  参数说明服务的 UUID（16位、32位或128位）

• num_handles

  类型number

  参数说明服务的句柄数量

异常:

• 未初始化 Peripheral 模式
• UUID 格式无效
• 创建服务失败
• 服务创建超时

返回值:

类型number

说明服务句柄

---

函数 addChar peripheral侧

原型: addChar (service_handle:number, uuid:string, perm:string|Array)

添加 GATT 特征（Peripheral 角色）

作为 Peripheral 在指定服务中添加一个 GATT 特征。

示例：

import * as bt from 'bt'

// 添加一个可读写的特征
const charHandle = bt.addChar(serviceHandle, '2A37', 'read,write,notify')

// 使用数组指定权限
const charHandle = bt.addChar(serviceHandle, '2A37', ['read', 'write', 'notify'])

参数:

• service_handle

  类型number

  参数说明服务句柄

• uuid

  类型string

  参数说明特征的 UUID

• perm

  类型string, Array

  参数说明权限，可以是字符串（如 "read,write"）或数组（如 ["read", "write"]）

  • read: 可读
  • write: 可写（需要响应）
  • writeNR: 可写（不需要响应）
  • notify: 支持通知
  • indicate: 支持指示

异常:

• 未初始化 Peripheral 模式
• UUID 格式无效
• 权限参数无效
• 添加特征失败
• 添加特征超时

返回值:

类型number

说明特征句柄

---

函数 setCharValue peripheral侧

原型: setCharValue (char_handle:number, value:string|ArrayBuffer|number)

设置特征值（Peripheral 角色）

作为 Peripheral 设置指定特征的本地值。当 Central 读取该特征时，会返回此值。

示例：

import * as bt from 'bt'

// 设置字符串值
bt.setCharValue(charHandle, 'hello world')

// 设置二进制数据
bt.setCharValue(charHandle, new Uint8Array([0x01, 0x02, 0x03]).buffer)

// 设置数字值（4字节小端序）
bt.setCharValue(charHandle, 12345)

参数:

• char_handle

  类型number

  参数说明特征句柄

• value

  类型string, ArrayBuffer, number

  参数说明要设置的值

异常:

• 未初始化 Peripheral 模式
• 特征句柄无效
• 值类型无效
• 设置值失败

返回值:

类型undefined

---

函数 sendNotify peripheral侧

原型: sendNotify (char_handle:number, data:string|ArrayBuffer, is_indication:boolean=false, conn_id:number)

发送通知或指示（Peripheral 角色）

作为 Peripheral 向已连接的 Central 设备发送特征值通知或指示。 如果数据长度超过 MTU，会自动分包发送。

示例：

import * as bt from 'bt'

// 发送通知
bt.sendNotify(charHandle, 'data updated')

// 发送指示（需要确认）
bt.sendNotify(charHandle, 'important data', true)

// 发送到指定连接
bt.sendNotify(charHandle, 'data', false, connId)

参数:

• char_handle

  类型number

  参数说明特征句柄

• data

  类型string, ArrayBuffer

  参数说明要发送的数据

• is_indication

  类型boolean

  默认值false

  参数说明是否为指示（需要确认）

• conn_id

  类型number

  参数说明连接 ID（可选，默认使用最后连接的 ID）

异常:

• 未初始化 Peripheral 模式
• 特征句柄无效
• 没有设备连接
• 数据类型无效
• 发送失败

返回值:

类型undefined

Peripheral 类

Peripheral 类提供了 BLE 从机模式的完整功能，包括：

• Service 创建与管理
• Characteristic 创建与管理
• 广播
• 连接管理

bt 模块已预创建了一个 Peripheral 实例，通过 bt.peripheral 或 bt.periph, bt.pher 访问，无需手动创建。

import {pher} as bt from 'bt'
pher.init()

事件

Peripheral 类继承自 EventEmitter，支持以下事件：

事件	参数	说明
connect	(connId)	Central 设备连接时触发
disconnect	(connId, reason)	Central 设备断开连接时触发，reason 为断开原因码
open	(status)	服务开启时触发，status 为 0 表示成功
close	(status)	服务关闭时触发

示例：

import * as bt from 'bt'

// 初始化 Peripheral（使用预创建的实例）
bt.peripheral.init()

// 设置设备名称
bt.setAdvName('MyDevice')

// 添加服务
const service = bt.peripheral.addService({
  uuid: '180d',
  primary: true,
  chars: [
    {
      uuid: '2a37',
      props: ['read', 'notify']
    }
  ]
})

// 设置特征值
service.chars['2a37'].setValue('hello')

// 发送通知
service.chars['2a37'].notify('data updated')

// 开始广播
bt.startAdv()

// 监听连接事件
bt.peripheral.on('connect', (connId) => {
  console.log('设备已连接:', connId)
})

bt.peripheral.on('disconnect', (connId, reason) => {
  console.log('设备已断开:', connId, reason)
})

方法 init

原型: init ()

初始化 Peripheral 模式

初始化 BLE Peripheral (从机) 模式，注册事件回调。

示例：

import * as bt from 'bt'
bt.peripheral.init()

返回值:

类型undefined

---

方法 addService

原型: addService (options:object)

添加 GATT 服务

添加一个 GATT 服务到 Peripheral，返回 Service 对象。

示例：

import * as bt from 'bt'

const service = bt.peripheral.addService({
  uuid: '180d',
  primary: true,
  chars: [
    {
      uuid: '2a37',
      props: ['read', 'notify']
    }
  ]
})

参数:

• options

  类型object (详见下方类型定义)

  参数说明服务配置选项

  options 类型定义：

  {
      uuid: string,          // 服务的 UUID
      primary: boolean,      // 是否为主服务
      chars: Array<{         // 特征数组
        uuid: string,        // 特征的 UUID
        props: string[]      // 特征属性数组，可选值：'read', 'write', 'writeNR', 'notify', 'indicate'
                             // - 'read': 支持读取
                             // - 'write': 支持写入（需要响应）
                             // - 'writeNR': 支持写入（无需响应）
                             // - 'notify': 支持通知（主动发送数据给 Central）
                             // - 'indicate': 支持指示（需要 Central 确认）
      }>
  }

返回值:

类型Service

说明返回 Service 对象

Service 类

Service 类，表示 GATT 服务

Service 类表示 Peripheral 中的一个 GATT 服务，包含多个 Characteristic。

示例：

import * as bt from 'bt'

const service = bt.peripheral.addService({
  uuid: '180d',
  primary: true,
  chars: [
    {
      uuid: '2a37',
      props: ['read', 'notify']
    }
  ]
})

// 访问特征
const char = service.chars['2a37']

属性 chars (只读)

类型: object

chars 属性

包含该服务中所有 Characteristic 的对象，以特征的 UUID 为键。 可以通过完整 UUID 或短 UUID（前8位）访问特征。

示例：

const service = bt.peripheral.addService({
  uuid: '180d',
  primary: true,
  chars: [{ uuid: '2a37', props: ['read', 'notify'] }]
})

// 通过完整 UUID 访问
const char1 = service.chars['2a37']

// 通过短 UUID 访问（如果 UUID 是 128 位格式）
// const char2 = service.chars['xxxxxxxx']

Characteristic 类

Characteristic 类（Peripheral 侧），表示 GATT 特征

Characteristic 类继承自 EventEmitter，表示 Peripheral 服务中的一个 GATT 特征。 支持读取、写入、通知和指示等操作。

事件

Characteristic 类继承自 EventEmitter，支持以下事件：

事件	参数	说明
write	(data, connId)	Central 写入特征值时触发，data 为写入的数据，connId 为连接 ID

示例：

import * as bt from 'bt'

const service = bt.peripheral.addService({
  uuid: '180d',
  primary: true,
  chars: [
    {
      uuid: '2a37',
      props: ['read', 'write', 'notify']
    }
  ]
})

const char = service.chars['2a37']

// 设置特征值
char.setValue('hello')

// 发送通知
char.notify('data updated')

// 监听写入事件
char.on('write', (data, connId) => {
  console.log('收到写入:', data)
})

方法 notify

原型: notify (data:string|ArrayBuffer)

Characteristic 类的方法：notify（Peripheral 侧）

向已连接的 Central 设备发送通知。

示例：

const char = service.chars['2a37']
char.notify('data updated')

参数:

• data

  类型string, ArrayBuffer

  参数说明要发送的数据

异常:

• 特征不支持通知
• 没有设备连接

返回值:

类型undefined

---

方法 indicate

原型: indicate (data:string|ArrayBuffer)

Characteristic 类的方法：indicate（Peripheral 侧）

向已连接的 Central 设备发送指示（需要确认）。

示例：

const char = service.chars['2a37']
char.indicate('important data')

参数:

• data

  类型string, ArrayBuffer

  参数说明要发送的数据

异常:

• 特征不支持指示
• 没有设备连接

返回值:

类型undefined

---

方法 setValue

原型: setValue (data:string|ArrayBuffer|number)

Characteristic 类的方法：setValue（Peripheral 侧）

设置特征的本地值，当 Central 读取时返回此值。

示例：

const char = service.chars['2a37']
char.setValue('hello world')

参数:

• data

  类型string, ArrayBuffer, number

  参数说明要设置的值

返回值:

类型undefined

---

方法 notify

原型: notify (data:string|ArrayBuffer)

Characteristic 类的方法：notify（Peripheral 侧）

向已连接的 Central 设备发送通知。

示例：

const char = service.chars['2a37']
char.notify('data updated')

参数:

• data

  类型string, ArrayBuffer

  参数说明要发送的数据

异常:

• 特征不支持通知
• 没有设备连接

返回值:

类型undefined

---

方法 indicate

原型: indicate (data:string|ArrayBuffer)

Characteristic 类的方法：indicate（Peripheral 侧）

向已连接的 Central 设备发送指示（需要确认）。

示例：

const char = service.chars['2a37']
char.indicate('important data')

参数:

• data

  类型string, ArrayBuffer

  参数说明要发送的数据

异常:

• 特征不支持指示
• 没有设备连接

返回值:

类型undefined

---

方法 setValue

原型: setValue (data:string|ArrayBuffer|number)

Characteristic 类的方法：setValue（Peripheral 侧）

设置特征的本地值，当 Central 读取时返回此值。

示例：

const char = service.chars['2a37']
char.setValue('hello world')

参数:

• data

  类型string, ArrayBuffer, number

  参数说明要设置的值

返回值:

类型undefined

贡献者: alee

上一页主机(Central)

下一页Mongoose(网络库)