Triggering with UDP

Introduction

Two common methods of transmitting information on a network are UDP and TCP. With TCP, messages are sent directly from one device to another, with the requirement that the receiving device sends a message back to verify it has received the message.

In situations where a message simply needs to be sent, and there need not be any verification back the other way, UDP is a simpler choice. With UDP, one device may still send a message to another device directly with unicast, which means sending it directly to the other device’s IP address. However, with UDP, one device may send a message to many devices at the same time via multicast or broadcast.

What are triggers?

Many Advatek products have support for creating triggers for various purposes. A trigger is essentially an action or a series of actions that are pre-defined to occur when an event is detected. The event can be internal, like when the device starts-up, or it can be external, like a DMX channel meeting a value or a UDP message being received.

In the context of UDP, the Advatek device can listen for a pre-defined message and, when this message is received, it will then proceed to complete the action that is defined.

In the context of lighting control systems, the UDP messages are commonly a string of text, which can be encoded in multiple ways but are often comprehendible English, like “PLAY_SCENE_12”, or “RECORD_2_MINS”.

For the above examples,

• The UDP message “PLAY_SCENE_12” could then trigger the Advatek device to begin playback of Scene 12, and perhaps loop forever, or
• “RECORD_2_MINS” could trigger the Advatek device to immediately start recording for a duration of two minutes.

The exact contents of the UDP message are entirely up to the user and can be entered into the Advatek device to tell it what to listen for.

How to generate UDP messages

When it comes to setting up an external device to send UDP messages, there are many options to choose from. There are applets and short programs to simply input a string and click send, or there are much larger programs where a custom user interface can be created with buttons and sliders, and UDP strings can be mapped to the interface.

Two options of these larger programs that are commonly used are TouchOSC and Kiosc by Visual Productions, however there are many more to choose from!

See the Integrating TouchOSC with PixLite Mk3 article for in-depth example.

If you’re unsure whether another device or software is compatible, contact our team.

Step 1: Set up your UDP generating software / system

Regardless of which option you choose to generate your UDP messages, there will typically be the following settings you’ll need to make sure are correct.

UDP Port Number

The software will send messages on a specific port number. The port number used for the triggering must not be used for other network data on the devices that send and receive triggers. The port number may or may not be configurable in your generating system. If it is configurable, then choose an available port to communicate between the software and the PixLite. If it isn’t, then the software’s vendor will likely document which port it will use.

It is important to only use UDP port numbers that are available, and not reserved for another purpose. Some port numbers are used by the Advatek devices for other network data, and so cannot be used. These reserved ports are currently: 0, 68, 5568, 6454, and 49151. Don’t worry, our devices will prevent you from entering something invalid when you get to that step later.

IP Address

As mentioned earlier, a UDP message may be sent directly to a device or to multiple devices.

If you only want these triggers to be sent to a single Advatek device, configure the IP address of the Advatek device in your trigger generating system.

If you need to trigger multiple Advatek or other devices, the simplest way to achieve this is to send the trigger messages to the entire local network. In this situation you may broadcast the UDP traffic to an appropriate broadcast address. 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.

UDP Message

If you can enter plain English characters, choose a string of text that is meaningful for your purpose and enter this into the generating software you’re using. Your message is probably being encoded as ASCII characters in this case. However, even though the message may be as simple as a string like “Hello World”, the software may send the message in a unique way by including padding or termination, or even by using a protocol like OSC over a UDP message.

A UDP message may instead have binary contents, but that is unlikely in these applications.

Step 2: Setting up your Advatek device

Create a UDP Trigger Source

In the Advatek device, navigate to where the triggers are configured. From here, you can add a "UDP Port" Trigger Source and enter in the Port Number that was chosen in the UDP generating software or system. The source can also be given a nickname, to help keep track of multiple sources. For example, you might enter the name of the sending software or system here.

Once you’re happy with the source, go ahead and “Apply” or “Save” the changes.

Create a Trigger

Add a trigger and set the Trigger Event Type to “Trigger Source Pattern”. Select the trigger source that was created above, and then go on to enter in the UDP message from your source system that will cause the trigger to fire.

In most situations, selecting “Starts With” and simply entering in the message as plain text will be sufficient. There are more advanced settings that can be configured, if required. These are explained below.

• “Starts With” will fire the trigger when any received UDP message starts with the configured message. “Exact Match” will only fire the trigger when a received UDP message is exactly equal to the configured message. “Starts With” may be more helpful if the end of a string is unknown and may contain special characters for padding or termination. If more control is required, then “Exact Match” may be useful.
• If “Exact Match” is used, then there are a few special characters that can be inserted. These are common characters for padding and termination, which include:
• • NUL (Null – 0x00)
  • CR (Carriage Return – 0x0D), and
  • LF (Line Feed – 0x0A)
• There are two formatting options available. “Plain Text” allows UTF-8 characters to be entered. This is useful for entering a text string to match. A Hex editor is also available which is useful for entering any arbitrary message, including binary content.

Remember to “Apply” or “Save” the changes.

Step 3: Test the UDP Triggers

You should now be able to use your chosen software to fire the triggers. Test that the triggers are working and enjoy having full control over UDP!

If the trigger is not quite working, then there may be issues with how the port number or UDP message has been entered in your trigger. If OSC is being used, then the actual contents of the UDP message may include padding or other characters to meet the OSC protocol. For more information, see the example in the article: Integrating TouchOSC with PixLite Mk3.

There may also be the need to check Firewall settings to ensure communication from the UDP generating software is permitted to be sent.

An example of a trigger in a PixLite A4-S Mk3 is shown below: