Revision as of 12:16, 26 December 2011

ola_trigger executes programs based on the values of DMX512 data. This allows a lighting console to trigger events on a computer, like playing music samples, advancing slides in presentations etc. . ola_trigger supports variable assignment, which offers a flexible way to control the behavior of the programs with the DMX512 data.

Config File Syntax

The config file defines the mapping of slot values to actions. Each line is a directive and directives are either action definitions or variable assignment. The order of directives within the config file doesn't matter - actions are triggered in the order of their slot numbers.

Any characters between a '#' and the end of the line are comments and are ignored.

Action Definitions

Action definitions are specified one per line, in the following form:

[Slot Number]   [Slot Values]   [Action]

The columns must be separated by whitespace.

Slot Number

The first column, slot number, specifies the DMX512 slot the action is valid for. Slot numbers range from 0 to 511. Slot numbers may be offset by using the --offset option (see the Usage section below).

Slot Values

The second column controls which DMX512 values trigger the action. Slot values range from 0 to 255. Multiple values are separated by commas. Ranges can be specified with a hyphen.

1,2,3,4   # Values 1 through to 4
1-4,10-14 # Values 1 to 4 and 10 to 14 (inclusive)

The % character the is default match. It triggers for all values that don't have an explicit action configured

0-100  # Values 0 to 100
%      # Triggers for everything else (101 - 255)

Actions are only triggered when the value changes. In the example above, if the value of slot 0 in the previous frame was 10, and a frame with slot 0 @ 10 arrived, the action will not be triggered. If a frame with slot 0 @ 5 arrives, the action will trigger again.

Actions

The third column specifies the action to run. Actions can be either variable assignments or commands.

Variable Assignment

Variables can be assigned values which can then be used in later commands. Variable assignments are in the form

variable=value

The value must be quoted if it contains whitespace:

variable="a quoted value"

Commands

Commands are enclosed in back ticks (`). Command arguments are separated by whitespace, quotes can be used with arguments that contain whitespace.

`echo hello world`  # Execute the '''echo''' command with two arguments [hello, world]
`echo "hello world"` # Execute the '''echo''' command with single argument "hello world".

Variables are specified with ${ }.

`echo ${foo}` # Run echo with the value of the foo variable.

Variables can be nested, which means you can do things like

# if i=1 and count_1=foo
`echo ${count_${i}}`   # runs echo foo

Full Action Definition Example

Putting everything together, the following will run `echo hello world` whenever the value of the first DMX slot changes to 0, 5 or 10.

0    0,5,10    `echo hello world`

Variables

Variables can be assigned default values using the same syntax as variable assignment actions:

# set the default value of foo
foo=bar

Special Variables

The variables ${slot_offset} and ${slot_value} are available for use within commands. For example:

0    %   `echo "Slot ${slot_offset} is at ${slot_value}"`

You should always use ${slot_offset} rather than hard coding slot numbers within command definitions, since the slot number may change with the --offset option.

Usage

Before running ola_trigger, make sure that olad is running and the universe has been configured with a DMX512 source. The config file is provided on the command line:

ola_trigger example.conf

Some useful options include:

-l, --log-level <level>

This change the logging level, valid values are 0 (minimum logging) to 4 (full logs). At log level 3 (INFO) and above, all actions (variable assignments and commands) will be logged.

-o, --offset <slot_offset>

This applies an offset to the configured slots. For example if the config file contains definitions for slots 0 and 1, if ola_trigger is run with -o 10 it will watch for values on slots 10 and 11. Defaults to 0.

-u, --universe <universe>

Specifies the universe to use. Defaults to 1.

Sample Configs

Sample configs are provided in the tools/ola_trigger/contrib directory.

A full example config is provided in the tools/ola_trigger directory. If you have configs that may be useful to others please submit them.

# Example DMX Trigger Config File                                                                                                                                                               

# Variable definitions
###############################################################################
# The default value of slot 2, this won't ever be used, since the variable is
# only used with slot 3, which implies we already got data for slot 2.
slot_2_value = "nan"  # nan isn't special in any way

# Triggers
###############################################################################
# Slot    Trigger Values   Action

# Slot 0 prints the current value of slot 0
0         %                `echo "Slot ${slot_offset} is at ${slot_value}"`

# Slot 1 runs a different command line tools
1         1                `ls`
1         2                `ps aux`
1         3                `who`

# Slot 2 sets a variable
2         %                slot_2_value="${slot_value}"

# Slot 3 prints the value of slot2 if slot3 is greater than 50%
3         128-255          `echo "Previous slot is ${slot_2_value}"`