Triggers

MudPi periodically gathers sensor and control 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 Types

There are currently three supported trigger types in the system. There are sensor, control and time triggers. The sensor and control triggers listen for an event emitted by sensors and controls respectively. Whereas a time trigger uses a schedule format to activate on a time based manner.

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.

Time Trigger

The time 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.

Trigger Activation

Triggers activate in one of two ways depending on the trigger type. The event based triggers, sensor and control types, will look for data in an event based on the source key you set. The trigger will then use thresholds to check if the data received meets the set criteria and activate the trigger accordingly. A time trigger type is a bit different in that it checks every minute to determine if it should activate based on a cron schedule string. The time 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

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 time and sensor trigger. Trigger groups will only activate if all triggers in the group are active.