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.
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.
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 | |
SequenceStarted | Emitted when the sequence starts. |
SequenceStopped | Emitted the the sequence is stopped/canceled. |
SequenceEnded | Emitted the the sequence has ended by completing all the steps. |
SequenceStepStarted | Emitted at the start of each step. Contains event data with current step of sequence. |
SequenceStepEnded | Emitted at the end of each step. Contains event data with current step of sequence that is ending. |
SequenceUpdated | Emitted when the sequence is updated. Contains event data with current status of sequence. |
SequenceRestarted | Emitted when the sequence is restarted. |
SequenceReset | Emitted when the sequence is reset to the start. |
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.
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:
| Action | Description |
start | Starts the sequence if it is not active. If the sequence is already active then it does nothing |
stop | Will immediately stop the sequence and reset it |
next_step | Attempts to advance the sequence to next step non-forcefully. If the duration is not complete is does not advance. |
previous_step | Moves the sequence one step back. If its already on the first step it resets it. |
skip_step | Immediately skips to the next step. If actions have not been triggered yet it will attempt to trigger them. |
reset_step | Resets the sequence to the beginning of the step without changing the active state |
reset | Resets the sequence to the beginning without changing the active state |
restart | Restarts the sequence to the beginning and starts it if its not started |
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.
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.
| Event | Sequence Response |
SequenceStart | starts the sequence if it is not active. If the sequence is already active then it does nothing |
SequenceStop | will immediately stop the sequence and reset it |
SequenceSkipStep | immediately skips to the next step. If actions have not been triggered yet it will attempt to trigger them. |
SequenceNextStep | flags 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. |
SequencePreviousStep | will immediately push the sequence back to the begging of the previous step. |
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.
| Comparison | Operator | Example |
| eq | == | value == source_value |
| ne | != | value != source_value |
| gt | > | value > source_value |
| gte | >= | value >= source_value |
| lt | < | value < source_value |
| lte | <= | value <= source_value |
| ex | is not None | value is not None |
Here are the available settings for the sequence:
| Option | Type | Required | Description |
| key | [String] | Yes | A unique slug to identify the trigger. Name will be slugged if key not set. |
| name | [String] | No | Friendly display name of the sequence. Useful for UI mainly. |
| topic | [String] | No | The channel the sequence listens on and broadcasts events too. Defaults to sequence/{key} |
| sequence | [Array] | No | List of sequence steps to be triggered. |
The sequence can contain one or many steps and below are the available settings for a step inside the sequence list.
| Option | Type | Required | Description |
| actions | [Array] | Yes | List of actions to be triggered. |
| delay | [Integer] | No | Number of seconds to wait before triggering actions. |
| duration | [Integer] | No | Number of seconds to wait after triggering actions. |
| thresholds | [Array] | No | List of thresholds to evaluate before triggering actions. |
Thresholds are conditions to check trigger values against and determine if the trigger should fire. Here are the threshold configuration options below.
| Option | Type | Required | Description |
| comparison | [String] | Yes | Comparison to run against value. Options: eq, ne, gt, gte, lt, lte or ex |
| value | [Integer] | Yes | Value to run comparison against source. |
| source | [String] | Yes | Redis key to get Value to run comparison against value. |
| nested_source | [String] | No | If source contains a dict then the nested_source is used as the key to find the value from that dict. |
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.