Triggering QLab from Eos using OSC

Last updated
Save as PDF

This article is about sending triggers from Eos to QLab. For the reverse scenario, see this article

Description

When playing back lighting and sound cues simultaneously, it is often desirable to have these execute at exactly the same time. This can be achieved using Open Sound Control (OSC), which allows sound to trigger lighting, or vice versa, using only a network connection between the devices - no additional hardware required. In this article, we will look at how to send triggers to the popular show control software QLab from an Eos family console.

This article is designed to get the new user up and running as fast as possible. There is also a series of articles on the et cetera blog which covers these topics in much more detail - these are linked in line, and in full at the end of the article.

This article is based on Eos software version 3.2.8 - in earlier versions, the show control and network settings were laid out differently

Setup and Shell Setting Changes in Eos v3.2 - Electronic Theatre Controls Inc

This article uses QLab v4. QLab is not an ETC product, and its layout and functions may change without warning

What is OSC?

OSC is an open protocol which allows the sending and receiving of human-readable messages between sound, lighting and other entertainment technology systems. For example, Eos can understand commands like "/eos/chan/1/out", which would turn off channel 1, or "/eos/cue/1/fire" to run Cue 1. Other devices implement OSC in different ways; for example, QLab would understand the incoming command "/cue/1/start".

In general, OSC messages can be sent either by UDP (User Datagram Protocol) or by TCP (Transmission Control Protocol).

UDP messages do not have guaranteed-delivery - they may be dropped by a network switch without acknowledgment
TCP messages are guaranteed-delivery - they must be forwarded by a network switch and they must be acknowledged by the receiving device
- If the sending device does not receive a timely acknowledgement from the receiver, it will re-send the message

QLab v4 only supports UDP messages. QLab v5 supports both UDP and TCP, but with strong caveats; see below for more details.

Part of the trick in getting different devices to talk to each other is to have them speak each other's language. If the sound software can only output in the format "/cue/1/go", but the lighting console can only understand in the format "/lights/cue/1/fire", we have a problem. Luckily, both Eos and QLab are flexible enough to avoid this.

Formerly, the MIDI protocol was commonly used for this purpose. The advantage of OSC is that no additional MIDI hardware is required, as everything happens on the network, and that OSC is much more powerful. The trade-off is that OSC can be more time-consuming to set up.

et cetera: Introduction to OSC

For an in-depth look at how OSC is implemented in Eos, see the Eos Manual.

Setting Everything Up

There are 3 main steps we need to take to successfully trigger QLab from Eos via OSC:

Set up a working network connection between both devices
Configure Eos correctly to send OSC to QLab
Configure QLab correctly to receive OSC

The Network

A quick note on IP addresses

Each device on a network must have an IP address, which must be unique within that network. An IP address consists of 4 digits between 0 and 254 separated by decimal points. So with two Eos family consoles, one could have the address 10.101.100.20, and the other 10.101.90.101 - so far so simple.

But the IP addresses of two devices must be in the same subnet, if those devices want to talk to each other. Subnets are complex, but we can keep it simple for now:

Set the Subnet Mask on every device to 255.255.0.0
Consequently, for 2 devices to be on the same subnet, their first 2 numbers must be the same (10.101...), but the remaining numbers can be different (and at least one of them must be)

In the example above, the two Eos family consoles can talk to each other because they share the 10.101... Another device with the IP address 192.168.1.55 could not talk to them.

This is all you need to know for a basic network setup between Eos and QLab - for more detail, see the et cetera blog post on IP addresses and subnets.

Cooperating with the Sound Department

ETC uses default IP addresses per product type, as detailed in this article. Consoles with 1 network port (Windows XP consoles and ETCnomad Puck) use a default IP address in the 10.101.x.x range. Consoles with 2 network ports (Windows 7 consoles) use the 192.168.x.x range for their second port by default.

If you have full control over all devices on the network (including the sound computer), or the sound department also use the 10.101.x.x range, it is easiest to stick with these defaults, and ensure the IP address of the QLab computer is in the same range.

But often, someone else is running sound, and they may have their own network, with their own IP address scheme. In that case, here are your options:

If your console has 2 network ports (see below), use the second port to connect to the sound department, and choose an (unused!) IP address in the same subnet as their QLab computer.
If your console has 1 network port, you will need to come to an arrangement so that the console and the QLab computer end up on the same subnet. This may depend who has the fewest devices to readdress! Of course, if you don't use your console's network port (because you use DMX only), you can follow option 1 above.

