Introduction: How to Control Addressable LEDs With Fadecandy and Processing
What
This is a step-by-step tutorial on how to use Fadecandy and Processing to control addressable LEDs.
Fadecandy is an LED driver which can control up to 8 strips of 64 pixels each. (You can connect multiple Fadecandys to one computer to increase this.)
Processing is a programming language used to make visuals. You have a canvas, just like you would in Photoshop or Paint but instead of drawing with the mouse, you draw by writing code.
Fadecandy and Processing work together. You write code that places the LEDs across the Processing canvas, and then anything you draw in Processing shows up on those LEDs in real time.
Why
There are lots of ways to control LEDs. I like Fadecandy because it's cheap to get started and you can have heaps of control over your LEDs in a very visual way using Processing.
Processing can also be hooked up to aaallll kinds of things, like Kinect, Arduino, a camera, or even just mouse/keyboard inputs. So there is lots of scope to make things interactive.
How
There are three parts to this project.
1. Hardware
See how everything physical connects together, solder things, get the LED strips powered.
2. Software: Fadecandy
Fadecandy works by running a server on your machine - it's super simple to set up.
3. Software: Processing
See how to place the LEDs on the canvas, and use the examples to see some animations on your LEDs.
Level
I try and write my tutorials in such a way that someone with absolutely no experience at all can at least enjoy reading it. With this one I'm going to do everything step by step so it's suitable for beginners to follow along and do themselves.
I'm not going to go into detail on Processing - If you want to develop your Processing skills and make more advanced animations then you might want to check out some tutorials specifically for that - I recommend Daniel Shiffman's YouTube channel.
This project includes soldering. I haven't written detailed instructions for beginner solderers, there are lots of other tutorials for that.
This project involves high voltages (when wiring up a mains plug to the power supply) so please be careful and do not allow kids to do this alone.
Code
All of the code (Arduino and Processing) is on my github here.
Step 1: Equipment and Tools
Here's a full list of everything you will need to create this project:
Parts
- Addressable LEDs (US Amazon | UK Amazon)
I use ws2812b LED strip. There are a few variables you can choose from
Coating: You can buy plain LED strip with no coating at all but it won't be waterproof. Or you can buy it in a flexible silicone housing which is IP67 rated, this means it is completely sealed and waterproof.
Color of backing: The strips come in black and white. If you are not going to cover your LED strip with a difusser then consider which would look best.
Number of LEDs: The standards are 30, 60 or 144 LEDs per metre. I'm using 30LED per metre but I linked to 60 as it's more commonly used.
Other: You can also buy ws2812b in strings (US Amazon | UK Amazon) instead of strips. They work the same way, so it's up to you which to use! - Fadecandy (US Amazon | UK Amazon)
- USB Cable to connect Fadecandy to computer (US Amazon | UK Amazon)
- Double header pins (US Amazon | UK Amazon)
- Capacitors (US Amazon | UK Ebay)
5V Power Supply (US Amazon | UK Amazon)
This power supply I've linked to would power 512 LEDs (one Fadecandy's worth)Plug (US Amazon | UK Amazon)
You can just use an old plug cable or, if you don't have one, a kettle lead is a good option.3-pin JST Connectors (US Amazon | UK Amazon)
You need one pair per strip (so 8 for one Fadecandy's worth)12-AWG Cable (US Ebay | UK Ebay)
This thick cable will carry the power from the power supply to some connectors that split it out to all the different strips.- 24-AWG Cable (US Ebay | UK Ebay)
This thinner cable will carry the power to each LED strip. - Wago connectors (US Amazon | RS Components UK)
- These will split the power from one power supply to multiple strips. They come in packs of 10 which is plenty for one Fadecandy.
Consumables
Tools
Step 2: LED Strips
Each LED strip needs to be connected to power, ground and data. There is an arrow printed on the strip which shows the direction that data must flow.
Each LED strip needs a JST connector and a capacitor attached to it.
The connector:
The JST connector has 3 pins/cables - one each for power, ground and data. Being able to disconnect or replace strips is useful in a lot of cases. If you are confident you don’t want to ever disconnect or easily replace your strips then you could just solder on cable instead but I strongly recommend having connectors.
The capacitor:
If there is a surge of current (this can happen when you first turn on the power supply) then the capacitor will protect the first LED in your strip from being damaged.
Cable:
If you are planning an LED installation you will need to think about how your strips, power supplies and Fadecandy(s) will be placed. To ensure your connections will all reach, you will most likely need to add some lengths of cable somewhere.
You can solder the cables to the LED strip and then solder the JST connectors to the other end of the cable. Alternatively you might solder the JST connectors directly to the strip and add cable lengths to the power supply/Fadecandy side instead. It will all depend on your installation layout and plans.
Cable that is connecting power/ground to one strip of up to 64 pixels can be 24AWG cable. 24AWG is also plenty for the data connection. Use different coloured cable for power/data/ground – ideally colours that match your JST connectors.
I’m just going to solder the JST connectors directly to the strips and not add any cable extension, because I’m not concerned with layout in this tutorial.
Step 3: Attach the JST Connector and Capacitor.
Prepare the Strip
Cut your LED strips to length (64 pixels max per strip).
Find the right end, the one that has the arrow pointing inwards. Cut a little piece of the waterproof cover away so you can see the three contacts. They are labelled 5V, GND and Data In. (If the contact is labelled Data Out then you have the wrong end).
Solder on the JST connector and capacitor
This can be a bit fiddly but I have found the best way to do it is to melt a little blob of solder onto each of the three contacts, then solder on the JST connector and then the capacitor.
Use the female JST connectors to be attached to the strip side. The JST connector has 3 cables, one for each of the contacts on the strip. Usually the cables are red, green and white, or red, green and black. Use red for power, green for data and white/black for ground.
Cutting the legs on the capacitor short will help it stay in place. One side of the capacitor has negative symbols, the leg on this side connects to the GND contact and the leg on the other side connects to the 5V contact.
Reseal the strip.
Cut a piece of clear heat shrink which will cover the exposed piece of strip and have plenty of overlap with the existing waterproof cover. Slot it over the strip (you can do this before you attached the JST connector/capacitor or just slide it on from the other end) and keep it next to the exposed piece.
Put lots of RTV silicone directly onto the contacts and around the existing waterproof cover, including on the back of the strip. Slide the clear heat shrink over the silicone. Blast it with a heat gun until the heat shrink has heat shrunk.
The silicone is a bit messy. Make sure you wash your hands if you get it on your skin. Consider having newspaper or something on your work surface.
Repeat this for all 8 of your LED strips.
Step 4: The Power Supply
You will need to attach a plug to your power supply. I've included instructions for UK and US plugs.
Prepare the Plug
Cut the cable a decent distance away from the plug end. Use a Stanley knife to carefully strip away the outer layer of the cable. You should find three cables inside, strip away about a centimetre of each of these cables.
In a UK plug you can usually assume that:
Yellow/Green striped - Ground
Brown - Live
Blue - Neutral
In a US plug you can assume that:
Green - Ground
Black - Live
White - Neutral
To be completely sure your plug is wired as expected, you can use a multimeter to check.
Check cables with a multimeter
United Kingdom:
Look at the plug pins, with the single pin at the top. The top pin is Earth, the bottom left is Live, the bottom right is Neutral. The pins are also marked with the letters, E, L and N on most plugs.
USA:
Look at the plug pins, with the single pin at the bottom. The bottom pin is Earth, the top left is Live, the top right is Neutral. The pins are also marked with the letters, E, L and N on most plugs.
Both:
Set your multimeter to continuity mode. Touch the multimeter prongs together to check it's working, you should hear a beep. Now touch one prong to one of the plug pins, lets start with ground. Now touch the other prong to the cable which you expect to be ground (yellow/green in the UK, green in the US). You should hear a beep, signifying that there is a continuous connection between the two prongs. Now check the live and neutral connections.
Attach the Plug
Loosen the screws labelled power, ground and live on the power supply. They might be marked L and N and then have the ground symbol.
Slot the appropriate cables in next to the screws and re-tighten them.
Adjust Input Voltage
Somewhere on/inside the power supply there may be a switch which allows you to change the input voltage from 110V to 220V, so make sure this is set correctly (most likely 220V in the UK and 110V in the US).
On my power supplies the switch is inside, and you will need to use a thin screwdriver or something to reach it.
Adjust Output Voltage
Plug in your power supply. There is usually an indicator light to show that it has turned on correctly.
Now you can check what voltage you are getting across two of the output pins. Turn your multimeter to DC voltage mode (the V with the straight/dashed lines, not the wiggly line). Touch one prong to a V- screw and one prong to a V+ screw. The multimeter should show a voltage somewhere near 5V.
Use a screwdriver to turn the adjustment screw until the voltage is 5V.
Step 5: Distributing Power
Most 5V power supplies will only have one or two outputs, but we need to power 8 strips.
Wago Connectors
I use Wago connectors to distribute the power out. These little connectors have several slots to pop cables into. All the slots are connected to each other so it’s a great way to connect lots of cable together without soldering.
They come in a few different sizes (2-way, 3-way, 5-way).
Power to the Wagos
Make sure your power supply is unplugged while you do this part.
Take two pieces of 10awg cable, one for ground (black) and one for power (red).
The length of the cable needed will depend on your installation layout. I have found it works quite well to keep all power supplies on the floor in one place and then have long 10awg cables which extend to near where the strips are, and distribute the power out there. Although the power supply has two outputs, I've found it's tidier and cheaper just to use one output when these 10awg cables need to be long, otherwise you're doubling the amount of thick 10awg cable you have to buy and keep tidy.
Strip about 1cm off one end of each cable, and attach it to the power supply using the screws like you did with the plug.
Strip about 1.25cm off the other end of each cable, and put the power connection into one 3-way Wago connector and the ground into a 5-way Wago connector. (Or you can just use 5 way connectors for everything, you'll just have some more spare slots)
Then take two short lengths of red 10awg cable and two short lengths of black 10awg cable. Strip 1.25cm off the ends of each and connect up the existing Wago connectors to four more 5-way connectors. (See attached diagram for clarification).
Power from the Wagos (to the strips)
Again, the exact design here will depend on your installation layout. I said before that you might want add cable length to your LED strips, or you might want to add length to the power distribution side. If you are adding cable here, then solder lengths of 24awg cable on to your JST-connectors and make sure it is heat shrinked.
Then either take the ends of those cables, or the ends of the JST-connectors and strip away at least 1.5cm of the power and ground cables on each.
Between the four 5-way connectors you have connected to the power supply, you should have eight free slots for power and eight free slots for ground. Pop all the appropriate cables into place.
Why do we sometimes use 10awg and sometimes 24awg cables?
The different cable gauges are because there are different amounts of current in different parts of the circuit.
Coming directly from the power supply, 512 LEDs all on full white brightness could be drawing up to ~30A. Use a thick 10awg cable to transmit that current.
Once we've split the power out to the different strips though, each one is only drawing up to ~3.5A so we can use a thinner cable, around 24awg works well.
If you use a cable which is too thin, it can heat up and this is dangerous as the coating may start to melt and this can cause your circuit to short out.
The length of the cable also makes a difference. If you use a cable which would be fine at a short distance, but is too thin for a long distance - it won't heat up but it can mean that the voltage has dropped by the time it gets to the LEDs, meaning they will not light up well.
This tool can help you figure out what cable gauge you need.
Step 6: Data
If you were to connect up the JST connectors now, then your LED strips would be supplied with power. But nothing would light up because these strips need to be told what colour to be. We need to set up a data connection to the Fadecandy which will supply them with these instructions.
Prepare the Fadecandy
First solder double header pins onto the Fadecandy. Push the short side of the header pins through the holes and turn the Fadecandy over so the protruding bits are visible.
Carefully solder each of the 16 pins individually, making sure that you do not accidentally connect two pins together. (Actually all of the ground pins are connected to one another anyway, but for neatness we may as well solder all the header pins.)
Female header pins as a connector
Using female header pins to plug into the male double header pins means that the Fadecandy can easily be unplugged or replaced.
Cut off a section of 8 female header pins. Take each of the data cables from the male JST-connectors (or if you are extending the cables on this side, for your installation layout, do that first). Then slide a piece of heat shrink over the cable and solder them individually to the 8 pins. Once the soldering is done, slide the heat shrink down and blast it with the heat gun. This can now be plugged onto the data pins of the Fadecandy.
Since the 8 ground pins of the Fadecandy are actually all connected to each other, we only need to ground one of them. Cut off another short section of female header pins – it may as well be 8 pins wide as well even though we’re only going to use one pin, cutting it to be 8 pins wide will make it sturdier and easier to handle. Solder a piece of 24awg cable to one of the female header pins and heat shrink it, connect this to the ground pins on the Fadecandy.
Connect the opposite end of this ground cable to any spare slot in your grounded Wago connectors.
Labels and tidiness
You may want to label your cables at this point. Also, once again depending on the structure and layout of your installation, you may want to think about creating some kind of housing for the Wago connectors so they're not just hanging. I have previously made little plaques of plywood and hot glued the Wagos on.
Step 7: Last Hardware Bits...
That's all the hardware set up. Just a few last bits:
Plug all the JST connectors in to one another.
Plug in the power supply.
Plug the Fadecandy into your laptop via USB.
Now let's get some things lit up!
My instructions and screenshots will be Windows-centric but things should work pretty much the same way on a Mac.
Step 8: Set Up Fadecandy Software
Go to the Fadecandy github and download the zip file.
Unzip everything.
Navigate to wherever you unzipped it, and open the "bin" folder.
Run fcserver.exe.
A window will open. It should say that you have a Fadecandy device connected. It also tells you the serial number of that device. Don't close this window, just minimise it. You need to keep it open the whole time you are using the Fadecandy.
Step 9: Fadecandy Server
In a browser window (like Chrome), navigate to:
127.0.0.1:7890
You should see your connected device here as well.
Now, under your connected device you can see a drop down labelled Test Patterns. You can use this drop down to light your LEDs up to 50% or full brightness.
Do that now! Lights! Yay!!
Step 10: Troubleshooting
Check over your LED strips and make sure all your lights are working.
Here are some troubleshooting tips...
One/Some strip(s) not lighting up:
Most likely a connection somewhere is bad. Double check all your solders. It's possible the first LED in a strip is damaged. You can try swapping the strips around by swapping which JST connector is used, this will help you isolate the problem.
A strip lights up part way and then suddenly no more:
The strip might be damaged, you will probably need to perform some surgery. The damage could be at the end of the last working pixel or in the first broken one so... cut out the last working pixel and the first broken one, and solder two new ones in their place.
The strips are all orange/red instead of white:
I've found that if the strips aren't getting proper power, they will draw a tiny bit of current through the usb connection - just enough to light them up red. Double check that the power supply is on and check the connections there.
The strips are white at the start but fade to orange:
This is unlikely if you're using the power supply I linked, but could happen if you're using a power supply that isn't strong enough.
None of the strips are lighting up:
If the Fadecandy is not being recognised and showing up, you might have some driver issues. If you are getting an error message in the console window then Google that and search for suggestions.
If the Fadecandy is showing up but nothing is lighting up - double check all your connections.
Step 11: Processing!
Now your LEDs are powered and you can control them using your computer but the only thing you can do from the Fadecandy interface is turn them on and off.
Let's bring Processing in, so that we can do some cooler stuff.
Download Processing
Download Processing from here.
I'm not going to go into heaps of detail about how to write Processing code, because there are lots of places online to learn that already, and it's a whole topic of its own.
I'm going to show you how to adjust one of the Processing examples that comes with Fadecandy to the strips you've made here. You can also download my example code here.
Step 12: Mapping Pixels
Fadecandy lets you "map" (or lay out) your leds across the Processing canvas. Usually you'd want to lay them out similarly to how they are laid out in real life.
When you draw something in Processing, it shows up in real time on the LEDs.
Get the files
In the Fadecandy files you downloaded, navigate to:
Fadecandy > examples > processing
Copy one of the strip64 example folders, and paste it wherever you keep your Processing files.
This example contains mapping for one strip of 64 pixels. Rename the folder and the .pde file inside, so that it says "strips" instead.
Mapping
Open up the file. Look at these lines in the setup section:
// Map one 64-LED strip to the center of the window
opc.ledStrip(0, 64, width/2, height/2, width / 70.0, 0, false);
This is the line that is creating one strip of 64 pixels. Each of the things written between the commas is a parameter of that strip. See the attached diagram that shows what each one is. (It's also in comments in my code.)
We can use a loop to create 8 strips of 15 pixels each. Remove those two lines and replace them with this:
// Map 8 strips of 15 pixels each
for (int i = 0; i < 8; i++){
opc.ledStrip(i*64, 15, width/2, i*15 + 30, 15, 0, false);
}
Your mapping
If you have a different number of pixels in each strip, or you want to lay your strips out differently, you will need to edit this code. Use the attached diagram or the comments in the code that explain what each bit of the mapping code is for to create the code you need.
Step 13: Hit Play in Processing!
When you hit play (in the top left of Processing), you'll see the mapped strips represented as little white dots on the canvas.
(If you don't see the white dots, you probably closed the server window. Go back to step 8 and make sure you have fcserver.exe running)
The animation in the example I've used is interactive. As you move the mouse around, a dot image follows the cursor. The dot will also appear on your lights at the same time.
The animation code
The bit of code that's making this happen is here:
void draw() {
background(0);
float dotSize = width*0.2;
image(dot, mouseX- dotSize/2, mouseY - dotSize -2, dotSize, dotSize);
}
Any code you write within the draw section will show up on the LEDs.
Step 14: More Examples... Time for You to Experiment
Here are some more examples of animations I've made for these lights - a rainbow, some random blobs, and one that uses a camera feed. These are all on my github here.
I'm using a sheet of corrugated plastic as a diffuser. You could experiment with all kinds of stuff!
I strongly recommend learning Processing and making more animations for your lights! It's really quick to get started and see fun results quickly. Dan Shiffman's tutorials are a great place to start.