针对 4G-Cat.1、MCU 等物联网终端的开发需求，LuatOS 应运而生，它是一款轻量级的嵌入式 Lua 脚本运行框架与实时系统，底层基于 Lua 5.3 进行了深度优化。在开发层面，LuatOS 以 Lua 脚本为开发载体，采用协程多任务的设计思路，且拥有完善的资源体系，70 多个核心库、20 多个扩展库结合千余个应用 demo，可支撑各类基础物联网应用的开发工作。

一、概述

看门狗（Watch Dog Timer，WDT）是一种用于监控嵌入式系统状态的电路，旨在提高系统的可靠性和稳定性。在看门狗电路的帮助下，当系统出现异常，如程序跑飞或死循环时，能够自动复位并重新启动系统。

1.1 各类看门狗的区别

1.1.1. 内部硬件看门狗（Always-On Watchdog Timer）

• 定义：AON WDT，位于芯片"Always-On"电源域的硬件看门狗
• 特点：开机后硬件层面自动开始计数，独立于软件系统运行
• 控制方式：完全由内核固件自动控制，不需要脚本干预
• 工作原理：硬件定时器持续计数，喂狗操作复位计数，超时（计数溢出）触发系统复位
• 可靠性：理论上能复位大部分系统异常，但在极端硬件故障（如 PSRAM 完全死锁）时可能无法正确重启

1.1.2. 软件看门狗

• 定义：基于操作系统任务调度机制的软件层面监控
• 特点：能够检测任务阻塞和软件死锁，依赖操作系统正常运行
• 控制方式：通过 wdt 库函数控制

1.1.3. 外部硬件看门狗

• 定义：独立的看门狗芯片，通过 GPIO/I2C 等接口通信
• 特点：完全独立于主系统，具有独立的电源和时钟，可靠性最高
• 控制方式：不通过 wdt 库，需使用 i2c、gpio 等外设驱动库实现喂狗操作

1.2 wdt 库专门用于控制芯片内部的看门狗

• 内部硬件看门狗：芯片内部集成的硬件看门狗单元，如 AON WDT(Always-On Watchdog Timer)，不同型号之间操作有所差异，见wdt函数详细说明；

• 软件看门狗：基于操作系统任务调度机制的软件层面看门狗，不同型号之间操作有所差异，见wdt函数详细说明；

• 低功耗模式pm.WORK_MODE,1 下，软件看门狗与内部硬件看门狗均可正常工作，具体是否同时支持内部硬件看门狗与软件看门狗，以及是否只支持内部硬件看够和软件看门狗中的一个，详见wdt函数说明；

• PSM+模式pm.WORK_MODE,3 下，软件看门狗失效，内部硬件看门狗也停止工作，详见wdt函数说明；

注意：外部硬件看门狗通过 GPIO/I2C 等接口控制，不在 wdt 库的控制范围内，需要使用相应的外设驱动库（如 i2c、gpio 库）来实现喂狗操作。

1.3 各种功耗模式下的看门狗特性

常规模式和低功耗模式（x 表示不支持）

PSM+ 模式（x 表示不支持）

二、核心示例

1、核心示例是指：使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码；

2、核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；

3、更加完整和详细的 demo，请参考 LuatOS 仓库 中各个产品目录下的 demo/wdt；

-- LuaTools需要PROJECT和VERSION这两个信息
PROJECT = "wdtdemo"
VERSION = "1.0.0"

log.info("main", PROJECT, VERSION)

-- 定义喂狗任务函数
function wdt_task()
    -- 这个demo要求有wdt库
    -- wdt库的使用,基本上每个demo的头部都有演示
    -- 模组/芯片的内部硬狗, 能解决绝大多数情况下的死机问题
    -- 但如果有要求非常高的场景, 依然建议外挂硬件,然后通过gpio/i2c定时喂狗
    if wdt == nil then
        while true do
            sys.wait(1000)
            log.info("wdt", "this demo need wdt lib")
        end
    end
    -- 注意, 大部分芯片/模块是 2 倍超时时间后才会重启
    -- 以下是常规配置, 9秒超时, 3秒喂一次狗
    -- 若软件崩溃,死循环,硬件死机,那么 最多 18 秒后,自动复位
    -- 注意: 软件bug导致业务失败, 并不能通过wdt解决
    wdt.init(9000)
    sys.timerLoopStart(wdt.feed, 3000)
