Skip to main content

Complete PeriphExec Management Guide

fastbeeAbout 16 min

Complete PeriphExec Management Guide

Synchronized Device Documentation

This page corresponds to the synchronized Chinese source. Commands, JSON examples, API paths, field names, and screenshots are kept aligned with the Chinese device-side source documentation.

What This Page Covers

  • Web console page purpose and related device-side configuration model.
  • Available fields, operational workflow, and safety checks.
  • Validation steps, logs, and maintenance recommendations.

Source Reference

The detailed operational source is preserved below so implementation details stay exact while the English navigation, titles, and reading path remain available.

外设执行管理完整指南

一、功能概述

外设执行（Periph-Exec）是 FastBee 系统的自动化规则引擎，通过配置**触发器（Trigger）和动作（Action）**实现设备联动。配置存储在 /config/periph_exec.json 中。

出厂默认规则均为 enabled: false，不会在未知接线环境中自动执行。新增或导入规则后，建议先保存为禁用状态，确认目标外设、引脚和动作参数正确后再启用。

外设执行规则列表
外设执行规则列表

规则列表用于快速核对触发器、动作数量、启用状态和手动执行入口。新增或编辑规则时，请先确认目标外设已存在且处于预期启用状态。

外设执行规则链路图
外设执行规则链路图

上图把页面中的“触发器、规则、动作、执行结果”对应到运行时链路。现场配置时优先保证每条规则名称可读、触发条件单一明确、动作顺序可回滚。

外设执行规则生命周期
外设执行规则生命周期

新增规则时按生命周期图推进：禁用保存、校验参数、手动执行、启用运行、异常回滚。这样能避免未知接线环境中规则一保存就驱动现场负载。

触发器与动作选择地图
触发器与动作选择地图

配置页面里的触发器和动作可以按上图快速归类。先确认触发来源，再选择控制、采集、输出或系统动作，保存后用“执行一次”和日志验证。

触发器时序对比
触发器时序对比

如果不确定该选哪种触发器，先按时序对比图判断数据来源：平台命令用平台触发，固定节拍用定时触发，按钮或数据源变化用事件触发，没有事件源的传感器或 Modbus 采集才用轮询触发。

外设执行规则表单安全检查
外设执行规则表单安全检查

涉及继电器、电机、Modbus 写入、系统重启或 OTA 等强动作时，保存前按安全检查图逐项确认。建议先禁用保存，再手动执行单个动作，确认日志和上报正常后再启用自动触发。

核心概念

概念说明类比
规则（Rule）完整的自动化逻辑单元IF-THEN语句
触发器（Trigger）何时执行规则（条件）IF部分
动作（Action）执行什么操作（结果）THEN部分
执行模式（execMode）动作执行策略同步/异步
上报数据（reportAfterExec）执行后是否上报状态反馈机制

规则结构

{
  "id": "exec_1717392000",
  "name": "高温报警",
  "enabled": true,
  "execMode": 0,
  "triggers": [
    { /* 触发器配置 */ }
  ],
  "actions": [
    { /* 动作配置 */ }
  ],
  "reportAfterExec": true
}

二、Web界面操作指南

2.1 访问外设执行页面

方式1：独立页面（推荐）
  1. 点击左侧菜单 外设配置
  2. 页面自动切换到 外设执行管理 标签
  3. 显示规则列表表格
方式2：从外设联动进入
  1. 在外设列表中点击某外设
  2. 查看关联的规则

2.2 创建新规则

操作步骤

  1. 点击新增按钮

    • 右上角 新增规则

  2. 填写基础配置

    字段必填说明示例
    规则名称✅有业务含义的名称高温报警
    上报数据-执行后上报状态到云平台✅ 默认启用
    启用-规则是否生效首次建议关闭，确认后启用

  3. 配置触发器（第二部分）

    • 点击 添加触发 按钮
    • 选择触发类型（平台/事件/定时/轮询）
    • 填写对应参数

  4. 配置动作（第三部分）

    • 点击 添加动作 按钮
    • 选择动作类型（GPIO/PWM/脚本等）
    • 选择目标外设
    • 填写动作参数

  5. 保存规则

    • 点击 保存 按钮
    • 系统验证配置
    • 写入 periph_exec.json
