Variables

Variables are a way of collecting numbers from inputs and using them in actions. Some examples would be:

Receiving a MIDI note on message and using the note value as a timeline number to start.
Using a DMX input channel to master the intensity of a group of fixtures.
Receiving a serial command on one Controller and outputting a related serial command on another.

Unless they have been enabled through the Project Features page, the variables will not be displayed. You can enable them using the Advanced Feature button.

Triggers that capture variables

Timeline Started, Timeline Ended and Timeline Released

The Timeline Started, Timeline Ended and Timeline Released triggers capture the timeline number as variable 1 if the Timeline parameter is set to Any.

Scene Started and Scene Released

The Scene Started and Scene Released triggers capture the timeline number as variable 1 if the Scene parameter is set to Any.

Timeline Flag

If the timeline and flag has been set to Any, the timeline number, flag and name are captured into variables 1, 2 and 3 respectively.

If the timeline number has been set and flag has been set to Any, the flag and name are captured into variables 1 and 2 respectively.

Digital Input

The Digital Input trigger will capture the input number if the Input parameter of the trigger is set to Any.

If triggering from a RIO's digital input, the trigger will capture the input number if the Input parameter of the trigger is set to Any. The RIO number will be captured as variable 1 and the input number as variable 2 if both these parameters are set to Any. If only one of these parameters is set to Any then the captured number will be stored as variable 1.

Analog Input

Captures the analog input as a percentage in variable 1. For example, if the input range of the Controller’s analog input is set to 0-10V and the input is 4V then variable 1 will be 40%.

If triggering from a RIO's analog input, the analog input value is captured as a percentage in variable 1, then the RIO number (if set to Any) and the input number (if set to Any) in subsequent variables. If the RIO number and the input number are set to Any then variable 2 will be the RIO number and variable 3 will be the input number. If the RIO number is specified then variable 2 will be the input number.

Serial and Ethernet Input

Serial and Ethernet trigger data is entered as a string of data bytes, represented in either ASCII, hex or decimal form. Any single byte or group of consecutive bytes can be matched by specifying a wildcard, and the value stored as a variable. Multiple wildcards can be used and each will store into the next available variable. There are three types of wildcards supported:

NOTE: If you need to capture a < or > symbol, please enter them as follows: \< or \>. For instance, to capture 1<2, you would enter 1\<2. This would then store 1<2 as a string.

<c> or <C>	Will match any single character (or byte) and store its raw value (0-255) as the next variable. You can add a length to the wildcard to match multiple characters and treat them as a single number - so <4c> would match a 32 bit number. Maximum length = 4.
<d> or <D>	Will match a decimal character (ASCII, 0-9) and store its numeric value (0-9) as the next variable. You can add a length to the wildcard to match multiple decimal characters and treat them as a single number - so <4d> would match four decimal characters and treat them as a number from 0-9999. Maximum length = 10. Optionally, an upper limit can be applied (<3d:255>) to set the maximum value for the incoming number. This way any range can be converted to a percentage for use with actions, e.g. Set RGB.
<x> or <X>	Will match a hexadecimal character (ASCII, 0-f) and store its numeric value (0-15) as the next variable. You can add a length to the wildcard to match multiple hexadecimal characters and treat them as a single number - so <2x> would match two hexadecimal characters and treat them as a number from 0-255. Maximum length = 8.
<s> or <S>	Will capture a string of arbitrary length. To determine where the string ends, you must either: Specify a terminator yourself. For example, the trigger <s>\n would capture everything up to (but not including) the first \n character received. A terminator cannot be another variable, it must be a literal character, so <s><d> is not a valid trigger. Send a NULL character (0x00) to the Controller to indicate the end of the string. This NULL character is assumed and is not shown in the Designer interface. You can also say that you want to capture a string with a predetermined number of characters. For example, <4s> will capture 4 bytes and store it as a string. There is no need for a terminator in this case.

Note that if the input data does not match the wildcard type then the trigger does not match. So if you have specified the wildcard <3d> and the input is ASCII "12y" then the trigger will not match because the 3 characters were not all of the required decimal type.

When using Ethernet Inputs the last two variables in the trigger will be the IP address and the source port number of the device the message was received from.

If triggering from a RIO's serial input, the RIO number will be captured as the first variable if set to Any.

To capture a float, this can be achieved using <s>. Once this has been captured, it needs to run through a script to turn it back into a float. For this, we could use the following:

Lua

floatVal = tonumber(get_trigger_variable(1).string)

DMX Input

When a DMX Input trigger matches it will implicitly store the channel value as variable 1.

MIDI Input

