We've launched our new site at www.openlighting.org. This wiki will remain and be updated with more technical information.
Difference between revisions of "OLA DMX Trigger"
From wiki.openlighting.org
Line 3: | Line 3: | ||
= Config File Syntax = | = 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. | + | 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 trigger in the order of their slot numbers. |
Any characters between a '#' and the end of the line are comments and are ignored. | Any characters between a '#' and the end of the line are comments and are ignored. |
Revision as of 10:36, 24 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.
Contents
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 trigger 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 above).
Slot Values
The second column controls which DMX512 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 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 can be quoted:
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).
- -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.
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}"`