DMX Overview

DMX Blueprint Template

Motivation

Lately, there has been increasing interest and demand for Unreal in the context of live events and permanent digital installations throughout the world. We have seen numerous executions that have been either partially or totally powered by Unreal. When Unreal was new to this market, it was missing some fundamental and usability features. Despite that, it has been adopted by talented groups willing to build the necessary and missing tools/plugins to push the boundaries of the possible further and achieve their desired creative goals.

The existing solutions in the live entertainment industry are a mix of hardware and software platforms that are scattered, proprietary, and expensive. The tools and production pipelines are convoluted, difficult to use, and often impair the overall creation and production processes.

Epic has decided to tackle this problem by adding support for DMX (Digital Multiplex) data communication through both Artnet and sACN variants. DMX is used throughout the industry to control various devices in the live events industry such as lighting fixtures, lasers, smoke machines, mechanical devices, among others.

Artnet and sACN are network protocols allowing to aggregate and send DMX data over ethernet (IP). Artnet allows sending 32,768 universes down a single network cable. Although it is an older protocol, it is supported by more gear and devices. sACN (streaming architecture for control networks), currently appears more popular and allows you to run 63,999 universes of DMX data down a single network cable.

Use Cases

Here are typical use cases that we have identified around the DMX feature.

Show Previs

The DMX protocol can be used in the input provided to Blueprint nodes and fixtures-type actors, for rapid live show stage previsualization. Live DMX input is used to drive and control enabled fixtures within a 3D UE level. Proper lighting attributes are used for realistic effects so that show designers can iterate in their creative process.

Device Control

The DMX protocol output and Blueprint nodes can be used to talk to DMX-enabled fixtures and devices, which enables controlling lighting consoles or devices from UE.

Content Trigger

DMX protocol input can be used to trigger live effects or animation sequences within UE that are meant to be displayed on a live show alongside lighting fixtures control.

What is DMX?

DMX is a standard for digital communication networks that are commonly used to control stage lighting and effects. It was originally intended as a standardized method for controlling light dimmers, which, prior to DMX512, had employed various incompatible proprietary protocols. It soon became the primary method for linking controllers (such as a lighting console) to dimmers and special effects devices such as fog machines and intelligent lights.

DMX has also expanded to uses in non-theatrical interior and architectural lighting, at scales ranging from strings of Christmas lights to electronic billboards. DMX can now be used to control almost anything, reflecting its popularity in theaters and venues.

While DMX is primarily used to control lighting devices, there are many other forms of hardware that can be driven using the DMX protocol, including the following.

• Special effects hardware
  • Foggers
  • Fireworks
  • Lasers
  • CO2 Cannons
  • Flame Cannons
  • Confetti Launchers
  • And so on.
• Motors
• Power Switches
• Microcontrollers
• And more.

DMX Data

DMX can be thought of as a package of digital information that is being sent from one location (our source) to a different location (or destination). Each package is created at some source with specific information that should be received and read by some recipients. Each packet is structured in a very intentional way and if you would like to know more about how this works on the hardware level, please read the ESTA standards. For our purposes, we are only concerned with the contained data. Each package contains an array of 512 bytes or values that range from 0-255.

In the next section, we will go over how these packets are sent and received.

Technical Details About DMX

By creating an Unreal Engine plugin for DMX which will enable:

1. Native DMX communication in both directions for both protocols (ArtNet and sACN).

2. A complete library of Blueprint nodes.

3. A preliminary UI for describing and building a library of controllers, fixture types, and actual devices.

DMX requires two primary components in order to work:

1. A DMX controller or DMX source.

2. At least one DMX fixture (typically a lighting fixture but it can be any kind of device controlled by DMX protocols).

We do not support USB interfaces.

DMX Controllers

DMX controllers (also referred to as "nodes") act as the signal source or the location at which the DMX signal is created. Additionally, controllers act as the distributor of the data to a set of daisy-chained fixtures. There are two forms a DMX controller can take, a USB/Network interface device or a standard DMX console.

1. A USB/Network interface converts USB signal or IP packets to DMX which is then transmitted out to a set of daisy-chained DMX fixtures.

   

   To view the image source, click here.

2. A DMX console allows the user to manually trigger outgoing DMX and, depending on the capability of the Console, may also be able to receive and broadcast DMX from network packets.

   

   To view the image source, click here.

DMX Fixtures

DMX fixtures are the devices actually responsible for receiving and executing commands based on the data received. This could mean turning a light on or off or rotating the device 90 degrees. There are many sorts of DMX fixtures from standard stage lights that simply turn on and off to intelligent lights that have multi-directional rotation and lighting filters.