界面布局
┌────────────────────────────────────────────────────┐
│  新增外设执行                                [×]   │
├────────────────────────────────────────────────────┤
│  【基础配置】                                       │
│  规则名称: [高温报警_____________]                  │
│  ☑ 上报数据    ☑ 启用                              │
├────────────────────────────────────────────────────┤
│  触发配置                    [+ 添加触发]           │
│  ┌──────────────────────────────────────────────┐ │
│  │ 1  [×] 删除                                  │ │
│  │ 触发类型: [轮询触发          ▼]               │ │
│  │ 目标外设: [dht_room          ▼]               │ │
│  │ 轮询间隔: [5   ] 秒    超时: [1000] ms        │ │
│  │ 重试次数: [2   ] 次    延迟: [100 ] ms        │ │
│  │ 比较操作: [大于              ▼]  比较值: [30] │ │
│  └──────────────────────────────────────────────┘ │
├────────────────────────────────────────────────────┤
│  执行动作配置                [+ 添加动作]           │
│  ┌──────────────────────────────────────────────┐ │
│  │ 1  [×] 删除                                  │ │
│  │ 动作类型: [高电平            ▼]               │ │
│  │ 目标外设: [relay_fan         ▼]               │ │
│  │ 执行模式: [同步              ▼]               │ │
│  └──────────────────────────────────────────────┘ │
│  ┌──────────────────────────────────────────────┐ │
│  │ 2  [×] 删除                                  │ │
│  │ 动作类型: [触发事件          ▼]               │ │
│  │ 事件ID:   [alarm_high_temp___]                │ │
│  └──────────────────────────────────────────────┘ │
├────────────────────────────────────────────────────┤
│                  [取消]    [保存]                  │
└────────────────────────────────────────────────────┘

2.3 触发器配置详解

触发器类型对比
类型触发时机适用场景配置难度
平台触发收到云平台指令IoT平台远程控制⭐⭐
事件触发系统/传感器事件按键按下/WiFi连接⭐⭐⭐
定时触发时间到达周期采集/定时开关⭐
轮询触发轮询检测条件满足传感器值判断⭐⭐
类型1：平台触发（triggerType=0）

触发条件：收到云平台下发的MQTT/Modbus指令

配置参数
参数必填说明示例
目标外设✅接收指令的外设uart_modbus
操作符✅匹配/设置模式匹配
比较值条件匹配的指令内容{"cmd":"on"}
操作符说明
操作符值名称说明
0匹配模式接收数据等于比较值时触发
1设置模式接收数据直接作为动作参数
配置示例
{
  "triggerType": 0,
  "triggerPeriphId": "uart_modbus",
  "operatorType": 0,
  "compareValue": "{\"cmd\":\"fan_on\"}"
}

触发流程：

云平台发送: {"cmd":"fan_on"}
        ↓
UART接收数据
        ↓
匹配 compareValue
        ↓
触发规则执行动作
类型2：事件触发（triggerType=4）

触发条件：系统事件、传感器数据事件、按键事件

事件分类
事件类别事件ID前缀说明
系统事件sys:WiFi/MQTT/NTP状态变化
传感器数据ds:传感器读取数据
按键事件button_物理按键按下
Modbus控制mc:Modbus子设备事件
自定义事件无前缀用户自定义事件
配置步骤

  1. 选择事件类别

    • 从下拉框选择（系统/传感器/按键等）

  2. 选择具体事件

    • 根据类别自动加载事件列表

  3. 配置条件判断（传感器事件）

    • 比较操作符：等于/大于/小于/区间等
    • 比较值：阈值
配置示例（温度>30℃）
{
  "triggerType": 4,
  "eventId": "ds:dht_room.temperature",
  "operatorType": 2,
  "compareValue": "30"
}
常用系统事件
事件ID触发时机
sys:wifi.connectedWiFi连接成功
sys:wifi.disconnectedWiFi断开
sys:mqtt.connectedMQTT连接成功
sys:mqtt.disconnectedMQTT断开
sys:boot.completed系统启动完成
按键事件

外设需配置为 GPIO_INTERRUPT 类型（type=18/19/20），自动生成事件：

