一、概述

exril_5101 是一个基于 LuatOS 框架，专为 Air5101 BLE 模块 开发的 LuatOS 扩展库；

该库封装了 Air5101 蓝牙模块的底层 AT 指令集，提供简洁、易用的 API 接口，简化了蓝牙应用的开发复杂度。

二、核心示例

-- 加载蓝牙扩展库
local exril_5101 = require("exril_5101")

-- =============== 任务队列和优先级管理 ===============
-- 看门狗定时喂狗任务和数据循环发送任务 可能会同时执行导致冲突，所以加上优先级处理
local task_queue = {}
local task_priority = {
    watchdog = 1,  -- 最高优先级
    data_send = 2, -- 次高优先级
}
local is_watchdog_running = false
local is_connected = false

-- 添加任务到队列
local function add_task(task_type, task_func, params)
    table.insert(task_queue, {
        type = task_type,
        priority = task_priority[task_type] or 999,
        func = task_func,
        params = params
    })
    -- 按优先级排序，优先级数字越小优先级越高
    table.sort(task_queue, function(a, b)
        return a.priority < b.priority
    end)
end

-- 任务处理函数
local function process_tasks()
    while true do
        if #task_queue > 0 then
            -- 取出第一个任务（优先级最高的）
            local task = table.remove(task_queue, 1)
            log.info("main", "执行任务:", task.type)

            -- 标记看门狗任务正在执行
            if task.type == "watchdog" then
                is_watchdog_running = true
            end

            -- 执行任务
            task.func(task.params)

            -- 标记看门狗任务执行完成
            if task.type == "watchdog" then
                is_watchdog_running = false
            end
        end
        sys.wait(100)  -- 每100ms检查一次任务队列
    end
end

-- 启动任务处理线程
sys.taskInit(process_tasks)

-- =============== 配置参数 ===============
local config = {
    -- 设备名称（不超过20字符）
    device_name = "Air5101_Demo",
    -- 广播类型（可连接）
    adv_type = exril_5101.ADV_C,
    -- 广播间隔（毫秒）
    adv_interval = 50,
    -- 广播数据
    adv_data = "02010603031218",
}

-- =============== 事件回调处理 ===============
local function ble_event_handler(event, payload)
    log.info("蓝牙事件", "事件类型:", event)
    if event == "connected" then
        log.info("蓝牙事件", "蓝牙已连接") 
        is_connected = true

    elseif event == "disconnected" then
        log.info("蓝牙事件", "蓝牙已断开")
        is_connected = false

    elseif event == "data" then
        -- 收到蓝牙数据
        log.info("main", "收到数据 [模式:" .. payload.mode .. "]:", payload.data)

        -- 收到数据后自动回复
        exril_5101.send("AT:ACK " .. payload.data)
    end
end

-- =============== 初始化示例 ===============
local function ble_init()
    log.info("main", "\n========== 初始化示例 ==========")

    -- 1. 获取当前工作模式
    local success, mode = exril_5101.mode()
    if success then
        log.info("main", "当前工作模式:", mode)
    else
        log.error("main", "获取模式失败:", mode)
    end

    -- 2. 切换到AT模式（确保可以配置参数）
    log.info("main", "切换到AT指令模式...")
    success, mode = exril_5101.mode(exril_5101.MODE_AT)
    if not success then
        log.error("main", "切换AT模式失败:", mode)
        return false
    end
    log.info("main", "已切换到:", mode)

    -- 3. 配置设备参数
    log.info("main", "配置设备参数...")
    local config_result, err = exril_5101.set({
        name = config.device_name,
        adv_type = config.adv_type,
        adv_data = config.adv_data,
        adv_interval = config.adv_interval
    })

    if config_result then
        log.info("main", "参数配置成功")
    else
        log.error("main", "参数配置失败:", err)
    end

    -- 4. 查询设备信息
    log.info("main", "查询设备信息...")
    local info, err = exril_5101.get({"name", "mac", "ver"})
    if info then
        log.info("main", "设备名称:", info.name or "未知")
        log.info("main", "MAC地址:", info.mac or "未知")
        log.info("main", "固件版本:", info.ver or "未知")
    else
        log.error("main", "查询失败:", err)
    end

    return true
end

-- =============== 功耗管理示例 ===============
local function power_demo()
    log.info("main", "\n========== 功耗管理示例 ==========")

    -- 获取当前功耗模式
    local success, mode = exril_5101.power()
    if success then
        local mode_names = {["exril_5101.P0"]="常规模式", ["exril_5101.P1"]="低功耗模式1", ["exril_5101.P3"]="低功耗模式3"}
        log.info("main", "当前功耗模式:", mode, mode_names[mode] or "未知")
    end

    -- 设置低功耗模式1
    log.info("main", "切换到低功耗模式1...")
    local success, msg = exril_5101.power(exril_5101.P1)
    if success then
        log.info("main", "低功耗模式1设置成功")
    else
        log.error("main", "低功耗模式1设置失败:", msg)
    end

    sys.wait(1000)
    -- 唤醒并切换到常规模式（最多尝试3次）
    local max_retries = 3
    local success = false
    local msg = ""

    for i = 1, max_retries do
        log.info("main", "尝试切换到常规模式 (" .. i .. "/" .. max_retries .. ")...")
        success, msg = exril_5101.power(exril_5101.P0, true)
        if success then
            log.info("main", "第" .. i .. "次切换到常规模式成功")
            break
        else
            log.error("main", "第" .. i .. "次切换常规模式失败:", msg)
            if i < max_retries then
                log.info("main", "300ms后重试...")
                sys.wait(300)
            end
        end
    end

    if not success then
        log.error("main", "多次尝试切换常规模式失败")
    end
end

