Controlling a WS2812 led matrix over ethernet using Arduino

I found this 8×32 WS2812 led matrix on amazon.de and was eager to get my hands on it. My idea was to control it using an Arduino Uno with ethernet shield I had laying around.

8x32 WS2812 led matrix from Amazon
8×32 WS2812 led matrix from Amazon

To control the leds from the Arduino I would use Adafruit NeoPixel library, I used it before building a DIY ambilight for my HTPC. The NeoPixel library is able to run WS2812 leds, WS2811 leds and more. You could also use the FastLED library for driving your matrix, it offers similar functionality as the NeoPixel library.

But what about the ethernet part? I want to control all the individual leds and offload as much of the hard processing power on a PC controlling it.
Would it be possible running a Hyperion server on an Arduino? Or what about something like DMX?

After some searching on the web I stumbled upon ArtNet, an Art-Net implementation for Arduino. Art-Net is actually a protocol for DMX over ethernet.

Now I would need to find some software to send Art-Net commands to the Arduino from my PC. I found a number of, for me incomprehensible, programs to send raw Art-Net commands but eventually found Jinx! from live-leds.de.  Software for controlling led matrices with Art-Net, exactly what I was looking for.

So let’s get started on bringing everything together!

Hardware

I used the following components for my build

  • Arduino Uno R3 16 Mhz with ethernet/SD shield
  • 5V 10A (50W) power supply I got from DealExtreme
  • Resistor, between 220Ω and 470Ω (this is important because without it you will fry the data pin of the first led)
  • (optional, but recomended) a capacitor
  • 8×32 WS2812 led matrix

[pic of all hardware]

Wiring the WS2812 led matrix

Connecting the led matrix is easy, you only need to connect three wires.

Hook up the positive lead (+5V) from the power supply to the cable marked ‘5V’ (red lead) on the led matrix and the negative lead to the cable marked ‘GND’ (white lead)

The last one is the data cable, the green cable marked ‘DIN’. This connects the WS2812 led matrix to the Arduino. You can connect this to a range of pins on your Arduino, I used pin 5. The Important thing is that you put a  470 Ohm resistor between your Arduino and the leds, otherwise the input of the first led will burn out and, unless you figure out how to replace the first led, your whole matrix will be broken.

[pic of connected led matrix to arduino]

I de-soldered the pass-through cable from the output side of the matrix and used the cable with plug to be able to plug in and out the matrix from the Arduino and power supply. Also i hooked up the AREF and GND from the Arduino board to the power supply so I don’t need to USB power the Arduino.

Led matrix led order

You will need to figure out how the leds on you WS2812 led matrix are wired, this might be in the specs of your led matrix but you can also figure it out yourself by writing a little loop that lights the leds one by one and observe the order they light up in. In my case it is wired as a snake crawling through the columns, starting top-left. Meaning down from the first led, move to the next column at the bottom and going back up, move to the next column and back down. Repeated for the whole matrix. I tried to visualize it in the image below.

[image led order]

WS2812 led matrix power usage

A single led doesn’t really use a lot of power (60ma), but 256 together will draw quite a bit of power at full brightness, up to 15A! Because full brightness will probably blind you, you might be able to use a lighter power supply than the maximum your led matrix can consume. But a decent power supply is required.

Arduino memory limitations

The cpu on the Arduino UNO only has 2kb of ram to work with, each led needs 3 bytes in memory. For 256 leds this adds up to 768 bytes. You could probably add a second matrix for a memory usage of 1536 bytes. But if you want to control more than two, you’ll need a more powerfull board.

Software

Arduino Sketch

Download the Adafruit Neo Pixel and ArtNet library  and load them into your Arduino IDE. Add it under Sketch -> Include Library -> Add .ZIP Library and choose the downloaded file.

[image of arduino add zip]

The ArtNet library comes with an ArtnetNeoPixel example there’s no need for a lot of programming skills, you only really need to adjust the following variables.

  • numLeds to 256 (for a 8×32, or 16×16 matrix)
  • dataPin to the Arduino data pin you will be using
  • ip[] to the IP address you want your Arduino to use

In the setup() function you can enable the Serial.begin(); line if you want to debug using a serial console. I commented out the initTest(); line. But for initial testing this might be useful, so keep it for now. When everything is connected and your Arduino boots it will flash the leds red, green and blue. So you can confirm all the leds are functioning correctly and the WS2812 led matrix is wired correctly.

Upload the sketch and hook it up to your matrix. If you kept the initTest line, you will now see your matrix flashing red, green and blue confirming everything is working and that the Arduino is now listening for Art-Net packages.

Jinx!

Download Jinx! from http://www.live-leds.de/

The Jinx! main window
The Jinx! main window

Setting it up

