Exploring the Network: OSC Connections

This is the second article explaining Open Sound Control (OSC) in a series titled Exploring the Network written by field service engineer and programmer Sam Smallman. In today’s article we will explore connecting two devices together and communicating via OSC. Whilst this article could be thought of as a guide, its aim is to be more educational in content allowing us to examine the different details necessary to implement such a system.

Dictionaries

Unlike other protocols such as MIDI, OSC doesn’t have a fixed name space. A name space, for those that haven’t read The Postcard (OSC), is the structure of a system or devices functions and parameters; laid out as a tree hierarchy. For each system or device that supports OSC as an input, there will exist their own name space or “dictionary”. This is important; as we connect our devices together, we need to recognise there are different dictionaries and that we may need to understand each devices dictionary for them to control and interact with each other.

Step 1. Find the dictionaries (see below for a list of popular dictionaries)

Interfaces

Most computers offer multiple interfaces, which at their core are pieces of hardware that allow the computer to communicate to other computers or peripheral devices e.g. USB Interfaces allow connection to keyboards, webcams, printers, etc.; HDMI Interfaces allows connection to displays. In terms of networking we are interested in Ethernet and Wi-Fi interfaces, most computers and, indeed, our consoles have more than one. These use Layer 3 protocols such as the Internet Protocol Suite (IP Suite), which we are now familiar with, to communicate. The ability to have multiple Ethernet interfaces allows us to have different networks and, importantly, define which network traffic goes where.

The sound department will not be happy being spammed with lighting network traffic!!!

Step 2. Configure the interfaces (default IP Addresses)

In the Shell -> Network, there are two important tables to consider:

Output Protocols; these options dictate whether or not Eos will output the streaming data of DMX using a variety of protocols (sACN, Artnet etc.) on a per interface basis. As a general housekeeping tip, it’s useful to uncheck the port settings for any protocols you know are not being used to control devices on that network. For example if your system is made up entirely of an Eos Family console and Net3 or Response gateways, there are no benefits to stressing the network with protocols which are unused by the receiving devices.

Interface Protocols; relate to the more communicative of protocols and the same consideration should be shown, when enabling their output on an interface, as Output Protocols. When a network is used purely for show control, via OSC, and Wi-Fi Remotes all other protocols should be disabled.

Network Settings:

The two devices must be on the same network, so before anything we should test and confirm this is the case. For those unsure of this process, you can read The Address, but to quickly recap; all the devices you wish to talk to each other should have the same first two octets of the IP Address e.g. 192.168.xxx.yyy, they should also have the same Subnet Mask e.g. 255.255.0.0.

Step 3. Check the devices can talk (Ping each other)

Note: If your devices can’t ping each other, go no further. Check the IP Addresses and Subnet Masks on each device are correct. Windows 7 by default blocks IGMP traffic on “public” networks. If you are trying to connect your personal computer and not seeing a response to the ping sent from eos, that may be the cause to your problem.

Ports

Step 4. Pick a port number (3001 is as good as any!)

Pick a number between 1025 and 65535… Ok, too many options and there are a few port numbers you should be aware of, so that you don’t clash.

3032 – This number is used by ETC’s Eos Family Range as a dedicated port to communicate OSC via TCP. Remember what TCP connections were? If not, read The Address. It’s useful to note that Eos only acts as a TCP Server and does not instigate a TCP connection as a client. As such the only time this number would be used is when an application is connecting to Eos via TCP e.g. Stamp, Moving Light Assistant, Lightwright & TouchOSC.

53000 – This number is used by Figure 53’s QLab as a dedicated port to receive OSC messages via UDP & TCP.

Note: There are two versions of OSC, which only bare significance when using a TCP connection. It’s important to recognise that some applications use different versions and be able to set the OSC TCP format in the Eos shell accordingly.

5568 – All multicast communication by Architectural for Control Networks (ACN) is done via this port, including streaming ACN (sACN, E1.31).

Application Settings

Step 5. Configure the Applications

Eos:

Displays -> Settings -> System Settings -> Show Control -> OSC

The settings found in System Settings -> OSC, only relate to UDP. Eos will transmit all OSC messages via UDP to the IP address 192.168.130.101 on port 53000, which is our MacBook running QLab. Make sure to enable OSC RX and OSC TX, meaning Eos will both receive and transmit OSC messages.

QLab:

Settings -> Network

