VERSION 0.

5 BY DAVID BUTLER
WWW . THEIMPERSONALSTEREO . COM

INDEX !"#$%&'(#!%") #+,)&-.)/$%#%(%0) 2,##!"2)&-.)!")#%3%'#)%4)-5.) 4%$-7)%4)&5#5) '7!"2)#+,)%9:,(#7) !-/<&-.<8#%=6) !-/<&-.<=6#%8) !-/<&-.<5$#",#!") !-/<&-.<5$#",#%'#) !-/<&-.<&,4!.) !-/<&-.<2,#) !-/<&-.</$,4!.) !-/<&-.</'#) !-/<&-.<$,5&) !-/<&-.<$29(-B) !-/<&-.<C$!#,) *! 1! 6! 8! ;! =>! ==! =?! =*! =1! =@! =6! =A! =8! =;! ?>!

INTRODUCTION
imp.dmx is a cross-platform collection of Max/MSP/Jitter abstractions for dealing with DMX data in various forms. It focuses around the use of jitter matrices to store data, which the objects then read and write to. The aim is to provide the bridge between your patch and whatever object or method you use to output DMX from Max. The abstractions use native Max objects only, excepting the Art-Net patches which use some custom java networking objects, included in the distribution package. If you have any questions or suggestions, please contact me at david@theimpersonalstereo.com. Check for updates at http://www.theimpersonalstereo.com.

FUTURE DEVELOPMENT
The roster of abstractions included in imp.dmx will increase in future versions. The following is a list of abstractions likely to be included in the next version: imp.dmx.test Quick, general purpose DMX testing functions. imp.dmx.blackout An easy switchable blackout function. imp.dmx.midiin Convert MIDI CC values to DMX channel values. imp.dmx.midiout Convert DMX channel values to MIDI CC values. imp.dmx.oscin Convert OSC information to DMX channel values. imp.dmx.oscout Convert DMX channel values to OSC information. imp.dmx.map~ - Map a signal level to a DMX value. imp.dmx.pixelmap Map an RGBA jitter matrix to DMX values.

LICENSING
Everything included in this package is released under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported license. This means that you are free to share and adapt the package, however you must credit the original work to David Butler / The Impersonal Stereo, and distribute the resulting adaptation under the same or a similar license. You may not use this work for commercial purposes (any venture where the primary goal is profit) without permission. If you wish to do so, please contact me at david@theimpersonalstereo.com. For the full terms of the license, see http://creativecommons.org/licenses/bync-sa/3.0/.

THE DMX PROTOCOL

DMX is a serial protocol used to control stage lighting devices. The data carried by the protocol is essentially a list of up to 512 8-bit integers (0-255). Whilst this was originally intended to simply map to light intensity across a number of lights, with the rise of intelligent and automated lighting a channel value can be mapped to any number of things, such as colour-mixing, pan/tilt, fan speed, etc.

T HE DMX S IGNAL
o A single cable carrying DMX can have up to 512 channels of information. Thats 512 integer values between 0 and 255. This is called 1 universe of DMX. o A full universe of DMX is transmitted at a maximum refresh rate of 44 Hz. This is sufficient for nearly all applications. However if a faster refresh rate is desired, it can be achieved by transmitting only a partial universe of data.

C ONNECTING DMX
o DMX connects to lighting fixtures with 5-pin XLR connectors, or 3-pin XLR connectors on cheaper or non-pro equipment. 5-pin is preferable however, as it prevents audio cables and DMX cables from becoming confused. Adaptors can be used to convert between 3 and 5 pin connectors. o DMX cable is actually physically different to audio cable (it has a different resistance value, more similar to Cat5 cable), so audio and microphone cables should not be used to carry DMX data. o DMX is connected in a daisy chain. Each lighting fixture will have a DMX in and a DMX out, which should be connected to the next fixture. A maximum of 32 devices can be connected in one chain before the signal starts to degrade. o At the end of a DMX chain, a terminator should be connected to the final DMX out. This is simply a male XLR connector with a 120! resistor connected between pins 2 and 3. This is to prevent electrical reflections of the data causing errors along the chain. o A DMX signal should never be split using a Y-splitter cable or similar passive device. To distribute 1 DMX signal over multiple cables, an active distribution box is required. o The last five points are recommended practice. However, in 99% of scenarios (especially small rigs), not using a terminator, or using audio cable instead of DMX cable is still going to work. Its just less reliable, so its a much better idea to follow the rules and have the right equipment. If youre in a fix though, you can cheat a little.