Each fixture has a set of attributes/commands that are predefined on the hardware level. These attributes are organized into groups called modes. Many fixtures contain multiple modes which predefine the available attributes the fixture will respond to.

Fixture makers give the user different mode options so that they can cater to a large range of use cases, including as many features as possible while allowing the user to pick and choose which are the most important to them. This results in the simplest, smallest channel count mode; a complex, huge channel mode; and some in-between modes. A lot of the time in professional lighting practice, the intermediate modes are chosen for their balance between features and ease of control, along with more frugal use of the DMX channel count.

Each mode contains a set of attributes. Attributes are responsible for telling the hardware how to respond to the received DMX data. In most cases, you can find all attributes for a particular fixture outlined in the fixture manual provided with the device.

To view the image source, click here.

Refer to the DMX Fixtures documentation for more information.

Universe

A universe consists of a set of fixtures all strung together reading the same data. A universe contains 512 bytes of information, so the number of fixtures in a universe will depend on how many bytes of data are needed to address each fixture.

Signal Communication

Let us next consider how controllers and fixtures talk to each other. Each controller is responsible for one or many universes each of which has multiple fixtures daisy-chained in a long string. A universe can be thought of as a form of identification for a group of addressed fixtures. In order to send data to the proper fixture, you need to also send it to the correct universe.

Once a controller has received the command to distribute a DMX packet, it locates the proper universe and sends a packet of data down the string for each connected fixture to receive and interpret. Each fixture receives the same packet of data and executes an internal command if the packet contains any data that is meant for that fixture. Once the data has been read, it is then passed down the chain onto the next fixture to repeat the process. In order to make sure the fixture is receiving the proper information it must be listening for the right data. This introduces the concept of fixture addressing or "patching", covered more in the next section.

Below you can see an overview of the signal hierarchy and data usage.

• Controllers can be responsible for one or more universes
  • Universes can contain many fixtures daisy-chained together (represented by the full 512-byte array)
    • Fixtures can occupy one or more addresses inside of a universe
      • Starting Address, each fixture has a starting address which determines how the fixture should interpret the received DMX data packet (a single index in the byte array)
      • Attributes, each fixture contains a set of attributes defined by its current mode which each take on an address that is determined by their attribute number (channel) plus the starting address (see the diagram below for an example).

Fixture Patching

The concept of fixture patching comes from the idea that we need to be able to virtually position our fixtures along a communication chain in order to receive the proper data. Since we send full packets of data to be read by multiple fixtures, it is important to have a way of identifying exactly which bytes in the packet should be read and interpreted and which ones should be ignored. This is done by assigning each fixture at a specific starting address in a universe. A starting address can be anywhere between 1 and 512 (the max number of values in our DMX packet). By assigning a fixture to a specific starting address, it then occupies a range of addresses from the assigned starting address through the starting address plus the number of attributes the fixture contains in its current mode.

See the example below:

Fixture 2 current mode = 8ChannelMode (contains 8 attributes)

1. Red (address 8)
2. Green (address 9)
3. Blue (address 10)
4. Strobe (address 11)
5. Pan (address 12)
6. Tilt (address 13)
7. Dimmer (address 14)
8. Macro (address 15)

Starting Address = 8 Address Range = 8 - 15

Using the example above, in order to pan, the fixture will be listening on address 12 for a byte value between 0-255 which will ultimately control the amount the fixture will pan within its defined rotation range.

Attribute Resolution

Most commonly an attribute will operate with an input range of a single byte (for example, 0-255). Occasionally, higher resolution is needed to achieve more precision in movements or lighting control. If this is the case, attributes take on larger input ranges constructed of multiple bytes instead of just one. The combination of multiple bytes results in higher possible values for controlling a particular attribute. Below you can see the possible attribute signal types.

1. 8 Bit Attribute - Min: 0, Max: 255 - Occupies 1 address
2. 16 Bit Attribute - Min: 0, Max: 65,536 - Occupies 2 addresses
3. 24 Bit Attribute - Min: 0, Max: 16,777,215 - Occupies 3 addresses
4. 32 Bit Attribute - Min: 0, Max: 4,294,967,296 - Occupies 4 addresses

When an attribute over 8 bit is needed, that attribute occupies more than one address in the universe. Depending on the resolution, it can occupy multiple consecutive addresses. You can see the number of addresses an attribute will occupy in the list above.

DMX Communication Over Network

