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 Events

The sequence will emit events during each step while it active on its set topic. These events can be useful to hook into if you want to interact with automation sequence updates.

Event
SequenceStartedEmitted when the sequence starts.
SequenceStoppedEmitted 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.
SequenceUpdatedEmitted when the sequence is updated. Contains event data with current status of sequence.
SequenceRestartedEmitted when the sequence is restarted.
SequenceResetEmitted when the sequence is reset to the start.

Interacting With Sequences

Sequences activate in a few ways depending on how you wish to use them. Sequences can be configured in triggers using the sequence actions in the actions option. Once the trigger is active is will call the actions on the automation sequence. Another way to interact with a sequence is through events on its topic.

Actions

Like many other components in MudPi sequences also provide actions in order to interact with them. Actions are the main way to interact with most components in MudPi. Here are some of the available actions for automation sequences:

ActionDescription
startStarts the sequence if it is not active. If the sequence is already active then it does nothing
stopWill immediately stop the sequence and reset it
next_stepAttempts to advance the sequence to next step non-forcefully. If the duration is not complete is does not advance.
previous_stepMoves the sequence one step back. If its already on the first step it resets it.
skip_stepImmediately skips to the next step. If actions have not been triggered yet it will attempt to trigger them.
reset_stepResets the sequence to the beginning of the step without changing the active state
resetResets the sequence to the beginning without changing the active state
restartRestarts the sequence to the beginning and starts it if its not started

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.

{
    "key": "activate_every_2_mins",
    "interface": "cron",
    "name": "Trigger Sequence Every 2 Mins",
    "schedule": "*/2 * * * *",
    "actions": [".example_sequence.next_step"]
},

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.

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
exis not Nonevalue is not None

Settings

Here are the available settings for the sequence:

OptionTypeRequiredDescription
key[String]YesA unique slug to identify the trigger. Name will be slugged if key not set.
name[String]NoFriendly display name of the sequence. Useful for UI mainly.
topic[String]NoThe channel the sequence listens on and broadcasts events too. Defaults to sequence/{key}
sequence[Array]NoList of sequence steps to be triggered.

Sequence Step Settings

The sequence can contain one or many steps and below are the available settings for a step inside the sequence list.

OptionTypeRequiredDescription
actions[Array]YesList of actions to be triggered.
delay[Integer]NoNumber of seconds to wait before triggering actions.
duration[Integer]NoNumber of seconds to wait after triggering actions.
thresholds[Array]NoList of thresholds to evaluate before triggering actions.

Step Thresholds

Thresholds are conditions to check trigger values against and determine if the trigger should fire. Here are the threshold configuration options below.

OptionTypeRequiredDescription
comparison[String]YesComparison to run against value. Options: eq, ne, gt, gte, lt, lte or ex
value[Integer]YesValue to run comparison against source.
source[String]YesRedis key to get Value to run comparison against value.
nested_source[String]NoIf source contains a dict then the nested_source is used as the key to find the value from that dict.

Configuration

An automation sequence contains a list of actions to be performed in order with a duration in between each step. The duration is in in seconds. If no duration is provided the step will wait indefinitely for another update. This update can come from the next_step action or when a SequenceNextStep event is received. Sequences help build on basic actions and allow your to build complex automations with MudPi. You can read more about the concepts of automation here.

Below is an example of a automation sequence configuration.

"sequence": [
    {
    "name":"Example Watering Sequence",
    "key": "example_sequence",
    "sequence": [
        {
            "actions": [".pump.turn_on", ".valve_1.turn_on"],
            "duration": 10
        },
        {
            "actions": [".valve_1.turn_off", ".valve_2.turn_on"],
            "duration": 10
        },
        {
            "actions": [".valve_2.turn_off", ".valve_3.turn_on"],
            "duration": 10,
            "thresholds": [
                {
                    "source": "soil_sensor_1",
                    "comparison":"lte",
                    "value":70
                }
            ]
        },
        {
            "actions": [".valve_2.turn_off", ".valve_3.turn_off, ".valve_4.turn_on"]
        },
        {
            "actions": [".valve_4.turn_off"],
            "duration": 0
        }
    ] }
]

The configuration above will create an action sequence that has 5 steps. Each step has a list of actions that it performs. If a delay is set then the actions performed after the delay is complete. Once the actions are performed then if a duration is set the sequence will wait until the duration is complete and then proceed to the next step.