Before you can start using Jinx! you need to set everything up for your hardware. There’s a couple of steps you need to follow to set everything up.

Matrix options

The first step is tell Jinx! the size of your led matrix, click ‘Setup’ -> ‘Matrix Options’ in the Jinx! main window.

The Jinx! Matrix Options window
The Jinx! Matrix Options window

In the new window fill in the dimensions of your led matrix, when you use a similar 8×32 WS2812 led matrix use 32 for width and 8 for height.

Output Devices

The Art-Net protocol has a limit of 512 bytes/channels per frame per universe. 512 bytes is enough for max. 170 leds with 1 byte per color. For 256 leds you will need two universes. The Arduino software doesn’t really care where you split your universe, as long as there is not more than the maximum needed amount of universes.

I decided to split on whole columns. 21 columns with 8 rows for the first universe (168 leds, 504 channels), 11 columns for the second universe (88 leds, 264 channels)

With this information we can setup the output devices. Each universe needs its own output device.

Choose ‘Setup’ in the menu and click ‘Output Devices’

The Jinx! Output Devices window
The Jinx! Output Devices window

In the new window click the ‘add’ button to create a output device. You’ll need to do this for each universe your setup uses.

[pic image add device]

I used the following configuration for my setup. Note the universe numbers and amount of channels per device. (If you adjusted the starting universe in the Arduino software, make sure to change the value of the universes to resemble that)

Device 1 Device 2
Device Type Art-Net
IP address IP of your arduino, disable broadcast
Net Leave 0
Subnet Leave 0
Universe 0 1
Enable ‘Send ArtNet Sequence Numbers’
Channels 504 264

With your devices set up it’s time for the next part of the configuration, patching the leds.

Output Patch

Now we need to tell Jinx! which physical led maps to which channels. To do so open the ‘Output Patch’ window from the ‘Setup’ menu.

The Jinx! Output Patch window
The Jinx! Output Patch window

The patch window will show you a representation of your led matrix, you can click each square and set the output device and channel numbers for each led individually. Because doing this 256 times is a lot of work you probably want to use the ‘Fast Patch’ option. This option allows you to bulk patch your leds to addresses.

Select the first led, top left, and click the Fast Patch button. You’ll see a window like the one below. Adjust the settings so they look like the picture below and click ok. Make sure you choose the right patch mode, Snakecolumns starting Top-Left (which might be different for you, if you want to use it in vertical orientation for example)

Jinx Fast Patch window device 1

You’ll see that the patch window has turned green, now scroll to the right and find the first red block (on row 22), click the top left block and click the Fast Patch button again. Adjust the dimension, choose the second  output device and this time, because we are on an even column, choose ‘Snakecolumns starting Bottom-Left‘ as opposed to the Top-Left we used previously.

Jinx Fast Patch window device 2

Everything in you patch window should no be green to indicate the leds are patched. You are ready to put on your first light show!

Play with Jinx!

Now you have Jinx! all set up and ready to use it’s time to hit the ‘Start Output’ option of the setup menu and start building your show!

The video above is a short demo of what I came up with after some playing with Jinx!.

To reduce the overall brightness of the matrix, use the ‘Master’ slider at the bottom-middle of the Jinx! window.

You can pick some effects from the different channels, mix them together and preview the result in the middle preview window. There’s a lot more to Jinx! to discover, for that go check out their website.

On brightness and colors

Reducing the brightness of the matrix will also reduce the amount of available colors it can show. This is because it will basically limit the maximum value for each color. Running the WS2812 led matrix on brightness 5 will be friendlier for your eyes, but you will only get pure red, green and blue colors on your matrix.

You probably want to play with it a bit and figure out what brightness is a good balance between visible colors and the amount of light you want.

Alternatives to Jinx!

If you aren’t running Windows, Jinx! will not be an option for you. In that case you could try Glediator. It’s a similar piece of software built in Java so it will run on all platforms. It requires you to do the configuration in a similar way, only the patching and creating output devices is done from one and the same window. I might write a short article on how to setup Glediator later.

I found Jinx! to be slightly easier to use, but Glediator has mostly the same (sort) of effects and features available.

Time to fly

With the above guide you can quickly setup a WS2812 led matrix and show some amazing animations. It’s Art-Net compatible, so if you have an existing DMX setup you should be able to use that for controlling the led matrix.

Now you probably want to create some sort of housing for it, i was thinking of placing the led matrix behind some milky glass, this way the brightness will be reduced a bit without losing any color depth and the displayed graphics will be a bit smoother. I will post an article to show it of, if I ever get to finish it. In the mean time, I would love to see what you can come up with!

Recording and playback

An interesting feature might be to be able to record and playback scenes that I created without needing to run Jinx!. The ethernet shield supplies a SD card slot, so it should be possible to write patterns to it and play them back later. This way the unit can act as a standalone light.

