Compiling and using the uDMX command line utility, on a modern Mac

Jackie and I are currently working on a hardware project that involves receiving DMX commands from a professional lighting desk.

We were loaned a uDMX USB-to-DMX interface (like this one) by another member of DoES Liverpool, so we could test out the DMX receiver hardware that we’re building.

Professional DMX equipment tends to be quite pricey, but the uDMX is a tiny, open source alternative, that typically costs about £20.

Being open source, uDMX interfaces are theoretically supported by a bunch of lighting control programs, like QLC+, Freestyler, and OLA.

But if—like us—you just want to send numbers 0–255 on a few channels over DMX, then there’s no need to overcomplicate stuff with third-party software. The uDMX developers provided a commandline utility that’s great for quickly debugging DMX devices.

Downloading the source code

Download the udmx_1_2.tar.gz from the Anyma uDMX webpage, then double-click it to unarchive it.

You’ll notice there’s a tempting binaries directory, and you might try to run binaries/commandline/uDMX but if you’re running on an Intel Mac, you’ll get this error:

./uDMX: Bad CPU type in executable

I think this uDMX executable was compiled on a PowerPC Mac (back in 2006), so it won’t run on an Intel Mac.

Instead, you’ll need to re-compile the binary yourself, from the C source code.

Installing Make and GCC on your Mac

If you haven’t already, you’ll need to install the (Xcode) Command Line Developer Tools to get access to make and gcc commands. You can do this with:

xcode-select --install

Compiling the uDMX command for your Mac

Now head over to sources/commandline/ in that udmx_1_2 directory you just downloaded:

cd udmx_1_2/sources/commandline/

You’ll notice that it has a few files in it:

  • Makefile – imagine gulp.js had been invented in 1976. Well, imagine no more, because that’s exactly what a Makefile is. A simple way of telling the Make compiler what to compile.
  • uDMX – yet another PowerPC-compiled executable.
  • uDMX.c – the source code we need to compile.
  • uDMX.o – an ignorable byproduct of compilation.

One of the core concepts about how Makefiles work is that they specify files to be created. If those files already exist, then the Makefile will do nothing. So we have to delete the files that the Makefile created last time before we can re-make them for our Intel CPU.

Handily, the uDMX Makefile contains a clean rule that deletes the two compiled files for us:

make clean

Now you’re ready to compile a fresh executable. Just run make without any arguments:

make

A second later, a new uDMX executable will appear in the directory, and this time it’ll actually run on your Mac’s Intel processor.

Installing libusb to communicate with the USB device

Before you can use a uDMX USB-to-DMX device, you’ll need to install the libusb library so your Mac can communicate with the device.

Assuming you have Homebrew installed on your Mac, you can get libusb fairly easily via the libusb-compat package:

brew install libusb-compat

Using uDMX on the Mac command line

Now, with all that stuff installed, you’ll excitedly run uDMX without any arguments, and either nothing will happen or you’ll get a Segmentation fault: 11. Useful!

Documentation for the uDMX command is basically non-existent, so here’s what I wish it printed when you ran uDMX without any arguments:

Usage: uDMX [channel] [value]

Arguments:
  channel      A number (usually 0–511) corresponding with the 
               address of the DMX device (1-512) for which the
               numeric [value] is intended.
  value        A numeric value (usually 0-255) to send.

Examples:
  uDMX 0 255   (sends value 255 to the device at DMX address 1)
  uDMX 1 0     (sends value 0 to the device at DMX address 2)

If you have a device like a DMX lighting controller plugged into your uDMX USB interface, and the controller’s DMX address is set to, say, 1, then running uDMX 0 255 would most likely turn the light on at full brightness and uDMX 0 0 would turn the light off.

Different DMX controllers and DMX devices have their own configurations though, so you’ll need to read the manual for the device you’ve got.

Finally, if you run uDMX with arguments, but you don’t have the uDMX USB device plugged in, you’ll get an error like:

Could not find USB device www.anyma.ch/uDMX
Could not find USB device "uDMX" with vid=0x16c0 pid=0x5dc

Check that you’ve got the USB interface plugged in, and that you installed libusb or libusb-compat as described above.