-- =============== 看门狗示例 ===============
-- 喂狗任务执行函数
local function execute_watchdog_task()
    -- 先切换到AT模式
    local mode_success, mode_result = exril_5101.mode(exril_5101.MODE_AT)
    if not mode_success then
        log.error("看门狗", "切换到AT模式失败:", mode_result)
        return
    end

    -- 执行喂狗
    local fed_success, fed_msg = exril_5101.wdfed()
    if fed_success then
        log.info("main", "喂狗成功")
    else
        log.error("main", "喂狗失败:", fed_msg)
    end
end

-- 喂狗任务函数
local function watchdog_feed_task()
    while true do
        sys.wait(10000)  -- 10秒喂一次
        add_task("watchdog", execute_watchdog_task)
    end
end
local function watchdog_demo()
    log.info("main", "\n========== 看门狗示例 ==========")

    -- 查询看门狗配置
    local success, config = exril_5101.wdcfg()
    if success then
        log.info("main", "当前看门狗配置:")
        log.info("main", "  使能:", config.en)
        log.info("main", "  超时:", config.timeout, "秒")
        log.info("main", "  电平:", config.level)
        log.info("main", "  脉宽:", config.width, "ms")
    end

    -- 开启看门狗（30秒超时，超时后拉低100ms）
    log.info("main", "开启看门狗...")
    local success, msg = exril_5101.wdcfg(true, 30, 0, 100)
    if success then
        log.info("main", "看门狗已开启")

        -- 启动喂狗任务
        sys.taskInit(watchdog_feed_task)
    else
        log.error("main", "看门狗配置失败:", msg)
    end
end


-- =============== 数据收发示例 ===============
-- 数据发送任务执行函数
local function execute_data_send_task()    
    if is_connected then
        local send_success, send_message = exril_5101.send("heartbeat" .. os.time())
        if send_success then
            log.info("心跳包", "发送成功")
        else
            log.error("心跳包", "发送失败:", send_message)
        end
    end
end

-- 数据发送任务函数
local function data_send_task()
    while true do
        sys.wait(5000)
        add_task("data_send", execute_data_send_task)
    end
end

local function data_transfer_demo()
    log.info("main", "\n========== 数据收发示例 ==========")

    -- 每10秒尝试发送一次数据
    sys.taskInit(data_send_task)
end


-- =============== 主任务 ===============
local function main_task()
    log.info("main", "====================================")
    log.info("main", "exril_5101 蓝牙模块启动")
    log.info("main", "项目:", PROJECT)
    log.info("main", "版本:", VERSION)
    log.info("main", "====================================")

    -- 注册事件回调
    local reg_success, reg_err = exril_5101.on(ble_event_handler)
    if reg_success then
        log.info("main", "事件回调注册成功")
    else
        log.error("main", "事件回调注册失败:", reg_err)
        return
    end

    -- 初始化
    local result = ble_init()
    if not result then
        log.error("main", "初始化配置失败，退出")
        return
    end

    -- 功耗管理演示
    power_demo()

    -- 看门狗演示
    watchdog_demo()

    -- 数据收发演示
    data_transfer_demo()

    log.info("main", "\n所有演示任务已启动，等待蓝牙连接...")
end

-- 启动主任务
sys.taskInit(main_task)

三、常量详解

扩展库常量，由 excloud 扩展库中定义的、不可重新赋值或修改的固定值；

3.1 功耗模式常量

3.1.1 exril_5101.P0

常量含义：常规模式，正常运行；
数据类型：string；
注意事项：无；
示例代码：exril_5101.power(exril_5101.P0)

3.1.2 exril_5101.P1

常量含义：低功耗模式1，蓝牙可连接，唤醒后继续保持低功耗模式1；
数据类型：string；
注意事项：蓝牙可以被发现、连接，可通过串口或蓝牙数据唤醒，唤醒后80ms左右后会再次进入低功耗模式1；
示例代码：exril_5101.power(exril_5101.P1)

3.1.3 exril_5101.P3

常量含义：低功耗模式3，唤醒后自动恢复到常规模式0；
数据类型：string；
注意事项：蓝牙可以被发现、连接，可通过串口或蓝牙数据唤醒，唤醒后自动退出低功耗模式3，恢复为常规模式0；
示例代码：exril_5101.power(exril_5101.P3)

3.2 蓝牙工作模式

3.2.1 exril_5101.MODE_UA

常量含义：uart透传模式；
数据类型：string；
注意事项：模组上电默认透传模式；
示例代码：exril_5101.mode(exril_5101.MODE_UA)

3.2.2 exril_5101.MODE_AT

常量含义：AT指令模式；
数据类型：string；
注意事项：模组上电默认透传模式；
示例代码：exril_5101.mode(exril_5101.MODE_AT)

3.3 广播类型

3.3.1 exril_5101.ADV_N

常量含义：不可连接广播；
数据类型：string；
注意事项：设备只广播数据，不接受连接请求；
示例代码：exril_5101.set("adv_type", exril_5101.ADV_N)

3.3.2 exril_5101.ADV_C

常量含义：可连接广播；
数据类型：string；
注意事项：设备广播数据并接受连接请求；
示例代码：exril_5101.set("adv_type", exril_5101.ADV_C)

四、函数详解

函数使用总体说明：

在使用 exril_5101 扩展库的 API 函数时，需要注意以下重要事项：

1、必须在任务（task）中使用的函数

以下函数包含 sys.wait() 延时操作，必须在任务函数中调用：

• exril_5101.send() – 当启用唤醒功能（wakeup_option）时，内部会调用 sys.wait() 进行延时

• exril_5101.mode()

• exril_5101.set()

• exril_5101.get()

• exril_5101.restore()

• exril_5101.restart()

• exril_5101.disconnect()

• exril_5101.status()

• exril_5101.power()

• exril_5101.wdcfg()

• exril_5101.wdfed()

• exril_5101.wakeup()

• exril_5101.save()

• exril_5101.send()

2、可在任意上下文使用的函数

以下函数不包含延时操作，可在任意上下文（包括回调函数）中调用：

• exril_5101.on() – 仅注册回调函数，无等待

4.1 exril_5101.mode(mode，timeout)