按键按下: button_{periphId}.pressed
按键长按: button_{periphId}.long_press
类型3：定时触发（triggerType=1）

触发条件：时间到达指定间隔或时间点

定时模式
模式timerMode说明适用场景
间隔定时0每隔X秒执行周期采集
每日定时1每天固定时间执行定时开关
间隔定时配置
参数必填说明示例
间隔秒数✅执行间隔（1~86400秒）60（1分钟）
每日定时配置
参数必填说明示例
时间点✅执行时间（HH:MM格式）08:30
配置示例
// 间隔定时：每5分钟执行
{
  "triggerType": 1,
  "timerMode": 0,
  "intervalSec": 300
}

// 每日定时：每天早上8:30执行
{
  "triggerType": 1,
  "timerMode": 1,
  "timePoint": "08:30"
}
类型4：轮询触发（triggerType=5）

触发条件：主动轮询传感器数据并判断条件

与事件触发的区别
特性事件触发轮询触发
数据来源被动接收事件主动读取传感器
实时性高（事件驱动）中（依赖轮询间隔）
适用传感器所有类型本地传感器
配置复杂度高（需配置事件）低（直接选外设）

实际配置中可以回到“触发器时序对比”图确认选择：轮询触发会主动占用外设或总线资源，适合没有事件源的数据；事件触发更适合已经由传感器读取动作、按键状态机或系统事件产生的数据源。

配置参数
参数必填默认值取值范围说明
目标外设✅--要轮询的传感器
轮询间隔✅60秒5~86400秒读取间隔
响应超时-1000ms100~5000ms读取超时时间
重试次数-2次0~3次失败重试
轮询延迟-100ms20~1000ms两次读取间隔
比较操作✅-0~9条件判断
比较值条件--阈值
比较操作符
operatorType名称示例说明
0等于value == 30精确匹配
1不等于value != 0非零判断
2大于value > 30上限报警
3小于value < 10下限报警
4大于等于value >= 30包含边界
5小于等于value <= 10包含边界
6区间内compareValue="20,30"正常范围
7区间外compareValue="20,30"异常范围
8包含value.contains("ON")字符串匹配
9不包含!value.contains("OFF")字符串匹配
配置示例（温度>30℃报警）
{
  "triggerType": 5,
  "triggerPeriphId": "dht_room",
  "intervalSec": 5,
  "pollResponseTimeout": 1000,
  "pollMaxRetries": 2,
  "pollInterPollDelay": 100,
  "operatorType": 2,
  "compareValue": "30"
}

执行流程：

每隔5秒
    ↓
读取 dht_room 传感器
    ↓
获取 temperature 值
    ↓
判断: temperature > 30 ?
    ↓ 是
触发规则执行动作

2.4 动作配置详解

动作类型速查表
actionType名称参数目标外设说明
0高电平无✅ GPIO输出HIGH
1低电平无✅ GPIO输出LOW
2闪烁actionValue=间隔ms✅ GPIO周期性闪烁
3呼吸灯actionValue=周期ms✅ PWM渐变效果
4设置PWMactionValue=占空比✅ PWM0~4095
5设置DACactionValue=0~255✅ DAC模拟输出
6系统重启无❌重启设备
7恢复出厂无✖重置配置为默认值
8NTP同步无❌同步时间
9OTA升级actionValue=URL❌远程升级
10调用外设actionValue=方法✅ 任意调用外设方法
15命令脚本actionValue=脚本❌PERIPH/DELAY序列
16Modbus线圈actionValue=0/1✅ Modbus控制继电器
17Modbus寄存器actionValue=值✅ Modbus写寄存器
18Modbus轮询自动配置✅ Modbus读取数据
19传感器读取actionValue=配置✅ 传感器采集数据
21触发事件actionValue=事件ID❌发射事件
22启用规则targetPeriphId=规则ID❌动态启用
23禁用规则targetPeriphId=规则ID❌动态禁用
24显示数字actionValue="12.34"✅ 数码管7段显示
25显示文本actionValue="PLAY"✅ 数码管字符显示
26清屏无✅ 显示屏清空内容
27OLED显示actionValue=模板✅ OLED多行文本
动作1~0/1：GPIO高/低电平

