Peripheral Execution Management

1. Overview

Peripheral Execution (Periph-Exec) is the automation rule engine of the FastBee system, achieving device linkage by configuring Triggers and Actions. Configuration is stored in /config/periph_exec.json.

Factory default rules are all enabled: false, not auto-executing in unknown wiring environments. After adding or importing rules, save as disabled first, confirm target peripheral, pin and action parameters are correct before enabling.

Rule list is for quick verification of triggers, action count, enabled status and manual execution entry. When adding or editing rules, first confirm target peripheral exists and is in expected enabled state.

The diagram maps "triggers, rules, actions, execution results" in the page to the runtime chain. When configuring in the field, prioritize making each rule name readable, trigger condition single and clear, action sequence rollbackable.

When adding rules, follow the lifecycle diagram: disabled save, validate params, manual execute, enable run, abnormal rollback. This prevents driving field loads immediately after saving in unknown wiring environments.

---

2. Web Interface Operation Guide

2.1 View Rule List

Rule list displays:

Field	Description
Name	Rule display name
Status	Enabled / Disabled
Trigger	Trigger type (Timer, Event, Platform, Poll)
Actions	Action count
Trigger Count	Number of times triggered
Operations	Execute Once / Edit / Enable / Delete

2.2 Add Rule

1. Click + Add Rule button
2. Fill in rule name
3. Select trigger type and configure trigger parameters
4. Add actions (one or more)
5. Save rule

2.3 Edit Rule

1. Find target rule in list
2. Click Edit button
3. Modify trigger or actions
4. Save changes

2.4 Execute Once

1. Find target rule in list
2. Click Execute Once button
3. View execution log

Note: Execute once does not depend on rule enabled status, convenient for debugging.

2.5 Enable/Disable Rule

• Enable: Rule joins scheduler, auto-triggers when conditions met
• Disable: Rule leaves scheduler, no longer auto-triggers

2.6 Delete Rule

1. Find target rule in list
2. Click Delete button
3. Confirm deletion

2.7 Batch Operations

• Batch Enable: Select multiple rules, batch enable
• Batch Disable: Select multiple rules, batch disable
• Import Configuration: Import periph_exec configuration via JSON file
• Export Configuration: Export current configuration to local JSON file

---

3. Trigger Types

3.1 Timer Trigger (TIMER_TRIGGER)

Trigger at fixed intervals.

Configuration Example:

{
  "type": "TIMER_TRIGGER",
  "params": {
    "interval": 60000
  }
}

Parameter	Type	Description
interval	Number	Trigger interval (ms)

3.2 Event Trigger (EVENT_TRIGGER)

Triggered by device events (e.g., GPIO state change, sensor threshold).

Configuration Example:

{
  "type": "EVENT_TRIGGER",
  "params": {
    "peripheralId": "btn_1",
    "event": "change",
    "condition": "value == 1"
  }
}

Parameter	Type	Description
peripheralId	String	Source peripheral ID
event	String	Event type: change, threshold, error
condition	String	Trigger condition expression

3.3 Platform Trigger (PLATFORM_TRIGGER)

Triggered by commands from MQTT platform.

Configuration Example:

{
  "type": "PLATFORM_TRIGGER",
  "params": {
    "topic": "device/cmd/execute",
    "matchField": "ruleId",
    "matchValue": "rule_001"
  }
}

Parameter	Type	Description
topic	String	MQTT subscription topic
matchField	String	JSON field to match
matchValue	String	Expected match value

3.4 Poll Trigger (POLL_TRIGGER)

Poll peripheral readings, trigger when condition met.

Configuration Example:

{
  "type": "POLL_TRIGGER",
  "params": {
    "peripheralId": "dht_temp",
    "field": "temperature",
    "operator": ">",
    "value": 35,
    "interval": 5000
  }
}

Parameter	Type	Description
peripheralId	String	Source peripheral ID
field	String	Data field name
operator	String	Comparison operator: >, <, ==, >=, <=, !=
value	Number	Comparison threshold
interval	Number	Poll interval (ms)