功能：

模式切换；

注意事项：

Air5101 模块上电默认是 exril_5101.MODE_UA 透传模式；

参数：

mode

参数含义：工作模式；
数据类型：number；
取值范围：exril_5101.MODE_UA或exril_5101.MODE_AT；
是否必选：否；
注意事项：不选表示获取当前模式，
         exril_5101.MODE_UA：透传模式，
         exril_5101.MODE_AT：AT指令模式；
参数实例：exril_5101.MODE_UA或exril_5101.MODE_AT

timeout

参数含义：同步超时时长；
数据类型：number；
取值范围：1-10000，单位：ms；
是否必选：否；
注意事项：仅同步调用时有效，默认200ms；

返回值：

local result1, result2 = exril_5101.mode(mode)

result1

含义说明：是否配置模式成功；
数据类型：boolean；
取值范围：true/false；
注意事项：true表示模式配置成功，false表示模式配置失败；
返回示例：成功返回：true 失败返回：false

result2

含义说明：当前模式或错误信息；
数据类型：string；
取值范围：模式字符串或错误信息；
注意事项：成功时返回当前模式，失败时返回错误信息；
返回示例：成功返回：exril_5101.MODE_UA或者exril_5101.MODE_AT
         失败返回：错误信息

示例：

-- 示例1：获取当前模式
local result1, result2 = exril_5101.mode()
log.info("success", result1, "mode", result2)

-- 示例2：切换到透传模式（准备传输数据）
local result1, result2 = exril_5101.mode(exril_5101.MODE_UA)
log.info("success", result1, "result", result2)

-- 示例3：切换回AT指令模式（需要配置参数时）
local result1, result2 = exril_5101.mode(exril_5101.MODE_AT)
log.info("success", result1, "result", result2)

4.2 exril_5101.set(config，timeout)

功能：

设置 Air5101 模块参数，如设备名称、广播参数、连接参数等;

注意事项：

1、必须在 AT 模式下设置参数，设置前请先调用 exril_5101.mode(exril_5101.MODE_AT) 切换到 AT 模式；

2、配置会自动保存到 Flash，掉电不消失；

3、配置成功后，函数会自动调用 exril_5101.save() 保存配置；

4、mac 地址不要轻易设置，模块出厂前已经内置了不可擦除的 mac 地址，如果使用此接口设置 mac 地址，则原先的 mac 地址将会被替换，同时设置后的 mac 地址可通过 exril_5101.restore()接口擦除！！！！！！

参数：

config

> 参数含义：配置参数表，用于配置Air5101模块参数；参数为table类型时，table内容格式说明如下：  
> {  
> 参数含义：设备广播时显示的名称；  
> 数据类型：string；  
> 取值范围：不超过20字节；  
> 是否必选：可选，默认设备名称为"Air5101S"；  
> 注意事项：无；  
> 参数示例：name = "Air5101"  
> 参数名称：config.name  
> 
> 参数含义：广播类型；  
> 数据类型：string；  
> 取值范围：exril\_5101.ADV\_N 或 exril\_5101.ADV\_C；  
> 是否必选：可选，默认exril\_5101.ADV\_C；  
> 注意事项：无；  
> 参数示例：adv\_type = exril\_5101.ADV\_C  
> 参数名称：config.adv\_type  
> 
> 参数含义：广播数据；  
> 数据类型：string；  
> 取值范围：不超过31字节的十六进制字符串；  
> 是否必选：可选，默认"020106",代表\[长度2\]\[类型1-广播标志\]\[06-通用发现模式\]；  
> 注意事项：无；  
> 参数示例：adv\_data = "02010603031218"  
> 数据解析:  
> 02 01 06 → \[长度2字节\]\[类型1-广播标志\]\[06-通用发现模式\]  
> 03 03 12 18 → \[长度3字节\]\[类型3-16位UUID\]\[0x1812\]  
> 参数名称：config.adv\_data  
> 
> 参数含义：扫描响应数据；  
> 数据类型：string；  
> 取值范围：不超过31字节的十六进制字符串；  
> 是否必选：可选，默认空；  
> 注意事项：仅在蓝牙连接状态下可设置；  
> 参数示例：scan\_rsp\_data = "080941697235313031"  
> 数据解析:  
> 08 = 长度字节 (1字节类型 + 7字节数据 = 8字节)  
> 09 = 数据类型 (09表示完整设备名称)  
> 41 69 72 35 31 30 31 = "Air5101"的ASCII码  
> 参数名称：config.scan\_rsp\_data  
> 
> 参数含义：广播间隔；  
> 数据类型：number；  
> 取值范围：20-10000ms；  
> 是否必选：可选，默认30ms；  
> 注意事项：无；  
> 参数示例：adv\_interval = 1000 --设置广播间隔为1s  
> 参数名称：config.adv\_interval  
> 
> 参数含义：连接间隔；  
> 数据类型：number；  
> 取值范围：7.5-2000ms；  
> 是否必选：可选，默认30ms；  
> 注意事项：仅在蓝牙连接状态下可设置；  
> 参数示例：conn\_interval = 1000 --设置连接间隔为1s  
> 参数名称：config.conn\_interval  
> 
> 参数含义：MTU长度；  
> 数据类型：number；  
> 取值范围：23-512；  
> 是否必选：可选，默认512；  
> 注意事项：仅在蓝牙连接状态下可设置；  
> 参数示例：mtu\_len= 512  
> 参数名称：config.mtu\_len  
> 
> 参数含义：波特率；  
> 数据类型：number；  
> 取值范围：可选择波特率表:{921600,460800,230400,115200,57600,38400,19200,9600,4800,2400}；  
> 是否必选：可选，默认9600；  
> 参数示例：baud = 115200  
> 参数名称：config.baud  
> }  
> 
> 数据类型：table；  
> 取值范围：无；  
> 是否必选：是；  
> 注意事项：无；  
> 参数示例：设置设备名称、广播类型和广播间隔：  
> {  
> name = "MyDevice",  
> adv\_type = exril\_5101.ADV\_C,  
> adv\_interval = 1000  
> }  