To edit the network settings on a console, click [displays] to open the file browser and navigate to Setup>Device Settings>Network

The IP address for each port is set at the top of this window. If you need to change it from the default, do so - a reboot will be required.

Once this is set, scroll down to the Interface Protocols section. Ensure that UDP Strings & OSC is ticked for the port you want to use.

If you're connecting to sound using your port 2, you may want to turn off sACN and Artnet for this port, to avoid spamming the sound network with level data.

For this article, we'll assume we're using Port 1 on an Eos Ti, with an IP address of 10.101.92.101.

et cetera blog post on network settings

Note: If you're running Eos ETCnomad on a laptop, you will have to set the IP address in Windows or macOS, rather than in Eos.

If using Windows, search the web for "setting a static IP in [your Windows version]"

If using a Mac, use the same method as detailed below under "QLab Network Settings"

QLab Network Settings

QLab only runs on macOS, so head to the Apple menu (top left of the screen) > System Preferences > Network. Choose the relevant network interface from the list (usually either wired Ethernet or a Thunderbolt adapter) and assign and IP address and subnet mask. These are the settings we're using in this example:

Mac Network Settings.png

Hit Apply and exit System Preferences

Configuring Eos to Send OSC

Now we need to check the settings within Eos. Press [Dispays] - {Setup}, choose System (rather than User or Device), and hit Show Control, then OSC.

The OSC options are divided into RX (receiving) on the left, and TX (transmitting) on the right. We're interested in TX, as Eos will be the transmitting device.

Set the following:

OSC TX: Enabled
OSC UDP TX Port: 53000 (this is the default port QLab listens on)
OSC Cue Send String: leave blank for now, see below for details
OSC UDP TX IP Address: The IP address of the QLab Mac
OSC TCP Mode: leave at Packet Length (v1.0) as seen below

Your window should now look something like this:

Eos is now set up to send OSC to IP address 10.101.155.1, port 53000. Now let's configure QLab.

Configuring QLab to Receive OSC

QLab just needs to be told to accept incoming OSC commands. Open up a QLab workspace, then click on the gear symbol (bottom right) for Workspace Preferences. Choose OSC in the left-hand menu, and ensure Use OSC Controls is ticked.

Mac Receive OSC.png

Hit Done.

Great! Now both devices have enough information to talk to each other.

Sending OSC Commands

There are several different ways you can send OSC cues to QLab

Sending an OSC string on a per-cue basis

If you only need to trigger a few QLab cues from Eos, it makes sense to send a specific OSC command from the relevant Eos cues.

Let's say you need to fire QLab cue 17 with Eos cue 5. To do this, type in:

[Cue] [5] {Execute} {More SK} {String} /cue/17/start [Enter]

Eos will send this string when Q5 is executed.

This is usually the best method for theatre shows where a couple of specific sound cues need to be triggered from Eos.

Sending QLab-readable OSC with every Eos cue

Eos outputs OSC natively every time it fires a cue, but not in a format that QLab understands. To get around this, we can use the OSC Cue Send String function in the Eos OSC Setup menu.

This allows you to send a custom string with a cue (or other) number as a variable. For example:

/cue/%1/start

would send that message with every cue, with the cue number in place of the %1 - which is the format that QLab understands.

There are 5 variables you can use in the string:

