Documentation

Sequence Extension

Automation sequences allow you to create multi-step action chains with delays, durations, and thresholds.

Overview

MudPi can use actions with triggers to perform a large variety of automations. However, actions and triggers alone are not enough for every situation. Automation Sequences build on actions by allowing you to create a list of steps that contain actions to trigger with a duration between each step.

Each step also supports a delay option that pauses before triggering actions, while the duration sets the wait time after actions are triggered before advancing to the next step. You can also use thresholds to conditionally determine whether a step should trigger its actions.

Sequence Lifecycle

A sequence starts when activated via a trigger or event. The first step checks for a delay, waits if set, then evaluates any thresholds. If thresholds pass, the step's actions fire. The step then waits for the duration before advancing. If no duration is set, the step waits indefinitely for a signal to advance.

Sequence Events

The sequence emits events during each step on its configured topic:

Event	Description
`SequenceStarted`	Emitted when the sequence starts
`SequenceStopped`	Emitted when the sequence is stopped or canceled
`SequenceEnded`	Emitted when all steps have completed
`SequenceStepStarted`	Emitted at the start of each step with current step data
`SequenceStepEnded`	Emitted at the end of each step
`SequenceUpdated`	Emitted when the sequence status is updated
`SequenceRestarted`	Emitted when the sequence is restarted
`SequenceReset`	Emitted when the sequence is reset to the start

Actions

Sequences provide actions to interact with them programmatically:

Action	Description
`start`	Starts the sequence if not already active
`stop`	Immediately stops and resets the sequence
`next_step`	Advances to the next step if the current step's duration is complete
`previous_step`	Moves back one step; resets if on the first step
`skip_step`	Immediately skips to the next step, triggering actions if not yet fired
`reset_step`	Resets the current step without changing the active state
`reset`	Resets the sequence to the beginning without changing the active state
`restart`	Restarts the sequence from the beginning and starts it if not active

Activation with Events

Sequences also listen for events to control them:

Event	Sequence Response
`SequenceStart`	Starts the sequence if not active
`SequenceStop`	Immediately stops and resets the sequence
`SequenceSkipStep`	Skips to the next step immediately
`SequenceNextStep`	Flags the current step as complete if delay is done
`SequencePreviousStep`	Pushes the sequence back to the previous step

Step Thresholds

Thresholds are conditions that a sequence evaluates to decide if a step should activate. If thresholds are not met, the step advances without waiting the duration.

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

Settings

Available settings for the sequence:

Option	Type	Required	Description
`key`	String	Yes	Unique slug identifier for the sequence
`name`	String	No	Friendly display name for the sequence
`topic`	String	No	Channel the sequence listens on and broadcasts to. Default: `sequence/{key}`
`sequence`	Array	No	List of sequence steps to be triggered

Step Settings

Each step inside the sequence array supports these options:

Option	Type	Required	Description
`actions`	Array	Yes	List of actions to trigger
`delay`	Integer	No	Seconds to wait before triggering actions
`duration`	Integer	No	Seconds to wait after triggering actions
`thresholds`	Array	No	List of thresholds to evaluate before triggering actions

Threshold Configuration

Option	Type	Required	Description
`comparison`	String	Yes	Comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, or `ex`
`value`	Integer	Yes	Value to compare against the source
`source`	String	Yes	Redis key to get the value for comparison
`nested_source`	String	No	Key to extract from the source if it contains a dict

Configuration Example

mudpi.config.json

{
  "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_3.turn_off", ".valve_4.turn_on"]
        },
        {
          "actions": [".valve_4.turn_off"],
          "duration": 0
        }
      ]
    }
  ]
}

Click to expand code…

Tip

Activate a sequence from a trigger by adding the sequence key to the trigger's actions, e.g. .example_sequence.next_step. You can also use cron triggers to run sequences on a schedule.

Previous ← RTSP Extension Next Socket Extension →