RS-232 DMX Engine

The Engineering Solutions RS-232 Driven Double DMX Engine

System Overview

architecture.jpg

The RS-232 DMX Engine is a self-contained DMX controller. It accepts simple, human-readable commands via RS-232 and uses these commands to generate, recall and crossfade between DMX scenes. Incoming serial data is buffered in the system’s memory until a carriage return is received, which signifies the end of a command.

Once the command has been received, it is parsed. Commands containing syntax errors are ignored, and an error message is transmitted back to the RS-232 host. Valid commands are processed immediately.

Commands can contain information directing the system to

  • Set DMX channels to certain levels. The entire universe of 512 channels is available.

  • Store scenes (a snapshot of the DMX output buffer) in memory.

  • Recall scenes from memory using a very simple command syntax.

  • Fade between different scenes. The system automatically calculates all intermediate DMX

    channel values, and requires only a crossfade time from the end user.

  • Report the state of any DMX channel back to the user via RS-232.

More significantly, commands may be processed simultaneously, with the only limit being (a) the RS-232 port speed and (b) the 512-byte receive buffer. This means that, for example, a group of channels can fade between levels at one rate while a second group of channels can fade to different levels at a completely different rate.

Users of high-end theatrical lighting consoles may recognize this feature as ‘simultaneous cue stacks,’ and it adds a great deal of flexibility to the system’s operation.


Power Supply

9-15v DC, 200 mA, center positive. Barrel size is 2.1 x 5.5 mm. System ships with a switching power supply, 9V DC output, 300 mA, 80-240V AC input. It will work worldwide, though an adapter for the two-pin American-style plug may be required. Check a travel shop, or ask at a hotel’s front desk if they have any in Lost & Found.

DMX Output

Standard XLR pinout per USITT. We use only official Neutrik XLR jacks.

  • Pin 1 ground

  • Pin 2 Data -

  • Pin 3 Data +

  • Pins 4 & 5, of XLR5 jack is installed are not connected

  • Each DMX output is driven by its own transmitter.

Serial Command Protocol

Baud Rate: 9600, 19,200, 38,400, 57,600 or 115,200, 8N1, user selectable. Default is 115,200.

  • Pin 2 is system transmit

  • Pin 3 is system receive

  • Pin 5 is ground

DB-9 connector pin 4 (DTR) is used to update the system’s firmware. This allows new features to be added in the field, without requiring the hardware to be shipped back to our shop. If asserted (set high) by the PC or other controlling equipment, the system will wait in ‘reset’ mode for new firmware and the system will neither accept serial commands nor output DMX. In normal use, either physically disconnect this wire or ensure that DTR is cleared.

Depending on which external devices is sending the RS-232 data, a crossover cable (which swaps pins 2 & 3) may be required. When connected directly to a PC, a ‘straight’ cable works properly. 


In the following pages, the text [cr] is used to represent a single data byte, the carriage return. This value is decimal 13 or hex 0x0D.

Many screenshots show data sent / received through a terminal program, as well as a screenshot from a DMX monitoring program. Data sent from the PC to the system is displayed in green text, and data generated by the system is yellow. Thus, system output can be easily compared with RS-232 input.


Drivers & Supported Platforms

Any control system with an RS-232 port can easily communicate with the DMX Engine. Over the years, our customers have used all major platforms (Crestron, Lutron, AMX, Savant, Universal Remote, RTI), industrial PLCs and even custom software written in any number of languages. 

We've tried our best to make the protocol open, stable and straightforward to use.

Though it's fun to roll your own, sometimes it makes sense to hit the ground running. Pre-built drivers for many platforms are readily available. Unfortunately, here in the shop we don't have the resources to do this work ourselves.

For Control4, we recommend the excellent driver written by Domaudeo and distributed through Blackwire

c4.jpg


Savant users can find the DMX Engine in their device library. One of our customers was kind enough to push their files back up through that ecosystem, so they're available for all.


urc.jpg

Universal Remote / Total Control developed an in-house driver which is now available, contact them for details at https://www.universalremote.com/support/ or  www.urcportal.com

Double DMX Engine w/ 2 x RJ45 outputs: https://urcportal.com/Main/ProductListDetail/8264

XLR3 / XLR5 outputs: https://urcportal.com/Main/ProductListDetail/8263

Dealerscope press release: 

https://www.dealerscope.com/article/urc-announces-integration-of-dmx-lighting-control-systems/


An Elan driver is being developed right now as well, check with us for more details.

 

 

 

Troubleshooting

Based on a distillation of support telephone calls, we’ve collected common startup hurdles into a single document which should prove useful to other users.

