Deep Dive: Rules and Actions
Rules and Actions
This page is under construction! I'm working on it :)
Rules let you automate responses to your IoT data. When conditions are met, actions are triggered automatically.
The flow: Payload arrives → Rules evaluated → Conditions checked → Actions triggered
How Rules Work
A rule has:
- Conditions - What must be true (all must be met)
- Actions - What happens when conditions are met
- Enabled - On/off switch
When a payload arrives, every enabled rule is evaluated. If all conditions pass, all linked actions execute.
Creating Actions
Actions are reusable - create them once, use them in multiple rules.
Device Command
Sends a command to your device. The device receives it on the next `sendPayload()` call.
- Name - Friendly name (e.g., "Turn Heater On")
- Schema - Which device type receives this command
- Command - Command name your device listens for
- Arguments - Optional key-value data
Example: Heater Control
1 | |
Your Arduino code receives this:
1 | |
Example: Pump with Duration
1 | |
Your code can use the argument:
1 | |
Webhook
Makes an HTTP request to an external URL.
- Name - Friendly name
- URL - The endpoint to call
- Method - GET, POST, PUT, PATCH, or DELETE
- Headers - Optional headers (e.g., Authorization)
- Body - Optional request body (for POST/PUT)
Example: Slack Notification
1 | |
Example: Home Assistant Integration
1 | |
Sends an email notification.
- Name - Friendly name
- To - Recipient email address
- Subject - Email subject line
- Body - Email body text
Example:
1 | |
Cooldown Period
Prevents an action from firing too often. Set a minimum time between executions.
1 | |
If the rule triggers again within 5 minutes, the action won't execute.
Use cases:
- Prevent email spam (set 1h cooldown)
- Avoid rapid on/off cycling of hardware (set 30s cooldown)
- Rate-limit webhook calls (set 1m cooldown)
Format: `30s`, `5m`, `1h`, `24h`
Creating Rules
Conditions
Each condition checks a field value. All conditions must be true (AND logic).
- Schema - Which schema to check
- Field - Which field to evaluate
- Time Bucket - Time window for aggregation
- Aggregation - How to combine values
- Comparisons - The actual checks
Time Buckets
How far back to look:
- `last_record` - Just the most recent payload
- `1m` - Last 1 minute of data
- `5m` - Last 5 minutes
- `10m` - Last 10 minutes
- `30m` - Last 30 minutes
- `1h` - Last 1 hour
Aggregations
How to combine multiple values in the time window:
- `last` - Most recent value (all types)
- `avg` - Average (numbers only)
- `sum` - Total (numbers only)
- `min` - Minimum (numbers only)
- `max` - Maximum (numbers only)
- `count` - Number of records (all types)
- `all` - Every value must match (all types)
- `none` - No value must match (all types)
`last_record` time bucket requires `last` aggregation.
Comparison Types
- `isEqualTo` - Equals (all types)
- `isNotEqualTo` - Not equals (all types)
- `isGreaterThan` - Greater than (numbers)
- `isLessThan` - Less than (numbers)
- `isGreaterThanOrEqualTo` - >= (numbers)
- `isLessThanOrEqualTo` - <= (numbers)
Example Rules
Heating Controller
Turn heater on when cold:
1 | |
Turn heater off when warm:
1 | |
Plant Watering
Water when soil is dry:
1 | |
Temperature Alert
Email when too hot:
1 | |
Why Check State Before Toggling?
In the heating example, we check `heater_on == false` before turning on. Why?
Without this check:
- Temperature drops to 17°C
- Rule triggers → heater_on command sent
- Next payload: still 17°C (heater just started)
- Rule triggers again → another heater_on command
- Repeat every payload...
Your device would receive the same command over and over.
With the state check:
- Temperature drops to 17°C, heater_on is false
- Rule triggers → heater_on command sent
- Device turns heater on, reports heater_on = true
- Next payload: 17°C but heater_on is true
- Condition fails (heater already on) → no command
This prevents command spam and makes debugging easier.
Enabling and Disabling Rules
Toggle rules on/off without deleting them:
- Enabled - Rule is evaluated on every payload
- Disabled - Rule is ignored (useful for testing or temporary suspension)
Debugging Rules
Use the Live Debug panel to see rule evaluation in real-time:
1 | |
Tips
Start with Manual Testing
Use Dashboard Action Buttons to manually trigger actions. Verify they work before creating rules.
Use Meaningful Cooldowns
- Device commands: 10s-60s (prevents rapid cycling)
- Emails: 1h+ (prevents inbox flooding)
- Webhooks: Depends on your rate limits
Keep Conditions Simple
More conditions = harder to debug. If a rule isn't firing, check each condition individually in Live Debug.
Name Things Clearly
"Turn Heater On When Cold" is better than "Rule 1". Your future self will thank you.
Test Edge Cases
What happens when: device sends bad data? Sensor reads extreme values? Multiple rules conflict?
Next Steps
- Dashboards - Visualise your data and actions
- Debugging - Troubleshoot when things go wrong