跳转至

exair153x_wdt-外部硬件看门狗

作者：马梦阳　|　最后修改：2026-08-03

一、概述

exair153x_wdt 是一个 LuatOS 硬件看门狗扩展库，用于控制合宙 Air153C/Air153D 外置看门狗芯片。通过 GPIO 引脚输出喂狗脉冲信号，实现系统稳定性保障。支持自动周期喂狗、手动补喂狗和强制硬件复位三种工作方式，兼容 Air153C 和 Air153D 两款芯片。

二、背景

2.1 基本信息

项目 说明
库名称 exair153x_wdt
引用方式 local exair153x_wdt = require("exair153x_wdt")
适配芯片 合宙 Air153C、Air153D 外置硬件看门狗芯片
芯片封装形式 SOT23-6
设计目标 提供统一的硬件看门狗控制接口，兼容 Air153C/Air153D，支持自动喂狗与强制硬件复位

2.2 Air153C 与 Air153D 硬件差异对照表

对比项 Air153C Air153D
芯片关系 基础型号 与 Air153C 同一颗芯片，仅软件不同
PIN1 NC，固定悬空 STRAP1，超时档位配置引脚
PIN6 NC，固定悬空 STRAP6，超时档位配置引脚
PIN2 GND GND
PIN3 WTDOG（喂狗输入） WTDOG（喂狗输入）
PIN4 PWR_OFF（复位输出） PWR_OFF（复位输出）
PIN5 VDD（供电） VDD（供电）
超时配置方式 硬件固定，不可修改 通过 STRAP1/STRAP6 上电电平配置 4 档
超时档位 固定 4 分钟（实测 209s～283s） 模式1：4分钟 / 模式2：90分钟 / 模式3：13小时 / 模式4：26小时
喂狗周期 ≤200秒 模式1：≤200秒 / 模式2：≤1小时 / 模式3：≤12小时 / 模式4：≤24小时
常态电流（3.3V） 1.5uA 与 Air153C 相同
复位电流（3.3V） 5uA 与 Air153C 相同

2.3 Air153D STRAP 引脚档位配置表

模式 STRAP1 (PIN1) STRAP6 (PIN6) 等待喂狗超时时间 喂狗时间
1 高/悬空 高/悬空 4 分钟 200 秒
2 低 高/悬空 90 分钟 1 小时
3 高/悬空 低 13 小时 12 小时
4 低 低 26 小时 24 小时

2.4 芯片统一时序要求

参考 Air153x 看门狗芯片硬件资料（待补充）

三、硬件接线与核心业务逻辑

3.1 硬件接线框图

whiteboard_exported_image

3.2 NPN 三极管电路说明

喂狗引脚和复位引脚均通过 NPN 三极管（如 MMBT3904LT1G）控制，信号经三极管后会被反相：

喂狗通路（GPIOx → WTDOG）：

  • GPIO 输出高电平 → NPN 导通 → WTDOG 保持低电平（空闲态）

  • GPIO 输出低电平 → NPN 截止 → WTDOG 被拉为高电平（喂狗有效）

  • 库内 GPIO 空闲电平固定为高电平，喂狗脉冲电平固定为低电平，与 NPN 反相特性匹配

复位通路（PWR_OFF → RESET）：

  • 正常喂狗时：Air153C/D 的 PWR_OFF 输出低电平，NPN 截止，主控 RESET 不被拉低，主控正常运行

  • 喂狗超时时：Air153C/D 的 PWR_OFF 输出 500ms 高电平，NPN 导通，主控 RESET 被拉低，主控被复位

3.3 核心业务逻辑说明

exair153x_wdt 扩展库的核心业务逻辑如下：

  1. 初始化阶段：用户调用 init(cfg) 完成 GPIO 配置、首次喂狗，库内开启自动喂狗常驻任务；

  2. 正常运行阶段：库内 task 按 auto_feed_period_s 周期自动喂狗，用户也可通过 feed() 手动补喂狗；

  3. 强制复位：用户调用 trigger_reset() 后，库内设置复位标志位并唤醒主循环，由主循环统一执行 3 次快速脉冲触发芯片硬件复位；

  4. FOTA 场景：

    • 如果使用的是 libfota、libfota2、libfota3 扩展库，库内自动执行完整 FOTA 流程，其中在差分包下载成功后，库内自动调用 feed() 进行补喂狗。该操作完全由扩展库内部实现，用户无需关心。
    • 如果使用的是 fota 核心库，需要用户在脚本逻辑中自行去控制差分包的下载，以及重启应用差分包，重启之前，需要在用户的脚本中调用 feed() 进行手动补喂狗。此时，该操作需要用户自行完成。我们也会在 fota 示例代码中进行描述。

四、核心示例

4.1 Air153C 完整核心示例

-- 引入看门狗扩展库
local exair153x_wdt = require("exair153x_wdt")

