exair153x_wdt-外部硬件看门狗

作者：马梦阳　|　最后修改：2026-09-21

一、概述

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

与旧库的关系

本库 exair153x_wdt 用于替代旧版喂狗库 air153C_wtd.lua。旧库官方已不再维护，现存放于 https://gitee.com/openLuat/LuatOS/tree/master/olddemo/lib。建议新项目优先使用本库 exair153x_wdt。

若坚持使用旧库 air153C_wtd.lua，请按以下步骤操作：

1. 从 https://gitee.com/openLuat/LuatOS/tree/master/olddemo/lib 下载 air153C_wtd.lua 文件。
2. 将下载的 .lua 文件添加进 Luatools 工程，作为项目文件一起打包烧录（不强制要求与主脚本同级目录）。
3. 在脚本中按旧库接口调用：init(pin)、feed_dog(pin, time)、close_watch_dog(pin)、callback()、version()；喂狗时需传入引脚号与喂狗时间。
4. 示例代码可参考：https://gitee.com/openLuat/LuatOS/blob/master/module/Air780EPM/demo/wdt/air153x_wdt.lua。
5. 注意：旧库官方不再维护，需由客户自行维护。建议预留将来迁移到本库 exair153x_wdt 的路径，避免后期升级困难。

二、背景

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 档
超时档位	随供电电压变化： 3.3V 时为 283 秒 3.8V 时为 240 秒 4.3V 时为 209 秒	随供电电压与不同模式发生变化： 供电电压为 3.3V 时： 模式1：16分钟 / 模式2：100分钟 / 模式3：20小时 / 模式4：40小时 供电电压为 4.35V 时： 模式1：12分钟 / 模式2：73分钟 / 模式3：15小时 / 模式4：29小时
喂狗周期	≤200秒	模式1：≤10分钟 / 模式2：≤60分钟 / 模式3：≤12小时 / 模式4：≤24小时
常态电流（3.3V）	1.5uA	与 Air153C 相同
复位电流（3.3V）	5uA	与 Air153C 相同

2.3 Air153D STRAP 引脚档位配置表

模式	STRAP1 (PIN1)	STRAP6 (PIN6)	喂狗时间	等待喂狗超时时间 （3.3V 供电电压下实测数据）	等待喂狗超时时间 （4.35V 供电电压下实测数据）
1	高	高	10 分钟	16 分钟内	12 分钟内
2	低	高	60 分钟	100 分钟内	73 分钟内
3	高	低	12 小时	20 小时内	15 小时内
4	低	低	24 小时	40 小时内	29 小时内

2.4 芯片统一时序要求

参考 Air153x 看门狗芯片硬件资料

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

3.1 硬件接线框图

3.2 NPN 三极管电路说明

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

喂狗通路（GPIOx → WTDOG）：

• GPIO 输出高电平 → NPN 导通 → WTDOG 被拉为低电平（准备/收尾阶段）

• GPIO 输出低电平 → NPN 截止 → WTDOG 为高电平（空闲态；喂狗有效脉冲段保持 250ms）

• 库内 GPIO 空闲电平固定为低电平（空闲时 NPN 截止，WTDOG 保持高电平）

• 喂狗时库内 _inner_feed() 实际输出时序：GPIO 拉高保持 2000ms（前置隔离段，WTDOG 低电平）→ GPIO 输出低电平保持 250ms（喂狗有效高脉冲）→ GPIO 再拉高保持 200ms（后置保持段，为下降后的低电平采样留出时间）→ GPIO 切回低电平空闲态

• 前置 2000ms 隔离段的作用：长时间空闲在 WTDOG 上形成的电平变化可能被芯片误记为第一次喂狗；若该次误识别与本次有效脉冲在检测窗口内被配对，会被判为两次有效识别而触发复位。因此每次喂狗前先保持 WTDOG 低电平 2000ms，等待连续喂狗检测窗口退出后，再发送真正的 250ms 有效高脉冲

• 后置 200ms 保持段的作用：为脉冲下降沿之后芯片对低电平的采样留出足够时间，保证本次识别完整闭合

• 单次普通喂狗波形总耗时 FEED_SEQUENCE_MS = 2000 + 250 + 200 = 2450ms；自动喂狗按目标起点间隔计算，内部实际等待时间为 max(2000ms, 配置周期×1000 - 2450ms)，即两次普通喂狗之间至少空闲 2000ms

• GPIO 初始化使用 gpio.setup(wdt_pin, PIN_IDLE_LEVEL, gpio.PULLUP)，PIN_IDLE_LEVEL 为 0（低电平），并启用内部上拉

• 风险提示 1：准备阶段可能会关闭看门狗，直到有效脉冲被芯片接受后才重新开启；若主控在该窗口内卡死，可能无法自动复位。2000ms 隔离时间须经目标器件实测验证，芯片的检测窗口按固件主循环计数，并非精确毫秒

• 风险提示 2：日志中的"喂狗完成"只表示 2000/250/200ms 波形已发送，不代表芯片已确认接收

