Integrating TouchOSC with PixLite Mk3

What is OSC?

Open Sound Control (OSC) is an encoding specification that can be used to send messages via many different types of communication protocols. Despite the name, the OSC protocol can be used in lighting applications too. OSC can be used over UDP, TCP, and others. In this guide, we will look at OSC messages sent via UDP packets. To learn how PixLite® Mk3 can receive UDP messages, see the article: Triggering with UDP.

OSC messages are built to include three main parts:

• The address pattern (typically the name given to an interactive element)
• The type-tag (used to specify the argument’s type, e.g. “i” denotes “integer”)
• Any arguments (can be thought of as variables)

An example of an OSC message is shown below. “button” is the address pattern, “i” is the type-tag, and the argument is an integer of value 0.

“/button,i0”

TouchOSC and Other Choices

TouchOSC is a piece of software commonly used to generate OSC messages. It provides a flexible array of buttons, dials, faders, etc. to design a graphical user interface. As a user interacts with the elements in the interface, OSC messages are sent.

For example, a button called “button1” is created below, and is configured so that when the button is clicked it is latched on, and when it is clicked again it is latched off.

In its “On” state, the integer is 1, and the OSC message is “/button1,i1”.

In its “Off” state, the integer is 0, and the OSC message is “/button1,i0”.

Elements are then added as needed, to build the required interface. An example of an interface that might be useful with a PixLite Mk3 device is shown below.

There are many options to consider when choosing a system to generate OSC messages, so you may need to compare options to find the one that suits your needs. Another common choice is Kiosc by Visual Productions.

Network Configuration

TouchOSC can have several outgoing connections. Follow these steps to create an outgoing OSC connection.

1. Navigate to the “Connections” window (Edit->Connections) and click on “OSC”.
2. Enable a Connection and select “UDP”.
3. Fill in the “Host” field with the IP address of the PixLite Mk3 device (if unicasting) or enter in an appropriate broadcast address if broadcasting to multiple PixLite devices. For example, to broadcast to all devices in the range of 192.168.0.X, you can enter in the IP address 192.168.0.255.
4. Fill in the “Send Port” field with the port number the UDP traffic will be routed to. If you are unsure which port numbers can be used, see the article: Triggering with UDP.
5. “Receive Port” can be left blank.

Structure of TouchOSC Messages

An OSC message will always include an address pattern but may or may not include arguments and/or type-tags. In TouchOSC, a simple OSC message for our example of a button called “button1” is encoded as ASCII:

“/button1”, which has hexadecimal data of 2f 62 75 74 74 6f 6e 31.

But if an argument is included in the message, then this OSC string will contain other data. For example. In TouchOSC, an argument is added to represent whether the button is on or off. The following examples show what the hexadecimal data is for various argument types.

Note that OSC messages are designed to be of specific lengths. To ensure this, TouchOSC will add null characters as padding within the message.

Integer Type-Tag, with values 0, 1: There is one common type-tag, which is “,i” [2c 69], and binary arguments to represent 0 and 1, which are [00] and [01].

Boolean Type-Tag, with values False, True: There is no argument in this case; there are two type-tags, which are “,F” [2c 54] to represent True and “,T” [2c 46] to represent False.

There are many other types of arguments, which are useful for various purposes and various elements in the TouchOSC interface. For example, an XY plane may have a Float argument for the X position, and another Float argument for the Y position.

Analyzing an OSC Message in Wireshark

It may be necessary to know the exact contents of an OSC message (the hexadecimal data that it contains) to configure an exact match in the PixLite® device. The easiest way to determine the data is to utilize a tool such as Wireshark to inspect the exact contents of the message your sending software is outputting. An example of Wireshark being used is shown below:

Using Arguments with a PixLite Mk3 Trigger

Whatever arguments or type-tags are used, the PixLite Mk3 can receive the message and fire a trigger if it matches the received string, however you should be aware of some limitations:

1. An argument cannot be received as a variable in PixLite®Mk3. If there is a fader, for example, which has a range of integer values between 0 – 100, then these values cannot be directly “mapped” to the PixLite’s intensity. The trigger in PixLite® Mk3 is a matched string only. You could create multiple triggers to handle multiple specific values of the argument, like 5 triggers to handle 0%, 25%, 50%, 75%, and 100%, but you can’t utilize arguments to send arbitrary values to the PixLite® Mk3. This is further explored in “Arguments that the PixLite® Should Honor” below.
2. The PixLite® has the capability to match all messages that start with a string. For example, if a configured trigger is set to fire when a received UDP string starts with “/button_1”, then the PixLite® could ignore any arguments that follow. This may be useful if you have another piece of equipment that can interpret the arguments fully, but you also need the PixLite® to trigger an action whenever a message is received. However you should beware, there may be other UDP messages that also start with this string which unintentionally cause the trigger to fire. In this example, “/button_10” and “/button_11” would also cause the trigger to fire.

Creating UDP Triggers in PixLite Mk3 for OSC

PixLite Mk3 devices all include the SHOWTime feature set, which allows triggers to be created to control the device from external sources. There are many options for Trigger Sources, one of these is UDP, which is the one we will be using for TouchOSC.

To create a UDP trigger, you will need to specify the port number, UDP message contents, and the action that should be completed when the message is detected.

OSC messages that use the UDP protocol can be detected by these triggers in PixLite Mk3. To learn how to create UDP triggers in more depth, see the article: Triggering with UDP.

No Arguments

If the OSC message to be received has no type-tag or arguments, and the message only contains the address pattern, then this is the simplest implementation of an OSC trigger.

Simply enter in the address pattern as a string, in Plain Text, like the following example.

Arguments that the PixLite® can Ignore

If there are arguments that are included in the message, but it is not necessary to distinguish between different “states”, then this trigger can be created in the same way as the above example screenshot.

Simply enter in the address pattern as the string and ensure that “Starts With” is selected. This will cause the trigger to fire whenever the OSC message is received, as long as the string starts with the text you have entered. This means that any time TouchOSC sends an OSC message, the type-tag and arguments will effectively be ignored.

Arguments that the PixLite® should Honor

If an element within TouchOSC does require the argument to be considered, then this may mean that multiple triggers are required to handle each state of the element. Each trigger in this situation will likely need to be set to “Exact Match”, so that you can specify the exact contents of the message, and there may be a need to enter the string as hexadecimal.

For example, the “On” state for the button with integer type-tag we have previously considered requires a UDP trigger with a hexadecimal string:

2f 62 75 74 74 6f 6e 31 00 00 00 00 2c 69 00 00 00 00 00 01

And the “Off” state requires a UDP trigger with a hexadecimal string:

2f 62 75 74 74 6f 6e 31 00 00 00 00 2c 69 00 00 00 00 00 00

The following screenshot shows what these triggers would look like in a PixLite® Mk3:

Download an Example Project

The example TouchOSC project that was shown earlier can be downloaded at the link below, which also includes a PixLite® Mk3 configuration file, and four basic scene files.