timeout

参数含义：同步超时时长；
数据类型：number；
取值范围：1-10000，单位：ms；
是否必选：否；
注意事项：仅同步调用时有效，默认200ms；

返回值：

local result1, result2 = exril_5101.set(config)

result1

含义说明：是否设置成功；
数据类型：boolean；
取值范围：true/false；
注意事项：true表示所有参数设置成功，false表示有参数设置失败；
返回示例：成功返回：true 失败返回：false

result2

含义说明：设置结果或错误信息；
         结果表结构（成功时）：   
         {       
             [参数名1] = {           
                 success  -- boolean 该参数是否设置成功          
                 value    -- any 实际设置的值          
                 message  -- string 设置结果描述      
             },       
             [参数名2] = {           
                 success  -- boolean 该参数是否设置成功         
                 value    -- any 实际设置的值         
                 message  -- string 设置结果描述       
             },       
             ...   
         }
数据类型：table/string；
取值范围：结果表或错误信息；
注意事项：成功时返回结果表，失败时返回错误信息；
返回示例：-- 成功时举例   
         {       
             name = {           
                 success = true,           
                 value = "Air5101_Test",           
                 message = "设置成功"       
             },       
             adv_type = {           
                 success = true,           
                 value = "0x03",           
                 message = "设置成功"       
             },       
             adv_interval = {           
                 success = true,           
                 value = 30,           
                 message = "设置成功"       
             }   
         }      

         -- 失败时举例   
         "config必须是table类型"

示例：

-- 构建配置表
local config = {
    name = "Air5101_Test",        -- 设备名称为Air5101_Test
    adv_type = exril_5101.ADV_C,  -- 可连接广播
    adv_interval = 30,            -- 广播间隔30ms
}

-- 同步设置参数
local result1, result2 = exril_5101.set(config)
if result1 then
    log.info("参数设置", "参数设置成功")
    -- result2 是一个table，包含每个配置项的设置结果
    for key, result in pairs(result2) do
        if result.success then
            log.info("参数设置", key, "设置成功，值:", result.value)
        else
            log.warn("参数设置", key, "设置失败:", result.message)
        end
    end
else
    -- 当result1为false时，result2是错误信息字符串_
    log.error("参数设置", "参数设置失败:", result2)
end

4.3 exril_5101.get(key, timeout)

功能：

获取 Air5101 模块参数，如设备名称、MAC 地址、固件版本等；

注意事项：

1、必须在 AT 模式下设置参数，设置前请先调用 exril_5101.mode(exril_5101.MODE_AT) 切换到 AT 模式；

2、支持获取单个参数或多个参数；

参数：

key

参数含义：要获取的参数键名或键名数组；
数据类型：string/table；
取值范围：单个键名或键名数组；
是否必选：是；
注意事项：支持的键名见下方说明：
          键名            含义          返回格式
          ver            固件版本       版本字符串
          name           设备名称       设备名称字符串
          baud           波特率         波特率数值
          mac            MAC地址        十六进制字符串
          adv_type       广播类型       广播类型常量
          adv_data       广播数据       十六进制字符串
          scan_rsp_data  扫描响应数据   十六进制字符串
          adv_interval   广播间隔       毫秒值
          conn_interval  连接间隔       毫秒值
          mtu_len        MTU长度        数值
          power_mode     功耗模式       模式数值
参数实例：单个键名：exril_5101.get("name")
         多个键名：exril_5101.get({"name", "mac", "ver"})

timeout

参数含义：同步超时时长；
数据类型：number；
取值范围：1-10000，单位：ms；
是否必选：否；
注意事项：仅同步调用时有效，默认200ms；

返回值：

local result1, result2 = exril_5101.get(key)

result1

含义说明：获取的参数值；
数据类型：取决于键名/nil；
取值范围：取决于键名；
注意事项：成功时返回参数值，失败时返回nil；
返回示例：成功返回：获取的参数值，比如获取设备名称，返回的字符串便是设备名称
         失败返回：nil

result2

含义说明：错误信息；
数据类型：string；
取值范围：错误信息；
注意事项：成功时返回nil，失败时返回错误信息；
返回示例：成功返回：nil
         失败返回：错误信息

示例：

-- 示例1：单个键获取
 local result1, result2 = exril_5101.get("name")
 if result1 then
     log.info("设备名称:", result1)
 else
     log.error("获取失败:", result2)
 end

 -- 示例2：多个键获取
 local result1, result2= exril_5101.get({"name", "mac", "ver"})
 if result1 then
     log.info("设备名称:", result1.name)
     log.info("设备MAC:", result1.mac)
     log.info("设备版本:", result1.ver)
 else
     log.error("获取失败:", result2)
 end

4.4 exril_5101.restore(timeout)

功能：

恢复 Air5101 模块的出厂设置，将所有参数重置为默认值;

注意事项：

1、必须在 AT 模式下执行此操作，执行前请先调用 exril_5101.mode(exril_5101.MODE_AT) 切换到 AT 模式；

2、恢复出厂设置后，模块会自动重启以应用默认设置；

3、恢复出厂设置会清除所有自定义配置，包括设备名称、广播参数等；

参数：

timeout

参数含义：同步超时时长；
数据类型：number；
取值范围：1-10000，单位：ms；
是否必选：否；
注意事项：仅同步调用时有效，默认200ms；

返回值：

local result = exril_5101.restore()

result

含义说明：是否恢复成功；
数据类型：boolean；
取值范围：true/false；
注意事项：true表示恢复出厂设置成功，false表示恢复失败；
返回示例：成功返回：true 失败返回：false

示例：

local result = exril_5101.restore()
if result then
    log.info("恢复出厂设置成功")
else
    log.error("恢复失败")
end

4.5 exril_5101.restart(timeout)

