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

 

 

2 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.

Leave a Reply

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