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
Step 1. Find the dictionaries (see below for a list of popular dictionaries)
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:
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]
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 3rd 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:
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:
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.