Personal tools
The Open Lighting Project has moved!

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

Jump to: navigation, search
m (Add migrated template)
 
(11 intermediate revisions by 4 users not shown)
Line 1: Line 1:
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 DMX.
+
{{PageMigrated|url=https://www.openlighting.org/ola/advanced-topics/ola-dmx-trigger/}}
 
+
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.
 
 
= 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:
 
 
 
<pre>
 
ola_trigger example.conf
 
</pre>
 
 
 
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 =
 
= 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 triggered 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.
Line 29: Line 13:
  
 
<pre>
 
<pre>
[Slot Number]   [Slot Values]  [Action]
+
[Slot Number]   [Slot Values]  [Action]
 
</pre>
 
</pre>
  
Line 36: Line 20:
 
=== Slot Number ===
 
=== 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).  
+
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 ===
 
=== Slot Values ===
  
The second column controls which DMX512 values trigger the action.  Slot values range from 0 to 255.
+
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.  
 
 
Values are separated by commas. Ranges can be specified with a hyphen.  
 
  
 
<pre>
 
<pre>
1,2,3,4  # Trigger on values 1 through to 4
+
1,2,3,4  # Values 1 through to 4
1-4,10-14 # Trigger on values 1 to 4 and 10 to 14 (inclusive)
+
1-4,10-14 # Values 1 to 4 and 10 to 14 (inclusive)
 
</pre>
 
</pre>
  
Line 53: Line 35:
 
<pre>
 
<pre>
 
0-100  # Values 0 to 100
 
0-100  # Values 0 to 100
%         # Triggers for everything else (101 - 255)
+
%     # Triggers for everything else (101 - 255)
 
</pre>
 
</pre>
  
Line 60: Line 42:
 
=== Actions ===
 
=== Actions ===
  
The third column specifies the action to run. Actions can be either variable assignments or commands.
+
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 ====
 
==== Variable Assignment ====
Line 70: Line 52:
 
</pre>
 
</pre>
  
The value can be quoted:
+
The value must be quoted if it contains whitespace:
  
 
<pre>
 
<pre>
Line 97: Line 79:
 
`echo ${count_${i}}`  # runs echo foo
 
`echo ${count_${i}}`  # runs echo foo
 
</pre>
 
</pre>
 +
 +
==== Rising / Falling Triggering ====
 +
 +
Commands can be specified to trigger only if the value rises or falls. This is done with the + and - symbols:
 +
 +
<pre>
 +
+`echo rising edge`  -`echo falling edge`
 +
</pre>
 +
 +
Either the rising or falling command can be omitted, in that case no action will be taken.
  
 
=== Full Action Definition Example ===
 
=== Full Action Definition Example ===
Line 120: Line 112:
  
 
<pre>
 
<pre>
0         %               `echo "Slot ${slot_offset} is at ${slot_value}"`
+
0   %   `echo "Slot ${slot_offset} is at ${slot_value}"`
 
</pre>
 
</pre>
  
 
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.
 
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.
  
= Example =
+
= Usage =
  
A full example config is provided in the tools/ola_trigger directory.
+
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:
  
 
<pre>
 
<pre>
# Example DMX Trigger Config File                                                                                                                                                             
+
ola_trigger example.conf
 +
</pre>
  
# Variable definitions
+
Some useful options include:
###############################################################################
+
; -l, --log-level <level>
# The default value of slot 2, this won't ever be used, since the variable is
+
: 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. 
# only used with slot 3, which implies we already got data for slot 2.
+
;-o, --offset <slot_offset>
slot_2_value = "nan"  # nan isn't special in any way
+
: 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>
# Triggers
+
: Specifies the universe to use. Defaults to 1.
###############################################################################
 
# Slot    Trigger Values  Action
 
  
# Slot 0 prints the current value of slot 0
+
= Sample Configs =
0        %                `echo "Slot ${slot_offset} is at ${slot_value}"`
 
  
# Slot 1 runs a different command line tools
+
Sample configs are provided in the [https://github.com/OpenLightingProject/ola/tree/master/tools/ola_trigger/contrib tools/ola_trigger/contrib] directory.
1        1                `ls`
 
1        2                `ps aux`
 
1        3                `who`
 
  
# Slot 2 sets a variable
+
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.
2        %                slot_2_value="${slot_value}"
 
  
# Slot 3 prints the value of slot3 if slot3 is greater than 50%
+
[[Raspberry Pi Media Player]] A combination of a Raspberry PI, ola_trigger and omxplayer
3        128-255          `echo "Slot 2 is ${slot_2_value}"`
 
</pre>
 

Latest revision as of 19:20, 31 May 2018

This page has migrated

This page has migrated to our new site, please see https://www.openlighting.org/ola/advanced-topics/ola-dmx-trigger/.

This content will not be updated and is just left here for reference and will be removed at some point in the future, see the link above for the most up-to-date version.


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