QLab has the option of setting multiple patches all of which, in respect to OSC, are UDP. Patch 1 will transmit OSC messages via UDP to the IP 192.168.98.101 on port 3001, which is our Eos console.

Note: QLab’s patch or “transmit” settings are the same as Eos’ “receive” settings and vice versa for Eos to QLab.

Sending the Messages

Using the dictionaries for both Eos and QLab, we first need to identify the action we wish the application to make and the corresponding OSC message for it.

A popular action is to fire a cue in one application from another device:

To fire an Eos cue – /eos/cue/<cue list number>/<cue number>/fire

To start a QLab cue – /cue/<cue number>/start

Eos to QLab – External Links from Cues

Attach an external link to a cue and write out the OSC message in equals/comma format. E.g. [Cue] [1] {Execute} [More SK] {String} /cue/1/start=1,3.142,“a string with spaces” [Enter]

Note: Multiple OSC messages can be sent by wrapping them in quotation marks. E.g. [Cue] [1] {Execute} [More SK] {String} “/osc/message/1” “/osc/message/2” [Enter]

Eos to QLab – Magic Sheet Objects

Set the Target of a magic sheet object to Command and write out the OSC message in equals/comma format. E.g. /cue/1/start=1,3.142,“a string with spaces”

Note: If you send no arguments with the address pattern, Eos automatically adds a float argument of either 1.000 or 0.000 and sends the message twice, once on the down edge, when the button is pressed and another on the up edge, when the button is released.

Add an argument to the address pattern to have the message send only once. It will then trigger on the up edge of the button being released. E.g. /cue/1/start=now.

Eos to QLab – Macros

Use the Send_String button to transmit OSC messages written in equals/comma format E.g. Send_String /cue/1/start=1,3.142,“a string with spaces”. The advantage of using a macro is that it can now be used as a reference throughout your showfile by linking it to a cue, targeting to it from a magic sheet object or triggering it from a fader. If for example the first QLab cue of the show was no longer 1, but cue 0.5, you could easily update the macro to reflect that and it would update throughout your showfile.

Implicit OSC Output

OSC events are fired as the console executes actions such as firing a cue. There is a wealth of information that gets sent implicitly, but one really useful OSC message that 3^rd party devices could listen out for is /eos/out/event/cue/<cue list number>/<cue number>/fire

QLab to Eos:

Use the text field in the settings tab of a Network Cue to write in the OSC message you wish to send.

To fire a cue within Eos the OSC Message is /eos/cue/<cue list number>/<cue number>/fire

Note: QLab use space formatting to annotate an OSC message and distinguish the address pattern and arguments. E.g. /an/address/pattern 1 3.142 “a string with spaces” would be written in Eos like this: /an/address/pattern=1,3.142,“a string with spaces” using equals/comma formatting.

Step 6. Send the message

Conclusion

There’s a lot to take in, with hundreds of possible of commands to send but there are essentially 3 important fault finding technique to take away from this:

1. Are the devices on the same network? Can they ping each other?
2. Are the port and IP addresses set correctly? You often want the transmit and receive port to be opposite between devices!
3. Are you sending the correct message? Use the dictionaries to verify the correct message to send.

Steps

Step 1. Find the dictionaries
Step 2. Configure the interfaces
Step 3. Check the devices can talk
Step 4. Pick a port number
Step 5. Configure the applications
Step 6. Send a message

Dictionaries

Eos Family Devices – Eos Family Show Control User Guide
QLab – OSC Dictionary
Disguise – OSC Transport Overview

OSC Annotation
Annotations for an OSC message can be written in two formats and describe the address pattern and arguments properties for a message.

For example an OSC annotation with space formatting would look like this:

/an/address/pattern 1 3.142 aString “a string with spaces” true false nil impulse

This annotation describes an OSC Message with an address pattern = “/an/address/pattern“, and 8 different arguments:

• Argument 1 = 1 (Int32) – (i)
• Argument 2 = 3.142 (32Float) (f)
• Argument 3 = aString (String) (s)
• Argument 4 = a string with spaces (String) (s)
• Argument 5 = True (T)
• Argument 6 = False (F)
• Argument 7 = Nil (N)
• Argument 8 = Impulse (I)

Another formatting for OSC annotations is equals/comma. The same OSC message above would be annotated as the following:

/an/address/pattern=1,3.142,aString,”a string with spaces”,true,false,nil,impulse.