模块: Bluetooth
约 1650 字大约 6 分钟
2026-03-18
构建固件和导入到JS
额外组件
该功能需要安装 beshell-bt 组件才能使用。
安装方法：
- 编辑项目根目录下的
idf_component.yml文件，添加依赖：
dependencies:
become-cool/beshell-bt: '>=1.0.3'- 或在 ESP-IDF 环境的命令行中执行：
idf.py add-dependency "become-cool/beshell-bt>=1.0.3"在 C++ 里加入以下代码, 然后重新编译构建固件：
// 为了控制固件的尺寸，BeShell 的 module 是按需引入的。
beshell.use<be::bt::BT>() ;在JS中导入 bt module：
import * as bt from 'bt'import bt简介
bt 模块提供了完整的 BLE（低功耗蓝牙）功能，支持 Central（主机）和 Peripheral（从机）两种模式。
导出对象
bt 模块预创建了以下对象：
peripheral - 类 Peripheral 实例，用于 BLE 从机模式
此外，bt 模块还导出了以下简写形式，与完整名称等价：
bt.centbt.periphbt.pher
使用示例：
import * as bt from 'bt'
// 以下写法等价
bt.central.init()
bt.cent.init()
bt.peripheral.addService({...})
bt.periph.addService({...})
bt.pher.addService({...})Central 模式（主机）
Central 模式用于连接并操作其他 BLE 设备（Peripheral）：
import * as bt from 'bt'
// 初始化并扫描设备
bt.central.init()
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)
await peer.search()
// 读写特征
const data = await peer['2a37'].read()
await peer['2a37'].write(new Uint8Array([0x01]))
}
})Peripheral 模式（从机）
Peripheral 模式用于创建 BLE 服务，供其他设备（Central）连接：
import * as bt from 'bt'
// 初始化并创建服务
bt.peripheral.init()
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()模块函数
函数 setPower
原型: setPower (level:number, type:number=0)
设置 BLE 发射功率
示例：
import * as bt from 'bt'
// 设置默认发射功率为 6dBm
bt.setPower(6)
// 设置指定类型的发射功率
bt.setPower(6, 0) // 设置默认功率类型参数:
level
类型number
参数说明功率等级，取值范围 -24 ~ 21 (dBm)
type
类型number
默认值0
参数说明功率类型，0 表示默认类型
异常:
- 功率等级无效
- 功率类型无效
返回值:
类型number
说明错误码，0 表示成功
函数 power
原型: power ()
获取 BLE 当前发射功率
示例：
import * as bt from 'bt'
const power = bt.power()
console.log('当前功率:', power, 'dBm')返回值:
类型number
说明当前发射功率等级 (dBm)
函数 setRandomMac
原型: setRandomMac (mac:string)
设置 BLE 随机 MAC 地址
示例：
import * as bt from 'bt'
// 设置随机 MAC 地址
bt.setRandomMac('AA:BB:CC:DD:EE:FF')参数:
mac
类型string
参数说明MAC 地址字符串，格式为 "xx:xx:xx:xx:xx:xx"
异常:
- MAC 地址格式无效
- 设置 MAC 地址失败
返回值:
类型undefined
函数 parseAdv central侧
原型: parseAdv (raw:ArrayBuffer)
解析广播数据（Central 角色）
作为 Central 将扫描到的原始广播数据解析为对象格式，方便读取设备名称、UUID 等信息。 支持的字段包括：flag、name、shortName、complete16、more16、complete128、 more128、txPower、service16、service128、msd 等。
示例：
import * as bt from 'bt'
bt.on('scan-res', (device) => {
const adv = bt.parseAdv(device.adv_raw)
// 获取设备名称
if (adv.name) {
const name = new TextDecoder().decode(adv.name)
console.log('设备名称:', name)
}
// 获取 16-bit UUID
if (adv.complete16) {
const uuid = '0x' + Array.from(adv.complete16).map(b => b.toString(16).padStart(2, '0')).join('')
console.log('UUID:', uuid)
}
// 获取制造商数据
if (adv.msd) {
console.log('制造商数据:', adv.msd)
}
})参数:
raw
类型ArrayBuffer
参数说明原始广播数据
返回值:
类型object
说明解析后的广播数据对象，包含 name、flag、complete16 等字段
函数 waitScanning central侧
原型: waitScanning (ms:number=10000)
等待扫描完成（Central 角色）
作为 Central 等待扫描完成，返回一个 Promise，当扫描完成时 resolve。 如果当前没有在扫描，立即 resolve。扫描可能因调用 stopScan() 或达到设定的扫描持续时间而完成。
示例：
import * as bt from 'bt'
bt.startScan()
// 等待最多 10 秒扫描完成
await bt.waitScanning(10000)
console.log('扫描完成')
// 无限等待扫描完成
await bt.waitScanning()参数:
ms
类型number
默认值10000
参数说明超时时间（毫秒），0 表示无限等待
返回值:
类型Promise<undefined>
说明扫描完成时 resolve，超时时 reject
函数 setMTU
原型: setMTU (mtu:number)
设置本地 MTU 大小
设置 BLE 协议栈的本地 MTU (Maximum Transmission Unit) 大小。 默认值为 23 字节，最大可设置为 517 字节。
示例：
import * as bt from 'bt'
// 设置 MTU 为 185 字节
bt.setMTU(185)参数:
mtu
类型number
参数说明MTU 大小，范围 23 ~ 517
异常:
- MTU 大小无效
- 设置 MTU 失败
返回值:
类型undefined
函数 getMTU
原型: getMTU ()
获取当前 MTU 大小
获取当前设置的本地 MTU 大小。
示例：
import * as bt from 'bt'
const mtu = bt.getMTU()
console.log('当前 MTU:', mtu)返回值:
类型number
说明当前 MTU 大小