As mentioned above in the "Controllers" section, DMX data can be sent in a variety of ways including through USB, IP packets, and directly from a console. Over the past few years, network communication methods have become increasingly more popular and important. As shows get larger and the number of fixtures increases there becomes a greater need for addressing more fixtures in a fast, efficient, and reliable way.

To overcome the channel restriction of DMX while still utilizing its structure, ethernet protocols were developed. These protocols allow multiple DMX universes to be transported over a single Cat5 cable using ethernet technology. There are two primary ethernet protocols that are the most widely used and that UE supports in the DMX plugin, Art-Net, and sACN.

Art-Net

Art-Net is a royalty-free communications protocol for transmitting the DMX512-A lighting control protocol and Remote Device Management (RDM) protocol over UDP. It is used to communicate between "nodes" (for example, intelligent lighting instruments) and a "server" (a lighting desk or general-purpose computer running lighting control software).

More detailed information about the Art-Net protocol can be found on the art-net site.

sACN

Streaming Architecture for Control Networks(sACN) is a standard protocol developed by ESTA to efficiently transport DMX universes over the network. It is comparable to ArtNET in many aspects. One nice thing is the multicast option allowing very easy configuration. sACN is a popular protocol to control a large number of RGB LEDs.

DMX User Types

Design Firms

Alongside architectural firms, AV specialists, and creative agencies, design firms are often mandated in designing overarching creative projects within the Live Events and Permanent Install verticals where real-time sources are used to generate content to be displayed within the physical space.

A design firm's mandate is to produce precise design documents for all parties involved, ensuring that all aspects of the project are delivered following a detailed and well-thought-out plan - minimizing ambiguities as much as possible. They need to know and understand on a high-level basis why Unreal Engine is the best tool for their projects, what its capabilities and limitations are, and how it integrates into the design master plan.

Creative Agencies and Production Companies

Creative agencies and production companies are essentially responsible for designing and executing the creative plan from a production perspective. Making things happen. They are the ones coding and using the Unreal Engine within the scope of the given project. They are your first front-line customers that are leveraging the existing features and possibly enhancing or modifying them for the needs and requirements of their project. They will need to understand inside-out the technical capabilities of such features and be able to use them to achieve a given creative or design objective within time and budget constraints. Sufficiently large creative agencies and production companies are often also the design firms.

AV Technology Specialists

Technicians and technical specialists from the AV industry responsible for speccing, engineering, and commissioning AV systems need to understand in detail how Unreal Engine can be used within those systems alongside other tools and devices. How does it integrate within the suggested AV infrastructure, how can it communicate with that infrastructure, how does it deal with failures, redundancy, or backup systems? These systems need to be addressed as a whole, often in 24/7 mostly automated environments with minimal human interaction.

Protocol Integration

ArtNet and sACN protocols are both integrated from the original source so that all code is internal to Epic. By building from the source we have greater control over how we can use and access library attributes and most importantly, building from a library source allows support for multi-platform usage.

In the Unreal Engine DMX Plugin, cross-platform support for both receiving and sending of DMX data through sACN and Art-Net protocol variants is included. Since both Art-Net and sACN are UDP network protocols, Unreal Engine's pre-existing network messaging features now natively implement each protocol built on top of the Unreal Engine architecture.

For this plugin, the most recent version of the Art-Net protocol, Art-Net 4, is integrated. Art-Net 4 has a theoretical limit of 32,768 universes or Port-Addresses (that is, 32 kiloverses) as opposed to Art-Net 3's universe limit of 256.

For the full Art-Net 4 protocol specification, you can find the official documentation here.

In comparison to Art-Net, sACN is a newer protocol that allows for as many as 63,999 universes.

For published documentation on the sACN protocol visit this link.

DMX Modulators

DMX Modulators are available data manipulation and conversion functions that can be used and applied to either inbound or outbound DMX data.

Input Modulators

Input Modulators are specified under Fixture Settings in the Details panel. You can add as many Modulators as needed. The following is a list of the input modulator options:

• None: No data manipulation or conversion applied.
• CMY to RGB: CMY to RGB color conversion.
• Constant Frame Delay: Delay outgoing DMX data by a specified number of frames.
• Extra Attributes: Set extra attributes on Pixel Mapping cells.
• RGB to CMY: RGB to CMY color conversion.

Output Modulators

Output Modulators are specified in the Pixel Mapping panel. The following is a list of the output modulator options:

• None: No data manipulation or conversion applied.
• CMY to RGB: CMY to RGB color conversion applied to the live input texture RGB pixels.
• Extra Attributes: Set extra attributes that aren’t driven by the live input texture.
• Extra Cell Attributes: Set extra attributes per cell that aren’t driven by the live input texture.
• Pixel Mapping Frame Delay: Delay outgoing DMX data by a specified number of frames.
• RGB to CMY: RGB to CMY color conversion applied to the live input texture RGB pixels.