end

-- 定义故障模拟任务函数
function fault_task()
    log.info("fault_task", "Entering infinite loop to simulate fault.")
    while true do
        -- 模拟故障场景，真的进入死循环
    end
end

-- 启动任务
sys.taskInit(wdt_task)
sys.taskInit(fault_task)

-- 用户代码已结束---------------------------------------------
-- 结尾总是这一句
sys.run()
-- sys.run()之后后面不要加任何语句!!!!!

三、常量详解

核心库常量，顾名思义是由合宙 LuatOS 内核固件中定义的、不可重新赋值或修改的固定值，在脚本代码中不需要声明，可直接调用；

每个常量对应的常量取值仅做日志打印时查询使用，不要将这个常量取值用做具体的业务逻辑判断，因为LuatOS内核固件可能会变更每个常量对应的常量取值；

如果用做具体的业务逻辑判断，一旦常量取值发生改变，业务逻辑就会出错；

wdt 核心库没有常量。

四、函数详解

4.1 wdt.init(timeout)

功能 初始化看门狗并立即启用。具体支持的范围取决于硬件设备。

参数

参数含义：看门狗超时时长
数据类型：number
取值范围：1000-90000毫秒 
是否必选：是
注意事项：具体支持的范围取决于硬件设备
参数示例：wdt.init(9000)

注意事项：

• 控制范围：wdt 库仅用于控制产品内部看门狗，外部硬件看门狗需要通过 i2c、gpio 等外设驱动库控制。

• 具体支持的范围取决于硬件设备。

Air8101系列：

常规模式和低功耗模式下：配置软件看门狗超时时长，然后开启软狗；内部硬件看门狗不支持用户设置，由LuatOS内核固件自动开启，默认超时时长为8秒。

PSM+模式下：软件看门狗和内部硬件看门狗均处于不工作的状态。

Air780 系列/Air700 系列及 Air8000 系列：

无软件看门狗,内部硬件看门狗由内核固件自动启动，不支持用户启动。

常规模式和低功耗模式下，LuatOS内核固件根据以下三种情况自动设置：

（1）从psm+模式下唤醒重启后，第一次超时时长固定为8秒。

（2）从psm+模式下唤醒重启，8秒内成功喂狗之后，超时时长固定为28秒。

（3）其余原因的重启或者开机，超时时长固定为28秒 。

PSM+模式下：内部硬件看门狗处于不工作的状态。

Air1601/Air1602系列：

内部硬件看门狗支持用户设置超时时长，最大超时时长为60秒；LuatOS内核固件自动开启时，默认超时时长为20秒。

• 失效情况：软件看门狗在操作系统死机时失效，内部硬件看门狗在 PSRAM 等关键硬件死机时可能无法正确复位。

返回值

local success = wdt.init(9000)

有一个返回值 success；

success

含义说明：看门狗初始化操作是否成功；
数值类型：boolean；
取值范围：true或false；
注意事项：当底层不支持或参数无效时返回false；
         初始化成功后看门狗立即开始计时；
返回示例：true；

示例

-- 初始化看门狗，超时时间10秒
local success = wdt.init(10000)
if success then
    log.info("wdt", "看门狗初始化成功")
else
    log.error("wdt", "看门狗初始化失败")
end

-- 配合定时喂狗使用
wdt.init(9000)
sys.timerLoopStart(wdt.feed, 3000)

4.2 wdt.feed()

功能 喂狗操作，使看门狗超时计时复位，重新开始计时。

参数

无

返回值

local success = wdt.feed()

有一个返回值 success

success

含义说明：喂狗操作是否成功；
数据类型：boolean；
取值范围：true或false；
注意事项：当看门狗未初始化或操作失败时返回false；
         喂狗成功后看门狗超时计时器从零开始重新计时；
返回示例：true

注意事项：

• 具体支持的范围取决于硬件设备。

Air8101系列：

常规模式和低功耗模式下：喂软件看门狗，不支持用户喂内部硬件看门狗，LuatOS内核固件中，1秒自动喂一次硬狗。

