Triggers

Triggers are user-configured conditions that cause a Sequence to change state. For instance, you might create a trigger to start a sequence when an Button is pressed.

Each sequence can have multiple triggers associated with it. Sequences are one of the most common methods of making your script respond to external stimuli. There's a variety of trigger types, such as I/O, variable, complex expressions, and date/time, and more.

Adding Triggers

You can add a new trigger to a sequence by clicking in the "Triggers" column of the Sequences window, or clicking the "Triggers" button in the menu bar. When you do so, the Triggers dialog for that sequence will appear.

From here, you can click the "+" button to add a new trigger. Then, choose the action to occur when the trigger fires, and the condition to make it fire.

For our example, we're going to choose the "Play" action from the first dropdown box, and the "when an I/O changes" condition from the second. Finally, we'll choose "Button1" from the Input/Output selection below.

Note

If you're scripting with a device that doesn't have front panel buttons, you'll see a different set of resources. The idea is the same whether it's a discrete input, or a push button trigger.

Click OK, and you'll see this sequence now has a trigger associated with it.

Pushing front panel button 1 now starts the "Default" sequence.

Trigger Actions

Logical Sequences and Timed Sequences running on internal timecode have the following action options:

Play

A play action causes a sequence to begin executing on the next frame. It is functionally equivalent to using the "Play" event on a sequence.

Loop

A loop action causes a sequence to begin executing on the next frame, and then restart when it finishes, continuously repeating until it is stopped. It is functionally equivalent to using the "Loop" event on a sequence.

Stop

A stop action causes a sequence to stop execution on the next frame. It is functionally equivalent to using the "Stop" event on a sequence.

Pause

A pause action causes a sequence to pause execution on the next frame. It is functionally equivalent to using the "Pause" event on a sequence.

Stop Looping

A Stop Looping action causes a sequence to leave the "Loop" state on the next frame. The sequence will continue playing, but will not restart when it reaches the end. It is functionally equivalent to using the "Set Loop" event with a 'false' parameter.

SMPTE LTC Trigger Actions

If the sequence is a Timed Sequence that is set to follow SMPTE LTC, you have two action options:

Arm

The Arm action sets the status of a sequence tracking SMPTE LTC timecode to the 'armed' state. In the 'armed' state, the sequence will be watching the LTC input and will chase timecode. It is functionally equivalent to using the "Arm" event on a sequence.

Disarm

The Disarm action sets the status of a sequence tracking SMPTE LTC timecode to the 'disarmed' state. In the 'disarmed' state, the sequence will ignore incoming timecode and not execute. It is functionally equivalent to using the "Disarm" event on a sequence.

Trigger Conditions

Within the Triggers dialog, the conditions that cause a trigger to fire are described in plain English, in such a way that reading the configuration will describe the trigger. For instance, "Play the sequence on power-up". The following options are available:

when an I/O changes

This trigger condition fires the trigger action when a single button, discrete input, or discrete output changes state. Additionally, you can specify either "Active On", or "Active Off".

For "Active On", the trigger will fire on the rising edge of the I/O change. For example, when a voltage is applied to a discrete input.

For "Active Off", the trigger will fire on the rising edge of the I/O change. For example, when a voltage is removed from a discrete input.

when a variable is set or changed

This trigger condition fires when a variable satisfies a basic statement. For instance, when an integer variable is greater than 50. Or when a variable is less than the value of another variable.

Importantly, you can choose for this trigger to fire "on set", or "on change only".

Warning

Misuse of the "On Set" setting is the cause of a lot of support tickets that we receive about mysterious script behavior.

When your trigger is configured to "Trigger on set", the trigger will evaluate and potentially fire every time a value is assigned to the variable, even if the value isn't changing. For example, if you have a trigger to fire when 'myVar' is equal to 100, your trigger would fire every time the variable is set to 100, even if it is already equal to 100. If you have a sequence that needs to fire every time a status variable is updated, regardless of the value, that would be a good use for this settings. Note that "Trigger on set" is not supported when using integer bits within a variable.

When your trigger is configured to "Trigger on change only", the trigger will evaluate and potentially fire when the value in the variable changes. This would be the desired configuration if you had a sequence that updated a section of the Display when a variable changes, for example.

at a specific date/time

This trigger condition fires at a specified date and time, or at sunrise or sunset. You can also make the trigger recurring at a daily, weekly, monthly, or yearly rate.

Sunrise and sunset are calculated based on the script's latitude and longitude settings, which you can configure in the "Locale' section of the Script Configuration window.

when a message is received

This trigger condition fires when an incoming message is received from a device already configured in the Device list of the script. The incoming message can be one already described in the Product File of the device, or it can be specified in the triggers dialog as a regular expression.

Triggers based on incoming message regular expressions are only evaluated after the message has already been compared against any expected incoming device responses, and after comparing against any unsolicited message regexes configured in the product file. Only if it does not match either of those will it be considered as a sequence trigger.

when an expression becomes true

This trigger condition allows you to create complex trigger logic in a single trigger. For instance, you might want a trigger to fire when 3 different variables are true, and one is false. Expressions are extremely powerful, learn more about them in the expressions documentation.

The "Test" button allows you to test your expression by simulating different values of the resources used within the expression and seeing whether the expression evaluates true or false.

on power-up

This trigger condition runs only once, when the show first starts. This trigger replaces the "A" (autostart) checkbox that you might be familiar with from the Sequences window in WinScript Live 5 and older.

Most scripts have at least one sequence of this trigger type, in order to start up any other monitoring or display updating sequences that might need to be always running.