Feature Guide

This is a high-level list of all features that are part of the DMX plugin.

Send DMX Data from Unreal Engine (ArtNet + sACN protocols)

• The two primary DMX communication protocols (ArtNet and sACN) have been implemented to send DMX over ethernet to 60,000+ universes.
• DMX can be sent directly from Unreal Engine at both runtime and from the editor.

Receive Incoming DMX Signals

Users can create getter Blueprints to allow receiving DMX data from any channel in any universe. A range of delegate events and a DMX component that will return current fixture value data are available to use incoming DMX data. These events can be applied to any actor such as a fixture, and control rotation, color, and so on using the incoming data.

Register DMX Fixtures with Attribute Names and Channel Mappings

Users can add any DMX fixture to their projects with any number of channels. If a fixture preset isn't in the fixture database, users will be able to register their own. Users can also set up channel mappings and register their own attributes to ultimately be used in their own custom Blueprints or the provided default fixture Blueprint actors.

Register DMX Controllers with Universe and Protocol Assignments

Users will be able to add different DMX controllers that are responsible for any range of DMX universes.

Send DMX from Blueprint Attributes

Dynamic Blueprint nodes allow users to execute pre-registered fixture attributes for a specific DMX fixture.

Control DMX From the Editor Using the Virtual Output Console

A custom DMX Console window enables users to test any channel or any range of channels in any Universe directly from the editor.

GDTF Integration

Support for the GDTF file format standard from VectorWorks enables importing numerous fixture types with their attributes. Currently, only importing attributes is supported. Spotlight is their software for Live Show previsualization that is extensively used in the industry.

All of the following features are part of the 4.26 release.

Attribute Naming System

The attribute naming system provides a way of standardizing imported function naming while also providing global access to easily accessible and understandable fixture properties. Prior to UE 4.26 there was no standardized naming convention which required the user to type in function names where needed. The attribute system allows users to simply select from a dropdown list of properties without the need to create a DMX library.

DMX Display Cluster Plugin

nDisplay supports replication for DMX. Enable the DMX DisplayCluster plugin in your project to use DMX with nDisplay clustered rendering.

When the DMX DisplayCluster plugin is enabled, DMX that is received on the primary node in the nDisplay cluster is replicated to all the cluster nodes. You can specify a primary node for receiving DMX that can be different from nDisplay’s primary node. To assign a computer to be the DMX primary node, add the following command-line parameter when launching the instance of Unreal Engine 4 on the computer:

-dc_dmx_master

You can also explicitly assign a node to be a cluster node for DMX, which won’t receive DMX information from external software or hardware. To assign a computer to be the DMX cluster node, add the following command-line parameter when launching the instance of Unreal Engine on the computer:

-dc_dmx_slave

DMX Sequencer Feature

DMX can be controlled from Sequencer. With this feature, you can add a range of patches from a DMX library into a Sequencer Track, from which you can program keyframes to output DMX to virtual or physical fixtures.

For more details on the Sequencer integration, refer to DMX Tracks.

DMX Recording

IIncoming DMX can be recorded so that users can use both a physical DMX console and Unreal Engine to build out their show.

DMX Remote Control Feature

You can control properties remotely in the engine with DMX through Remote Control. Refer to Remote Control Protocols for more details.

Pixel Mapping

This feature lets users sample the pixels of a user-specified texture and output the color sample as DMX to a variety of DMX types.

Unicast/Multicast Output

This feature provides additional DMX communication methods for specifying send destinations.

Improved DMX Library UI

Fixture Type Panel

The Feature Type panel separates fixture details, modes, and functions/attributes into separate columns for improved organization and visualization.

Fixture Patch Panel

The Fixture Patch panel is an interactive visualizer for addressing fixture patches to an IP address and universe.

Improved DMX Output Console and Input Monitoring

The Output Console and DMX Monitor tools have been moved outside the DMX Library.

Output Console

Offers quick fader addition tools and enables using macros for quickly testing and controlling faders.

Input Monitoring

The multi-universe DMX monitor tool enables listening to any incoming DMX on any universe.

Matrix Fixture Support

DMX can be sent to and received from multi-cell fixtures through blueprints, sequencer, and the take recorder.

Modular DMX Fixture Blueprint Templates

DMX Stats

DMX send and receive statistics can be displayed to the screen.

DMX Input and Output Refresh Rate