概述: 外设执行模块是实现“当条件满足时执行动作”的规则引擎,采用触发-动作模型,支持 4 种触发器(平台/定时/事件/轮询)和 27 种动作(GPIO/PWM/传感器/显示/系统等)。规则异步执行,Worker 池预创建 3 个任务,最小堆内存门控 30KB。配置存储在 /config/periph_exec.json 中。
出厂 data/config/periph_exec.json 中的规则全部默认禁用，避免未知接线环境下自动驱动外设。导入示例或创建规则后，请先确认目标外设存在且已完成引脚核对，再启用规则；Lite/Standard 文件系统生成会过滤当前档位不支持或引用已裁剪外设的动作。
本目录包含外设执行规则系统的分模块详细文档，按触发器、动作和完整场景组织。
| 名称 | 状态 | 触发方式 | 目标外设 | 动作 | 统计 | 操作 |
|---|
| ADC电压采集上报 | 已禁用 | 定时触发 | ADC模拟转换 | 传感器数据读取 -> ADC模拟转换 | 触发次数：1 | 执行一次 / 编辑 / 启用 / 删除 |
| ADC电压低于2.30V关闭继电器 | 已禁用 | 事件触发 | - | 设置低电平 | 触发次数：1 | 执行一次 / 编辑 / 启用 / 删除 |
| ADC电压高于2.50V打开继电器 | 已禁用 | 事件触发 | - | 设置高电平 | 触发次数：1 | 执行一次 / 编辑 / 启用 / 删除 |
| ADC电压显示到数码管 | 已禁用 | 定时触发 | - | 显示数字 | 触发次数：1 | 执行一次 / 编辑 / 启用 / 删除 |
| NTP时间同步 | 已禁用 | 平台触发(MQTT) | - | NTP同步 | 触发次数：1 | 执行一次 / 编辑 / 启用 / 删除 |
| OLED温湿度显示 | 已禁用 | 定时触发 | - | OLED自定义显示 | 触发次数：1 | 执行一次 / 编辑 / 启用 / 删除 |
| OLED自定义显示-按键触发设备信息 | 已禁用 | 事件触发 | - | OLED自定义显示 | 触发次数：1 | 执行一次 / 编辑 / 启用 / 删除 |
| OLED自定义显示-定时混排 | 已禁用 | 定时触发 | - | OLED自定义显示 | 触发次数：1 | 执行一次 / 编辑 / 启用 / 删除 |
| OLED自定义显示-MQTT下发消息 | 已禁用 | 平台触发(MQTT) | - | OLED自定义显示 | 触发次数：1 | 执行一次 / 编辑 / 启用 / 删除 |
| OTA升级 | 已禁用 | 平台触发(MQTT) | - | OTA升级 | 触发次数：1 | 执行一次 / 编辑 / 启用 / 删除 |
规则列表用于确认每条规则的启用状态、触发器数量、动作数量和手动执行入口。现场首次上线时建议逐条验证，再打开“启用”。
| 触发器 | 输入来源 | 检查时机 | 适合场景 | 常见风险 |
|---|
| 平台触发 | MQTT / HTTP / 云端命令 | 消息到达后立即匹配字段 | 远程开关、参数下发、联动控制 | 字段名不一致、messageId 重复、权限不足 |
| 定时触发 | 本地时钟 / cron / interval | 到达时间点后执行 | 周期上报、定时开关、夜间模式 | NTP 未同步、首次触发语义不清 |
| 事件触发 | 按键、传感器、系统事件 | 事件发布时匹配 eventId | 按键控制、超限报警、状态变化 | 防抖、事件名拼写、缓存值过期 |
| 轮询触发 | 主动读取外设或协议数据 | 每个 pollInterval 检查条件 | Modbus 采集、模拟量阈值、距离报警 | 频率过高、串口忙、低内存降频 |
上面两张图适合先看：数据模型说明一条规则由哪些字段组成，时序对比说明什么时候该选择平台、定时、事件或轮询触发。
| 文档 | actionType | 说明 |
|---|
| gpio-actions.md | 0,1,13,14 | GPIO输出（高/低/反转） |
| pwm-actions.md | 2,3,4,5 | PWM/呼吸灯/DAC |
| system-actions.md | 6,7,8,9 | 系统重启/恢复/NTP/OTA |
| modbus-actions.md | 16,17,18 | Modbus线圈/寄存器/轮询 |
| sensor-actions.md | 19 | 传感器数据读取 |
| display-actions.md | 24,25,26,27 | 数码管/OLED显示 |
| event-actions.md | 21,22,23 | 触发事件/规则控制 |
| script-actions.md | 10,11,12,15 | 发送指令/灯效控制/电机控制/命令脚本 |
{
"id": "exec_<timestamp>",
"name": "规则名称",
"enabled": true,
"execMode": 0,
"triggers": [ /* 触发器数组，OR关系 */ ],
"actions": [ /* 动作数组，顺序执行 */ ],
"reportAfterExec": true
}
| triggerType | 名称 | 典型用途 |
|---|
| 0 | 平台触发 | IoT平台MQTT指令匹配 |
| 1 | 定时触发 | 周期采集、定时控制 |
| 4 | 事件触发 | WiFi/MQTT/按键/传感器数据事件 |
| 5 | 轮询触发 | Modbus传感器周期数据条件判断 |
| actionType | 名称 | 参数说明 |
|---|
| 0 | 高电平 | targetPeriphId=GPIO外设ID |
| 1 | 低电平 | targetPeriphId=GPIO外设ID |
| 2 | 闪烁 | actionValue=间隔ms |
| 3 | 呼吸灯 | actionValue=周期ms |
| 4 | 设置PWM | actionValue=占空比值 |
| 5 | 设置DAC | actionValue=0~255 |
| 6 | 系统重启 | 无参数 |
| 7 | 恢复出厂 | 无参数 |
| 8 | NTP同步 | 无参数 |
| 9 | OTA升级 | actionValue=URL |
| 10 | 发送指令 | targetPeriphId=目标外设，actionValue=JSON/文本 |
| 11 | 灯效控制 | NeoPixel预设灯效/颜色值（支持 $value） |
| 12 | 电机控制 | forward/reverse/stop/步数 |
| 13 | 高电平(反转) | 物理输出低电平 |
| 14 | 低电平(反转) | 物理输出高电平 |
| 15 | 命令脚本 | actionValue=脚本内容 |
| 16 | Modbus线圈 | FC05 |
| 17 | Modbus寄存器 | FC06 |
| 18 | Modbus轮询 | 采集子设备数据 |
| 19 | 传感器读取 | 采集温度/湿度/距离/电流/电压 |
| 21 | 触发事件 | actionValue=事件ID，支持规则链式联动 |
| 22 | 启用规则 | targetPeriphId=规则ID |
| 23 | 禁用规则 | targetPeriphId=规则ID |
| 24 | 显示数字 | actionValue="12.34" |
| 25 | 显示文本 | actionValue="PLAY" |
| 26 | 清屏 | 无参数 |
| 27 | OLED显示 | actionValue=多行模板 |
| 28 | 射频发送 | actionValue=射频编码 |
| 29 | 串口发送 | actionValue=文本数据（支持 $value） |
| operatorType | 名称 | 说明 |
|---|
| 0 | 等于 (EQ) | value == compareValue |
| 1 | 不等于 (NEQ) | value != compareValue |
| 2 | 大于 (GT) | value > compareValue |
| 3 | 小于 (LT) | value < compareValue |
| 4 | 大于等于 (GTE) | value >= compareValue |
| 5 | 小于等于 (LTE) | value <= compareValue |
| 6 | 区间内 (BETWEEN) | compareValue="min,max" |
| 7 | 区间外 (NOT_BETWEEN) | compareValue="min,max" |
| 8 | 包含 (CONTAIN) | 字符串包含 |
| 9 | 不包含 (NOT_CONTAIN) | 字符串不包含 |