功能：

软重启 Air5101 模块，使模块重新初始化并加载配置；

注意事项：

1、必须在 AT 模式下执行此操作，执行前请先调用 exril_5101.mode(exril_5101.MODE_AT) 切换到 AT 模式；

2、重启后，模块会重新初始化并加载默认配置或已保存的配置；

3、重启过程中，蓝牙连接会断开；

参数：

timeout

参数含义：同步超时时长；
数据类型：number；
取值范围：1-10000，单位：ms；
是否必选：否；
注意事项：仅同步调用时有效，默认200ms；

返回值：

local result = exril_5101.restart()

result

含义说明：是否重启成功；
数据类型：boolean；
取值范围：true/false；
注意事项：true表示重启命令发送成功，false表示重启失败；
返回示例：成功返回：true 失败返回：false

示例：

local result = exril_5101.restart()
if result then 
    log.info("重启成功")
else
    log.erroe("重启失败")
end

4.6 exril_5101.disconnect(timeout)

功能：

断开当前蓝牙连接，使设备回到可发现状态；

注意事项：

1、必须在 AT 模式下执行此操作，执行前请先调用 exril_5101.mode(exril_5101.MODE_AT) 切换到 AT 模式；

2、断开连接后，设备会重新开始广播，可被其他设备发现和连接；

3、如果当前没有蓝牙连接，此操作仍然会返回成功；

参数：

timeout

参数含义：同步超时时长；
数据类型：number；
取值范围：1-10000，单位：ms；
是否必选：否；
注意事项：仅同步调用时有效，默认200ms；

返回值：

local result = exril_5101.disconnect()

result

含义说明：是否断开成功；
数据类型：boolean；
取值范围：true/false；
注意事项：true表示断开成功，false表示断开失败；
返回示例：成功返回：true 失败返回：false

示例：

local result = exril_5101.disconnect()
if result then 
    log.info("断开成功")
else
    log.erroe("断开失败")
end

4.7 exril_5101.status(timeout)

功能：

查询蓝牙连接状态，获取设备当前的连接状态信息；

注意事项：

1、必须在 AT 模式下执行此操作，执行前请先调用 exril_5101.mode(exril_5101.MODE_AT) 切换到 AT 模式；

2、此函数会返回内部缓存的连接状态，同时会更新状态信息；

参数：

timeout

参数含义：同步超时时长；
数据类型：number；
取值范围：1-10000，单位：ms；
是否必选：否；
注意事项：仅同步调用时有效，默认200ms；

返回值：

local result1, result2 = exril_5101.status()

result1

含义说明：是否查询成功；
数据类型：boolean；
取值范围：true/false；
注意事项：true表示查询成功，false表示查询失败；
返回示例：成功返回：true 失败返回：false

result2

含义说明：状态信息或错误信息；
         如果返回的是状态信息表，则字段如下：
          {
            参数含义：蓝牙连接状态；
            数据类型：boolean；
            取值范围：true/false；
            注意事项：无；
            参数名称：connected

            参数含义：当前工作模式；
            数据类型：string；
            取值范围：exril_5101.MODE_UA或者exril_5101.MODE_AT；
            注意事项：无；
            参数名称：mode

            参数含义：模块原始的响应上报信息；
            数据类型：string；
            取值范围："AT:CONNECTED"：已连接；
                    "AT:DISCONNECT"：未连接；
            注意事项：无；
            参数名称：raw_respnse
          }
数据类型：table/string；
取值范围：状态表或错误信息字符串；
注意事项：成功时返回状态表，失败时返回错误信息；
返回示例：成功返回table，失败返回错误信息；

示例：

local status_success, status_info = exril_5101.status()
if status_success then
    log.info("连接状态:", status_info.connected)
    log.info("当前模式:", status_info.mode)
else
    log.error("查询失败:", status_info)
end

4.8 exril_5101.power(mode, wakeup_option, timeout)

功能：

设置或获取 Air5101 模块的功耗模式，以控制模块的功耗状态；

注意事项：

1、设置功耗模式时必须在 AT 模式下执行，执行前请先调用 exril_5101.mode(exril_5101.MODE_AT) 切换到 AT 模式；

2、功耗模式信息：

• exril_5101.P0 常规模式 0：蓝牙正常工作；
• exril_5101.P1 低功耗模式 1：可被发现和连接，唤醒后，会在 80ms 后再次进入低功耗模式 1；
• exril_5101.P3 低功耗模式 3：可被发现和连接，唤醒后，自动退出低功耗模式 3，进入常规模式 0；

3、wakeup_option 内的 data 表示唤醒数据，可以在 Air5101 低功耗模式下，发送此数据来唤醒 Air5101:

• ≤ 115200：发送任意 1 个字节唤醒即可，后面可以加上回车换行，与后面真正要发的 AT 指令分隔开；
• ＞ 115200：此时基本不能通过串口数据来唤醒了，如果一定要用串口唤醒，需要发十六进制 0x00，这样单字节低电平持续时间最长(大于 115200 波特率的唤醒，低电平时间要持续 60uS 以上)；

参数：

mode

参数含义：功耗模式；
数据类型：string；
取值范围：exril_5101.P0/exril_5101.P1/exril_5101.P3；
是否必选：否；
注意事项：不选表示获取当前功耗模式；
参数实例：exril_5101.power(exril_5101.P1)

wakeup_option

参数含义：唤醒Air5101配置；
          该参数为 table 类型，字段如下：
          {
            参数含义：是否在设置功耗模式前先唤醒Air5101；
            数据类型：boolean；
            取值范围：true/false；
            是否必选：否；
            注意事项：默认是false；
            参数名称：enable

            参数含义：唤醒数据；
            数据类型：string；
            取值范围：任意字符串；
            是否必选：否；
            注意事项：默认是"wakeup"；
            参数名称：data

            参数含义：唤醒后延时多久再设置功耗模式；
            数据类型：string；
            取值范围：1ms-100ms；
            是否必选：否；
            注意事项：默认是25ms（推荐值）；
            参数名称：delay
          }
