在嵌入式物联网应用中，低功耗蓝牙（BLE）是实现短距离无线交互的关键技术。LuatOS通过其内置的【ble】库，为开发者提供了完整且高效的API接口，支持从角色管理到GATT服务操作的全流程控制，适用于各类传感器节点、智能穿戴设备等场景开发。
一、概述
1.1 模式解释 -> BLE 不同模式的解读
BLE设备，可以工作在几种不同的模式： 外围设备模式，中心设备模式，广播者模式，观察者模式。
外围设备模式(peripheral), 设备会被扫描到, 并且可以被连接；
中心设备模式(central), 设备会扫描其他设备, 并且可以连接其他设备；
广播者模式(ibeacon), 设备会周期性的广播 beacon 信息, 可以被扫描到, 但一般不会被连接；
观察者模式(scan), 设备会扫描其他设备, 但不会连接其他设备。
注： 目前Air8000,Air8101 只能支持同时连接一个从设备。
1.2 蓝牙中的重要概念
1、GATT（通用属性配置文件）
定义 BLE 设备如何组织和传输数据，以 “服务（Service）” 和 “特征（Characteristic）” 为单位。
示例：心率监测设备的 GATT 服务包含 “心率特征”，手机通过读取该特征获取心率数据。
2、服务和特征
服务是特征的容器，通过逻辑分组简化复杂功能的管理；
特征是数据交互的最小单元，通过属性定义实现灵活的读写与推送机制；
两者结合构成 GATT 协议的核心框架，支撑蓝牙设备间的标准化数据交互（如智能穿戴、医疗设备、物联网传感器）。
3、特征的关键属性（Properties）
特征通过"属性"定义数据的操作方式。从 GATT 通信角色看：
服务端（通常为外围设备）：存储特征值的数据提供方
客户端（通常为中心设备）：操作特征值的数据消费方
常见属性包括：
1）可读（Read）：允许客户端读取服务端的特征值（如手机读取手环的电量）。
2）可写（Write）：允许客户端向服务端写入特征值（如手机设置设备的参数）。
3）通知（Notify）：服务端主动向客户端推送特征值更新（如手环向手机推送心率数据）。
4、UUID
UUID 是蓝牙 GATT 协议的 “数字身份证”，通过标准化的唯一标识机制，实现了跨厂商设备的功能互认（标准 UUID）与厂商个性化功能的扩展（自定义 UUID）
注：
一个蓝牙设备可以包含多个服务（Service），每个服务通过一个 UUID（服务UUID） 进行标识。
每个服务下包含多个特征（Characteristic），每个特征都拥有一个独立的UUID（特征UUID）作为其唯一标识。
特征是最小的数据单元，我们通过读写特征来与设备交互。
1.3 四种模式的基本流程
1.3.1 外围设备模式(peripheral)的基本流程(概要描述)
1、初始化蓝牙框架
bluetooth_device = bluetooth.init()
2、创建 BLE 对象
local ble_device = bluetooth_device:ble(ble_callback)
3、创建 GATT 描述
local att_db = {xxx}
ble_device:gatt_create(att_db)
4、创建广播信息
ble_device:adv_create(adv_data)
5、开始广播
ble_device:adv_start()
6、等待连接
7、在回调函数中处理连接事件, 如接收数据, 发送数据等
1.3.2 中心设备模式(central)的基本流程(概要描述)
1、初始化蓝牙框架
bluetooth_device = bluetooth.init()
2、创建 BLE 对象
local ble_device = bluetooth_device:ble(ble_callback)
3、扫描目标 BLE 设备
ble_device:scan_start()
4、建立与目标设备的连接
ble_device:connect(mac, add_type)
5、处理各类 BLE 事件（连接、断开连接、扫描报告、GATT 操作完成等）
1.3.3 广播者模式(ibeacon)的基本流程(概要描述)
1、初始化蓝牙底层框架
bluetooth_device = bluetooth.init()
2、创建 BLE 对象
local ble_device = bluetooth_device:ble(ble_callback)
3、配置 ibeacon 广播数据包
包含厂商特定数据格式,ibeacon 类型标识符，设置UUID、Major、Minor等关键参数
4、启动 BLE 广播功能
ble_device:adv_start()
1.3.4 观察者模式(scan)的基本流程(概要描述)
1、初始化蓝牙框架
bluetooth_device = bluetooth.init()
2、创建 BLE 对象
local ble_device = bluetooth_device:ble(ble_callback)
3、开始扫描
ble_device:scan_start()
4、在回调函数中处理扫描事件, 如接收设备信息等
5、按需停止扫描
ble_device:scan_stop()
1.4 应用场景
1.4.1 外围设备 + 中心设备（连接模式）
设计框图：
1.4.2 广播者 + 观察者（无连接模式）
设计框图：
1.5 注意事项
1、Air8000,Air8101 只能支持同时连接一个从设备。
2、Air8000,Air8101 蓝牙发射功率固定为 6dBm，不可调节；最大通讯距离约为10米。
3、Air8000,Air8101 的MTU（最大传输单元）为 256 字节，不可调整，超过256字节的数据需要分包处理。
二、核心示例
核心示例是指：使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码；
核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；
2.1 中心设备模式(central)的核心示例
2.2 外围设备模式(peripheral)的核心示例
2.3 广播者模式(ibeacon)的核心示例
2.4 观察者模式(scan)的核心示例
三、常量详解
核心库常量，顾名思义是由 LuatOS 内核固件中定义的、不可重新赋值或修改的固定值，在脚本代码中不需要声明，可直接调用；
每个常量对应的常量取值仅做日志打印时查询使用，不要将这个常量取值用做具体的业务逻辑判断，因为LuatOS内核固件可能会变更每个常量对应的常量取值；
如果用做具体的业务逻辑判断，一旦常量取值发生改变，业务逻辑就会出错；
3.1 地址模式常量
3.1.1 ble.PUBLIC
3.2 特征属性常量
3.2.1 ble.READ
3.2.2 ble.WRITE
3.2.3 ble.NOTIFY
3.2.4 ble.IND
3.2.5 ble.WRITE_CMD
3.3 事件类型常量
3.3.1 ble.EVENT_CONN
3.3.2 ble.EVENT_DISCONN
3.3.3 ble.EVENT_WRITE
3.3.4 ble.EVENT_READ_VALUE
3.3.5 ble.EVENT_SCAN_REPORT
3.3.6 ble.EVENT_GATT_ITEM
3.3.7 ble.EVENT_GATT_DONE
3.3.8 ble.EVENT_SCAN_STOP
3.4 广播相关常量
3.4.1 ble.COMPLETE_LOCAL_NAME
3.4.2 ble.CHNLS_ALL
3.4.3 ble.CHNL_37
3.4.4 ble.CHNL_38
3.4.5 ble.CHNL_39
3.4.6 ble.FLAGS
3.4.7 ble.SERVICE_DATA
3.4.8 ble.MANUFACTURER_SPECIFIC_DATA
3.5 扫描相关常量
3.5.1 ble.SCAN_ACTIVE
3.5.2 ble.SCAN_PASSIVE
四、函数详解
4.1 bluetooth.init()
功能
初始化蓝牙框架
注意事项
必须在使用蓝牙功能之前调用；
仅需要调用一次,若创建失败, 会返回nil, 请检查内存是否足够。
参数
无
返回值
local bluetooth_device = bluetooth.init()
bluetooth_device
示例
4.2 bluetooth_device:ble(ble_callback)
功能
创建一个BLE对象, 用于操作BLE设备
注意事项
必须在bluetooth.init()初始化成功后调用
参数
ble_callback
返回值
local ble_device = bluetooth_device:ble(ble_callback)
ble_device
示例
4.3 ble_device:scan_create(addr_mode,scan_interval,scan_window,scan_type)
功能
创建一个 BLE 扫描
注意事项
默认扫描模式为 ble.SCAN_PASSIVE，仅接收广播包，不向广播设备发送任何请求；
如果设备名称在扫描响应包中，则需要设置扫描模式为 ble.SCAN_ACTIVE ，此时会向广播设备发送扫描请求（Scan Request），并接收广播设备的扫描响应（Scan Response）；
参数
addr_mode
scan_interval
scan_window
scan_type
返回值
local result = ble_device:scan_create(addr_mode,scan_interval,scan_window,scan_type)
result
示例
4.4 ble_device:scan_start()
功能
开始 BLE 扫描
注意事项
扫描会一直进行, 直到调用 ble.scan_stop()停止扫描；
扫描到结果会触发 ble.EVENT_SCAN_REPORT 事件，执行通过 bluetooth_device:ble(ble_callback)创建 BLE 对象时注册的回调函数；
扫描到同一个设备不会去重, 扫描到数据就会执行回调。
参数
无
返回值
local result = ble_device:scan_start()
result
示例
4.5 ble_device:scan_stop()
功能
停止 BLE 扫描
注意事项
扫描会一直进行, 直到调用 ble.scan_stop()停止扫描。
参数
无
返回值
local result = ble_device:scan_stop()
result
示例
4.6 ble_device:connect(mac, addr_type)
功能
发起 BLE 连接请求
注意事项
无
参数
mac
addr_type
返回值
local result = ble_device:connect(mac, addr_type)
result
示例
4.7 ble_device:disconnect()
功能
发起 BLE 断开连接请求
注意事项
无
参数
无
返回值
local result = ble_device:disconnect()
result
示例
4.8 ble_device:gatt_create(opts)
功能
创建一个 BLE GATT 服务
注意事项
确保 UUID 格式正确，且特征属性使用正确的权限常量；
特征属性必须是 ble.NOTIFY | ble.READ | ble.WRITE | ble.IND 的一种或多种组合；
参数
opts
返回值
local result = ble_device:gatt_create(opts)
result
示例
4.9 ble_device:adv_create(opts)
功能
创建一个 BLE 广播
注意事项
无
参数
opts
返回值
local result = ble:adv_create(opts)
result
示例
4.10 ble_device:adv_start()
功能
开始广播
注意事项
对于外围设备模式, 如果被断开了连接, 则需要重新开始广播, 才能被重新搜索到
参数
无
返回值
local result = ble_device:adv_start()
result
示例
4.11 ble_device:adv_stop()
功能
主动停止广播
注意事项
无
参数
无
返回值
local result = ble_device:adv_stop()
result
示例
4.12 ble_device:write_notify(opts,value)
功能
写入带通知的特征值
注意事项
外围设备使用，主动向中心设备发送通知数据
参数
opts
value
返回值
local result = ble_device:write_notify(opts,value)
result
示例
4.13 ble_device:write_indicate(opts,value)
功能
写入带指示的特征值
注意事项
外围设备使用，主动向中心设备发送指示数据
参数
opts
value
返回值
local result = ble:write_indicate(opts,value)
result
示例
4.14 ble_device:write_value(opts,value)
功能
写入特征值
注意事项
无
参数
opts
value
返回值
local result = ble_device:write_value(opts,value)
result
示例
4.15 ble_device:read_value(opts)
功能
读取特征值
注意事项
无
参数
opts
返回值
local result = ble_device:read_value(opts)
result
示例
4.16 ble_device:notify_enable(opts,enable)
功能
开关通知监听
注意事项
中心设备使用，配置是否接收外围设备发送的通知消息
参数
opts
enable
返回值
local result = ble_devie:notify_enable(opts,enable)
result
示例
4.17 ble_device:indicate_enable(opts,enable)
功能
开关指示监听
注意事项
中心设备使用，配置是否接收外围设备发送的指示消息
参数
opts
enable
返回值
local result = ble_device:indicate_enable(opts,enable)
result
示例
4.18 ble_device:adv_decode(data)
功能
解码广播数据
注意事项
广播数据通常来自于 ble.EVENT_SCAN_REPORT 事件的 ble_param.data
参数
data
返回值
local adv_data = ble_device:adv_decode(data)
adv_data
示例
4.19 ble.mac()
功能
获取蓝牙 MAC
注意事项
1、AP，STA，BLE三者的MAC地址关系：
AP = STA + 1 BLE = STA + 2
例如： STA = "C8C2C6906511" AP = "C8C2C6906512" BLE = "C8C2C6906513"
2、如何获取AP或者STA MAC地址？
使用wlan.getMac(mode, hexstr) 获取AP或者STA MAC地址，具体用法请参考：https://docs.openluat.com/osapi/core/wlan/#410-wlansetmacmode-mac
参数
无
返回值
local mac = ble.mac
mac
示例
五、模组支持说明
适用于 Air8000,Air8000A,Air8000W,Air8000XB,Air8000U,Air8000WU,Air8000N,Air8000WN，以及 Air6101/Air8101 系列 此类支持蓝牙功能的模组。
今天的内容就分享到这里了~