-- Air153C 看门狗初始化与自动喂狗任务
local function wdt_task()
    -- 初始化看门狗，使用 GPIO24 喂狗引脚
    local success = exair153x_wdt.init({
        wdt_pin = 24,                  -- 喂狗 GPIO 引脚号
    })

    if success then
        log.info("main", "Air153C 看门狗初始化成功，自动喂狗已启动")
    else
        log.error("main", "Air153C 看门狗初始化失败")
        return
    end

    -- 扩展库内部自动喂狗已由 init 创建，无需额外操作
    -- 业务任务正常运行即可
    while true do
        log.info("main", "正常运行中...")
        sys.wait(10000)
    end
end

-- 启动看门狗任务
sys.taskInit(wdt_task)

4.2 Air153D 完整核心示例

-- 引入看门狗扩展库
local exair153x_wdt = require("exair153x_wdt")

-- Air153D 看门狗初始化（4 分钟超时档位：STRAP1=高/悬空，STRAP6=高/悬空）
-- STRAP 引脚配置由硬件电路决定，软件层不参与
local function wdt_task()
    local success = exair153x_wdt.init({
        wdt_pin = 24,                  -- 喂狗 GPIO 引脚号
    })

    if success then
        log.info("main", "Air153D 看门狗初始化成功")
    else
        log.error("main", "Air153D 看门狗初始化失败")
    end
end

-- 启动看门狗任务
sys.taskInit(wdt_task)

4.3 FOTA 升级示例

4.3.1 使用 libfota 库（libfota/libfota2/libfota3）

使用 libfota 库进行 FOTA 升级时，差分包下载成功后，库内部会自动调用 exair153x_wdt.feed() 喂狗，无需用户手动操作。

-- 引入看门狗扩展库
local exair153x_wdt = require("exair153x_wdt")
-- local libfota = require("libfota")
-- local libfota2 = require("libfota2")

local function wdt_task()
    local success = exair153x_wdt.init({
        wdt_pin = 24,                  -- 喂狗 GPIO 引脚号
    })

    if success then
        log.info("main", "看门狗初始化成功")
    else
        log.error("main", "看门狗初始化失败")
        return
    end
end

local function fota_upgrade_task()
    -- 根据实际情况配置 FOTA 升级参数
    -- 差分包下载成功后，libfota 库会自动调用 exair153x_wdt.feed() 喂狗
end

-- 启动看门狗任务
sys.taskInit(wdt_task)
-- 启动 FOTA 升级任务
sys.taskInit(fota_upgrade_task)

4.3.2 使用 fota 核心库

使用 fota 核心库进行 FOTA 升级时，用户需要在下载差分包后手动调用 feed() 喂狗。

-- 引入看门狗扩展库
local exair153x_wdt = require("exair153x_wdt")

local function wdt_task()
    local success = exair153x_wdt.init({
        wdt_pin = 24,                  -- 喂狗 GPIO 引脚号
    })

    if success then
        log.info("main", "看门狗初始化成功")
    else
        log.error("main", "看门狗初始化失败")
        return
    end
end

-- FOTA 升级任务
local function fota_upgrade_task()
    -- 下载差分包（示例）
    -- ... 下载逻辑 ...

    -- 差分包下载成功后，手动喂狗，防止应用差分包过程中超时复位
    log.info("main", "差分包下载成功，手动喂狗")
    local result = exair153x_wdt.feed()

    if result then
        log.info("main", "手动喂狗成功，准备重启应用差分包")
        -- 执行升级
        -- ... 升级逻辑 ...
        sys.wait(1000)
        pm.reboot()
    else
        log.error("main", "手动喂狗失败")
    end
end

-- 启动看门狗任务
sys.taskInit(wdt_task)
-- 启动 FOTA 升级任务
sys.taskInit(fota_upgrade_task)

4.4 强制硬件复位示例

-- 引入看门狗扩展库
local exair153x_wdt = require("exair153x_wdt")

local function wdt_task()
    local success = exair153x_wdt.init({
        wdt_pin = 24,                  -- 喂狗 GPIO 引脚号
    })

    if not success then
        log.error("main", "看门狗初始化失败")
        return
    end

    -- 等待业务运行一段时间
    sys.wait(60000)

    -- 触发强制硬件复位
    local result = exair153x_wdt.trigger_reset()
    if result then
        log.info("main", "强制复位操作执行成功，芯片将立即触发硬件复位")
    end
end

-- 启动看门狗任务
sys.taskInit(wdt_task)

五、常量详解

exair153x_wdt 扩展库没有常量。

六、函数详解

6.1 exair153x_wdt.init(cfg)

功能：

初始化看门狗控制引脚，配置全局参数，执行首次喂狗，并创建自动喂狗常驻任务。

注意事项：

  • 重复调用时，如果已初始化直接返回 false

  • 初始化成功后扩展库内部自动喂狗任务立即开始工作

  • 初始化成功后立即执行一次喂狗

参数

cfg