数据类型：table；
取值范围：暂无；
是否必选：否；
注意事项：若不提供此参数或提供空表，默认不唤醒；

timeout

参数含义：同步超时时长；
数据类型：number；
取值范围：1-10000，单位：ms；
是否必选：否；
注意事项：仅同步调用时有效，默认200ms；

返回值：

local result1, result2 = exril_5101.mode(mode)

result1

含义说明：是否获取/设置成功；
数据类型：boolean；
取值范围：true/false；
注意事项：不传mode参数，表示获取当前功耗模式，true表示获取成功，false表示获取失败；
         若传了mode参数，表示设置功耗模式，true表示设置成功，false表示设置失败；
返回示例：成功返回：true 失败返回：false

result2

含义说明：当前模式或错误信息；
数据类型：string；
取值范围：模式数值或错误信息；
注意事项：成功时返回当前模式，失败时返回错误信息；
返回示例：成功返回：exril_5101.P0，exril_5101.P1，exril_5101.P3
         失败返回：错误信息

示例：

-- 1. 获取当前功耗模式
local result1, result2 = exril_5101.power()
if result1 then
    log.info("当前功耗模式为：", result2)
else
    log.info("获取当前功耗模式失败")
end

-- 2. 设置为低功耗模式1
local set_success, set_message = exril_5101.power(exril_5101.P1)
if set_success then
    log.info("功耗模式设置成功:", set_message)
else
    log.error("设置失败:", set_message)
end

-- 3. 唤醒后设置为低功耗模式1（使用默认的data和delay） 
local set_success, set_message = exril_5101.power(exril_5101.P1，true)
if set_success then
    log.info("功耗模式设置成功:", set_message)
else
    log.error("设置失败:", set_message)
end

4.9 exril_5101.wdcfg(en, timeout, level, width, sync_timeout)

功能

1、配置看门狗功能参数，用于监控主控设备运行状态。

2、当主控设备在指定时间内未喂狗时，蓝牙模块将通过 SWITCH 引脚复位主控。

3、看门狗复位脉冲波形说明：

• 当看门狗超时发生时，SWITCH 引脚会输出一个复位脉冲信号

• 脉冲的极性由 level 参数控制：

注意事项

1、必须在 AT 模式下执行此操作，执行前请先调用 exril_5101.mode(exril_5101.MODE_AT) 切换到 AT 模式；

2、配置看门狗后，需要定期调用 exril_5101.wdfed() 进行喂狗，否则看门狗会超时；

3、配置成功后，函数会自动调用 exril_5101.save() 保存配置；

参数

en

参数含义：是否开启看门狗功能；
数据类型：boolean；
取值范围：true/false;
是否必选：否；
注意事项：不提供则表示查询当前配置；

timeout

参数含义：喂狗超时时长；
数据类型：number；
取值范围：1-99999999，单位：s；
是否必选：否；
注意事项：不选则默认60s；

level

参数含义：超时动作电平；
数据类型：number；
取值范围：0/1;
是否必选：否；
注意事项：默认值：0
         0：超时后拉低SWITCH
         1：超时后拉高SWITCH

width

参数含义：复位脉冲宽度；
数据类型：number；
取值范围：10-10000，单位：ms；
是否必选：否；
注意事项：不选则默认100ms

sync_timeout

参数含义：同步超时时长；
数据类型：number；
取值范围：1-10000，单位：ms；
是否必选：否；
注意事项：仅同步调用时有效，默认200ms；

返回值

local result1，result2 = exril_5101.wdcfg(en, timeout, level, width)

result1

含义说明：是否获取/配置成功；
数据类型：boolean；
取值范围：true/false；
注意事项：true表示看门狗获取/配置成功，false表示看门狗获取/配置失败；
返回示例：成功返回：true 失败返回：false
         -- 配置看门狗
         local result = exril_5101.wdcfg(en, timeout, level, width)
         log.info("result", result)

result2

含义说明：当前配置信息表或错误信息；
          如果返回的是配置信息表，则字段如下：
          {
            参数含义：看门狗状态；
            数据类型：boolean；
            取值范围：true/false；
            注意事项：无；
            参数名称：en

            参数含义：喂狗超时时间；
            数据类型：number；
            取值范围：1-99999999秒；
            注意事项：无；
            参数名称：timeout

            参数含义：超时动作电平；
            数据类型：number；
            取值范围：0/1；
            注意事项：0：超时后拉低SWITCH
                     1：超时后拉高SWITCH；
            参数名称：level

            参数含义：脉冲宽度；
            数据类型：number；
            取值范围：10ms-10000ms；
            注意事项：无；
            参数名称：width
          }
数据类型：table/string；
取值范围：当前配置信息表或错误信息；
注意事项：成功时返回当前配置信息表，失败时返回错误信息；
返回示例：成功返回：table 
         失败返回：错误信息

示例

-- 开启看门狗，45秒超时，超时后拉高SWITCH引脚持续500ms
local result = exril_5101.wdcfg(true, 45, 1, 500)
log.info("result", result)

-- 开启看门狗，使用默认配置
exril_5101.wdcfg(true)

-- 关闭看门狗
exril_5101.wdcfg(false)

-- 查询看门狗配置
local query_success, config = exril_5101.wdcfg()
if query_success then
    log.info("看门狗配置:", json.encode(config))
    log.info("是否开启:", config.en)
    log.info("超时时间:", config.timeout, "秒")
    log.info("电平状态:", config.level)
    log.info("脉冲宽度:", config.width, "毫秒")
else
    log.error("查询失败:", config)
end

4.10 exril_5101.wdfed(timeout)

功能

看门狗喂狗；

注意事项

1、必须在 AT 模式下执行此操作，执行前请先调用 exril_5101.mode(exril_5101.MODE_AT) 切换到 AT 模式；

