Theater System OSC Protocol

The various components of the theater system communicate using OSC messages transmitted via UDP packets either over the network or within the theater server. Following is a summary of available messages.

This is a work in progress.

Lighting Hardware

The lighting server is organized by logical fixtures. The following table describes each fixture and the associated hardware and DMX addressing. This is highly subject to change as the setup evolves. The current values can be found in the theater.config module.

Please note that DMX addresses are specified conventionally as 1-based following the physical device display settings, although internally the code uses zero-based addressing.

name	number	device	DMX addr	function
white	0	Dimmer 1	1	Soraa PAR30 aimed at disco ball
blue	1	Dimmer 1	2	Soraa PAR30 with blue gel
magenta	2	Dimmer 1	3	Soraa PAR30 with magenta gel
straw	3	Dimmer 1	4	Soraa PAR30 with straw-colored gel
black	4	Dimmer 2	5	LED black light
unused1	5	Dimmer 2	6	unused
unused2	6	Dimmer 2	7	unused
fan	7	Dimmer 2	8	box fan
rgba1	8	Slim Par Pro 1	9-12	Red-Green-Blue-Amber footlight
rgba2	9	Slim Par Pro 2	13-16	Red-Green-Blue-Amber footlight

Lighting OSC Messages

The system uses a single DMX output device so all fixtures are managed by a single lighting server.

/fixture

The /fixture message initiates a smooth change on a single fixture using a single-beat cubic spline with ease-in and ease-out. Each dimmer pack output is treated as a separate fixture. The first value is a fixture identifier, followed by one DMX value per fixture channel. E.g., a mono dimmer pack output uses one value between 0 and 255, or a RGBA color fixture uses four.

The fixture identifier may be either a name (recommended) or a number.

Examples:

/fixture white 255
/fixture rgba1 255 255 255 0
/fixture fan 128
/fixture 0 128

/spline

Animated lighting effects can be achieved using the /spline message which appends a multi-segment cubic Bezier spline path to the interpolator buffer for a single fixture.

The first message value specifies a fixture identifier, followed by a row-major array representing a matrix of Bezier spline knots. The matrix has one column per fixture channel and three rows per spline segment, and specifies DMX output values. The implicit first knot is the current fixture state (not included in the message).

Example:

/spline white 0 255 255
/spline white 255 180 180 180 0 0
/spline rgba1 0 0 0 0 255 255 255 0 255 255 255 0

The first example is a single-segment spline for a mono segment smoothly ending at 255 (full on) The second example is a two-segment spline which smoothly transitions to half-on and then off. The third example is a single-segment spline for a four-channel RGBA fixture which smoothly transitions to pure white (with the fourth amber channel off). Each grouping of four values represents a single row of the knot matrix.

/tempo

The lighting spline execution rate is set by the /tempo message which accepts a fixture identifier followed by a rate in segments/minute. This value is applied to all subsequent paths on that fixture. The initial default is 60 segments/minute, i.e. one second per segment.

Examples:

/tempo white 60
/tempo white 30
/tempo rgba1 120

Deprecated Messages

Several other messages are still in the code but are not recommended for current use.

Examples:

/set 0 0 0 0
/fade 0 0 0 0
/channel 0 0

Motion OSC Messages

Each motion server operates a single device. Currently, we have up to four systems running the ArduinoSpline firmware, each of which can drive up to four stepper motors. The motion units use sequential UDP ports.

/spline

The essential motion primitive is the /spline message which appends a multi-segment cubic Bezier spline path to the motion buffer for a single axis. The spline is specified in degrees of rotation relative to the starting position. The first knot is implicitly zero and is omitted, so each segment requires three knot values. The firmware buffer is limited to 20 segments, so overly-long sequences may be silently truncated.

Example:

/spline x 0 360 360 180 180 180 0 0 0

This is interpreted as a three-segment spline to be executed by the X axis motor. The first segment has an implicit zero followed by the first three values: [0, 0, 360, 360], which moves one full rotation with smooth boundary conditions at start and end. The second segment begins with the same endpoint and adds three more values: [360, 180, 180, 180], which produces a half-rotation backwards with an initial velocity discontinuity and a smooth end. The third segment is similar: [180, 0, 0, 0], finishing with a smooth deceleration to the starting position.

Format:

/spline <axis> k01 k02 k03 [k11 k12 k13 ...]

The axis specifier may be either a letter chosen from xyza or a number from 0 to 3. The implicit first knot of zero is omitted, then each segment adds three knot values, with the end point of one segment always used as the initial point of the next.

/tempo

The spline execution rate is set by the /tempo message which accepts a an axis identifier followed by a rate in segments/minute. This value is applied to all subsequent paths on that axis. The power-on default is 60 segments/minute, i.e. one second per segment.

Examples:

/tempo x 60
/tempo x 30
/tempo y 120.0

Other Messages

Several other messages are available for system testing but are not recommended for performance scripts as they are subject to change.

Examples:

/goto 0 0 0 0
/goto 0 90 0 360
/channel 0 360
/channel x 360