Latest revision as of 18:20, 31 May 2018

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 and can trigger on rising values, falling values or both.

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

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.

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.

Raspberry Pi Media Player A combination of a Raspberry PI, ola_trigger and omxplayer