DMX O VER IP
o DMX data can be transmitted in other ways, for example, using IP protocols such as Art-Net. This allows conventional IT equipment such as routers and switches to be used and to transmit data over Cat5 cable. (and also over wireless networks). However, the data must be transferred back to DMX at some point in the signal chain in order to connect to the lighting fixtures. o The Art-Net protocol is supported by nearly all tools for processing DMX in software as it negates the need for a specialised hardware device connected to the computer.

A DDRESSING IN DMX
o Channels in DMX are numbered from 1 to 512. There is no channel 0. o An important concept to grasp is that of the start address. Whilst DMX consists of 512 values, many lighting fixtures will read multiple channels at once. Therefore a start address is set on each fixture, which tells it the address of the first channel it should start reading data from. For example, for a fixture that requires 3 channels, given a start address of 45 it will read data from channels 45, 46 and 47. o All the data transmitted is accessible from each fixture, so two fixtures can be given the same start address if they will always be performing the same function.

T YPES OF FIXTURES
o Dimmers will use 1 channel per dimming circuit (bear in mind however that you may be able to connect more than one light to a single dimming circuit depending on its power rating). o LED lights vary, but will usually use a channel for each colour of LED in the fixture (most often RGB), perhaps with an extra channel for master intensity. o Moving and automated lights will use a complex layout of channels for whichever parameters they have, intensity, pan/tilt, strobe, colour mixing, iris, zoom, focus, effects, gobos, etc. Every fixture is different and some can use more than 30 channels. o Generally for any complex fixture, to determine what data goes where, download the manual from the manufacturers website. Contained within this will be a DMX specification which lists how the parameters are mapped to the channels. o In complex DMX specifications, sometimes a single parameter uses two channels, as a coarse and fine control.

GETTING DMX IN TO/OUT OF MAX

Please see the hardware examples folder in the distribution package for examples on how to use imp.dmx with these interfaces.

H ARDWARE I NTERFACES
Enttec DMX USB Pro http://www.enttec.com/dmxusb.php The Enttec DMX USB Pro is a small black box with male and female 5-pin XLR connectors, and a USB type B socket. It supports both transmission and reception of DMX, although not simultaneously. It has 1500V isolation between the XLR and USB connectors, meaning the connected computer will not be affected in case of any power surges. To use this device with Max, an external is available for purchase from Olaf Matthes (http://www.nullmedium.de/dev/dmxusbpro/). This allows transmission and reception of DMX in the form of channel/value pairs (prefixed lists). Anyma DMX http://www.anyma.ch/research/udmx/ The Anyma DMX is a very simple device in the form of a cable with a female XLR connector on one end and a USB plug on the other. It supports transmission of data only, and is not electrically isolated, meaning the connected computer will be damaged in the event of a power surge. A max external to communicate with this device is available for free download from the above link. CDS LanBox-LCX http://www.lanbox.com/products/LCXDataSheet.html The CDS Lanbox is a more sophisticated and feature-rich device than the hardware listed above. It has the ability to function as a stand-alone unit, and connects via UDP to a LAN. The device also features MIDI input and output, analog inputs, digital outputs up to 20mA, and numerous other features. However, for DMX the device can only transmit at 20Hz. For a full specification, see the above link. Max externals to transmit data over IP to the LanBox are freely available from http://www.lanbox.com/downloads/downloads.html.

S OFTWARE I NTERFACES
Art-Net http://www.artisticlicence.com/WebSiteMaster/User Guides/art-net.pdf Art-Net is an open-specification IP protocol developed by Wayne Howell of Artistic License. It is supported by most network-aware lighting fixtures and equipment. It allows transmission of up to 40 universes (theoretically, realistically 20) of DMX data over a single network connection. However, to connect to the majority of lighting fixtures, data must be converted back to serial DMX at some stage. Various pieces of hardware are available for this job, but perhaps the cheapest option for a single universe is the Enttec ODE, available from http://www.enttec.com/ode. Open Lighting Architecture http://www.opendmx.net/index.php/Open_Lighting_Architecture OLA is a free service for OS X only to allow multiple applications on the same computer to output DMX to a central location, which deals with hardware and IP transmission. It supports a large range of hardware interfaces, more than are supported in Max alone. For a full compatibility list see the above link. It also supports numerous IP protocols other than Art-Net, such as ShowNet and sACN. To send data from Max to OLA an external is available, developed by Daniel Edgar with assistance from Simon Newton and myself. This is available for download from http://code.google.com/p/olaoutput/. For instructions see http://www.opendmx.net/index.php/OlaOutput_Max_External. There is currently no solution for receiving data from OLA in Max.

