There's no two ways of saying it, ArtNet is complex – especially when you're attempting to use it for one of the most common purposes, to transfer live video to numerous LED light strips. In this tutorial, we will go over terminology, techniques, tips and end up with a working example that shows how to use Isadora to control three LED strips via ArtNet.

First, a little background on how ArtNet is implemented in Isadora v2.6

As with other DMX systems controlled by Isadora, the heart of the system is the Matrix Value Receive actor. This is a multipurpose actor, that actually can receive lists of values and send them to a wide variety of output devices. (While this actor is most often used in DMX and ArtNet applications, it can in fact be used in many ways. For instance, you could also use it to control faders on an audio console that reads MIDI.)

We're not going to explain the Matrix Value Receive actor in a general way here. Instead, we're going to focus on using it to send DMX data via ArtNet.

We'll start by having you download an Isadora file for this tutorial, which is called "ArtNet Send Tutorial.izz"

In the first scene, you'll see some User Actors called "ArtNet MVR". Double click one to have a look inside. You'll find a Matrix Value Receive that is already configured to work well with ArtNet.

The first thing to notice here is the 'port' input of the Matrix Value Receive actor. Any Matrix Value Send or Color Matrix Send actor that wants to send this Matrix Value Receive actor data must use the same 'port' number.

It has 512 inputs channels that will each be directly routed to the 512 ArtNet DMX output channels. (You could change both of those ranges to lower numbers, e.g., 100 and 100 if you only needed that many DMX outputs. But when you start working with LED strips where you need 3 or even 4 values for each individual LED, you'll need a fare more than 512 channels in the end.) The remainder of the parameters are set up to produce a long string of hexadecimal values from 00 to FF, which is what the ArtNet Send actor needs to send the DMX values. (Hex 00 to FF represent the decimal numbers 0 to 255, which is the full range of DMX values that can be sent.)

One thing that's important to understand for any future work with the Matrix Value Send is that it contains an internal routing table called the "Channel Map." To see Channel Map editor, double click the Matrix Value Send actor.

If you work at all with lighting consoles, this will be familiar to you: it's the "magic sheet," that allows you to route a single input channels to one or more outputs. For this application, we want a one-to-one relationship, where each input goes to the matching DMX output. This Channel Map is already set up to handle the 512 ArtNet/DMX outputs, so just hit the Cancel button to exit the editor.

CRUCIAL TIP! when you increase the number of channels in the Matrix Value Send actor, this new entries created in this table are blank! If you want a one-to-one routing, double click the Matrix Value Send actor and then click the "Set Defaults" button. This will route input channel 1 to output 1, input 2 to output 2, etc.

Now let's take a look at actor that actually sends the data via ArtNet, the ArtNet Send actor.

The first input property is 'name/addr.' Normally you will simply want to leave this blank. If you do, this actor will broadcast it's ArtNet packets to the entire network. Leaving this input blank is the easiest way to ensure your ArtNet packets get where they are supposed to go.

The second input is called 'universe.' Here we're going to get into some tricky terminology that is partly a result of some less than optimum naming choices by the designers of ArtNet. We're going to take a little diversion here to learn some important ArtNet terminology.

UNDERTSANDING ARTNET NODES, SUBNETS, AND UNIVERSES

This actor represents an ArtNet "node." Each node has something called an ArtNet "subnet" address, which can range from 0 to 15. This is not to be confused with the similar named "sub net" used when configuring TCP/IP connections – it has nothing to do with that kind of sub net!

Each node can have up to four "ports" – individual connections that can send or receive ArtNet data. These each have a "universe" identifier, which also ranges from 0 to 15. Like the subnet, the name is a bit misleading. an ArtNet universe number is not the same as a DMX universe.

The 'universe' input of the ArtNet Send and ArtNet Receive actors really represents a DMX universe. (Actually there can be exceptions to that… but let's stick to how we're doing it in this tutorial which is most definitely the most common case.) Our universe number is actually a combination of the ArtNet Sub Net and Universe values:

Matrix Value Receive Universe = Art Net SubNet * 4 + Art Net Universe.

Because some controllers use the subnet/universe terminology, the ArtNet Send actor has two handy outputs that show you the ArtNet Subnet and ArtNet Universe values for whatever number you type into the 'universe' input. For example, if you set the 'universe' input to 18, you'll see that this comes out as ArtNet SubNet 1 and ArtNet Universe 2.

BACK TO OUR REGULARLY SCHEDULED PROGRAM

Continuing now with the ArtNet Send actor, you'll see the 'intf addr' input. Normally you'll always leave this input empty so that the ArtNet actor will use the first network interface it finds on your computer. If you have multiple network interfaces, with some ArtNet devices connected to one and other ArtNet devices connected to the other, then you would need to use this input to specify the IP address of the network adapter you want to target. For this tutorial, we're going to leave this input empty. The 'intf addr' output of the ArtNet Send actor allows you to confirm the actual network interface that was discovered by the actor.

The 'update' input allows you to "throttle" the ArtNet messages being sent to the network. Slow networks can quickly get bogged down with thousands of channels of ArtNet data. Setting this to a non-zero value allows you to specify the maximum frequency at which message can be sent. We've got this set to 0 because we've already got a data rate limit of 1 mS because of the 'min period' input of the Matrix Value Send actor, which performs the same throttling function as the 'update' input.

Finally, there's the 'raw dmx' input. This is where the hexadecimal DMX data encoded by the Matrix Value Receive actor is received, and converted into the actual ArtNet packets that will be sent over the network.

Now that you've had a look at this User Actor, you can close it.

After doing so, take a look at the three ArtNet MVR actors. Note that the first one is set to Universe 0, and Matrix Value port 1. The second is universe 1 / port 2, and the final one is set to universe 2 / port 3. This means that, if you wanted a Matrix Value Send or Matrix Color Send actor to control DMX channels on the first universe, you'd need to send them to Matrix Value port 1. For the second universe, port 2, and so on. 

Understanding how this works is critically important to using the Matrix Color Send which we'll get to a bit later.

TURNING VIDEO INTO ARTNET

This next part of the tutorial is going to be bit tricky, because you probably don't have the same LED strips as we do. Still, we're hopeful that taking you through the setup we created will at least give you some good clues about how to configure your particular hardware.

For this tutorial, we used a set of three LED light strips from a company called Advatek, each with 144 RGB LEDs per strip. (Big shout out to long time Isadora user Fubbi Karlsson who lent this rig to us so we could make this tutorial. Thank you Fubbi!)

The first step is to connect the LED strip controller to the same network to which your computer is connected. To accomplish, we grabbed an Ethernet cable to connect the controller to one of the Ethernet ports of our wireless router. The computer was connected via Wifi.

The next step is configure the LED strip controller. Advatek provides has a handy, free app called "Advatek Assistant" that makes this relatively easy. (Hopefully, if you have different hardware, the vendor will have a similar configuration app.) After double-clicking the app to open it and clicking the "Search" button, we were presented with this:

As you can see, it says "Found 1 Device(s)" and shows us that it found a "PixLIte 4," which is the name of the LED controller hardware. This confirms that that our computer can "see" the device, which means Isadora will be able to see it too.

In this particular app, you can set the configuration of the device by double-clicking it.

From here, we enable the "Advanced" option and click the "Advanced" button to show a dialog that is key to successfully configuring the device for use with Isadora. But before we look at that, we have to take another slight detour to do a bit of math.

CALCULATING THE REQUIRED NUMBER OF DMX UNIVERSES

LED strips offer many color options, like RGB, RGBW (RGB + white) or even just W (white.) For an RGB strip, each LED in the strip is going to require three DMX channel to control the individual red, green and blue color components; RGBW would require four channels, etc. The trick is to map those hundreds or even thousands of DMX channels in an organized fashion so you can get use them effectively.

In our real world example for this tutorial, we have three LED strips, each with 144 LEDs. To calculate the number of ArtNet/DMX channels required, you simply multiply the number of color components by the number of LEDs in the strip. In our case

LEDs per Strip x Colors Per LED = DMX Channels Per Strip

So, 144 x 3 = 432 DMX channels are required for the LED strips we're using in this tutorial. Since we have three LED strips of this size, we will end up needing a total of 1296 DMX channels (432 channels x 3 strips) to illuminate every LED available to us.

You can easily calculate find out how many DMX universes you'll need in total by dividing the final channel count calculated above by the maximum number of DMX channels per universe.

Number of DMX Universes Required = ROUND_UP(Total Required Channels / 512)

In our case, 1296 / 512 = 2.53, which rounded up to the next integer is 3. So we'll need three DMX universes to control the three LED strips for this tutorial

Another other thing to consider is that one DMX universe (512 channels) is more than the channels per individual LED strip. That means that the first 432 channels will address the 144 LEDs on the first strip, and the remaining channels will address pixels on the next strip. To find out how many, we do the following:

512 Channels per Universe - Number of Channels Per Str = Channel Wraparound To Next Strip

In our case:

512 - 432 = 80 DMX channels left over.

80 DMX channels / 3 channels per color = 26.666

Ignoring the numbers after the decimal point, we see that 26 LEDs on Strip #2 will be controlled by DMX Universe 1, for a total of 26 x 3 = 78 DMX channels.

So the first point that might be confusing is that one DMX universe might "spill over" from the first strip to the next. But the important thing to understand is that – if you configure your LED controller correctly – DMX Universe 2 will pick up exactly where DMX Universe 1 left off.

For us, the 27th LED on Strip #2 will be controlled by DMX Universe 2, channel 1.

So obviously all these calculations are a bit of a hassle. But they are critical to understanding how to set up your LED Strip Controller.

To add one further challenge to this setup, we connected the three LED strips to the controller hardware as follows:

Output 1 -> Strip #1 -> Strip #2 (288 LEDs x 3 colors = 864 DMX channels)

Output 2 -> Strip #3 (144 LEDs x 3 colors = 432 DMX channels.) 

We did this because it's very common to "daisy chain" the strips, i.e., to connect them in series, one after the other, to a single output. So we wanted you to see how to manage this.

BACK TO THE MAIN ROAD

So, before we delved into the mathematics of this, we had just clicked the "Advanced" button to get the advanced configuration dialog. It looks like this:

This is where you tell the controller how many channels will be used by each output. 

As mentioned above, Output 1 has two LED strips connected to it, with a total of 288 pixels. So, we set the "Start Universe" and "Start Channel" to 1, and enter 288 under the "Num Pixels" column. The values under "End Universe" and "End Channel" automatically update to show us that the last LED in the two strips is controlled by DMX Universe 2 / Channel 354.

That's super helpful, because we then set Output 2 to start at Universe 2 / Channel 355, which is the next channel after the one shown above. We then enter 144 under the "Num Pixels" column, and, voilá, we've now configured our two outputs.

Note also that the ending Universe/Channel for Output 2 was updated to say 3 / 276. If we were to continue with Output 3, we'd enter 3 and 277 in the "Start Universe" and "Start Channel" columns. But since outputs 3 and 4 are disconnected, we set the Start Universe for outputs 3 and 4 to Universe 4 and Universe 5; this ensures that they are not in conflict with outputs 1 and 2.

Click OK to confirm this dialog, and then OK again to confirm the "Controller Configuration" dialog. The strip may go dark while it's settings are updated (ours did) but then the system should return to it's working status.

OK, we did it! The LED strips are now configured and we can now go make some light in Isadora.

VIDEO TO ARTNET WITH THE MATRIX COLOR SEND

So, the normal companion to the Matrix Value Receive is the Matrix Value Send actor. It allows you to send individual values to the input of channels in the Matrix Value Receive. We'll use a Matrix Value Send actor to perform an initial test on our LED strip setup.

Test One Pixel

Click on the Q2 of the tutorial file, which is entitled "Test One Pixel." First, take note that we have three copies of the ArtNet MVR actor, one for each of the three ArtNet/DMX universes require to control the LED strips. Then, have a look at the User Actor called "LED Index to Mat. Value. Port and DMX Chan." This User Actor converts an LED number, from 1 to 432, into the proper DMX Universe and DMX channels to make one LED turn white. A counter actor increments the LED number 30 times per second, so that it cycles through every LED. If you had the equivalent setup to use, you'd see one white light marching along the strips as the LED index is incremented.

Single Color

But since our goal is to use video to control the LED strips, we're going to take advantage of an actor new in v2.6, the Matrix Color Send.

First things first: let's just light up all the LEDs with a single color. Go to the third scene of the ArtNet Send tutorial, entitled "Single Color". There you'll find a preconfigured MCS actor that was used to light up all three LED strips in our setup.

The part of the patch on the left is straightforward: it just generates a solid color using a Background Color actor, changing between red, green and blue once every second. The video output of the Background Color actor is fed into the Matrix Color Send actor (MCS for short), which will convert a video signal into its individual RGB values and send the those numbers to the ArtNet MVS actor. Let's have a look at some specific inputs of this actor.

First, look at the 'base port' input. This specifies the Matrix Value Receive port number to which the color values will be sent. But note the word 'base' here – we'll come back to that in a second

The 'base chan' and 'chan skip' inputs indicate the starting channel for the first RGB value, and the number of channels to skip after each RGB triad. In some situations, the ordering of the channels for a strip might R G B X RGB X, where the fourth value X controls some other parameter of the strip. In this case, you'd set the 'chan skip' input to 1 so that the X channel would be skipped.

Next look at the 'mode' input. Right now it's set to 'rgb', but it can actually be set to every possible combination of the order of 'r', 'g' and 'b'. For instance, if you're LED strip were ordered as BGR instead of RGB, you could change this input to say 'bar' and the colors will come out right on the strip. 

Also take a look at the 'size px' input. This defines the width (when the 'rows/cols' input is set to rows) or height (when the 'rows/cols' input is set to cols) of an area of the video whose RGB values will be sampled and then sent to the ArtNet MVR User Actor. You can see a single bright green line in the darker green area of the MCS actor. That shows you the source of the pixels within the image.

And now, we go back to the 'base port' input. The reason the word "base" is in its name is because it is a starting point. If the 'chan/port' (channels per port) input is set to a non-zero value, then that the Matrix Value port number will be incremented each time that chan/port limit is exceeded.

To make this ultra clear, let's create a simple example where there are only 9 channels per universe instead of 510. In this case you'd set 'chan/port' to 9. Assuming the 'base port' is set to 1, and the 'base chan' is also set to 1, this would be the Matrix Value port and channel used to send values to the ArtNet MVR actor

  • Pixel 1 -> MV Port 1, channels 1-3
  • Pixel 2 -> MV Port 1, channels 4-6
  • Pixel 3 -> MV Port 1, channels 7-9
  • Pixel 4 -> MV Port 2, channels 1-3
  • Pixel 5 -> MV Port 2, channels 4-6
  • Pixel 6 -> MV Port 2, channels 7-9
  • Pixel 7 -> MV Port 3, channels 1-3

etc.

If the 'base chan' input was set to 4, then the output would go like this

  • Pixel 1 -> MV Port 1, channels 4-6
  • Pixel 2 -> MV Port 1, channels 7-9
  • Pixel 3 -> MV Port 2, channels 1-3
  • Pixel 4 -> MV Port 2, channels 4-6
  • Pixel 5 -> MV Port 2, channels 7-9
  • Pixel 6 -> MV Port 3, channels 1-3

etc.

But in our real example, setting this to 510 means that all 432 pixels can be analyzed and their RGB values will automatically be routed to the correct pixel on the LED strips.

Let's jump to the next scene to see this in action.

Sliding Colors

Go to the Q4 of the ArtNet Send tutorial, entitled "Sliding Color". This patch is almost the same as the previous patch, but instead of a Background Color actor providing a single, solid color, we're now using a Shapes actor and a Wave Generator to create small patch of color that slides across the screen from left to right. (Choose "Show Stages" to see what the actual video looks like.)

That's the only difference between the first scene and the second. But now you'll see the 10 colored pixels sliding along the three LED strips.

Three Parallel Strips

Finally for this tutorial go to the Q5 of the ArtNet Send tutorial, entitled "Three Parallel Strips". This patch again builds on the previous patch, but now we have three Shapes actors, each generating a different color and sliding back and forth at different rates. These three video signal are combined into one using a pair of Effect Mixer actors. This is just to make the output a bit more spectacular.

But the big difference here is in the Matrix Color Send actor. Note the 'size px' input now says 144 (matching the number of LEDs in one strip), the 'repetitions' input says 3, and the 'spacing px' input says 5. You'll also notice that there are three lines in the center display of the Matrix Color Send actor.

So now you are sampling three separate areas from the source image, each 144 pixels wide, and spaced apart by 5 pixels. If your LED strips are configured properly, you should see the lines moving in parallel on all three strips, as you can see here in this animated GIF.

SUMMARY

Phew! That was an intense one. ArtNet and LED controllers are not simple to configure, but hopefully this tutorial has given you a better understanding so you can take on the challenge with your own LED systems.