跳至主要內容

外设执行

fastbee大约 16 分钟

外设执行管理

一、功能概述

外设执行（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控制开始，逐步学习事件触发和脚本动作。

上次编辑于:
贡献者: kerwincui
蜂信物联 | 曲靖蜂信科技有限公司
Copyright © 2026 fastbee