最基础的控制动作

配置参数
参数必填说明
目标外设✅GPIO数字输出外设ID
配置示例
{
  "actionType": 0,
  "targetPeriphId": "relay_fan"
}
动作2：闪烁
配置参数
参数必填说明示例
目标外设✅GPIO外设led_status
闪烁间隔✅亮/灭时间（ms）500
配置示例
{
  "actionType": 2,
  "targetPeriphId": "led_alarm",
  "actionValue": "500"
}

效果：LED每500ms翻转一次（1秒周期）

动作15：命令脚本

灵活的多步控制

支持的命令
命令格式说明
PERIPHPERIPH <id> <动作> [值]控制外设
DELAYDELAY <毫秒>延时
LOGLOG <消息>打印日志
MQTTMQTT <qos> <payload>发送消息
PERIPH子命令
子命令格式说明
HIGHPERIPH led1 HIGH高电平
LOWPERIPH led1 LOW低电平
PWMPERIPH motor PWM 2048设置PWM
BLINKPERIPH led BLINK 500闪烁
COLORPERIPH strip COLOR #FF0000NeoPixel颜色
配置示例（流水灯）
{
  "actionType": 15,
  "actionValue": "PERIPH led1 LOW\nDELAY 300\nPERIPH led1 HIGH\nPERIPH led2 LOW\nDELAY 300\nPERIPH led2 HIGH\nPERIPH led3 LOW\nDELAY 300\nPERIPH led3 HIGH\nLOG 流水灯一轮完成"
}

执行流程：

点亮led1 → 延时300ms → 熄灭led1
    ↓
点亮led2 → 延时300ms → 熄灭led2
    ↓
点亮led3 → 延时300ms → 熄灭led3
    ↓
打印日志
动作19：传感器读取
配置参数
{
  "actionType": 19,
  "targetPeriphId": "dht_room",
  "actionValue": "{\"dataField\":\"temperature\",\"decimalPlaces\":1}"
}
actionValue字段
字段类型默认值说明
dataField字符串"temperature"要读取的字段
decimalPlaces整数2小数位数
scaleFactor浮点1.0缩放系数
offset浮点0偏移量
可用dataField
传感器类型dataField单位
DHTtemperature, humidity℃, %
DS18B20temperature℃
HC-SR04distancecm
BH1750lightlux
BMP280temperature, pressure℃, hPa
动作27：OLED显示
配置参数
{
  "actionType": 27,
  "targetPeriphId": "oled_ctrl",
  "actionValue": "温度: ${temperature}℃\n湿度: ${humidity}%"
}
模板变量
  • ${temperature} - 从触发器数据中获取
  • ${humidity} - 从触发器数据中获取
  • ${value} - 当前轮询值
显示效果
┌─────────────────┐
│ 温度: 28.5℃     │
│ 湿度: 65%       │
└─────────────────┘

2.5 编辑规则

操作步骤
  1. 在规则列表找到目标规则
  2. 点击 编辑 按钮
  3. 模态窗自动填充当前配置
  4. 修改触发器或动作
  5. 点击 保存 确认
注意事项
  • ⚠️ 触发器/动作可增删：点击删除按钮移除
  • ⚠️ 修改后立即生效：保存后系统自动重新加载
  • ⚠️ 引用检查：修改目标外设ID需确认外设存在

2.6 启用/禁用规则

操作方式
方式操作效果
列表快捷操作点击启用/禁用按钮立即切换
编辑模态窗切换启用开关保存后生效
使用场景
  • 调试：禁用规则观察系统行为
  • 临时停用：保留配置但不执行
  • 测试：逐个启用规则排查问题

2.7 删除规则

操作步骤
  1. 点击 删除 按钮（红色）
  2. 确认对话框
  3. 从 periph_exec.json 移除
⚠️ 警告
  • ❌ 删除不可恢复
  • 💡 建议先禁用观察
  • 🔗 检查依赖：是否有其他规则引用

三、配置实战演练

3.1 场景1：智能温控系统

需求
  • 每5秒读取DHT22温度
  • 温度>30℃时启动风扇
  • 温度<25℃时关闭风扇
  • OLED显示当前温度