FORMS OF DATA
imp.dmx deals with DMX data in Max in various forms. Here is an explanation of what they are:

J ITTER M ATRIX
This is a standard jitter matrix configured to store DMX data. The matrices used by imp.dmx are one-dimensional, single plane char-type with 512 values. All abstractions default to referencing a matrix named imp.dmx, which will be sufficient when dealing with a single universe of DMX. However, for people that wish to use multiple universes, all abstractions that deal with jitter matrices support the @matrix attribute which specifies the name of the matrix referenced. All matrices are just standard jitter matrices with a particular configuration to make it more convenient to use them to store DMX. You can still access them using a normal jit.matrix object.

L IST O F C ONSECUTIVE V ALUES

This is a simple list of up to 512 int values between 0 and 255 in the order of their DMX channel addresses. It does not have to start at channel 1.

C HANNEL /V ALUE PAIR

This is a list of two ints, the first specifying a DMX channel, and the second the value.

P REFIXED L IST
This is a list of channel/value pairs. It can be up to 1024 values long, as with a maximum of 512 values each will also require a channel address.

GUIDE TO THE ABSTRACTIONS

O BJECT L IST
The majority of the abstractions can be put into pairs, where one performs the opposite function to its partner. imp.dmx.read reads a list of consecutive DMX values out from a matrix. imp.dmx.write writes a list of consecutive DMX values into a matrix. imp.dmx.get gets the values of specified channels from a matrix. imp.dmx.put puts specified values into specified channels in a matrix. imp.dmx.prefix prefixes channel addresses to a list of consecutive DMX values to create a prefixed list. imp.dmx.defix creates a list of consecutive DMX values from multiple lists of channel/value pairs (prefixed lists). imp.dmx.artnetin broadcasts an inputted list of consecutive DMX values over IP using the Art-Net protocol. imp.dmx.artnetout receives Art-Net broadcast DMX and outputs it as a list of consecutive DMX values. imp.dmx.8to16 converts a single 16-bit int into two 8-bit ints, the MSB and LSB. imp.dmx.16to8 converts two 8-bit ints into a 16-bit int, using them as the MSB and LSB. imp.dmx.rgbcmy converts RGB values to CMY or vice versa.

T IPS
o For abstractions that use the jit.matrix object, remember to use qmetro rather than metro. o An appropriate time value to use for metro and qmetro objects is 22 ms. This is because the DMX maximum refresh rate is 44 Hz. 1000ms / 44 = 22.72. Therefore by using 22 ms the patch will always refresh before the hardware device is ready to send. o If youre dealing with a DMX matrix using a jit.matrix object alone, remember that the cell numbers are always one less than the DMX channel, as cells in a matrix are numbered from 0. o For a simple project, the best strategy is to set up an output patcher, which constantly converts from a DMX jitter matrix to the format your output method requires, and then use other abstractions elsewhere in your patch to write into this matrix. This way you maintain a central data store and will have a continuous DMX output.

IMP.DMX.8TO16
D ESCRIPTION
imp.dmx.8to16 converts two 8-bit values (0-255), the MSB and LSB, into a 16bit value (0-65535). This is useful when formatting DMX data from fixtures that use fine control channels.

A RGUMENTS
None.

M ESSAGES
int float Set the value of the MSB or LSB, calculate and send out the 16-bit value. Converted to int.

O UTPUT
int: A 16-bit value calculated from the two inputted 8-bit values.

10

IMP.DMX.16TO8
D ESCRIPTION
imp.dmx.16to8 converts a 16-bit value (0-65535) into two 8-bit values (0255), the MSB and LSB. This is useful when formatting data for fixtures that use fine control channels.

A RGUMENTS
None.

M ESSAGES
int float Set the value of the 16-bit int, calculate and send out the MSB and LSB. Converted to int.