2、配置看门狗后，需要定期调用此函数进行喂狗，否则看门狗会超时；

参数

timeout

参数含义：同步超时时长；
数据类型：number；
取值范围：1-10000，单位：ms；
是否必选：否；
注意事项：仅同步调用时有效，默认200ms；

返回值

local result = exril_5101.wdfed()

result

含义说明：看门狗喂狗是否成功；
数据类型：boolean；
取值范围：true/false；
注意事项：true表示看门狗喂狗成功，false表示看门狗喂狗失败；
返回示例：成功返回：true 失败返回：false
         local result = exril_5101.wdfed()
         log.info("result", result)

示例

local result = exril_5101.wdfed()
log.info("result", result)

4.11 exril_5101.wakeup(source, level, width, timeout)

功能

1、配置或查询 Air5101 模块的唤醒功能，用于配置模块如何唤醒主控设备；

2、当蓝牙连接断开或收到数据时，需要唤醒主控（通过 WAKEUP 引脚）以恢复主控的数据处理能力；

3、唤醒脉冲波形说明：

• 当唤醒事件发生时，WAKEUP 引脚会输出一个脉冲信号

• 脉冲的极性由 level 参数控制：

注意事项

1、必须在 AT 模式下执行此操作，执行前请先调用 exril_5101.mode(exril_5101.MODE_AT) 切换到 AT 模式；

2、配置唤醒功能后，函数会自动调用 exril_5101.save() 保存配置；

3、使用该功能前，请确保硬件连接正确，WAKEUP 引脚可用于唤醒主控。

参数

source

参数含义：唤醒源配置；
数据类型：number；
取值范围：0,1,2,3；
是否必选：否；
注意事项：默认值：0
         0：禁用所有唤醒源
         1：使能蓝牙连接断开作为唤醒源
         2：使能蓝牙接收到数据作为唤醒源
         3：同时使能蓝牙连接断开和蓝牙接收到数据作为唤醒源；

level

参数含义：唤醒电平；
数据类型：number；
取值范围：0/1;
是否必选：否；
注意事项：默认值：0
         0：当唤醒事件发生时，拉低 WAKEUP
         1：当唤醒事件发生时，拉高 WAKEUP

width

参数含义：复位脉冲宽度；
数据类型：number；
取值范围：10-10000，单位：ms；
是否必选：否；
注意事项：默认值：100

timeout

参数含义：同步超时时长；
数据类型：number；
取值范围：1-10000，单位：ms；
是否必选：否；
注意事项：仅同步调用时有效，默认200ms；

返回值

local result1，result2 = exril_5101.wakeup(source, level, width)

result1

含义说明：唤醒查询/设置是否成功；
数据类型：boolean；
取值范围：true/false；
注意事项：true表示唤醒查询/设置成功，false表示唤醒查询/设置失败；
返回示例：成功返回：true 失败返回：false
         local result = exril_5101.wakeup(source,level, width)
         log.info("result", result)

result2

含义说明：当前配置信息表或错误信息；
          如果返回的是配置信息表，则字段如下：
          {
            参数含义：唤醒源配置；
            数据类型：number；
            取值范围：0,1,2,3；
            注意事项：0：禁用所有唤醒源
                     1：使能蓝牙连接断开作为唤醒源
                     2：使能蓝牙接收到数据作为唤醒源
                     3：同时使能蓝牙连接断开和蓝牙接收到数据作为唤醒源；
            参数名称：source

            参数含义：唤醒电平；
            数据类型：number；
            取值范围：0/1；
            注意事项：0：当唤醒事件发生时，拉低 WAKEUP
                     1：当唤醒事件发生时，拉高 WAKEUP；
            参数名称：level

            参数含义：脉冲宽度；
            数据类型：number；
            取值范围：10ms-10000ms；
            注意事项：无；
            参数名称：width
          }
数据类型：table/string；
取值范围：当前配置信息表或错误信息；
注意事项：成功时返回当前配置信息表，失败时返回错误信息；
返回示例：成功返回：table 
         失败返回：错误信息

示例

-- 查询唤醒配置
local query_success, config = exril_5101.wakeup()
if query_success then
    log.info("唤醒配置:", json.encode(config))
    log.info("唤醒源:", config.source)
    log.info("唤醒电平:", config.level)
    log.info("唤醒脉宽:", config.width, "毫秒")
else
    log.error("查询失败:", config)
end

-- 设置蓝牙连接唤醒，低电平，100ms脉宽
local set_success, set_message = exril_5101.wakeup(1, 0, 100)
if set_success then
    log.info("唤醒功能设置成功:", set_message)
else
    log.error("设置失败:", set_message)
end

4.12 exril_5101.save(timeout)

功能：

保存当前配置到 Flash，确保配置在设备重启后仍然有效；

注意事项：

1、必须在 AT 模式下执行此操作，执行前请先调用 exril_5101.mode(exril_5101.MODE_AT) 切换到 AT 模式；

2、配置参数后，建议调用此函数保存配置，以确保配置在设备重启后仍然生效；

3、exril_5101.set()、exril_5101.wdcfg() 、exril_5101.wakeup() 这三个接口会自动调用此函数保存配置；

参数：

timeout

参数含义：同步超时时长；
数据类型：number；
取值范围：1-10000，单位：ms；
是否必选：否；
注意事项：仅同步调用时有效，默认200ms；

返回值：

local result1 = exril_5101.save()

result

含义说明：是否保存成功；
数据类型：boolean；
取值范围：true/false；
注意事项：true表示保存成功，false表示保存失败；
返回示例：成功返回：true 失败返回：false

示例：

local result = exril_5101.save()
if result then
    log.info("配置保存成功")
else
    log.error("保存失败:")
end

4.13 exril_5101.send(data，wakeup_option, timeout)

功能：

向已连接的蓝牙主设备发送数据;

注意事项：

1、需要蓝牙已连接才能发送成功；

2、根据当前工作模式自动选择发送方式：