步骤1：配置外设

（参考外设配置文档，添加dht_room、relay_fan、oled_ctrl）

步骤2：创建高温启动规则

  1. 点击新增规则

  2. 基础配置

    • 名称：高温启动风扇
    • 上报数据：✅
    • 启用：✅

  3. 添加触发器

    • 触发类型：轮询触发
    • 目标外设：dht_room
    • 轮询间隔：5秒
    • 比较操作：大于
    • 比较值：30

  4. 添加动作1

    • 动作类型：高电平
    • 目标外设：relay_fan

  5. 添加动作2

    • 动作类型：OLED显示
    • 目标外设：oled_ctrl
    • 动作值：温度: ${temperature}℃\n状态: 风扇启动

  6. 保存

完整JSON配置
{
  "id": "exec_high_temp_start",
  "name": "高温启动风扇",
  "enabled": true,
  "execMode": 0,
  "triggers": [
    {
      "triggerType": 5,
      "triggerPeriphId": "dht_room",
      "intervalSec": 5,
      "pollResponseTimeout": 1000,
      "pollMaxRetries": 2,
      "pollInterPollDelay": 100,
      "operatorType": 2,
      "compareValue": "30"
    }
  ],
  "actions": [
    {
      "actionType": 0,
      "targetPeriphId": "relay_fan",
      "execMode": 0
    },
    {
      "actionType": 27,
      "targetPeriphId": "oled_ctrl",
      "actionValue": "温度: ${temperature}℃\n状态: 风扇启动",
      "execMode": 0
    }
  ],
  "reportAfterExec": true
}
步骤3：创建低温关闭规则

（类似步骤2，比较操作改为"小于"，比较值改为25，动作为低电平）

3.2 场景2：按键控制灯光

需求
  • 短按按键：切换LED开关
  • 长按按键：启动呼吸灯模式
配置外设
{
  "peripherals": [
    {
      "id": "btn_ctrl",
      "name": "控制按键",
      "type": 18,
      "enabled": true,
      "pins": [0]
    },
    {
      "id": "led_main",
      "name": "主LED",
      "type": 12,
      "enabled": true,
      "pins": [15],
      "params": { "initialState": 0 }
    }
  ]
}
规则1：短按切换
{
  "id": "exec_btn_short",
  "name": "短按切换LED",
  "enabled": true,
  "triggers": [
    {
      "triggerType": 4,
      "eventId": "button_btn_ctrl.pressed"
    }
  ],
  "actions": [
    {
      "actionType": 10,
      "targetPeriphId": "led_main",
      "actionValue": "toggle",
      "execMode": 0
    }
  ]
}
规则2：长按呼吸灯
{
  "id": "exec_btn_long",
  "name": "长按呼吸灯",
  "enabled": true,
  "triggers": [
    {
      "triggerType": 4,
      "eventId": "button_btn_ctrl.long_press"
    }
  ],
  "actions": [
    {
      "actionType": 3,
      "targetPeriphId": "led_main",
      "actionValue": "3000",
      "execMode": 0
    }
  ]
}

3.3 场景3：定时上报传感器数据

需求
  • 每1分钟读取温湿度
  • 通过MQTT上报到云平台
规则配置
{
  "id": "exec_periodic_report",
  "name": "定时数据上报",
  "enabled": true,
  "triggers": [
    {
      "triggerType": 1,
      "timerMode": 0,
      "intervalSec": 60
    }
  ],
  "actions": [
    {
      "actionType": 19,
      "targetPeriphId": "dht_room",
      "actionValue": "{\"dataField\":\"temperature\"}",
      "execMode": 0
    },
    {
      "actionType": 15,
      "actionValue": "MQTT 0 [{\"id\":\"temperature\",\"value\":\"${temperature}\"},{\"id\":\"humidity\",\"value\":\"${humidity}\"}]"
    }
  ]
}

四、执行模式详解

4.1 同步模式（execMode=0）

特点：

  • 动作按顺序执行
  • 前一个动作完成后才执行下一个
  • 适合有依赖关系的动作

示例：

动作1: 读取传感器
    ↓ （等待完成）