%1 - cue number
%2 - cuelist number
%3 - cue whole number only (i.e. if it's cue 17.5, send only 17)
%4 - cue point number only (i.e. if it's cue 17.5, send only 5)
%5 - cue label

This method works best when one person has control of the cue numbering of both Eos and QLab.

Other Methods

OSC is very flexible, and QLab's implementation has many options.

For example, you can send a simple /go which is the same as hitting the GO button on QLab itself. Normally sending a specific cue number is preferable, but it's good to know this is possible.

QLab can also accept custom commands for certain playback functions - for example, you could map the command /eos/says/GO to the Go button. This is done in the Workspace Preferences > OSC Controls section.

Turning OSC On and Off

At times you may want to turn the OSC link between lighting and sound off, especially during tech rehearsal. Rather than going into the Setup menu every time, you can create a pair of macros to enable and disable OSC TX, and put these on a magic sheet.

This is done half in live, and half in blind.

From Live, start recording a macro using [Learn] [Marco] [1] [Enter]
Hit [Displays] {Setup}, navigate back to the Show Control > OSC menu, and click on the OSC TX cell (it doesn't matter what state it's in)
Hit [Learn] to finish learning
Enter the macro list using [Macro] [Macro]
Your macro will contain several unwanted things. Hit {Edit}
Use the {Delete} softkey to remove all commands from the macro except OSC_TX and the final Enter (diamond)
Using the "Common" tile in the CIA, insert the word "Enable" after OSC_TX, before the Enter
Hit {Done} to finish editing your macro

The macro should now simply read OSC_TX Enable ♦

Within the macro list, copy this macro using [1] [CopyTo] [2], and edit the new macro to read OSC_TX Disable ♦

You can test these out from live, and create magic sheet objects to fire them.

It's Not Working!

If you followed the steps above, but the QLab cue won't fire, don't despair. There are many variables in a network system, and sometimes a little fault finding is required.

The Eos Diagnostics Tab

Eos has a built-in diagnostics tab, which shows you what's happening on the console in real time. To access it, hold down the [Tab] key, and type in 99, then release the [Tab] key. In the window at the top, you will see a live stream of events within Eos.

On the right-hand side, ensure the Outgoing OSC option is set to On. Now run an Eos cue that should send OSC to QLab. If the OSC is leaving Eos, you should see the following message (among a large number of other messages beginning with /eos)

Diag OSC Send.PNG

This confirms that the OSC command was sent.

If you don't see this, the OSC message isn't being generated. Check your OSC String TX field, or the execute field of your cue, is correct. Check that OSC TX is turned on.

If you see this but nothing happens, check that there is a cue 2 in QLab.

If there is, check a few basics:

Is the Eos OSC TX port set to 53000, and the TX IP Address set to that of the QLab Mac? You can check both these things in QLab Workspace Settings > OSC Controls
Is "Use OSC Controls" ticked in this window?
Does Eos definitely think that the correct IP address is online? With an empty command line, press [About], and check that the expected IP appears here
- This is especially important if running Eos on a laptop, which may have many network interfaces.

Network Connection Troubleshooting

If all of this is fine, we should confirm that the Mac and Eos can talk to each other at all. To do this, we will Ping the Eos from the Mac.

Open the Terminal app on the Mac (Finder > Applications > Utilties > Terminal)
Type in the following and hit Enter (with the IP address of your Eos):
ping 10.101.92.101
You should see the reply "64 bytes from 10.101.92.101"
If not, you will get the failure message "Request timeout for icmp_seq"

If your ping fails, investigate the cabling between your devices. Ensure both devices think the relevant network interface is online. If there's a switch in the mix, make sure it's happy (powered on, network lights blinking). If it's a managed switch, there may be settings preventing the message getting through. Managed switches are beyond the scope of this article; consult your favourite network expert.

If you're running Eos on a laptop, Windows or third-party firewall rules may be preventing the connection. Ensure that the Eos application is permitted free access to the relevant network interface.

If it still doesn't work, please contact ETC Technical Services in your region, who will be happy to help.

Notes and Additional Information

Now you have a basic overview of how to make Eos talk to QLab, and use OSC to fire a cue. There are other possibilities; most aspects of Eos control are exposed to OSC, so you could use QLab to raise a submaster, bring up a channel, or fire a macro. See the OSC section of the Eos User Manual for details on how to access these functions.

QLab 4 does not natively support TCP client connections

While we have recommended TCP as the best way to send OSC from Eos, QLab doesn't support TCP connections natively as a client. Both programs can receive OSC via TCP but neither program is able to initiate the TCP connection due to both Eos and QLab acting as a server in a TCP connection, leaving them unable to communicate. For this reason it is best to use UDP OSC when communicating with QLab.

QLab 5 supports TCP client connections but closes them after 3 seconds of inactivity

In v5 QLab added support to create TCP connections: Network Cues | QLab 5 Documentation

In v5 QLab creates a TCP client connection when sending Network-type OSC messages to a Server (such as Eos) but then closes the connection after 3 seconds of inactivity. Once the connection is closed, Eos software cannot send messages back to QLab any longer until QLab re-establishes the connection. As such, it is not practical to have Eos software trigger QLab over a TCP connection.

Triggering other OSC Software from Eos

The same principles apply if you're sending OSC to a different program - simply set the correct IP address, port and string to send. You can use the OSC Cue Send String field in the same way as shown above.

For example, let's say we're using the fictional software "Soundzz", which understands OSC, but only in the form "/soundzz/q/label/preshow/start". We can use the label variable in the OSC Cue Send String field, and make sure the Eos and Soundzz cue labels match where necessary.

/soundzz/q/label/%5/start