O UTPUT
int (left outlet): The MSB of 16-bit int. int (right outlet): The LSB of 16-bit int.

11

IMP.DMX.ARTNETIN
D ESCRIPTION
imp.dmx.artnetin receives DMX data broadcast using the Art-Net UDP networking protocol. It cannot receive data which is sent using the newer unicast mode. The first argument sets the Art-Net subnet (0-15) and the second the Art-Net universe (0-15). When a packet is received, it is decoded, and sent out the left outlet as a list of ints. This can be directly connected to an imp.dmx.write object as a method by which to bring an external DMX source into jitter. Additional information about the received packet is sent out the right outlet. NOTE: This abstraction uses an external java object. The .java and .class files for this object are included in the imp.dmx package. If this object cannot be found check the files are included in your search path. NOTE FOR USING MULTIPLE COPIES OF THE OBJECT: The raw byte data received over UDP by imp.dmx.artnetin is sent via a Max send object using the name 'imp.dmx.artnetraw'. This is done to allow multiple copies of imp.dmx.artnetin to receive data. The first copy of the object to be created will bind to the port, and will then send data to all other copies, which will fail to bind.

A RGUMENTS
Name Subnet Universe Type int int Description First argument. Art-Net subnet to receive data on, 0-15. Defaults to 0. Second argument. Art-Net universe to receive data on, 0-15. Defaults to 0.

M ESSAGES
int float In left inlet: Sets subnet value. In right inlet: Sets universe value. Converted to int.

O UTPUT
List (left outlet): List of consecutive DMX values starting at channel 1. List (right outlet): Additional Art-Net packet information. ProtVer, Sequence, Physical and Length. Use route to filter.

12

IMP.DMX.ARTNETOUT
D ESCRIPTION
imp.dmx.artnetout broadcasts DMX data using the Art-Net UDP networking protocol. It cannot send data using the newer unicast mode. The first argument sets the Art-Net subnet (0-15) and the second the Art-Net universe (0-15). To send data, a list of values should be send into the left inlet. A bang sends the most recent data again. NOTE: This abstraction uses an external java object. The .java and .class files for this object are included in the imp.dmx package. If this object cannot be found check the files are included in your search path.

A RGUMENTS
Name Subnet Universe Type int int Description First argument. Art-Net subnet to send data on, 0-15. Defaults to 0. Second argument. Art-Net universe to send data on, 0-15. Defaults to 0.

A TTRIBUTES
Name start_address full_universe alt_ip Type int int int Description Sets the first DMX channel to send data on. Defaults to 1. If 1, forces object to send a full universe of data regardless of the length of the inputted data. Defaults to 1. If 1, broadcasts data on the address 10.255.255.255 rather than 2.255.255.255. Defaults to 0.

M ESSAGES
list int float In left inlet: A list of consecutive DMX values will be broadcast via Art-Net protocol. In middle inlet: Sets subnet value. In right inlet: Sets universe value. Converted to int.

O UTPUT
None.

13

IMP.DMX.DEFIX
D ESCRIPTION
imp.dmx takes a list of channel/value pairs (prefixed list) and outputs a full universe of DMX in a list of consecutive values by placing the received values in the outputted list at the location specified by their channel address.

A RGUMENTS
None.

A TTRIBUTES
Name autoclear Type int Description When 1, automatically sets all channels back to 0 after outputting data. This way only the data that was last received will be outputted. Changing this parameter will cause current data to be cleared. Defaults to 0.

M ESSAGES
list (ints) bang float clear List of channel/value pairs updates values at their respective channels and outputs list. Outputs current data. Converted to int. Clears currently stored data by setting all channels to 0, and outputs data.

O UTPUT
list: List of consecutive DMX values.

14

IMP.DMX.GET
D ESCRIPTION
imp.dmx.get gets the values of specific channels from a DMX Jitter matrix and outputs them as channel/value pairs. By connecting to a qmetro, it can be used to continuously lookup the values of certain channels rather than an entire matrix.

A RGUMENTS
Name channels-toget Type list Description List of channel addresses to get. Must be between 1 and 512 inclusive. Defaults to 1 2 3 4 5 6 with no argument.

A TTRIBUTES
Name matrix Type symbol Description Sets the jitter DMX matrix currently referenced for this object. Defaults to imp.dmx.