动作2: 判断数值
    ↓ （等待完成）
动作3: 控制继电器

4.2 异步模式（execMode=1）

特点：

  • 动作立即返回，不等待完成
  • 多个动作可并行执行
  • 适合独立动作

示例：

动作1: 打开LED     ─┐
动作2: 打开蜂鸣器   ├─ 同时执行
动作3: 发送MQTT    ─┘

4.3 选择建议

场景推荐模式原因
传感器读取→控制同步需要等待数据
多设备同时控制异步提高响应速度
命令脚本同步命令有顺序依赖
日志记录异步不影响主流程

五、常见错误与解决方案

5.1 配置错误

错误原因解决方案
规则不触发enabled=false启用规则
触发条件不满足比较值错误检查传感器数据范围
动作无效果目标外设未启用确认外设enabled=true
脚本报错语法错误查看日志排查
定时不准NTP未同步确保网络连通
轮询超时传感器响应慢增加pollResponseTimeout
事件不触发事件ID错误检查前缀和拼写

5.2 排查步骤

  1. 检查启用状态

    • 规则enabled: true
    • 外设enabled: true

  2. 查看统计信息

    • 列表显示触发次数
    • 0次表示未触发

  3. 查看日志

    • Web界面日志
    • 串口日志

  4. 简化测试

    • 先测试单个触发器
    • 先测试单个动作

  5. 手动触发

    • 使用API触发规则
    • 验证动作是否正常

  6. 检查数据源

    • 传感器是否正常读取
    • 事件是否正确发射

六、高级技巧

6.1 多触发器OR逻辑

一个规则可以有多个触发器，任一触发即执行：

{
  "triggers": [
    { "triggerType": 4, "eventId": "button_btn1.pressed" },
    { "triggerType": 4, "eventId": "button_btn2.pressed" },
    { "triggerType": 1, "timerMode": 0, "intervalSec": 3600 }
  ]
}

触发条件：按键1 或 按键2 或 每小时定时

6.2 规则联动

规则可以启用/禁用其他规则：

// 规则1：启用规则2
{
  "actions": [
    {
      "actionType": 22,
      "targetPeriphId": "exec_rule2_id"
    }
  ]
}

// 规则2：禁用自己
{
  "actions": [
    {
      "actionType": 23,
      "targetPeriphId": "exec_rule2_id"
    }
  ]
}

6.3 使用系统事件

监听WiFi/MQTT状态变化：

{
  "triggers": [
    {
      "triggerType": 4,
      "eventId": "sys:wifi.connected"
    }
  ],
  "actions": [
    {
      "actionType": 15,
      "actionValue": "LOG WiFi已连接，IP: ${ip}\nMQTT 0 {\"event\":\"wifi_connected\",\"ip\":\"${ip}\"}"
    }
  ]
}

6.4 性能优化

优化项方法效果
降低轮询频率增加intervalSec减少CPU占用
使用事件触发代替轮询实时响应
禁用未使用规则enabled=false节省资源
合并相似规则多触发器OR简化配置
异步执行独立动作execMode=1提高响应

七、API参考

PeriphExec API 路由地图
PeriphExec API 路由地图

API 参考不仅用于接口调用，也可用于排查页面问题。若页面操作后状态没有变化，可按图检查浏览器请求、API 响应、Manager 方法、配置文件和日志是否在同一次操作中对应起来。

7.1 查询规则列表

GET /api/periph-exec/rules

响应：

{
  "success": true,
  "data": [
    {
      "id": "exec_xxx",
      "name": "高温报警",
      "enabled": true,
      "triggerCount": 2,
      "actionCount": 3
    }
  ]
}

7.2 手动触发规则

POST /api/periph-exec/rules/{ruleId}/trigger

7.3 启用/禁用规则

POST /api/periph-exec/rules/{ruleId}/toggle

7.4 删除规则

DELETE /api/periph-exec/rules/{ruleId}

八、相关文档

提示：外设执行是FastBee系统的核心功能，建议先从简单的定时触发+GPIO控制开始，逐步学习事件触发和脚本动作。

Last update:
Contributors: kerwincui
fastbee
Copyright © 2026 fastbee