Triggers

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.

Trigger Interfaces

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.

Sensor Trigger

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.

Control Trigger

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.

State Trigger

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.

Cron Trigger

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.

Toggle Trigger

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.

Trigger Activation

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.

Activation Frequency

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

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.

ComparisonOperatorExample
eq==value == threshold_value
ne!=value != threshold_value
gt>value > threshold_value
gte>=value >= threshold_value
lt<value < threshold_value
lte<=value <= threshold_value
exis not Nonevalue is not None

Trigger Groups

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.