Automation Sequences

MudPi can use actions with triggers to perform a large variety of automations. However in some cases actions and triggers alone are not enough to solve every situation. Automation Sequences build on actions by allowing you to create a list of steps that contain actions to trigger with a duration in between each step once the actions have been triggered. As you may imagine this opens up the possibility to a variety of complex combinations to make some very useful automations.

Along with the duration and delay option is also available that causes the step to pause for the set number of seconds before triggering the actions. The duration option is used to set the number of seconds after the step is triggered before it should advance to the next step.

In addition to the ability to have a delay between steps and duration after steps, you can also use thresholds to determine whether or not a step should even trigger actions. Thresholds are a set of conditions that take system readings and activate if the threshold(s) have been met.

Sequence Lifecycle

A sequence starts by being activated via a trigger or event. The first step is toggled and it checks to see if a delay is set. The step will wait the duration of the delay seconds before triggering the actions that are set. While the step is waiting the delay and duration it still listens for events in the background in case a step needs to be interrupted quickly.

Once the step is ready to trigger actions it will check if any thresholds are set. If they are it will check them to see if the step activate or if it should skip to the next step without waiting the duration.

After the actions phase a step will wait the duration seconds if one is set. A step is flagged completed once the duration wait is completed. If no duration is set the step waits indefinitely for this signal from a trigger or event in order to be flagged complete and advance to the next step.

Sequence Activation

Sequences activate is one of two ways depending on how you wish to use them. Sequences can be configured in triggers using the sequences option. Once the trigger is active is will activate the sequence just like does for actions. The other way to interact with a sequence is by passing events to it on its topic.

Activation with Triggers

To activate a sequence with a trigger you can do so by adding the sequence key to the triggers sequences option. The configuration below is an example of a time trigger that will activate a sequence with a key of example_sequence every 2 minutes.

{
    "type": "time",
    "key": "activate_every_2_mins",
    "name": "Trigger Sequence Every 2 Mins",
    "schedule": "*/2 * * * *",
    "sequences": ["example_sequence"]
},

Once the trigger activates if the sequence is not active it will start. If the sequence is already active it will be signaled to advance to the next step only if the current step is already completed.

In the event a sequence is already active, the current step has a duration and the trigger sends a signal then the sequence will ignore this signal.

Activation with Events

The other way to interact with the Sequence is through events. The sequence will emit events during each step and it also listens for events as well. The sequence will listen for SequenceStart, SequenceStop, SequenceSkipStep, SequenceNextStep and SequencePreviousStep.

EventSequence Response
SequenceStartstarts the sequence if it is not active. If the sequence is already active then it does nothing
SequenceStopwill immediately stop the sequence and reset it
SequenceSkipStepimmediately skips to the next step. If actions have not been triggered yet it will attempt to trigger them.
SequenceNextStepflags the sequence current step as complete if the sequence is active and the delay is complete. If the sequence is not active it will do nothing.
SequencePreviousStepwill immediately push the sequence back to the begging of the previous step.

Sequence Events

The sequence will emit events during each step while it active on its set topic. The sequence will emit events SequenceStarted, SequenceStoped, SequenceEnded, SequenceStepStarted and SequenceStepEnded.

Event
SequenceStartedEmitted when the sequence starts.
SequenceStopedEmitted the the sequence is stopped/canceled.
SequenceEndedEmitted the the sequence has ended by completing all the steps.
SequenceStepStartedEmitted at the start of each step. Contains event data with current step of sequence.
SequenceStepEndedEmitted at the end of each step. Contains event data with current step of sequence that is ending.

Step Thresholds

Thresholds are a set of conditions that a sequence uses to evaluate if it should activate the current step. Thresholds are optional and if not evaluated to True then the step will advance without waiting the duration.

A threshold has three properties, a comparison, value and source. If the source is a dict then you can also add the nested_source option to specify the key of the dict to get the value from for the threshold.

The comparison property is an operator used to check between the source and value then returns 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 == source_value
ne!=value != source_value
gt>value > source_value
gte>=value >= source_value
lt<value < source_value
lte<=value <= source_value

You can read more about configuring automation sequences in the sequences configuration section.