复位通路（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 示例代码中进行描述。

5. 喂狗周期与冷却约束：

   • 自动喂狗以 auto_feed_period_s 为目标起点间隔（默认 180 秒，其中包含约 2.45 秒的普通喂狗波形），库内实际等待时间为 max(2000ms, 配置周期×1000 - 2450ms)；

   • 手动 feed() 与最近一次普通喂狗完成之间至少间隔 2000ms，不足 2000ms 时直接返回 false，以避免准备下降沿与前一次喂狗在芯片检测窗口内配对而触发误复位；

   • 因此实际最短自动喂狗周期约为 4.45 秒（2450ms 波形 + 2000ms 冷却），配置 auto_feed_period_s = 0 只表示非负周期，不表示关闭自动喂狗；调度延迟可能进一步延长实际间隔。

四、核心示例

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 看门狗初始化（16（3.3V）/12（4.35V） 分钟超时档位：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

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

• 初始化成功后立即执行一次喂狗，首次喂狗波形与后续周期喂狗一致（GPIO 高 2000ms → 低 250ms → 高 200ms，再切回空闲低电平）

• 若 auto_feed_period_s 配置过小（周期×1000 < 2450 + 2000 ms），库内只打印告警日志、不会返回 false；实际最短自动喂狗周期约 4.45 秒

• 配置 auto_feed_period_s = 0 表示非负周期，不表示关闭自动喂狗

• 准备阶段可能会关闭看门狗，直到有效脉冲被接受才重新开启；若主控在此期间卡死，可能无法自动复位

参数

cfg

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

                -- 参数含义：自动喂狗目标起点间隔；
                -- 数据类型：number；
                -- 取值范围：非负整数（大于等于 0），单位为秒；
                -- 是否必选：可选传入此参数，默认值为 180； 
                -- 注意事项：小于 0 初始化直接失败，返回 false；
                --          该参数为目标起点间隔，其中包含约 2.45 秒的普通喂狗波形，库内实际等待时间为 max(2000ms, 周期×1000 - 2450ms)；
                --          配置值过小时只打印告警日志、初始化不会失败；实际最短自动喂狗周期约 4.45 秒（2450ms 波形 + 2000ms 冷却）；
                --          配置 0 表示非负周期，不表示关闭自动喂狗；调度延迟可能进一步延长实际间隔；
                --          默认值 180 秒适用于 Air153C（喂狗周期 ≤200 秒）及 Air153D 模式 1，其他超时档位需按第 2.3 节喂狗时间自行调大；
                -- 参数示例：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 初始化（16（3.3V）/12（4.35V） 分钟超时档位：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

• 距最近一次普通喂狗完成不足 2000ms 时，为防误触发强制复位，直接返回 false（本次不会执行喂狗），并打印告警日志

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

• feed() 内部只通过事件唤醒库内主循环，真正的 2000/250/200ms 波形仍由主循环统一输出；返回 true 仅表示请求已受理

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

参数

无

返回值

local success = exair153x_wdt.feed()

有一个返回值 success

success

含义说明：手动喂狗请求是否成功受理；
数据类型：boolean；
取值范围：true 或 false；
注意事项：未初始化时返回 false；距最近一次普通喂狗完成不足 2000ms 时同样返回 false；返回 true 仅表示请求已受理；
返回示例：true

示例

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

6.3 exair153x_wdt.trigger_reset()

功能：

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

注意事项：

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

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

• 3 次脉冲宽度均为 250ms、相邻间隔 100ms，第 1 次到第 3 次脉冲开始的跨度约 700ms

• 芯片接受复位序列后，PWR_OFF 输出高电平经 NPN 三极管拉低主控 RESET；日志"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；
取值范围：格式为年月日时分，例如 "202609201735"；
注意事项：无；
返回示例："202609201735"

示例

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

七、版本更新说明

版本号：202609201735

1、更新时间：2026-09-20 17:35

2、更新内容

• 普通喂狗采用 2000/250/200ms 波形，保持 GPIO 空闲低电平

• 自动周期扣除 2450ms 波形时长，普通喂狗完成后至少空闲 2000ms

• 手动喂狗冷却时间改为 2000ms；小周期仍可配置，实际最短约 4.45 秒

• 保留快速三脉冲强制复位流程，说明发送完成与芯片接收确认的区别

版本号：202609091030

1、更新时间：2026-09-09 10:30

2、更新内容

• PIN_IDLE_LEVEL 由 1 改为 0（空闲电平从高电平改为低电平）

• 对应注释调整：GPIO 空闲电平/切回电平由"高电平"改为"低电平"

• gpio.setup 增加 gpio.PULLUP 参数

• _inner_feed 函数逻辑调整：增加脉冲前后 50ms 延迟和中间电平切换

版本号：202608260000

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

2、更新内容

• 将 auto_feed_period_s 的最小限制从 150 秒改为 0（不能为负数）

版本号：202608030000

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

2、更新内容

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

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

八、产品支持说明

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