• 透传模式：发送数据，最大 MTU-3 字节（MTU 最大是 512，所以 data 最大是 509 字节）；

• AT 指令模式：使用 AT+BS 命令，最大 80 字节；

3、wakeup_option 内的 data 表示唤醒数据，可以在 Air5101 低功耗模式下，发送此数据来唤醒 Air5101:

• ≤ 115200：发送任意 1 个字节唤醒即可，后面可以加上回车换行，与后面真正要发的 AT 指令分隔开；

• ＞ 115200：此时基本不能通过串口数据来唤醒了，如果一定要用串口唤醒，需要发十六进制 0x00，这样单字节低电平持续时间最长(大于 115200 波特率的唤醒，低电平时间要持续 60uS 以上)；

参数：

data

参数含义：要发送的数据；
数据类型：string；
取值范围：透传模式下，最大509字节；AT模式下，最大80字节；
是否必选：是；
注意事项：注意单包数据量大小；

wakeup_option

参数含义：唤醒Air5101配置；
          该参数为 table 类型，字段如下：
          {
            参数含义：是否在发送数据前先唤醒Air5101；
            数据类型：boolean；
            取值范围：true/false；
            是否必选：否；
            注意事项：默认是false；
            参数名称：enable

            参数含义：唤醒数据；
            数据类型：string；
            取值范围：任意字符串；
            是否必选：否；
            注意事项：默认是"wakeup"；
            参数名称：data

            参数含义：唤醒后延时多久再发送数据；
            数据类型：string；
            取值范围：1ms-100ms；
            是否必选：否；
            注意事项：默认是25ms（推荐值）；
            参数名称：delay
          }
数据类型：table；
取值范围：暂无；
是否必选：否；
注意事项：若不提供此参数或提供空表，默认不唤醒；

timeout

参数含义：同步超时时长；
数据类型：number；
取值范围：1-10000，单位：ms；
是否必选：否；
注意事项：仅同步调用时有效，默认200ms；

返回值：

local result = exril_5101.send(data)

result

含义说明：是否发送成功；
数据类型：boolean；
取值范围：true/false；
注意事项：true表示发送成功，false表示发送失败；
返回示例：成功返回：true 失败返回：false

示例：

-- 1. 发送数据给已连接的蓝牙设备，不唤醒
local success, message = exril_5101.send("Hello, Bluetooth!")
if success then
    log.info("数据发送成功")
else
    log.error("发送失败:", message)
end

-- 2. 简单唤醒（使用默认的data和delay） 
exril_5101.send("Hello", true)

-- 3. 唤醒并指定延时20ms（使用默认的data）
exril_5101.send("Hello", 20)

-- 4. 完整唤醒配置
exril_5101.send("Hello", {
    enable = true,
    data = "0x00",     -- 唤醒数据
    delay = 30        -- 延时30ms
})

4.14 exril_5101.on(callback)

功能：

注册蓝牙事件回调函数，用于接收和处理蓝牙相关事件；

注意事项：

1、此函数可以在任何模式下调用，不需要切换到 AT 模式；

2、首次注册回调函数时，会自动注册 URC 处理器；

3、多次调用此函数会覆盖之前注册的回调函数；

参数：

callback

参数含义：事件回调函数；格式为：
         function callback(event, payload)
             -- 用户代码
         end
         该回调函数接收 event和payload 两个参数，参数说明如下：

         参数含义：事件类型
         数据类型：string；
         取值范围："connected", "disconnected", "data"；
         是否必选：必选；
         参数名称：event

         参数含义：事件数据
                  该参数为 table 类型，字段如下：
                  {
                    参数含义：蓝牙连接状态；
                    数据类型：boolean；
                    取值范围：true/false；
                    注意事项：仅在 event 为 "connected" 或 "disconnected" 时存在；
                    参数名称：payload.connected

                    参数含义：收到的数据内容；
                    数据类型：string；
                    取值范围：任意字符串；
                    注意事项：仅在 event 为 "data" 时存在；在 AT 模式下会去掉 "AT:" 前缀；
                    参数名称：payload.data

                    参数含义：原始完整数据；
                    数据类型：string；
                    取值范围：任意字符串；
                    注意事项：仅在 event 为 "data" 时存在；包含完整的原始响应数据；
                    参数名称：payload.raw

                    参数含义：数据前缀；
                    数据类型：string/nil；
                    取值范围：字符串或 nil；
                    注意事项：仅在 event 为 "data" 时存在；在 AT 模式下会有前缀AT:；
                    参数名称：payload.prefix

                    参数含义：当前工作模式；
                    数据类型：string；
                    取值范围："at" 或 "uart"；
                    注意事项：仅在 event 为 "data" 时存在；表示数据接收时的工作模式；
                    参数名称：payload.mode
                  }
         数据类型：table；
         取值范围：暂无；
         是否必选：必选；
         参数名称：payload
数据类型：function；
取值范围：暂无；
是否必选：必选；
参数示例：-- 1. 定义蓝牙事件处理函数
         function callback(event, payload)
             -- 用户代码
         end
         -- 2. 注册蓝牙事件回调函数
         exril_5101.on(callback)

返回值：

无；

示例：

-- 定义蓝牙事件处理函数
local function bluetooth_event_handler(event, payload)
    log.info("蓝牙事件", "事件类型:", event)

    if event == "connected" then
        -- 连接成功
        log.info("蓝牙事件", "蓝牙已连接")
    elseif event == "disconnected" then
        log.info("蓝牙事件", "蓝牙已断开")
    elseif event == "data" then
        log.info("蓝牙事件", "收到数据:", payload.data)
        log.info("蓝牙事件", "当前模式:", payload.mode)
        -- 处理收到的数据
    end
end

-- 注册蓝牙事件回调函数
exril_5101.on(bluetooth_event_handler)

五、模组支持说明

支持 LuatOS 开发的所有产品都支持 exril-5101 扩展库，使用此扩展库需要接 Air5101 模块。