In short MIDI messages, you can capture data 1 and/or data 2 into a variable by checking the 'Capture' checkbox. If both are checked, data 1 is variable 1 and data 2 is variable 2. For some short messages, i.e. Pitch Wheel, the two data bits are treated as a single 14 bit value. To capture this 14 bit value, check 'Capture' for data 1 and check the '14 bit variable' checkbox.

In MSC messages, if the 'Cue number' and 'List number' are left blank, the received values will be captured in variables. Cue number is captured into variable 1 and list number into variable 2.

Extended messages support the same wildcard format as serial triggers. The only difference is that <2c> captures a 16-bit value in serial triggers and it captures a 14-bit value in MIDI triggers.

If triggering from a RIO A's MIDI input, the RIO A number will be captured as the first variable if set to Any.

Audio Input

When an Audio input trigger matches it will implicitly store the level for the band as variable 1.

If triggering from a RIO A, the RIO A number will be captured if set to Any.

DALI Input

If the trigger is set to match to 'Any' for Group or Ballast then the Group or Ballast number will be stored as variable 1.

If the trigger is using a Min to Max range then the matching number will be stored as variable 2.

DALI Ballast Error

If All is selected instead of a specific address then the address of the ballast reporting the error will be stored as variable 1.

DALI Button Event

The trigger captures five variables:

Short address
Device group
Instance number
Instance group
Event type

DALI Illuminance

The trigger captures five variables:

Short address
Device group
Instance number
Instance group
Illuminance value (0-1023)

DALI Occupancy

The trigger captures six variables:

Short address
Device group
Instance number
Instance group
Occupancy type
Movement type

BPS Button

If the button number is set to Any, the trigger captures the pressed button as variable 1.

Alternatively, if the BPS station number is set to Any, then the station number is captured as variable 1 and the button number as variable 2.

Touch Button Event

You can use one trigger to respond to multiple buttons by using variables - the syntax is the same as for Serial and Ethernet Input triggers, e.g. button<3d> will match a button with the control key button001 or button002, etc. and capture the number as a variable. The name of the page that the button is on will also be captured as the final variable.

Touch Slider Move

You can use one trigger to respond to multiple sliders by using variables - the syntax is the same as for Serial and Ethernet Input triggers, e.g. slider<3d> will match a slider with the control key slider001 or slider002, etc. and capture the number as a variable.

The value of the slider will be captured as a variable.

The order of captured variables will be:

Any captures from Key (with additional variables where required)
Slider Position (0-255)
Name of the interface page containing the slider

Touch Colour Change

You can use one trigger to respond to multiple colour pickers by using variables - the syntax is the same as for Serial and Ethernet Input triggers, e.g. colour<3d> will match a colour picker with the control key colour001 or colour002, etc. and capture the number as a variable.

The RGB values will always be captured as 3 variables.

The order of captured variables will be:

Any captures from Key (with additional variables where required)
Red level (0-255)
Green level (0-255)
Blue level (0-255)
Name of the interface page containing the colour picker

Touch Page Change

You can use one trigger to respond to multiple pages by using variables - the syntax is the same as for Serial and Ethernet Input triggers.

Touch Keypad Code

You can use one trigger to respond to multiple keypads by using variables - the syntax is the same as for Serial and Ethernet Input triggers, e.g. keypad<3d> will match a keypad with the control key keypad001 or keypad002, etc. and capture the number as a variable.

The code entered into the keypad will be captured as a variable.

The order of the captured variables will be:

Any captures from Key (with additional variables where required)
The entered code (as a string)
Name of the interface page containing the keypad

Paradigm Indicator

If any of the parameters are set to Any then they will be captured as variables. The variable index order will follow the order that the parameters are displayed in the trigger.

Conditions that capture variables

Digital Word

This condition will capture a variable from the inputs set to match either value. This variable will be added on the end of any variables captured by the trigger.

Conditions that use variables

Run Script

Variables can be accessed from Lua scripts.

DALI Ballast Errors

The DALI ballast address on a specific interface can be passed in by variable. Select the relevant "Variable" option and then choose the variable index.

Actions that use variables

Captured variables can then be used in actions by specifying the variable index (corresponding to the order in which the variables were captured). If you have multiple actions associated with a trigger then each action can use the variables independently.

Start, Release, Toggle, Pause and Resume Timeline

Rather than selecting a timeline as a property of the action you can specify the timeline number in a variable. This is a very powerful feature when you want an external system to be able to call up any one of a large number of timelines because you do not need to define separate triggers for each timeline.

Start, Release and Toggle Scene

Rather than selecting a Scene as a property of the action you can specify the Scene number in a variable. This is a very powerful feature when you want an external system to be able to call up any one of a large number of Scenes because you do not need to define separate triggers for each Scene.

Set Timeline Rate

