From OpenDMX.net

Jump to: navigation, search

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.

[edit] 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.

[edit] 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.

[edit] 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).

[edit] 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.

[edit] Actions

The third column specifies the action to run. Actions can be either variable assignments or commands and can trigger on rising values, falling values or both.

[edit] 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"

[edit] 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

[edit] Rising / Falling Triggering

Commands can be specified to trigger only if the value rises or falls. This is done with the + and - symbols:

+`echo rising edge`  -`echo falling edge`

Either the rising or falling command can be omitted, in that case no action will be taken.

[edit] 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`

[edit] Variables

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

# set the default value of foo
foo=bar

[edit] 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.

[edit] 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.

[edit] 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.

OLA DMX Trigger