LuatOS 看门狗统一说明
一、看门狗总览
看门狗（Watch Dog Timer，WDT）用于监控嵌入式系统运行状态。当系统出现程序跑飞、死循环、死机等异常，且在设定时间内未及时“喂狗”时，看门狗会自动复位并重启系统，从而提高系统可靠性和稳定性。
LuatOS 中的看门狗按实现位置分为三大类：
| 分类 | 实现位置 | 控制方式 |
| 内部硬件看门狗 | 芯片内部 Always-On 电源域（AON WDT） | `wdt` 核心库（可不控制，由内核固件自动运行） |
| 内部软件看门狗 | 操作系统任务调度层 | `wdt` 核心库 |
| 外部硬件看门狗 | 独立看门狗芯片/模组（GPIO/UART） | `air13C_wtd`（Air153C）/ Air5101S / HK005（待发布） |
二、内部硬件看门狗（wdt 核心库）
2.1 特点
- 位于芯片 “Always-On” 电源域，开机后硬件层面自动开始计数，独立于软件系统运行。
- 由 LuatOS 内核固件自动开启和控制，用户脚本可以不干预（内核固件会自动喂狗）。
- 硬件定时器持续计数，喂狗操作复位计数，计数溢出（超时）触发系统复位。
- 理论上能复位绝大多数系统异常；但在极端硬件故障（如 PSRAM 完全死锁）时可能无法正确重启。
2.2 与 wdt 核心库的关系
wdt 核心库既可以控制内部硬件看门狗，也可以控制内部软件看门狗。 其中内部硬件看门狗由内核固件自动管理，用户可以选择不控制；如需干预，可在支持的型号上调用 wdt.feed() 喂狗。
2.3 各系列内部硬件看门狗差异
| 系列 | 开启 | 设置超时时长 | 喂狗 | 关闭 |
| Air700/Air780/Air8000 系列 | 内核固件自动开启，不支持用户开启 | 不支持用户设置，LuatOS内核固件根据以下三种情况自动设置：(1)从psm+模式下唤醒重启后，第一次超时时长固定为8秒；(2)从psm+模式下唤醒重启，8秒内成功喂狗之后，超时时长固定为28秒；(3)其余原因的重启或者开机，超时时长固定为28秒 | 用户脚本可调用 `wdt.feed()`；内核固件也会自动定时喂狗（间隔远小于最小超时 8 秒） | 不支持 |
| Air8101 系列 | 内核固件自动开启，不支持用户开启 | 不支持用户设置，默认 8 秒 | 不支持用户喂狗；内核固件每 1 秒自动喂一次 | 不支持 |
| Air1601/Air1602 系列 | 内核固件自动开启，不支持用户开启 | 支持用户设置，最大 60 秒，默认 20 秒 | 用户脚本可调用 `wdt.feed()`；内核固件也会自动定时喂狗 | 不支持 |
PSM+ 模式（
pm.WORK_MODE, 3）下，内部硬件看门狗停止工作。
三、内部软件看门狗（wdt 核心库）
3.1 特点
- 基于操作系统任务调度机制，在软件层面进行监控。
- 能够检测任务阻塞和软件死锁，但依赖操作系统正常运行，OS 死机时会失效。
- 通过
wdt核心库函数控制。 - 特殊说明：在 Air8101 中，软件看门狗检测函数同时也会喂内部硬件看门狗。
3.2 各系列软件看门狗支持情况
| 系列 | 是否支持软件看门狗 | 说明 |
| Air700/Air780/Air8000 系列 | 不支持 | 仅有内部硬件看门狗 |
| Air8101 系列 | 支持 | 常规/低功耗模式下可用 `wdt.init` 开启、`wdt.setTimeout` 设置、`wdt.feed` 喂狗、`wdt.close` 关闭 |
| Air1601/Air1602 系列 | 不支持 | 仅有内部硬件看门狗 |
PSM+ 模式下软件看门狗失效。
四、外部硬件看门狗
外部硬件看门狗是独立于主控的看门狗芯片/模组，具有独立的电源和时钟，可靠性最高。它不受主控系统死机影响，能在主控完全失效时强制复位主控。目前 LuatOS 提供以下方案：
4.1 Air153C（air153C_wtd 扩展库）
Air153C 是外部硬件看门狗芯片，通过 GPIO 引脚以脉冲信号喂狗。
- 看门狗超时时长默认 240 秒，且不允许修改。
- 通过
air153C_wtd扩展库控制，使用 GPIO 脉冲喂狗。 - 芯片资料：https://docs.openluat.com/accessory/Air153C/
- 扩展库详细资料请跳转：https://docs.openluat.com/osapi/ext/air153C_wtd/
4.2 Air5101S（BLE 模组内置看门狗）
Air5101S 是 BLE 模组，内置看门狗功能，可与 4G 主控模组实现“互为看门狗”的可靠机制：
- Air5101S 守护主控：作为独立硬件看门狗，当主控运行异常、未在设定时间内喂狗时，Air5101S 通过 SWITCH 引脚输出指定电平，强制重启主控。
- 主控守护 Air5101S：主控可拉低 Air5101S 的 RESET 脚，在其工作异常时复位 Air5101S。
Air5101S 看门狗有两种使用方式：
- 方式一：LuatOS 扩展库 exril_5101 —— 主控通过串口以 AT 方式控制 Air5101S，使用
exril_5101.wdcfg（配置/查询看门狗）、exril_5101.wdfed（喂狗）等接口。 - 方式二：直接使用 AT 指令 —— 主控发送
AT+WDCFG（配置看门狗）、AT+WDFED（喂狗）、AT+SAVE（保存配置）等指令给 Air5101S。
以上功能均需在 AT 模式下使用；透传模式下需注意在喂狗超时前切换为 AT 模式喂狗，否则会触发看门狗复位。具体参数与示例见上方跳转链接。
4.3 HK005（待发布）
HK005 外部硬件看门狗方案目前尚未发布，相关资料与使用方式待官方后续补充。发布后本文将同步更新。