nimble - 蓝牙BLE库(nimble版)#

已适配 Air101/Air103 ESP32C3 ESP32S3

备注

本页文档由这个文件自动生成。如有错误，请提交issue或帮忙修改后pr，谢谢！

小技巧

示例

-- 本库当前支持Air101/Air103/ESP32/ESP32C3/ESP32S3
-- 用法请查阅demo, API函数会归于指定的模式

nimble.init(name)#

初始化BLE上下文,开始对外广播/扫描

参数

传入值类型	解释
string	蓝牙设备名称,可选,建议填写

返回值

返回值类型	解释
bool	成功与否

例子

-- 参考 demo/nimble
-- 本函数对所有模式都适用

nimble.deinit()#

关闭BLE上下文

参数

无

返回值

返回值类型	解释
bool	成功与否

例子

-- 仅部分设备支持,当前可能都不支持
-- 本函数对所有模式都适用

nimble.send_msg(conn, handle, data)#

发送信息

参数

传入值类型	解释
int	连接id, 当前固定填1
int	处理id, 当前固定填0
string	数据字符串,可包含不可见字符

返回值

返回值类型	解释
bool	成功与否

例子

-- 参考 demo/nimble
-- 本函数对peripheral/从机模式适用

nimble.scan()#

扫描从机

参数

无

返回值

返回值类型	解释
bool	成功与否

例子

-- 参考 demo/nimble
-- 本函数对central/主机模式适用
-- 本函数会直接返回, 然后通过异步回调返回结果

nimble.mode(tp)#

设置模式

参数

传入值类型	解释
int	模式, 默认server/peripheral, 可选 client/central模式 nimble.MODE_BLE_CLIENT

返回值

返回值类型	解释
bool	成功与否

例子

-- 参考 demo/nimble
-- 必须在nimble.init()之前调用
-- nimble.mode(nimble.MODE_BLE_CLIENT) -- 简称从机模式,未完善

nimble.setUUID(tp, addr)#

设置server/peripheral的UUID

参数

传入值类型	解释
string	配置字符串,后面的示例有说明
string	地址字符串

返回值

返回值类型	解释
bool	成功与否

例子

-- 参考 demo/nimble, 2023-02-25之后编译的固件支持本API
-- 必须在nimble.init()之前调用
-- 本函数对peripheral/从机模式适用

-- 设置SERVER/Peripheral模式下的UUID, 支持设置3个
-- 地址支持 2/4/16字节, 需要二进制数据
-- 2字节地址示例: AABB, 写 string.fromHex("AABB") ,或者 string.char(0xAA, 0xBB)
-- 4字节地址示例: AABBCCDD , 写 string.fromHex("AABBCCDD") ,或者 string.char(0xAA, 0xBB, 0xCC, 0xDD)
nimble.setUUID("srv", string.fromHex("380D"))      -- 服务主UUID         ,  默认值 180D
nimble.setUUID("write", string.fromHex("FF31"))    -- 往本设备写数据的UUID,  默认值 FFF1
nimble.setUUID("indicate", string.fromHex("FF32")) -- 订阅本设备的数据的UUID,默认值 FFF2

nimble.mac()#

获取蓝牙MAC

参数

无

返回值

返回值类型	解释
string	蓝牙MAC地址,6字节

例子

-- 参考 demo/nimble, 2023-02-25之后编译的固件支持本API
-- 本函数对所有模式都适用
local mac = nimble.mac()
log.info("ble", "mac", mac and mac:toHex() or "Unknwn")

nimble.ibeacon(data, major, minor, measured_power)#

配置iBeacon的参数,仅iBeacon模式可用

参数

传入值类型	解释
string	数据, 必须是16字节
int	主版本号,默认2, 可选, 范围 0 ~ 65536
int	次版本号,默认10,可选, 范围 0 ~ 65536
int	名义功率, 默认0, 范围 -126 到 20

返回值

返回值类型	解释
bool	成功返回true,否则返回false

例子

-- 参考 demo/nimble, 2023-02-25之后编译的固件支持本API
-- 本函数对ibeacon模式适用
nimble.ibeacon(data, 2, 10, 0)
nimble.init()

nimble.advData(data, flags)#

配置广播数据,仅iBeacon模式可用

参数

传入值类型	解释
string	广播数据, 当前最高128字节
int	广播标识, 可选, 默认值是 0x06,即不支持传统蓝牙(0x04) + 普通发现模式(0x02)

返回值

返回值类型	解释
bool	成功返回true,否则返回false

例子

-- 参考 demo/nimble/adv_free, 2023-03-18之后编译的固件支持本API
-- 本函数对ibeacon模式适用
-- 数据来源可以多种多样
local data = string.fromHex("123487651234876512348765123487651234876512348765")
-- local data = crypto.trng(25)
-- local data = string.char(0x11, 0x13, 0xA3, 0x5A, 0x11, 0x13, 0xA3, 0x5A, 0x11, 0x13, 0xA3, 0x5A, 0x11, 0x13, 0xA3, 0x5A)
nimble.advData(data)
nimble.init()

-- nimble支持在init之后的任意时刻再次调用, 以实现数据更新
-- 例如 1分钟变一次
while 1 do
    sys.wait(60000)
    local data = crypto.trng(25)
    nimble.advData(data)
end

nimble.advParams(conn_mode, disc_mode, itvl_min, itvl_max, channel_map, filter_policy, high_duty_cycle)#

设置广播参数

参数

传入值类型	解释
int	广播模式, 0 - 不可连接, 1 - 定向连接, 2 - 未定向连接, 默认0
int	发现模式, 0 - 不可发现, 1 - 限制发现, 3 - 通用发现, 默认0
int	最小广播间隔, 0 - 使用默认值, 范围 1 - 65535, 单位0.625ms, 默认0
int	最大广播间隔, 0 - 使用默认值, 范围 1 - 65535, 单位0.625ms, 默认0
int	广播通道, 默认0, 一般不需要设置
int	过滤规则, 默认0, 一般不需要设置
int	当广播模式为”定向连接”时,是否使用高占空比模式, 默认0, 可选1

返回值

返回值类型	解释
nil	无返回值

例子

-- 当前仅ibeacon模式/peripheral/从机可使用
-- 例如设置 不可连接 + 限制发现
-- 需要在nimble.init之前设置好
nimble.advParams(0, 1)
-- 注意peripheral模式下自动配置 conn_mode 和 disc_mode