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.
DMX Hardware¶
The lighting server is organized by logical fixtures. The current fixture
configuration is specified in the theater.config
source code as per
Theater Configuration.
Please note that DMX addresses are conventionally specified as 1-based following the physical device display settings, although internally the code uses zero-based addressing.
DMX OSC Messages¶
The system uses a single DMX output device so all light fixtures and fans 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
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