Revision as of 09:12, 24 December 2011

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

Usage

Before running ola_trigger, make sure that olad is running and the universe has been configured with a DMX512 source. ola_trigger reads a config file, which contains the mappings of DMX slot values to actions. 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).

-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.

Config File Syntax

The config file defines which commands are to be run. Each line is a directive The config file contains action definitions and default variable assignment.

Action Definitions

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

[Slot Offset]    [Slot Values]   [Action]

The columns must be separated by whitespace.

Slot Offset

The first column, Slot Offset, specifies the slot the action is valid for. Slot offsets range from 0 to 511.

Slot Values

The second column controls which slot values trigger the action. Slot values range from 0 to 255.

Values are separated by commas. Ranges can be specified with a hyphen.

1,2,3,4   # Trigger on values 1 through to 4
1-4,10-14 # Trigger on 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 executed 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 execute again.

Command Execution

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

Variable Assignment

Variables can be assigned values, and can be used in commands. Variable assignments are in the form

variable=value

The value can be quoted.

Commands

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

`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

Example

As an example, 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

Rather than executing a command, an action can set a variable

Special Variables

The variables ${slot_offset} and ${slot_value}

Comments

The # character comments out the rest of the text until the end of the line. This can be used at any location.

Example

A full example config is provided in the tools/ola_trigger directory.

# 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 slot3 if slot3 is greater than 50%
3         128-255          `echo "Slot 2 is ${slot_2_value}"`