---

4. Action Types

4.1 GPIO Actions

Set Output Level:

{
  "type": "GPIO_ACTION",
  "params": {
    "peripheralId": "relay_1",
    "value": 1
  }
}

4.2 PWM Actions

Set PWM Duty Cycle:

{
  "type": "PWM_ACTION",
  "params": {
    "peripheralId": "pwm_led",
    "duty": 128
  }
}

4.3 Sensor Read Actions

Read Sensor Data:

{
  "type": "SENSOR_ACTION",
  "params": {
    "peripheralId": "dht_temp"
  }
}

4.4 Display Actions

Display Text or Value:

{
  "type": "DISPLAY_ACTION",
  "params": {
    "peripheralId": "oled_ssd1306",
    "text": "Hello FastBee",
    "x": 0,
    "y": 0
  }
}

4.5 Modbus Actions

Read/Write Modbus Registers:

{
  "type": "MODBUS_ACTION",
  "params": {
    "slaveId": 1,
    "function": 3,
    "address": 0,
    "quantity": 10
  }
}

4.6 Script Actions

Execute Rule Script:

{
  "type": "script",
  "params": {
    "code": "var temp = getVar('temperature', 25); if (temp > 35) { gpioWrite('fan_relay', 1); }"
  }
}

4.7 MQTT Publish Actions

Publish Message to MQTT:

{
  "type": "MQTT_ACTION",
  "params": {
    "topic": "device/data/custom",
    "payload": "{\"event\": \"alarm\", \"value\": ${event.data}}"
  }
}

4.8 System Actions

Device Restart / Log Output:

{
  "type": "SYSTEM_ACTION",
  "params": {
    "command": "restart"
  }
}

---

5. Configuration File Format

All execution rules stored in /config/periph_exec.json:

{
  "version": "2.0",
  "rules": [
    {
      "id": "rule_001",
      "name": "Temperature Alarm",
      "enabled": true,
      "trigger": {
        "type": "POLL_TRIGGER",
        "params": {
          "peripheralId": "dht_temp",
          "field": "temperature",
          "operator": ">",
          "value": 35,
          "interval": 5000
        }
      },
      "actions": [
        {
          "type": "GPIO_ACTION",
          "params": {
            "peripheralId": "relay_fan",
            "value": 1
          }
        },
        {
          "type": "MQTT_ACTION",
          "params": {
            "topic": "device/alarm",
            "payload": "{\"type\": \"temp_high\"}"
          }
        }
      ]
    }
  ]
}

---

6. Version Availability

Feature	Lite	Standard	Full
Timer Trigger	✅	✅	✅
Event Trigger	❌	✅	✅
Platform Trigger	❌	✅	✅
Poll Trigger	❌	✅	✅
GPIO/PWM Actions	✅	✅	✅
Sensor Actions	✅	✅	✅
Display Actions	❌	✅	✅
Modbus Actions	❌	✅	✅
Script Actions	❌	✅	✅
MQTT Actions	❌	✅	✅
Import/Export Config	❌	✅	✅

---

7. Troubleshooting

Issue	Possible Cause	Solution
Rule not triggering	Trigger condition not met	Check trigger type and parameters, confirm source peripheral working
Action not executing	Target peripheral disabled	Enable target peripheral
Script execution error	Syntax error	Check script syntax, refer to Rule Script documentation
Modbus action timeout	Communication failure	Check Modbus wiring, baud rate, slave address
Rule execution too slow	Too many actions	Reduce action count, use async execution
Trigger count not increasing	Scheduler not running	Confirm at least one rule enabled
Import config failed	JSON format error	Check JSON syntax, ensure field types correct
MQTT action not sending	MQTT not connected	Check MQTT connection status

---

8. Related Documentation

• Peripheral Configuration - Peripheral hardware configuration
• Rule Script - Script syntax and built-in functions
• Protocol Configuration - MQTT and Modbus protocol settings