PSM+模式下：软件看门狗和内部硬件看门狗均处于不工作的状态。

Air780 系列/Air700 系列及 Air8000 系列：

无软件看门狗。

常规模式和低功耗模式下，喂内部硬件看门狗支持以下两种方式：

（1）LuatOS用户脚本中，调用一次wdt.feed()接口喂一次狗

（2）LuatOS内核固件中，每隔一段时间自动喂一次狗，这个间隔远远低于看门狗最小超时时长的8秒。

PSM+模式下：内部硬件看门狗处于不工作的状态。

Air1601/Air1602系列：

无软件看门狗。

常规模式下，喂内部硬件看门狗支持以下两种方式：

（1）LuatOS用户脚本中，调用一次wdt.feed()接口喂一次狗

（2）LuatOS内核固件中，每隔一段时间自动喂一次狗。

高可靠性场景：建议同时使用内部看门狗 + 外部看门狗。

示例

-- 初始化看门狗
wdt.init(9000)

-- 定时喂狗（推荐方式）
sys.timerLoopStart(wdt.feed, 3000)

4.3 wdt.setTimeout(timeout)

功能 重新设置看门狗超时时长（部分设备支持）。

参数

参数含义：新的超时时长，单位为毫秒
数据类型：number
取值范围：正整数
是否必选：是
注意事项：不是所有设备都支持此功能。建议使用定时器定期调用这个函数。
参数示例：wdt.setTimeout(5000)

返回值

local success = wdt.setTimeout(5000)

有一个返回值 success;

success

含义说明：超时时间设置操作是否成功；
数据类型：boolean；
取值范围：true或false；
注意事项：当设备不支持此功能或参数无效时返回false；
设置成功后新的超时时间立即生效；
返回示例：true；

注意事项：

• 具体支持的范围取决于硬件设备。

Air8101系列：

常规模式和低功耗模式下：配置软件门狗超时时间，不支持用户设置内部硬件看门狗超时时长，LuatOS内核固件自动开启时，默认超时时长为8秒。

PSM+模式下：软件看门狗和内部硬件看门狗均处于不工作的状态。

Air780系列/Air700系列及Air8000系列：

无软件看门狗，内部硬件看门狗不支持用户设置超时时长，因此不支持此函数。

Air1601/Air1602系列：

无软件看门狗，内部硬件看门狗支持用户设置超时时长，最大超时时长为60秒。

示例

-- 初始化看门狗
wdt.init(10000)
sys.timerLoopStart(wdt.feed, 3000)

-- 5秒后调整超时时间
sys.timerStart(function()
    local success = wdt.setTimeout(5000)
    if success then
        log.info("wdt", "超时时间已调整为5秒")
    else
        log.info("wdt", "设备不支持动态调整超时时间")
    end
end, 5000)

4.4 wdt.close()

功能 关闭看门狗（通常不被支持或功能有限）。

参数

无

返回值

local success = wdt.close()

有一个返回值 success;

success

含义说明：看门狗关闭操作是否成功；
数据类型：boolean；
取值范围：true或false；
注意事项：当设备不支持关闭操作或操作失败时返回false；
         具体支持的范围取决于硬件设备；
返回示例：false；

注意事项：

• 具体支持的范围取决于硬件设备。

Air8101系列：

常规模式和低功耗模式下：关闭软件看门狗，不支持关闭内部硬件看门狗。

PSM+模式下：软件看门狗和内部硬件看门狗均处于不工作的状态。

Air780 系列/Air700 系列及 Air8000 系列：

无软件看门狗，不支持关闭内部硬件看门狗。

Air1601/Air1602系列：

无软件看门狗，不支持关闭内部硬件看门狗。

示例

wdt.init(10000)

-- 运行一段时间后尝试关闭（通常不会成功）
sys.timerStart(function()
    local success = wdt.close()
    if success then
        log.info("wdt", "看门狗已关闭")
    else
        log.info("wdt", "看门狗关闭失败（正常情况）")
    end
end, 9000)

五、模组支持说明

支持 LuatOS 开发的所有产品都支持 wdt 核心库。

今天的内容就分享到这里啦~