MudPi periodically gathers readings to emit on the system. This is very useful to monitor the system but you may wonder how to then use this data to invoke a response. This is where Triggers are useful.
A trigger is a set of conditions with thresholds that take system readings and activates if the threshold(s) have been met. An active trigger on its own is not very useful, but paired with actions it becomes a very powerful feature of MudPi.
There are currently several supported trigger interfaces in the system. There are sensor, control, state, toggle, group and cron triggers available. All triggers respond to events and will use the event data during its threshold checks. Some triggers react based on component state where others are tracking time change. Using combinations of triggers can lead to some awesome possibilities.
A sensor trigger listens for a sensor event. When a sensor event occurs the trigger looks for data identified by a source key and evaluates the sensor reading against the set threshold.
A control trigger listens for a control event. When a control event occurs the trigger looks for data identified by a source key and evaluates the control reading against the set threshold.
A state trigger listens for a state event. When a StateUpdated event occurs the trigger looks for data identified by a source key and evaluates the control reading against the set threshold.
The cron trigger is used for schedule based triggering and different from the other triggers because it does not take thresholds. Instead it takes a schedule property, which is a cron-like string, that it checks every minute to see if the trigger should activate. Check out this crontab tool to help you create cron string schedules. Keep in mind most cron syntax is supported but not everything.
A toggle trigger listens for a toggle event. When a toggle is updated this event occurs and the trigger looks for data identified by a source key and evaluates the control reading against the set threshold.
Triggers activate in one of two ways depending on the trigger. The triggers will look for data in an event based on the source key you set. It then will then use thresholds to check if the data received meets the set criteria and activate the trigger accordingly. A cron trigger is a bit different in that it checks every minute to determine if it should activate based on a cron schedule string. The cron triggers are really useful in making schedules for MudPi.
An active trigger can behave in one of two ways based on the frequency configuration option. When a trigger with a frequency of once activates it will fire all it's linked actions only one time. It then waits to reset by checking the thresholds until they are False. Once reset it will then be ready to fire again.
A trigger with a frequency of many will also fire all its actions once triggered but it will not wait to reset before activating again. Instead it will continue to fire while the threshold is met each time without the need to reset.
Thresholds are a set of conditions that a trigger uses to evaluate event data with. Thresholds are used in both control and sensor trigger types. A threshold has two properties, a comparison and a value. The comparison property is an operator used to check against the source value and return True or False if the threshold has been met. Below is a list of available comparison options and how the threshold gets evaluated.
| Comparison | Operator | Example |
| eq | == | value == threshold_value |
| ne | != | value != threshold_value |
| gt | > | value > threshold_value |
| gte | >= | value >= threshold_value |
| lt | < | value < threshold_value |
| lte | <= | value <= threshold_value |
| ex | is not None | value is not None |
| is | is | value is threshold_value |
| not | is not | value is not threshold_value |
| in | in | value in threshold_value |
Threshold configurations are passed through a thresholds array on your trigger configuration. Below are the available options for threshold configuration. If you want to cast the value to a specific type you can do so through the type option. This is useful if your data source is providing a string format and you want it to be treated as an integer.
| Option | Type | Required | Description |
| comparison | [String] | Yes | The type of comparison to check the triggered value against. Options: eq, ne, gt, gte, lt, lte, ex, is, not, in |
| value | [String], [Boolean] or [Integer] | Yes | The value to perform the comparison against. Can be cast using the type option. |
| type | [String] | No | Variable type to explicitly cast the value to. Options: int, float, str, datetime, list, dict, json. Default: None |
| format | [String] | No | The format to cast into datetime when datetime. Default: %I:%M %p. See python datetime for all formatting options. |
| source_type | [String] | No | The type to cast the source value to. Options: int, float, str, datetime, list, dict, json. Default: None |
| source_format | [String] | No | The format to cast into datetime when datetime. Default: %I:%M %p. See python datetime for all formatting options. |
Here is a config for a threshold that checks if {triggered value} >= 25
"trigger": [{
...
"thresholds": [
{
"comparison": "gte",
"value": 25,
}
]
}]
Here is a config for a threshold that converts the value to a datetime and checks if its before a certain time. The python datetime comparsion looks like {triggered value} < 11:05 PM
"trigger": [{
...
"thresholds": [
{
"comparison": "lt",
"value": "11:05 PM",
"type": "datetime",
"format": "%I:%M %p"
}
]
}]
Individual Triggers can be very useful to toggle components in the system. However there may be situations where a combination of triggers would be more ideal. For example a watering schedule could be combined with a soil sensor to only water on the days the soils was dry. This situation is possible using a trigger group with a cron and sensor trigger. Trigger groups will only activate if all triggers in the group are active. Triggers can be apart of multiple groups and also still have independent behavior.
You can read more about group triggers in the group extension.