Peripheral Execution Documentation
Overview: The Peripheral Execution module is a rule engine that implements "execute actions when conditions are met", using a trigger-action model. It supports 4 trigger types (Platform/Timer/Event/Poll) and 27 action types (GPIO/PWM/Sensor/Display/System etc.). Rules execute asynchronously with a Worker pool pre-created with 3 tasks and a minimum heap memory gate of 30KB. Configuration is stored in
/config/periph_exec.json.
All factory rules are disabled to avoid driving unknown wiring. After importing or creating a rule, verify the target peripheral and pins before enabling it; the UI and API validate actions against the target device's runtime capabilities.
This directory contains modular detailed documentation for the peripheral execution rule system, organized by triggers, actions, and complete scenarios.
| Name | Status | Trigger | Target Peripheral | Action | Statistics | Operations |
|---|---|---|---|---|---|---|
| ADC Voltage Collection Report | Disabled | Timer Trigger | ADC Analog Conversion | Sensor Data Read -> ADC Analog Conversion | Trigger Count: 1 | Execute Once / Edit / Enable / Delete |
| ADC Voltage Below 2.30V Close Relay | Disabled | Event Trigger | - | Set Low Level | Trigger Count: 1 | Execute Once / Edit / Enable / Delete |
| ADC Voltage Above 2.50V Open Relay | Disabled | Event Trigger | - | Set High Level | Trigger Count: 1 | Execute Once / Edit / Enable / Delete |
| ADC Voltage Display on Digital Tube | Disabled | Timer Trigger | - | Display Number | Trigger Count: 1 | Execute Once / Edit / Enable / Delete |
| NTP Time Sync | Disabled | Platform Trigger (MQTT) | - | NTP Sync | Trigger Count: 1 | Execute Once / Edit / Enable / Delete |
| OLED Temp/Humidity Display | Disabled | Timer Trigger | - | OLED Custom Display | Trigger Count: 1 | Execute Once / Edit / Enable / Delete |
| OLED Custom Display - Button Trigger Device Info | Disabled | Event Trigger | - | OLED Custom Display | Trigger Count: 1 | Execute Once / Edit / Enable / Delete |
| OLED Custom Display - Timer Mixed | Disabled | Timer Trigger | - | OLED Custom Display | Trigger Count: 1 | Execute Once / Edit / Enable / Delete |
| OLED Custom Display - MQTT Message | Disabled | Platform Trigger (MQTT) | - | OLED Custom Display | Trigger Count: 1 | Execute Once / Edit / Enable / Delete |
| OTA Upgrade | Disabled | Platform Trigger (MQTT) | - | OTA Upgrade | Trigger Count: 1 | Execute Once / Edit / Enable / Delete |
The rule list is used to confirm the enable status, number of triggers, number of actions, and manual execution entry for each rule. During initial on-site deployment, it is recommended to verify each rule one by one before turning on "Enable".
| Trigger | Input Source | Check Timing | Suitable Scenarios | Common Risks |
|---|---|---|---|---|
| Platform Trigger | MQTT platform command | Match fields immediately upon message arrival | Remote on/off, parameter delivery, linkage control | Inconsistent field names, duplicate messageId, insufficient permissions |
| Timer Trigger | Local clock / cron / interval | Execute when time point is reached | Periodic reporting, scheduled on/off, night mode | NTP not synced, first trigger semantics unclear |
| Event Trigger | Button, sensor, system events | Match eventId when event is published | Button control, threshold alarm, state change | Debouncing, event name spelling, cached value expiry |
| Poll Trigger | Actively read peripheral or protocol data | Check conditions every pollInterval | Modbus collection, analog threshold, distance alarm | Too frequent, serial port busy, low memory frequency reduction |
The two diagrams above are best reviewed first: the data model explains what fields a rule consists of, and the timing comparison explains when to choose platform, timer, event, or poll triggers.
Documentation Index
Trigger Documentation
| Document | triggerType | Description |
|---|---|---|
| platform-trigger.md | 0 | Platform trigger (MQTT/Modbus command delivery) |
| timer-trigger.md | 1 | Timer trigger (interval/daily time point) |
| event-trigger.md | 4 | Event trigger (system/button/data/peripheral events) |
| poll-trigger.md | 5 | Poll trigger (local data source condition evaluation) |
Action Documentation
| Document | actionType | Description |
|---|---|---|
| gpio-actions.md | 0,1,13,14 | GPIO output (high/low/inverted) |
| pwm-actions.md | 2,3,4,5 | PWM/breathing light/DAC |
| system-actions.md | 6,7,8,9 | System restart/factory reset/NTP/OTA |
| modbus-actions.md | 16,17,18 | Modbus coil/register/poll |
| sensor-actions.md | 19 | Sensor data reading |
| display-actions.md | 24,25,26,27 | Digital tube/OLED display |
| event-actions.md | 21,22,23 | Trigger event/rule control |
| script-actions.md | 10,15 | Call peripheral/command script |
Complete Scenario Documentation
| Document | Scenario | Modules Involved |
|---|---|---|
| temperature-alarm.md | DHT temperature control + relay linkage | DHT11/22 + Relay |
| smoke-alarm.md | Smoke alarm + buzzer | MQ-2 + Buzzer + MQTT |
| light-control.md | Photosensitive auto light control | Photosensitive ADC + LED/Relay |
| button-control.md | Button multi-mode control | Button + Multi-action |
| modbus-monitor.md | Modbus device monitoring | Modbus sub-device + Alarm |
| ultrasonic-alarm.md | Ultrasonic distance alarm | HC-SR04 + Buzzer |
Quick Start
Rule Structure
json
{
"id": "exec_<timestamp>",
"name": "Rule Name",
"enabled": true,
"execMode": 0,
"triggers": [ /* Trigger array, OR relationship */ ],
"actions": [ /* Action array, sequential execution */ ],
"reportAfterExec": true
}Trigger Type Quick Reference
| triggerType | Name | Typical Use |
|---|---|---|
| 0 | Platform Trigger | IoT platform MQTT command matching |
| 1 | Timer Trigger | Periodic collection, scheduled control |
| 4 | Event Trigger | WiFi/MQTT/button/sensor data events |
| 5 | Poll Trigger | Modbus sensor periodic data condition evaluation |
Action Type Quick Reference
| actionType | Name | Parameter Description |
|---|---|---|
| 0 | High Level | targetPeriphId=GPIO peripheral ID |
| 1 | Low Level | targetPeriphId=GPIO peripheral ID |
| 2 | Flash | actionValue=interval ms |
| 3 | Breathing Light | actionValue=cycle ms |
| 4 | Set PWM | actionValue=duty cycle value |
| 5 | Set DAC | actionValue=0~255 |
| 6 | System Restart | No parameters |
| 7 | Factory Reset | No parameters |
| 8 | NTP Sync | No parameters |
| 9 | OTA Upgrade | actionValue=URL |
| 10 | Call Peripheral | targetPeriphId=target peripheral |
| 13 | High Level (Inverted) | Physical output low level |
| 14 | Low Level (Inverted) | Physical output high level |
| 15 | Command Script | actionValue=script content |
| 16 | Modbus Coil | FC05 |
| 17 | Modbus Register | FC06 |
| 18 | Modbus Poll | Collect sub-device data |
| 19 | Sensor Read | Collect temperature/humidity/distance/current/voltage |
| 21 | Trigger Event | actionValue=event ID |
| 22 | Enable Rule | targetPeriphId=rule ID |
| 23 | Disable Rule | targetPeriphId=rule ID |
| 24 | Display Number | actionValue="12.34" |
| 25 | Display Text | actionValue="PLAY" |
| 26 | Clear Screen | No parameters |
| 27 | OLED Display | actionValue=multi-line template |
Condition Operators
| operatorType | Name | Description |
|---|---|---|
| 0 | Equal (EQ) | value == compareValue |
| 1 | Not Equal (NEQ) | value != compareValue |
| 2 | Greater Than (GT) | value > compareValue |
| 3 | Less Than (LT) | value < compareValue |
| 4 | Greater Than or Equal (GTE) | value >= compareValue |
| 5 | Less Than or Equal (LTE) | value <= compareValue |
| 6 | Between (BETWEEN) | compareValue="min,max" |
| 7 | Not Between (NOT_BETWEEN) | compareValue="min,max" |
| 8 | Contains (CONTAIN) | String contains |
| 9 | Not Contains (NOT_CONTAIN) | String does not contain |