参数含义：看门狗初始化配置参数，参数为 table 类型，table 内容格式说明如下：
        {
                -- 参数含义：喂狗 GPIO 引脚号；
                -- 数据类型：number；
                -- 取值范围：有效的 GPIO 引脚号，具体取值取决于硬件平台；
                -- 是否必选：必须传入此参数；
                -- 注意事项：GPIO 引脚的选用要求如下：
                --          Air700Exx、Air780Exx、Air8000 系列模组，支持休眠模式，需要选用“进入休眠后不掉电”的 GPIO，我们将其称为 AGPIO；
                --          Air1601、Air8101 系列模组，没有 AGPIO，不支持休眠模式，在选择 GPIO 时没有限制；
                -- 参数示例：wdt_pin = 24
                wdt_pin = ,

                -- 参数含义：自动喂狗周期；
                -- 数据类型：number；
                -- 取值范围：正整数，单位为秒，强制最小 150 秒；
                -- 是否必选：可选传入此参数，默认值为 180；
                -- 注意事项：小于 150 初始化直接失败，返回 false；
                -- 参数示例：auto_feed_period_s = 180
                auto_feed_period_s = ,
        }
数据类型：table；
取值范围：见上方子参数说明；
是否必选：必须传入此参数；
注意事项：必须传入有效的 table 类型参数，否则会返回 false；
参数示例：exair153x_wdt.init({ wdt_pin = 24 })

返回值

local success = exair153x_wdt.init(cfg)

有一个返回值 success

success

含义说明：初始化操作是否成功；
数据类型：boolean；
取值范围：true 或 false；
注意事项：参数非法或 GPIO 初始化失败时返回 false；
返回示例：true

示例

local exair153x_wdt = require("exair153x_wdt")

-- Air153C 初始化
local success = exair153x_wdt.init({
    wdt_pin = 24,                  -- 喂狗 GPIO 引脚号
})
if success then
    print("Air153C 看门狗初始化成功")
else
    print("Air153C 看门狗初始化失败")
end

local exair153x_wdt = require("exair153x_wdt")

-- Air153D 初始化（4 分钟超时档位：STRAP1=高/悬空，STRAP6=高/悬空）
-- STRAP 引脚配置由硬件电路决定，软件层不参与
local success = exair153x_wdt.init({
    wdt_pin = 24,                  -- 喂狗 GPIO 引脚号
})
if success then
    print("Air153D 看门狗初始化成功")
else
    print("Air153D 看门狗初始化失败")
end

6.2 exair153x_wdt.feed()

功能：

手动执行单次喂狗操作。

注意事项：

  • 未初始化时调用，直接返回 false

  • 手动喂狗成功后，重置自动喂狗任务的计时起点，避免刚手动喂完又自动喂一次

  • 使用场景：fota 核心库 FOTA 升级过程中差分包下载成功后，重启前临时手动补喂狗；长时间业务阻塞场景临时手动补喂狗

参数

无

返回值

local success = exair153x_wdt.feed()

有一个返回值 success

success

含义说明：手动喂狗操作是否成功；
数据类型：boolean；
取值范围：true 或 false；
注意事项：未初始化时返回 false；
返回示例：true

示例

-- fota 核心库 FOTA 差分包下载成功后，手动补喂狗
local success = exair153x_wdt.feed()
if success then
    print("手动喂狗成功")
else
    print("手动喂狗失败，可能未初始化")
end

6.3 exair153x_wdt.trigger_reset()

功能：

手动触发看门狗复位操作，用于复位主控设备。

注意事项：

  • 未初始化时调用，直接返回 false

  • 调用后扩展库内部设置复位标志位，并在内部主循环中统一执行 3 次快速脉冲触发芯片硬件复位

参数

无

返回值

local success = exair153x_wdt.trigger_reset()

有一个返回值 success

success

含义说明：调用是否成功；
数据类型：boolean；
取值范围：true 或 false；
注意事项：未初始化时返回 false；
返回示例：true

示例

-- 执行强制复位操作（立即执行 3 次脉冲触发芯片硬件复位）
success = exair153x_wdt.trigger_reset()
if success then
    print("强制复位操作执行成功")
end

6.4 exair153x_wdt.version()

功能：

获取库版本信息，返回格式为年月日时分的字符串，用于版本标识和调试。

注意事项：

  • 无需初始化即可调用

  • 返回值格式固定为 "YYYYMMDDHHMM"，共 12 位字符

参数

无

返回值

local ver = exair153x_wdt.version()

有一个返回值 ver

ver

含义说明：库版本信息字符串；
数据类型：string；
取值范围：格式为年月日时分，例如 "202608030000"；
注意事项：无；
返回示例："202608030000"

示例

local ver = exair153x_wdt.version()
print("exair153x_wdt 版本:", ver)
-- 输出: exair153x_wdt 版本: 202608030000

七、版本更新说明

版本号：202608030000

1、更新时间：2026-08-03 00:00

2、更新内容

  • 初始版本发布，提供 init(cfg)、feed()、trigger_reset()、version() 四个外部 API

  • 支持 Air153C/Air153D 双芯片，Air153D 超时档位由硬件 STRAP 引脚配置，软件层不参与

八、产品支持说明

支持 LuatOS 开发的合宙二次开发模组均支持 exair153x_wdt 扩展库。

搜索
AirMaster 实时解答