First, consider these points:

 

 

 

 

Our standard telephone troubleshooting steps look like this:

1. Does the power light turn on? If no, consider a different power supply.  We recommend 9-12v DC, center positive, 300 mA or greater supply current. Barrel size is 2.1 x 5.5mm, which is a global standard.

2. With no RS-232 or DMX cables connected, do the RS-232 and DMX LEDs first flash and then resume their normal operation? If yes, move to step #3. If no, contact Engineering Solutions for more information.   

3. Load a copy of RealTerm on a convenient PC, then connect the DMX engine using a straight serial cable and either a USB/serial bridge or an on-board RS-232 port. https://sourceforge.net/projects/realterm/

step1.jpg

In RealTerm, choose the ‘port’ tab and open a connection at 115200 baud.  When a connection is properly opened, the speed and port number will appear in the very bottom right corner of the RealTerm window.  

step2.jpg

Choose 'half duplex' so that communication to and from the box will be called out in different colors.

step3.jpg

In the ‘pins’ tab, make sure that the green checkbox near DTR / pin 4 is de-selected.  After a power cycle OR a DTR set / clear cycle, a startup message will appear in the terminal window. If the message appears, we know that at least the RS-232 RX line is good. 

step4.jpg

Choose the ‘send’ tab and type the string Q1-10 in one if the text entry areas. Check the ‘+cr’ box to the right of the text box and click ‘Send ASCII’.  The box will reply with the state of the first ten DMX channels.

At  this point, the box is stable.  Pins 2, 3 and 5 are connected properly.  The next step is to move upstream and recreate this same setup in Control4 / Crestron / AMX / etc.

 

Other thoughts:

 

 

 

 

In our online store, we sell a molded 6' RS-232 cable which has only pins 2, 3 and 5 connected end to end.

Command Syntax

Here's how to talk with the box.

Command Syntax

Overview

In the following pages, the text [cr] is used to represent a single data byte, the carriage return. This value is decimal 13 or hex 0x0D. All commands are terminated with a carriage return.

Also, in the following pages some syntax may be provided in code blocks, like this:

This is code in a block. 
It's how our online markdown language calls out this type of text. 

--! Note the grey '1' and '2', etc in the far left column. !--

These are line numbers for reference only. Don't include 
them in actual commands!

Some sample real RS-232 commands just for reference:

C[cr]
G0@255:0[cr]
G1-10@100,11@238:35[cr]
B115200[cr]

 

Command Syntax

Group Command

If you're starting from scratch, most of the engine's functionality can be accessed through the G command. It doesn't require leading zeros like 'A' or 'F' and includes other syntax for controlling large groups of channels in a single command.

Occasionally it is useful to set a large group of DMX channels to the same level. While this can be accomplished using the standard ‘F’ or ‘A’ commands, the new ‘G’ command allows the channels to be adjusted in a less verbose way.

GA-B@C:T[cr]

This command sets channels in range [A B] to value C and crossfade time T. A and B are valid between [1 512] and leading zero is not required. C is the channel value, range [0 255]. T is the time, in tenths of a second, for the crossfade to take place. Range for T is [0 999] or 99.9 seconds maximum.

Example: Set DMX channels 37 - 126 to 50% over 7.6 seconds:

G37-126@127:76[cr]

Or, set every 'S'th channel to a level. This is useful if, perhaps, there are multiple RGB LED tape dimmers in a single room, and you'd like to set all of the red channels to the same value:

GA-B/S@C:T[cr]

As above, but the slash and S allows for a group of channels in a particular pattern to be set. For example, if a group of RGB fixtures had sequential start addresses (1, 4, 7, 10...) the red channel in each fixture could be controlled easily, skipping through the array.

Example:

5 RGB fixtures are sequentially connected, and the first start address is 100. Turn on all the green and blue elements over 2.5 seconds:

G101-114/3@255:25[cr]  <--- this sets channel 101, 104, etc which is probably RED
G102-114/3@100:25[cr] <--- this sets channel 102, 105, etc which is probably GREEN

Fixture #

Channel

Value (Red)

Channel

Value (Green)

Channel

