BeShell 文档

简体中文

English

简体中文

English

从机

约 1702 字大约 6 分钟

2026-03-19

Peripheral 类

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

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