Script System Guide
Script System 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
- Script System Guide context and expected reader workflow.
- Configuration, verification, and release-readiness details.
- Source-aligned implementation notes, screenshots, and troubleshooting references.
Source Reference
The detailed operational source is preserved below so implementation details stay exact while the English navigation, titles, and reading path remain available.
脚本系统指南
本文档涵盖 FastBee 外设执行系统的两大脚本功能：
- 规则脚本（数据转换模板引擎） -- 用于多协议数据格式转换
- 命令脚本（硬件控制脚本引擎） -- 用于 GPIO/PWM/DAC 硬件自动化控制
当前默认
esp32、esp32c3、esp32s3精简版关闭FASTBEE_ENABLE_RULE_SCRIPT，Web 页面也不发布 RuleScript 管理入口。本文档主要适用于esp32s3-full完整版或自行开启 RuleScript 的定制构建。精简版的本地联动请优先使用“外设执行”中的定时、事件、传感器和 Modbus 动作。
完整版中的规则脚本页面用于维护脚本列表；轻量命令脚本通常从外设执行动作中进入。
脚本调试建议先从固定字段模板开始，确认输入数据、规则匹配和输出 payload 都正确后，再逐步加入条件、表达式和外设动作。
命令脚本更适合短动作序列，例如流水灯、PWM 渐变或简单显示刷新。复杂判断仍建议放在外设执行触发器或 RuleScript 中。
第一部分：规则脚本（数据转换模板）
1. 功能概述
规则脚本是 FastBee 的多协议数据格式转换管道。当设备通过不同协议（MQTT、Modbus RTU/TCP、HTTP、CoAP、TCP）收发数据时，规则脚本可以在数据流经系统时自动进行格式转换。
核心用途：
- 将平台标准数组格式与第三方系统的自定义 JSON 格式互转
- 统一不同协议的数据格式，使外部设备无缝接入 FastBee 平台
- 无需修改固件代码即可适配新的数据格式需求
执行模型：
输入数据 (JSON) --> 提取 key-value --> 替换模板占位符 --> 输出结果规则脚本是纯数据转换管道，不产生副作用（不控制 GPIO、不发送消息），仅对经过的数据做格式变换。
2. 基本概念
2.1 触发类型
规则脚本有两种触发类型：
| 触发类型 | 编号 | 说明 | 数据流向 |
|---|---|---|---|
| 数据接收 (DATA_RECEIVE) | 0 | 协议数据到达时触发 | 外部 --> ESP32 |
| 数据上报 (DATA_REPORT) | 1 | 协议数据发送前触发 | ESP32 --> 外部 |
数据接收 (triggerType=0)： 设备从外部接收到数据后，先经过规则脚本转换，再交给系统处理。典型场景是将第三方设备发来的自定义 JSON 格式转为 FastBee 标准数组格式。
数据上报 (triggerType=1)： 设备准备向外部发送数据前，先经过规则脚本转换。典型场景是将 FastBee 内部的标准数组格式转为目标平台要求的 JSON 格式。
2.2 协议类型
每条规则绑定一种协议类型，只对该协议的数据流生效：
| 协议类型 | 编号 | 说明 |
|---|---|---|
| MQTT | 0 | MQTT 消息收发 |
| Modbus RTU | 1 | Modbus 串口通信 |
| Modbus TCP | 2 | Modbus TCP/IP 通信 |
| HTTP | 3 | HTTP 请求/响应 |
| CoAP | 4 | CoAP 物联网协议 |
| TCP | 5 | 原始 TCP 套接字 |
2.3 模板语法 (${key} 占位符)
规则脚本使用纯文本模板，通过 ${key} 占位符引用输入数据中的字段值。
工作原理：
- 系统解析输入的 JSON 数据，提取所有 key-value 对
- 扫描模板中的
${key}占位符 - 将每个占位符替换为对应的值
- 返回替换后的字符串作为输出
调试规则脚本时，先把输入 JSON、占位符和输出模板三者摆在一起核对。若 ${key} 保持原文，通常说明输入数据里没有同名 key，或数组格式没有按 id/value 提取。
支持的输入格式：
- 数组格式（FastBee 标准）：
[{"id":"temperature","value":"27.43"}, ...]- 提取规则：
id字段作为 key，value字段作为 value
- 提取规则：
- 对象格式（扁平 JSON）：
{"temperature": 27.43, ...}- 提取规则：对象的每个键名作为 key，键值作为 value
3. 创建和管理规则脚本
3.1 创建规则
- 打开 Web 管理页面，进入 规则脚本 页面
- 点击 新增规则 按钮
- 填写规则信息：
- 名称：规则的描述性名称，如 "MQTT上报:数组转对象"
- 触发类型：选择 "数据接收" 或 "数据上报"
- 协议类型：选择该规则适用的通信协议
- 脚本内容：编写
${key}占位符模板（详见下文）
- 点击 保存
3.2 编辑规则
在规则脚本表格中，点击对应规则的 编辑 按钮，修改后保存。
3.3 启用/禁用规则
- 点击规则行的 启用/禁用 按钮切换状态
- 禁用的规则不参与数据转换匹配
- 新建的预设示例默认禁用，需手动启用
3.4 删除规则
点击规则行的 删除 按钮移除规则。删除操作不可撤销。
3.5 规则匹配优先级
- 同一协议类型和触发方向，只有第一条匹配的已启用规则会生效
- 如果没有匹配的规则，数据原样传递不做任何转换
4. 脚本语法详解
4.1 占位符格式
${变量名}- 变量名对应输入 JSON 中的 key（数组格式的
id值，或对象格式的键名） - 变量名区分大小写：
${temperature}和${Temperature}是不同的 - 未匹配到的占位符保持原样不替换
4.2 数组格式输入的解析
输入数据为 FastBee 标准数组格式时：
[
{"id": "temperature", "value": "27.43", "remark": ""},
{"id": "humidity", "value": "32.18", "remark": ""}
]系统提取的 key-value 对：
| key | value |
|---|---|
| temperature | 27.43 |
| humidity | 32.18 |
4.3 对象格式输入的解析
输入数据为扁平 JSON 对象时：
{"temperature": 26.5, "humidity": 65.8}系统提取的 key-value 对：
| key | value |
|---|---|
| temperature | 26.5 |
| humidity | 65.8 |
4.4 限制参数
| 项目 | 限制值 | 说明 |
|---|---|---|
| 脚本最大长度 | 2048 字节 | scriptContent 字段的最大字节数 |
| 最大 key-value 对数 | 32 个 | 超出部分忽略 |
| 输入格式 | JSON 数组或对象 | 非 JSON 输入返回原始数据 |
5. 实际应用案例
案例 1：MQTT 上报 -- 数组转对象
场景： FastBee 内部使用数组格式存储传感器数据，但云平台要求扁平 JSON 对象格式。
触发类型： 数据上报 (DATA_REPORT) 协议类型： MQTT
输入数据（FastBee 标准格式）：
[
{"id": "temperature", "value": "27.43", "remark": ""},
{"id": "humidity", "value": "32.18", "remark": ""}
]脚本内容：
{"temperature": ${temperature}, "humidity": ${humidity}}输出结果：
{"temperature": 27.43, "humidity": 32.18}案例 2：MQTT 接收 -- 对象转数组
场景： 外部设备发来扁平 JSON，需要转为 FastBee 标准数组格式才能被系统正确解析。
触发类型： 数据接收 (DATA_RECEIVE) 协议类型： MQTT
输入数据（外部设备格式）：
{"temperature": 26.5, "humidity": 65.8}脚本内容：
[{"id":"temperature","value":"${temperature}","remark":""},{"id":"humidity","value":"${humidity}","remark":""}]输出结果：
[{"id":"temperature","value":"26.5","remark":""},{"id":"humidity","value":"65.8","remark":""}]案例 3：Modbus RTU 数据接收转换
场景： Modbus RTU 从站返回的寄存器数据被驱动层解析为 JSON 对象后，需要转为 FastBee 标准数组格式上报平台。
触发类型： 数据接收 (DATA_RECEIVE) 协议类型： Modbus RTU
输入数据：
{"temperature": 25.3, "humidity": 60.1}脚本内容：
[{"id":"temperature","value":"${temperature}","remark":""},{"id":"humidity","value":"${humidity}","remark":""}]输出结果：
[{"id":"temperature","value":"25.3","remark":""},{"id":"humidity","value":"60.1","remark":""}]案例 4：HTTP 上报自定义格式
场景： 向第三方 HTTP API 推送数据，目标 API 要求特定的 JSON 结构。
触发类型： 数据上报 (DATA_REPORT) 协议类型： HTTP
输入数据：
[{"id":"temperature","value":"27.43"},{"id":"humidity","value":"32.18"}]脚本内容：
{"device":"esp32","temp":${temperature},"humi":${humidity}}输出结果：
{"device":"esp32","temp":27.43,"humi":32.18}案例 5：TCP 上报精简文本
场景： 通过 TCP 连接向服务器发送精简文本格式数据，节省带宽。
触发类型： 数据上报 (DATA_REPORT) 协议类型： TCP
输入数据：
[{"id":"temperature","value":"27.43"},{"id":"humidity","value":"32.18"}]脚本内容：
T:${temperature},H:${humidity}输出结果：
T:27.43,H:32.18案例 6：多传感器组合转换
场景： 设备同时采集温度、湿度、气压、光照四个传感器值，需要转为嵌套 JSON 格式。
脚本内容：
{"sensors":{"temp":${temperature},"humi":${humidity},"press":${pressure},"light":${light}},"unit":"metric"}6. 最佳实践
6.1 命名规范
使用清晰的命名格式：协议名 + 方向 + 简要说明
MQTT上报:数组转对象
MQTT接收:对象转数组
ModbusRTU接收转换
HTTP上报:自定义格式6.2 先禁用再编辑
编辑复杂的转换模板时，建议先禁用规则，编辑完成后再启用。避免编辑过程中不完整的模板影响数据流。
6.3 一个协议方向一条规则
同一协议类型 + 同一触发方向只有第一条匹配规则生效。避免创建重复的规则。
6.4 注意值类型
- 数值类型直接使用占位符：
"temp": ${temperature}-- 输出"temp": 27.43 - 字符串类型需要加引号：
"name": "${deviceName}"-- 输出"name": "esp32"
6.5 预设示例数据
系统首次启动时会自动创建 7 条预设示例规则，覆盖所有 6 种协议类型。这些示例默认禁用，可以直接修改后启用使用，也可作为参考模板。
| 示例名称 | 触发类型 | 协议 | 说明 |
|---|---|---|---|
| MQTT上报:数组转对象 | 数据上报 | MQTT | 标准数组 --> 扁平对象 |
| MQTT接收:对象转数组 | 数据接收 | MQTT | 扁平对象 --> 标准数组 |
| ModbusRTU接收转换 | 数据接收 | Modbus RTU | 对象 --> 标准数组 |
| ModbusTCP接收转换 | 数据接收 | Modbus TCP | 对象 --> 标准数组 |
| HTTP上报:自定义格式 | 数据上报 | HTTP | 标准数组 --> 自定义 JSON |
| CoAP接收转换 | 数据接收 | CoAP | 对象 --> 标准数组 |
| TCP上报:精简格式 | 数据上报 | TCP | 标准数组 --> 纯文本 |
7. API 接口说明
规则脚本由独立的 RuleScriptManager 管理，通过专用 REST API (/api/rule-script*) 进行增删改查。规则脚本存储在独立配置文件 /config/rule_scripts.json 中，与外设执行规则 (/config/periph_exec.json) 完全分离。
7.1 获取所有规则
GET /api/rule-script响应字段：
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 规则唯一标识 |
| name | string | 规则名称 |
| enabled | boolean | 是否启用 |
| triggerType | number | 触发类型（0=数据接收, 1=数据上报） |
| protocolType | number | 协议类型（0-5） |
| scriptContent | string | 模板脚本内容 |
| lastTriggerTime | number | 上次触发时间（毫秒时间戳） |
| triggerCount | number | 累计触发次数 |
7.2 新增规则
POST /api/rule-script
Content-Type: application/x-www-form-urlencoded
name=MQTT上报:数组转对象
&triggerType=1
&protocolType=0
&scriptContent={"temperature": ${temperature}, "humidity": ${humidity}}
&enabled=true7.3 更新规则
POST /api/rule-script/update
Content-Type: application/x-www-form-urlencoded
id=script_mqtt_a2o
&name=MQTT上报:数组转对象
&triggerType=1
&protocolType=0
&scriptContent={"temperature": ${temperature}, "humidity": ${humidity}}7.4 启用/禁用规则
POST /api/rule-script/enable id=script_mqtt_a2o
POST /api/rule-script/disable id=script_mqtt_a2o7.5 删除规则
DELETE /api/rule-script/?id=script_mqtt_a2o第二部分：命令脚本（硬件控制）
1. 功能概述
命令脚本是 FastBee 外设执行系统的高级功能，允许用户通过简单的文本命令序列实现复杂的自动化控制逻辑。脚本在 ESP32 设备端本地解析和执行，支持 GPIO/PWM/DAC 硬件控制、外设联动、MQTT 数据上报以及随机数生成等能力。
命令脚本适合短小、顺序、可审计的硬件动作。涉及复杂条件、循环判断或长时间等待时，优先把条件放到触发器里，把脚本保留为明确的执行步骤。
2. 快速开始
在 Web 管理页面中，进入 外设执行 > 新增规则，将动作类型选择为 命令脚本，然后在脚本编辑框中输入命令即可。
最简示例 -- 控制 GPIO 5 闪烁一次：
GPIO 5 HIGH
DELAY 500
GPIO 5 LOW3. 支持的命令一览
| 命令 | 格式 | 说明 |
|---|---|---|
GPIO | GPIO <pin> HIGH|LOW | 设置引脚高/低电平 |
DELAY | DELAY <ms> | 延时等待（最大 10 秒/条） |
PWM | PWM <pin> <duty> | 设置 PWM 占空比（0-255） |
DAC | DAC <pin> <value> | 设置 DAC 模拟输出（0-255） |
LOG | LOG <message> | 输出调试日志（支持随机数表达式） |
PERIPH | PERIPH <id> <action> [param] | 通过 ID 控制已配置外设 |
MQTT | MQTT <topicIndex> <message> | 发布 MQTT 消息（支持随机数表达式） |
随机数表达式（可用于 MQTT 和 LOG 命令）：
| 表达式 | 说明 | 示例 | 输出 |
|---|---|---|---|
RANDOM(min,max) | 随机整数 | RANDOM(-10,100) | 27 |
RANDOMF(min,max,decimals) | 随机浮点数 | RANDOMF(-10,100,1) | 23.5 |
4. 基本语法规则
- 每行一条命令
- 命令名不区分大小写（
GPIO、gpio、Gpio均有效） - 参数之间用空格或制表符分隔
- 以
#开头的行为注释，会被跳过 - 空行会被自动忽略
## 这是注释，不会执行
GPIO 5 HIGH # 行内注释不支持，此行会解析失败
## 正确写法：注释独占一行
GPIO 5 HIGH5. 命令参考
GPIO -- 数字引脚控制
设置指定 GPIO 引脚的高/低电平。
GPIO <引脚号> HIGH|LOW| 参数 | 说明 |
|---|---|
| 引脚号 | GPIO 编号，如 2、4、5、12-33 等 |
| HIGH/LOW | 输出电平，HIGH 为高电平，LOW 为低电平 |
示例：
GPIO 2 HIGH # 板载 LED 亮（大部分 ESP32 开发板）
GPIO 2 LOW # 板载 LED 灭
GPIO 15 HIGH # GPIO15 输出高电平注意： 引脚 6-11 为 SPI Flash 专用，脚本中禁止使用。
DELAY -- 延时等待
暂停脚本执行指定的毫秒数。
DELAY <毫秒>| 参数 | 说明 |
|---|---|
| 毫秒 | 等待时间，单位 ms，范围 1-10000 |
示例：
DELAY 500 # 等待 500 毫秒
DELAY 1000 # 等待 1 秒
DELAY 5000 # 等待 5 秒限制：
- 单条 DELAY 最大 10000ms（10 秒）
- 脚本中所有 DELAY 的累计时间不超过 30000ms（30 秒）
PWM -- PWM 输出
设置指定引脚的 PWM 占空比。
PWM <引脚号> <占空比>| 参数 | 说明 |
|---|---|
| 引脚号 | GPIO 编号 |
| 占空比 | 0-255，0 为完全关闭，255 为完全导通 |
示例：
PWM 4 128 # 50% 占空比
PWM 4 255 # 100% 占空比（全亮）
PWM 4 0 # 关闭 PWM 输出说明： 脚本中的 PWM 使用 LEDC 通道 15（专用），频率 5000Hz，8 位分辨率，不会与外设管理器的通道冲突。
DAC -- 模拟输出
设置指定引脚的 DAC 模拟输出值。
DAC <引脚号> <输出值>| 参数 | 说明 |
|---|---|
| 引脚号 | DAC 引脚，ESP32 仅支持 GPIO 25 和 GPIO 26 |
| 输出值 | 0-255，对应 0V-3.3V |
示例：
DAC 25 128 # 输出约 1.65V
DAC 26 255 # 输出约 3.3V
DAC 25 0 # 输出 0VLOG -- 输出日志
在系统日志中输出一条信息，用于调试和追踪脚本执行过程。支持 RANDOM/RANDOMF 随机数表达式。
LOG <消息内容>| 参数 | 说明 |
|---|---|
| 消息内容 | 任意文本，支持空格，多个词会自动拼接。支持 RANDOM/RANDOMF 表达式 |
示例：
LOG 脚本开始执行
LOG Setting GPIO 5 to HIGH
LOG 温度过高，启动风扇
LOG 当前模拟温度: RANDOMF(20,35,1) 度日志会以 [Script] 前缀输出到系统日志，可在 设备日志 页面查看。
PERIPH -- 外设控制
通过外设 ID 控制已配置的外设，支持多种子动作。
PERIPH <外设ID> <子动作> [参数]| 参数 | 说明 |
|---|---|
| 外设ID | 外设配置中的标识符，如 led_1、fan、relay_main |
| 子动作 | 控制动作，见下表 |
| 参数 | 部分子动作需要额外参数 |
支持的子动作：
| 子动作 | 参数 | 说明 |
|---|---|---|
HIGH | 无 | 设置外设为高电平 |
LOW | 无 | 设置外设为低电平 |
PWM <duty> | 占空比 0-255 | 设置 PWM 占空比 |
BLINK [ms] | 可选，间隔毫秒，默认 500 | 启动闪烁效果（异步定时器） |
BREATHE [ms] | 可选，周期毫秒，默认 2000 | 启动呼吸灯效果（异步定时器） |
STOP | 无 | 停止当前定时器动作（闪烁/呼吸灯） |
DISPLAY <内容> | 数字字符串，支持模板 | 数码管显示数字（最多 4 位，支持小数点和冒号） |
TEXT <内容> | 最多 4 字符，支持模板 | 数码管显示英文/数字混合文本 |
CLEAR | 无 | 数码管清屏（全段熄灭） |
BRIGHTNESS <级别> | 0-7 | 数码管调节亮度（0=最暗，7=最亮） |
示例：
## 基本开关控制
PERIPH relay_1 HIGH # 打开继电器
PERIPH relay_1 LOW # 关闭继电器
## PWM 调光
PERIPH led_strip PWM 200 # LED 灯带亮度调到 200
## 效果控制
PERIPH status_led BLINK 300 # 状态灯 300ms 间隔闪烁
PERIPH mood_led BREATHE 1500 # 氛围灯 1.5 秒周期呼吸
PERIPH mood_led STOP # 停止呼吸灯效果
## 数码管显示（TM1637）
PERIPH tm1637_01 DISPLAY 25.3 # 显示 25.3
PERIPH tm1637_01 DISPLAY 12:34 # 显示时钟 12:34
PERIPH tm1637_01 TEXT HELO # 显示 HELO（最多 4 字符）
PERIPH tm1637_01 BRIGHTNESS 5 # 亮度调到 5 级
PERIPH tm1637_01 CLEAR # 清屏注意：
- 外设 ID 必须与外设配置页面中已配置的外设一致
BLINK和BREATHE启动异步定时器后立即返回，不阻塞后续命令- 若外设 ID 不存在，该命令会被跳过（记录警告日志），脚本继续执行
DISPLAY/TEXT/CLEAR/BRIGHTNESS仅对数码管（TM1637）类型外设有效，需在外设配置中启用数码管
数码管显示（TM1637）专用说明
当 PERIPH 命令的目标外设为 TM1637 四位数码管时，可使用 DISPLAY、TEXT、CLEAR、BRIGHTNESS 四个子动作进行显示控制。
DISPLAY -- 显示数字
在数码管上显示数字内容，支持整数、小数和冒号分隔的时钟格式。
PERIPH <数码管ID> DISPLAY <内容>| 格式 | 示例 | 显示效果 |
|---|---|---|
| 整数 | DISPLAY 1234 | 1234 |
| 带小数点 | DISPLAY 25.3 | 25.3（显示到对应位的小数点） |
| 时钟格式 | DISPLAY 12:34 | 12:34（中间冒号点亮） |
| 负数 | DISPLAY -12 | -12（首位显示减号） |
| 模板占位符 | DISPLAY ${dht_01.temperature} | 动态替换为传感器读数 |
注意：
- 数码管仅有 4 位，超出部分会被截断或提示溢出
- 浮点数会根据数位自动放置小数点
- 当占位符未命中缓存时，保留原始文本便于调试
TEXT -- 显示文本
在数码管上显示英文字母与数字混合字符（最多 4 字符）。受限于 7 段数码管段码表，仅部分字母可清晰显示（如 A/b/C/d/E/F/H/L/o/P/U 等）。
PERIPH <数码管ID> TEXT <内容>示例：
PERIPH tm1637_01 TEXT ON # 显示 ON
PERIPH tm1637_01 TEXT OFF # 显示 OFF
PERIPH tm1637_01 TEXT HELO # 显示 HELO
PERIPH tm1637_01 TEXT ${dht_01.temperature.unit} # 显示单位字符CLEAR -- 清屏
熄灭所有段，清空数码管显示。
PERIPH <数码管ID> CLEARBRIGHTNESS -- 亮度调节
设置数码管亮度级别，共 8 级。
PERIPH <数码管ID> BRIGHTNESS <级别>| 级别 | 说明 |
|---|---|
| 0 | 最暗（几乎不可见） |
| 1-2 | 夜间低亮度 |
| 3 | 默认亮度（适合室内） |
| 4-5 | 正常亮度 |
| 6-7 | 最亮（适合强光环境） |
示例：
PERIPH tm1637_01 BRIGHTNESS 0 # 夜间熄灯前降到最暗
PERIPH tm1637_01 BRIGHTNESS 3 # 恢复默认亮度
PERIPH tm1637_01 BRIGHTNESS 7 # 白天户外最亮超出 0-7 范围的值会被自动截断到边界。
传感器数据模板（${periphId.field}）
命令脚本中的 PERIPH ... DISPLAY 与 PERIPH ... TEXT 子动作以及外设执行规则的 显示数字/显示文本 动作值，都支持通过 ${periphId.field} 占位符动态读取传感器数据缓存，实现"采集 -> 显示"的联动。
语法格式
${<外设ID>.<字段名>[.<属性>]}| 属性 | 说明 | 示例 |
|---|---|---|
| 省略（默认 value） | 读取字段当前值 | ${dht_01.temperature} -> 25.3 |
.unit | 读取字段单位 | ${dht_01.temperature.unit} -> ℃ |
.label | 读取字段显示标签 | ${dht_01.temperature.label} -> 温度 |
工作机制
- 传感器类外设（如 DHT11/DHT22/DS18B20/Modbus 采集）在采集完成后，将每个字段以
<外设ID>_<字段名>作为键写入全局缓存 DISPLAY/TEXT执行前，扫描${...}占位符并从缓存查找对应值进行文本替换- 未命中缓存时保留原始占位符文本，方便在日志中定位未采集或 ID/字段名拼写错误
典型字段名
| 外设类型 | 常见字段名 |
|---|---|
| DHT11/DHT22 | temperature、humidity |
| DS18B20 | temperature |
| Modbus 采集 | 由物模型标识符决定，如 temp、humi、voltage 等 |
示例
## 显示 DHT11 温度读数
PERIPH tm1637_01 DISPLAY ${dht_01.temperature}
## 显示湿度读数
PERIPH tm1637_01 DISPLAY ${dht_01.humidity}
## 显示 DS18B20 温度
PERIPH tm1637_01 DISPLAY ${ds18b20_01.temperature}注意：
- 模板替换发生在脚本运行时，每次执行都会重新读取最新缓存值
- 若外设未启用或尚未完成首次采集，缓存为空会保留占位符原文
- 外设 ID 与字段名均区分大小写，需与外设配置页面显示完全一致
MQTT -- MQTT 数据上报
通过 MQTT 协议发布消息到指定的发布主题，可用于模拟数据上报、状态通知等场景。
MQTT <主题索引> <消息内容>| 参数 | 说明 |
|---|---|
| 主题索引 | 已配置的 MQTT 发布主题索引（从 0 开始） |
| 消息内容 | 要发布的消息文本，支持 RANDOM/RANDOMF 随机数表达式 |
示例：
## 上报固定数据
MQTT 0 [{"id":"switch","value":"1"}]
## 上报随机温度（整数，-10 到 100）
MQTT 0 [{"id":"temperature","value":"RANDOM(-10,100)"}]
## 上报随机温度（浮点数，保留 1 位小数）
MQTT 0 [{"id":"temperature","value":"RANDOMF(-10,100,1)"}]
## 同时上报多个属性
MQTT 0 [{"id":"temperature","value":"RANDOMF(15,35,1)"},{"id":"humidity","value":"RANDOMF(30,90,1)"}]注意：
- 主题索引对应 MQTT 配置页面中 发布主题 列表的顺序（第一个为 0，第二个为 1，以此类推）
- MQTT 未连接时该命令会被跳过（记录警告日志），脚本继续执行
- 消息内容中的
RANDOM/RANDOMF表达式会在每次执行时生成新的随机值
随机数表达式
随机数表达式可用于 MQTT 和 LOG 命令的消息内容中，每次脚本执行时生成不同的随机值。
RANDOM(min,max) -- 随机整数
生成 [min, max] 范围内的随机整数（闭区间）。
RANDOM(min,max)| 参数 | 说明 |
|---|---|
| min | 最小值（整数，可为负数） |
| max | 最大值（整数） |
RANDOMF(min,max,decimals) -- 随机浮点数
生成 [min, max] 范围内的随机浮点数，并格式化到指定小数位数。
RANDOMF(min,max,decimals)| 参数 | 说明 |
|---|---|
| min | 最小值（可为负数或小数） |
| max | 最大值 |
| decimals | 小数位数（0-6） |
6. 命令脚本限制参数
| 项目 | 限制值 | 说明 |
|---|---|---|
| 脚本最大长度 | 1024 字节 | 脚本文本的总字节数 |
| 最大命令数 | 50 条 | 不含注释和空行 |
| 单条 DELAY 上限 | 10,000 ms | 10 秒 |
| DELAY 累计上限 | 30,000 ms | 30 秒 |
| 脚本执行超时 | 35,000 ms | 35 秒，超时自动中止 |
| 禁用引脚 | GPIO 6-11 | SPI Flash 专用，不可使用 |
这些限制的目标是保证脚本不会长期阻塞设备主流程。若必须执行较长过程，建议拆成多条规则，通过事件或平台命令分阶段触发，并在每个阶段写入日志。
7. 命令脚本实用示例
示例 1：报警闪烁
温度过高时触发，LED 快速闪烁 5 次进行报警提示。
## 温度报警 - LED快速闪烁5次
LOG 温度报警触发
GPIO 2 HIGH
DELAY 200
GPIO 2 LOW
DELAY 200
GPIO 2 HIGH
DELAY 200
GPIO 2 LOW
DELAY 200
GPIO 2 HIGH
DELAY 200
GPIO 2 LOW
DELAY 200
GPIO 2 HIGH
DELAY 200
GPIO 2 LOW
DELAY 200
GPIO 2 HIGH
DELAY 200
GPIO 2 LOW
LOG 报警闪烁完成示例 2：渐亮效果
通过 PWM 实现 LED 从暗到亮的渐变效果。
## LED 渐亮效果
LOG 开始渐亮
PWM 4 0
DELAY 100
PWM 4 50
DELAY 100
PWM 4 100
DELAY 100
PWM 4 150
DELAY 100
PWM 4 200
DELAY 100
PWM 4 255
LOG 渐亮完成示例 3：多外设联动
通过外设 ID 协调控制多个设备。
## 场景：晚间模式
LOG 进入晚间模式
PERIPH main_light LOW
DELAY 500
PERIPH night_light PWM 30
PERIPH mood_led BREATHE 3000
LOG 晚间模式已激活示例 4：定时上报模拟传感器数据
配合定时触发，周期性上报随机环境数据到 MQTT 平台。
## 上报模拟环境传感器数据
LOG 开始上报环境数据
MQTT 0 [{"id":"temperature","value":"RANDOMF(-10,45,1)"},{"id":"humidity","value":"RANDOMF(20,95,1)"},{"id":"co2","value":"RANDOM(400,2000)"}]
LOG 环境数据上报完成示例 5：报警联动 + 状态上报
检测到异常后，控制外设报警并上报状态。
## 异常报警联动
LOG 检测到异常，启动报警
PERIPH alarm_led BLINK 200
PERIPH alarm_out HIGH
DELAY 3000
PERIPH alarm_out LOW
MQTT 0 [{"id":"alarm","value":"1"},{"id":"alarm_type","value":"temperature_high"}]
LOG 报警状态已上报示例 6：数码管温湿度轮换显示
配合外设执行的定时触发（建议 intervalSec=8），数码管先显示 3 秒温度，再显示 3 秒湿度，循环往复。依赖 DHT11 外设已启用并完成首次采集。
## TM1637 温湿度轮换显示
PERIPH tm1637_01 DISPLAY ${dht_01.temperature}
DELAY 3000
PERIPH tm1637_01 DISPLAY ${dht_01.humidity}
DELAY 2800配合配置要点：
- 外设配置中
tm1637_01（数码管）与dht_01（DHT11）均需enabled=true - 外设执行规则建议
execMode=1（异步执行），避免阻塞主调度循环 intervalSec应大于脚本内DELAY累计时间 1-2 秒，给任务栈释放留出缓冲
示例 7：数码管状态与亮度联动
夜间自动调暗数码管，清晨恢复默认亮度。
## 进入夜间模式
LOG 进入夜间模式
PERIPH tm1637_01 BRIGHTNESS 1
PERIPH tm1637_01 TEXT NITE
DELAY 2000
PERIPH tm1637_01 DISPLAY ${dht_01.temperature}第三部分：常见问题与故障排除
脚本排障建议先分类：保存失败看语法和长度，规则未触发看触发器和启用状态，变量未替换看输入 JSON 与占位符，动作无效果看目标外设和日志。不要一上来就重写脚本。
规则脚本 FAQ
Q: 为什么我的转换规则没有生效？
检查项：
- 规则是否已启用（enabled=true）
- 触发类型是否正确（0=数据接收，1=数据上报）
- 协议类型是否匹配（确保与实际使用的通信协议一致）
- 脚本内容中的
${key}变量名是否与输入数据中的 key 完全一致（大小写敏感）
Q: 同一协议可以创建多条转换规则吗？
可以创建多条，但同一协议类型 + 同一触发方向只有第一条匹配的已启用规则生效。建议每种协议每个方向只保留一条规则。
Q: 输入的 JSON 解析失败会怎样？
如果输入数据不是有效的 JSON，模板引擎会跳过转换，返回原始数据不做任何修改。系统日志中不会产生错误，数据流不受影响。
Q: ${key} 中的 key 找不到会怎样？
未匹配的占位符保持原样。例如输入中没有 pressure 字段，模板中的 ${pressure} 会保留为字面文本 ${pressure}。
Q: 规则脚本的执行会影响设备性能吗？
影响很小。模板引擎使用简单的字符串替换，不涉及正则表达式或脚本解释器。转换过程在微秒级完成。mutex 锁仅在匹配规则阶段持有，模板替换在无锁状态下执行。
Q: 如何查看规则脚本的转换日志？
在设备日志页面查找 [PeriphExec] Template applied: 前缀的日志。每次成功转换都会记录变量数量和数据大小变化。
命令脚本 FAQ
Q: 脚本保存失败，提示"脚本内容不能为空"
脚本编辑框为空或只有空行/注释。请输入至少一条有效命令。
Q: 脚本保存失败，提示"脚本超过最大长度"
脚本超过 1024 字节。请精简脚本内容，减少注释。
Q: 脚本不执行
检查规则是否已启用。进入规则列表确认启用状态为开。
Q: PERIPH 命令无效果
外设 ID 不匹配。核对外设配置页面中的 ID 是否与脚本中使用的一致。
Q: MQTT 命令无效果
MQTT 未连接或主题索引错误。检查 MQTT 连接状态，确认主题索引对应的发布主题存在。
Q: 数码管不亮或不显示内容
按以下顺序排查：
- 硬件启用：确认
platformio.ini已启用-DFASTBEE_ENABLE_SEVEN_SEGMENT=1，重新编译并烧录固件 - 外设启用：外设配置页面确认数码管条目
enabled=true - 规则启用：外设执行规则确认
enabled=true，并已触发（查看触发次数） - 接线：CLK/DIO 引脚与外设配置的
pins一致，交流 VCC/GND 供电正常 - 亮度：
BRIGHTNESS若设为 0 几乎看不到，试设为 3-5
Q: ${periphId.field} 显示为原文而非值
表示传感器缓存中没有对应键。常见原因：
- 传感器外设（如 DHT11）
enabled=false，从未采集 - 传感器首次采集尚未完成（设备刚启动或定时间隔过长）
- 外设 ID 或字段名拼写错误（大小写敏感）
- 传感器采集失败，缓存未更新，查看日志
[PeriphExec] Update sensor cache确认
Q: 数码管轮换显示规则报告 "insufficient memory"
intervalSec 与脚本 DELAY 累计时间过于接近，异步任务栈来不及释放。解决方法：
- 加大
intervalSec（建议比 DELAY 总和多 2 秒以上） - 关闭其他高频异步规则（如流水灯、BLINK/BREATHE）
- 简化脚本，减少命令条数
调试方法
- 添加 LOG 命令：在关键步骤前后添加
LOG标记执行进度 - 查看设备日志：进入 Web 管理页面的 设备日志，查找
[Script]和[PeriphExec]前缀的日志 - 分段测试：将复杂脚本拆分为小段，逐段验证后再合并
- 检查触发条件：确认规则的触发类型和条件配置正确
附录
GPIO 引脚速查
以下为 ESP32 常用可用引脚（因开发板型号不同可能有差异）：
| 引脚 | 说明 | 脚本可用 |
|---|---|---|
| GPIO 0 | BOOT 按钮，上拉 | 谨慎使用 |
| GPIO 1 | TX0 串口输出 | 不建议 |
| GPIO 2 | 板载 LED（部分开发板） | 可用 |
| GPIO 3 | RX0 串口输入 | 不建议 |
| GPIO 4 | 通用 | 可用 |
| GPIO 5 | 通用 | 可用 |
| GPIO 6-11 | SPI Flash | 禁止使用 |
| GPIO 12-33 | 通用 | 可用 |
| GPIO 34-39 | 仅输入（无内部上拉） | 仅读取，不支持输出 |
配置文件
脚本系统使用两个独立配置文件：
/config/rule_scripts.json— 存储规则脚本（数据转换模板），由RuleScriptManager管理。triggerType字段含义：0: 数据接收（DATA_RECEIVE）1: 数据上报（DATA_REPORT）
/config/periph_exec.json— 存储外设执行规则（含命令脚本动作），由PeriphExecManager管理。triggerType字段含义：0: 平台触发1: 定时触发2: 设备触发
两类规则使用不同的 REST API 命名空间（/api/rule-script* 与 /api/periph-exec*），互不干扰。