Make it smart

Another option would be to combine this with a RaspberryPi/wifi and create a smart-light/display. Lighting your room but also being able to notify you of incoming mails or even display stock tickers or RSS headlines. I’m not sure if I will ever take it this far, but if I do I will post about it here!

 

Links

Some usefull links for readers looking to build their own Arduino driven WS2812 led matrix.

Buy a 8×32 WS2812 led matrix

Arduino Libraries

Art-Net matrix control software

Further reading on WS2812/NeoPixel leds

 

 

12 Replies to “Controlling a WS2812 led matrix over ethernet using Arduino”

  1. Hi there…. Great writeup. I wanted to give this a try and was wondering if you could correct the missing images ie [pic of connected led matrix to pi] thanks!!

    1. Thanks for your reply! You are right, those pictures are long overdue. It is actually connected to an arduino.. green wire, through a 470 ohm resistor, to pin 5. power wires to power supply. (if you power the arduino from another power supply, like usb, make sure you also connect the grounds to eachother)
      I don’t have it set up right now, i’ll see what i can do this week or next to add those images.

  2. hello, i’m trying to follow your instruction above. the Jinx already detect the ArtNet, but when i patch and output to jinx, nothing happened. may you could enlight me more.

  3. Hi Mannes,
    First of all thans for your great job. I’m using your advice to drive WS2811 leds via Artnet. I have 768 Led (32*24) I already drive 512 of them but I think there is a limit in receiving buffer at Artnet.h

    // Buffers
    #define MAX_BUFFER_ARTNET 530

    I think code is not accept more than this size. When i define the led count 512 and map it from jinx its working. If i change the Led count 768 and compile there is no error but nothing received. I’ll try to change buffer size and try again.
    Do you suggest any other options to drive 768 Led or this is right spot? what you think…

    1. Hey, this buffer defines the maximum size of the Art-Net message, this is specified by the protocol to max 512 bytes. I tried to explain this in the ‘Output Devices’ section. You need to cut up your leds into ‘universes’ so that multiple messages are sent after eachother to the receiving side without overstepping protocol boundries.

      Also check out the ‘Arduino memory limitations’ section. An Arduino Uno only has 2kb of ram. For 768 leds the needed buffer is 2304 bytes, which is more then the total available memory on the Uno. You should consider using a heavier chip or you could physically cut the signal line in your led grid and use a second Arduino to power the last 256 leds.

      Hope this helps you getting further.

  4. The test works but Jinx doesn’t see my device… Device is open to receive pings ETC and shows in console that it is connected to my network but Jinx doesn’t see it or work with it when I enter the details manually.

  5. Hi there,

    I’m having an issue where the program will not work with over 158 pixels. It works fine with 158 or less, but at 159+, it will not run. Even the initTest doesn’t light any of the LEDS; including the first 158. I’m using an Arduino Uno. It would make more sense to me if it was at 170 pixels, which would mean there’s an issue with multiple universes. The fact that it is at 158 makes me think more along the lines of a hardware limitation?

    Before I go digging deeper, I’m wondering if this is something you’ve run across? I have checked all the normal culprits such as bad pixels, power drop across the circuit, etc. I can control more than 158 pixels using the hardware I have without issue when using other protocols, just not with the artnet sketch. Could it have to do with the Ethernet shield processing data too slowly or something along those lines?

    Any help is greatly appreciated.

    1. Hey,

      I haven’t come across this issue. My first guess would be a memory-limit (RAM) issue. Have you also used the NeoPixel library to power your leds in your other tests? You were able to light all the leds?

      The initTest function does not rely on any communication or ArtNet message, it just fires up all the led for a test. If this doesn’t work I would guess it’s in the NeoPixel config somewhere or some sort of hardware limitation.

      This project has been gathering dust on a shelve since I moved house a while ago. I will give it a try soon to see maybe an update in one of the libraries, possibly increasing its memory footprint, is responsible for this issue.

  6. Hello,
    Thanks for the great dicription to build an Art-Net Node.
    Everything works fine if i stay at a number of pixels to 156. If i increase the number, nothing works. Even not the initTest Programm shows up on the pixels.
    I have no idea where to search for the problem.
    Do you maybe have an idea what´s wrong?

    i used the same sketches as you did, so theoreticialy it should work out well.

    Thanks a lot!!!
    Greets Valentin

    1. Hey, you seem to heave the same problem as DI above. I haven’t run into this myself but i suspect it’s a memory issue because the initTest doesn’t run at all. An update in the libraries could be the issue, i will try to make some time to investigate this. Can you tell me the type number of the chip on the Arduino you are using? Is it an official one or a Chinese knockoff?

Leave a Reply

Your email address will not be published. Required fields are marked *