You can select the timeline to modify with a variable (as for Start Timeline). You can also choose to pass in the rate percentage using a variable.

Set Timeline Position

You can select the timeline to modify with a variable (as for Start Timeline). You can also choose to pass in the position percentage using a variable.

Enqueue Trigger

You can select the trigger to Enqueue with a variable. You can append the originating trigger's name, number and/or description as variables.

Run Script

Variables can be accessed from Lua scripts.

Master, Increase and Decrease Intensity

The intensity level or increment can be passed in by a variable. Select the "Variable" option and then choose the variable index.

Set RGB

The target for the Set RGB can be set from a variable. First select the override type (Fixture or Group) and then set the selector to Variable and then choose the variable index.

The Red, Green and Blue values for colour can be passed in as variables. Select the "Variable" option for the colour you want to adjust and then choose the variable index. The fade time for the action can also be passed in as a variable. Select the "Variable" option and then choose the variable index.

Clear RGB

The target for the Set RGB can be set from a variable. First select the override type (Fixture or Group) and then set the selector to Variable and then choose the variable index.

The Red, Green and Blue values for a group of fixtures can be passed in as variables. Select the "Variable" option for the colour you want to adjust and then choose the variable index. The fade time for the action can also be passed in as a variable. Select the "Variable" option and then choose the variable index.

Set Text Slot

The slot that is to be set an be selected using a Variable. Set the selector to Variable and then choose the variable index. This variable should be a string that matches the identifier of the text slot.

The text to set the Text sot to can also be set from a Variable. Set the selector to Variable and then choose the variable index.

Set Volume

The level can be set from a variable.

Serial and Ethernet Output

In the same way that you can use wildcards to match data in a serial or Ethernet trigger, you can insert the value of captured variables into your serial output messages. The same wildcard types are supported to define how to output a variable:

<c>	Will output the value of a variable as a raw byte (0-255).
<d>	Will output the value of a variable as a decimal number (ASCII, 0-9).
<x>	Will output the value of a variable as a hexadecimal number (ASCII, 0-f). Any letters will be lowercase.
<X>	Will output the value of a variable as a hexadecimal number (ASCII, 0-f). Any letters will be uppercase.
<s>	Will output a captured string. <s> will output the entire captured string. <4s> would output the first 4 characters of the captured string.

As with input you can specify a length if you want to output the variable as a longer decimal or hexadecimal number. So a variable value of 175 output with <4d> would add ASCII "0175" to the serial output. Note that it is padded with leading zeros to fill the specified length. If the value was too large to express in the specified length it would be truncated from the left, so <2d> would output the number 123 as ASCII "23".

Output strings are allowed to begin with a wildcard. By default each wildcard takes the next variable in the order they were captured. If you want to output the variables in a different order then you can add a variable index to the wildcard in the form <3,2d> where 3 is the variable index. If you specify an output wildcard where there is no corresponding capture variable then it will have value of zero and output accordingly.

Output Digital

The Device number (not type), Output number and State can all be set from a variable.

The Output number will be in the range 1-4 or 1-8 depending on the number of outputs on the RIO.

The State will be an integer where 0 is off and any other integer is on.

MIDI Output

Short messages can output a captured value for data 1 and data 2. Pick a variable using the 'Variable Index' controls. If data 1 is outputting a captured value, you can optionally send it as a 14-bit value, with the lower 7 bits in data 1 and the upper 7 bits in data 2, by checking '14 bit variable'.

Outputting a MSC message allows you to set the cue number and/or list number by choosing a variable with the 'Variable Index' controls.

Extended messages allow you to output captured variables using the same syntax as serial actions.

DALI Set Level

The DALI group or ballast number on a specific interface can be passed in by variable. Select the relevant "Variable" option and then choose the variable index.

The level of a DALI ballast, group or all DALI ballasts can be passed in by a variable. Select the "Variable" option and then choose the variable index.

DALI Recall Scene

The DALI group or ballast number on a specific interface can be passed in by variable. Select the relevant "Variable" option and then choose the variable index.

Recall a DALI scene on a specific interfaces single ballast, group or all of the ballasts. Select the "Variable" option and then choose the variable index.

DALI Command

The DALI group or ballast number on a specific interface can be passed in by variable. Select the relevant "Variable" option and then choose the variable index.

Start DALI Emergency Test

The DALI ballast address on a specific interface can be passed in by variable. Select the relevant "Variable" option and then choose the variable index.

Stop DALI Emergency Test

The DALI ballast address on a specific interface can be passed in by variable. Select the relevant "Variable" option and then choose the variable index.

Mark DALI Ballast Fixed

The DALI ballast address on a specific interface can be passed in by variable. Select the relevant "Variable" option and then choose the variable index.

Set BPS Button LED