M ESSAGES
list List of channel addresses gets values for those channels and outputs as channel/value pairs. These pairs are sent one by one, in the order they were placed in the input list. Gets values for the most recent list of channels (or the list in the argument if no additional list of channels has been inputted). Converted to int.

bang float

O UTPUT
list: DMX channel followed by channel value.

15

IMP.DMX.PREFIX
D ESCRIPTION
imp.dmx.prefix prefixes channel addresses to a list of DMX values. Argument is the address of the first channel. Useful for formatting data for the Enttec DMX USB Pro interface, which requires channel/value pairs.

A RGUMENTS
Name start address Type int Description Channel address of the first value in the inputted list of consecutive DMX values. Defaults to 1 with no argument.

M ESSAGES
list In left inlet: For a list of consecutive DMX values, prefixes channel addresses before each value starting from the start address set by the argument or by a message in the right inlet. Outputs this prefixed list. In left inlet: Gets values for the most recent list of channels (or the list in the argument if no additional list of channels has been inputted). In right inlet: Sets the channel address of the first value in the inputted list of consecutive DMX values. Converted to int.

bang int float

O UTPUT
list: List of prefixed data (channel/value pairs).

16

IMP.DMX.PUT
D ESCRIPTION
This patch is for writing the values of specific channels to a DMX Jitter matrix. A list of channels values is specified in the left inlet and a list of channel addresses is specified in the right.

A RGUMENTS
Name channels-toput Type list Description List of channel addresses to put channel values at. Must be between 1 and 512 inclusive. Defaults to 1 2 3 4 5 6 with no argument.

A TTRIBUTES
Name matrix Type symbol Description Sets the jitter DMX matrix currently referenced for this object. Defaults to imp.dmx.

M ESSAGES
list In left inlet: A list of channel values are written into the DMX matrix at the respective channel addresses specified by the argument or by a list sent in the right inlet. In right inlet: Updates the list of channel addresses to put channel values at. bang float Repeats put operation with most recent lists. Converted to int.

O UTPUT
None.

17

IMP.DMX.READ
D ESCRIPTION
imp.dmx.read reads a list of consecutive values from a DMX jitter matrix. It can also output a list of values prefixed with channel addresses.

A RGUMENTS
Name Start Address Output Length Type int int Description Channel address of the first channel in the list. Defaults to 1. Number of channels that should be read in total. Defaults to 512.

A TTRIBUTES
Name matrix prefix Type symbol int Description Sets the jitter DMX matrix currently referenced for this object. Defaults to imp.dmx. When 1, prefixes channel values with their channel address, creating a prefixed list output. Defaults to 0.

M ESSAGES
bang int float Performs read operation and outputs result. In middle inlet: Sets start address. In right inlet: Sets output length. Converted to int.

O UTPUT
list: List of consecutive DMX values.

18

IMP.DMX.RGBCMY
D ESCRIPTION
imp.dmx.rgbcmy converts RGB values to CMY, or CMY values to RGB. In both cases, the process is simply inverting the values. CMY values are used to specify subtractive rather than additive colour mixing and are required for colour-values to send to moving lights, which use subtractive colour filter wheels.

A RGUMENTS
None.

A TTRIBUTES
Name 8bit Type int Description When 1, causes the object to calculate values using an int range of 0-255 rather than a float range of 0. to 1. Defaults to 0.

M ESSAGES
list float Sets all values and causes output with these values. In left inlet: Sets red/cyan value and causes output with currently stored values. In middle inlet: Sets green/magenta value. In right inlet: Sets blue/yellow value. Converted to float.

int

O UTPUT
list: RGB/CMY values.

19

IMP.DMX.WRITE
D ESCRIPTION
imp.dmx.write writes a list of consecutive DMX values into a jitter matrix. The resulting matrix is outputted. The length of the inputted list determines the number of channel values written.

A RGUMENTS
Name Start Address Type int Description Channel address to begin writing on. Defaults to 1.

A TTRIBUTES
Name matrix Type symbol Description Sets the jitter DMX matrix currently referenced for this object. Defaults to imp.dmx.

M ESSAGES
list float A list of consecutive DMX values writes these values into the matrix and outputs it. Converted to int.

O UTPUT
matrix: DMX jitter matrix.

20