Value (Blue

1

100

0

101

255

102

100

2

103

0

104

255

105

100

3

106

0

107

255

108

100

4

109

0

110

255

111

100

5

112

0

113

255

114

100

Finally, multiple sub-commands can be chained together in the same command, separated by commas and ending with a fade time. As above, the syntax is Gchannel@value,channel@value...channel@value:time[cr]

G1@255,3@127,12@10,27@255:24[cr]

Secret shortcut: Using 0 as the channel is the same as 'all call', or channels [1 512]. An easy way to turn on all connected equipment for a sanity check is to use a command like G0@255:0[cr] or perhaps G0@0:0[cr].

 

Command Syntax

Build a New Scene (F)

Building a New Scene

This command is useful but tricky. ANY CHANNEL not specifically called out in a control string is set to zero. If you're starting from scratch or writing your own driver, in general it's easier to use the A (add) command or (group) command instead. However, there are legacy systems out there with programming based on F, so it's included here for reference.

A common tech support call has the gist of "I sent a command and it worked perfectly, then I sent a second command and all the first lights turned off. What's wrong?"  Don't use F unless you know exactly what you're doing.

                          FXXX@YYY:TTT[cr]
                  FXXX@YYY,AAA@BBB,CCC@DDD:TTT[cr]
  • F is a capital F

  • @ is the ASCII 'at' character, hex 0x40

  • XXX, AAA, CCC are three digit DMX channel numbers with range [001 512]. As only channels

    1-512 exist in a typical DMX universe, channel 000 can used to select all channels.

  • YYY, BBB, DDD are three digit channel values with range [000 255] (:) is the ASCII colon character,

    hex 0x3A


  • TTT is a three digit time value, in tenths of a second, range [000 999]

  • [cr] is the carriage return character, decimal 13 or hex 0x0D.

For example, following the completion of these (one with a zero fade time, one with 2.4 seconds and one with 1.0 second crossfades):

F001@100:000[cr]
F010@128,011@127,012@126:024[cr]
F007@010:010[cr]

... the DMX output buffer would have the following values:


CH1 - CH6: 0

CH7: 010

CH8-CH512: 0

Command Syntax

Build A Scene (A)

The A command allows new channel:value combinations to be stacked on the existing DMX output universe. This command adds to what's currently being output. In Photoshop, it's similar to creating a new layer. Nothing below is affected, the A command just adds new channel:value information to the existing scene.

If you're starting from scratch or building your own driver, use the G (group) command instead. It's easier to design with because leading zeroes are omitted and the syntax is more powerful.

AXXX@YYY:TTT[cr] 
AXXX@YYY,AAA@BBB,CCC@DDD:TTT[cr]
  • A is a capital A

  • XXX, AAA, CCC are three digit DMX channel numbers with range [001 512]

  • YYY, BBB, DDD are three digit channel values with range [000 255]

  • TTT is a three digit time value, in tenths of a second, range [000 999] 


     

  • For ‘A’ commands, the channel:value information contained in each string adds to data in the DMX output buffer. Higher values take precedence. Thus, lighting data may be added to existing scenes a few channels at a time. In a photo editing application, this process would be similar to adding layers to an image.

  • Leading zeros are required.


If a channel is not specifically mentioned in an A command, its value remains the same as it as before the command was processed.

If the following commands were transmitted:

F001@100:000[cr] 
A002@255:000[cr]
A010@128,011@127,012@126:024[cr]
A007@010:010[cr]

... the DMX output buffer would have the following values:

CH1 : 100
CH2 : 255

CH10 : 128 

CH11 : 127 CH12 : 126 CH7 : 10

Command Syntax

Jog a Channel

Individual DMX channels may be jogged up and down. In this mode, it is not required to know the channel’s exact value. Rather, it can be added to or subtracted from in arbitrary amounts, up to the limits of 0 or 255. This command may be useful when implementing bump buttons on a human interface control panel.

If a channel is jogged past the maximum or minimum values allowed in DMX, the command is ignored.

JN:X[cr] 
JN:-X[cr] 
JN:+X[cr]

 

  • J is a capital J
  • N is the DMX channel number, range is [1 512]

  • X is a decimal number, either positive or negative, range [1 255]

  • [cr] is a carriage return.

Command Syntax

Store a Scene

Up to 63 DMX scenes may be saved in memory. A scene is a copy of the current DMX output buffer. This memory is permanent and will survive a power cycle.

Typically, a group of 'G, ‘F’ or ‘A’ commands will be used to build a particular lighting scene. Once the desired look has been achieved, it can be stored in memory for future use. This greatly reduces programming and execution time.

There are no write protect settings. Any scene may be, at any time, re-recorded with an M command. Previously stored data in that memory bank will be replaced.

MXXX[cr]

For example, following the completion of these commands:

F001@100:000[cr]
A002@255:000[cr]
A010@128,011@127,012@126:024[cr]
A007@010:010[cr]
M22[cr]

... the DMX output buffer would have the following values:

CH1 : 100

CH2 : 255

CH10 : 128
CH11 : 127
CH12 : 126
CH7 : 10

...
and memory bank #22 may be recalled at any time in the future.

 

 

Command Syntax

Recall a Scene

Recalling a Stored Scene

                            SXXX:TTT[cr]
  • S is a capital S

  • XXX is the desired scene number, valid range is [1 063]

TTT is the scene crossfade time, valid range is [000 999] tenths of a second 


Up to 63 DMX scenes may be saved in memory. This memory is permanent and will survive a power cycle. Scenes may be recalled from memory and faded in over a specific time. Scene recall commands overwrite the DMX output buffer with stored data. Using this basic command, all channels are changed from their ‘live’ value to that which was stored in memory.

Example: recall stored scene #1 instantly:

S001:000[cr]


Example: crossfade from the current DMX output buffer with the contents of scene 32 over 5.7 seconds:

S032:057[cr]

However, in some instances it is desirable to recall a stored scene, but only apply it to part of a DMX universe. For example, consider a three-room home automation installation. Each room uses 15 channels of DMX for RGB accent lighting. It might be useful to recall a scene but only apply that data to a specific range of DMX channels. One room can change color while leaving the other rooms unaffected.

For that purpose, the S command can be overloaded with mask values:

                          SXXX:TTT,L,H[cr]

In this case, L and H represent the lower and upper bounds of the DMX channel range to be copied from system memory to the constantly repeating DMX output buffer. Other valid commands could include:

 

S6:030[cr] Recall scene six, three second crossfade.

 

S6:030,10,30[cr]As above, but only copy channels between 10 and 30 from memory to the DMX output buffer.

 

S6:000,100,150[cr] As above, but only copy channels 100-150 from memory to output. All other channel information carries through. Zero fade time.

Command Syntax

Set Startup Scene & Timeout Delay

It may be useful for the DMX engine to auto-load a stored scene immediately after a power cycle. Often a control system may take tens of seconds, or even several minutes, to restore its state after an unplanned outage. For this reason, the DMX Engine can load a pre-saved scene immediately after power is applied.

Syntax

UX,T[cr]

U?[cr] 

Examples

U1,5[cr] Load scene #1 five seconds after a power cycle

U0,0[cr] Change to zero startup scene. All DMX channels are zero until the connected equipment (Crestron, AMX, Control4, etc) sends commands:

Where

  • U is a capital U

  • X is the pre-saved scene number, [0 60]. Leading zeros not required.

  • If X = 0, no scene will load and system will run normally. The default startup behavior is to set all

    channels to zero. If X is set to zero, T should be zero as well.

  • X is followed by a comma [,]

  • T is the approximate time, in seconds, the system will wait after startup to load the scene. DMX

    output will be live and the system will respond to commands during this period. If any regular serial command is received during this time, the startup scene will not be recalled. Value here is [0 255], leading zeroes not required.

  • [cr] is a carriage return, hex $0D or decimal 13.

  • U?[cr] queries the startup scene status, and an ASCII string is returned to the user.

     

Notes:

  • Prior to defining a startup scene, the scene should be built and stored using the regular 'G', ‘F’ or ‘A’ commands, then stored with ‘S’. 

  • An uninitialized scene will probably / possibly default to ‘all channels on.’ This is because a raw-

    from-factory memory chip is loaded with ‘255’ or ‘0xFF’ as values. So be careful what you choose

    to load without first pre-programming.

  • The timing value ‘T’ is approximate and may vary by +/- 10% or so.

     

 

Command Syntax

Selectable DMX Output Speed

By default, the DMX engine transmits full-speed, full-frame DMX, and speeds close to the maximum available by the USITT spec. Unfortunately, we’ve learned that some DMX LED fixtures, particularly Amazon / eBay / Alibaba ‘bargain bin’ specials, have a hard time keeping up with this datastream.

To generate DMX with relaxed packet and inter-byte timing, ~ 15 frames per second, send the command:

Slow[cr]

For full frame DMX at ~40 frames per second, send the command:

Fast[cr]

The output speed command survives a power cycle. Immediately after a command is received, the system will reboot. The reboot process takes 2-3 seconds to complete. The DMX LED on the chassis will flash in sync with DMX packets, providing additional user feedback of the current setting.

For a more in-depth discussion of this issue, please visit www.response-box.com/gear/decabox-dmx-slowdowner/

Command Syntax

Query DMX Channel Values

Sometimes it's useful to check the state of DMX channels..

QXXX-YYY[cr] 
QA[cr]
Q100-100[cr]  <-- Query a single channel
Q70-35[cr]
Q35-70[cr]

QA[cr]  <-- Returns a list of all DMX channel:value combinations
This can take a while to transmit, depending on
system baud rate.