Normally, your computer controls how your Christmas lights are animated.  You create animations with the xLights software, then it sends commands to your light controllers and strings of strings to animate the them.

While the convenience of having a single computer for creating animations and animating your lights is nice, leaving your computer powered on all day during the Christmas season is not that efficient.  If you accidentally turn off your computer, reboot it, the computer crashes, etc., your light show stops.  Powering a computer 24x7 is not efficient with electric, either.

Some people solve this problem by creating your animations using your home computer, then playing back the animations and controling your lights using a separate, low-power computer.  This way you can continue to use your home computer as usual throughout the day, while the low-power computer is running 24x7, dedicated to playing your light show.  The Raspberry Pi is perfect for this purpose.  In xLights, you save your animations as playback files, then upload them into a special program (Falcon Player) on the Raspberry Pi that simply plays the files.

The Falcon Player software is quite powerful.  With a little bit of tweaking, not only can it play animations created from xLights, but it can allow Internet control of your light show!  By saving the xLights animations as multiple playback files (one animation per file, for example), people visiting a webpage can click buttons that tells Falcon Player which animation file to play.  For instance, an animation can make your lights look like candy canes with red & white lights, while another animation file can make your house sparkle with twinkling lights.  When no one is actively "controlling" your lights, a "regular" animation file is played for cars passing by.

The nice thing about Internet control of your Christmas lights is that is uses your existing knowledge of xLights (for creating animations).  And if you are already using Falcon Player to playback the animations, you don't have to learn much new there, either!  Internet control is mostly about tweaking Falcon Player to accept commands from the Internet and it's not that hard to do!

The Enclosure

Because the controller will be outdoors (sitting under the mega tree), I purchased a Dri-Box.  This does a good job of keeping water and moisture from entering the box due to rain, snow, changing temperatures, etc.  The disadvantage is that the power supply has no ventilation, no way to dissipate heat.  But, I have not had any controller failure due to overheating, so I think it is OK.  

There are five areas where wires can enter the box.  That is a far cry from the 16 wires that need to enter it.  I clustered 3-4 wires per area and anchored them inside their areas with black tape.

Mounting the Arduino and network board

Use only an Arduino Mega 2560 board for the WS2811 & RGB controller. This is necessary as this boards has additional RAM and plenty of output pins on it.  I found a plastic bumper on www.thingiverse.com for the Arduino.  I press-fit the Arduino in the bumper, then used foam tape to affix the bumper to a wall in the box.  I also mounted the network board to the wall of the enclosure, inserting the board in a 3D printed bracket that sticks to the box's side. Here is where you can download the bracket if you wish to print your own.

Mounting the power supply

The controller uses a computer power supply that I had lying around.  This power supply provides 5V to power the ws2811 lights and 12V to power the RGB lights.  I mounted it to the floor of the box with foam tape.  I also attached an inexpensive voltage display to the box's side. You can search for "dc voltage display" on eBay to find similar displays. This way, the power supply displays the current voltage as the lights are running, as it's important to keep the voltage as close to 5V as possible (at least for the 5V ws2811 strings).

Mounting the relays

Each of the three trees using two strings of "dumb" RGB lights for a total of six strings.  Each string require three relays to switch on/off 12V to them, a total of 18 relays.  I purchased three of the below 8-relay boards.  To mount them in the box, I cut two strips of wood, mounted them vertically on the box floor, then screwed down the three relay boards horizontally down the wooden strips.  

Important, before mounting the relays in in the box, it will be much easier to connect wires to the relays' screw-down terminals first!  Especially all of the 18 ground wires.  Please see the "Connecting the "dumb" RGB strings to the Arduino" section below on how to connect wires to the relays.

Mounting the ws2811 connectors

The original ws2811 strings either came with bare ended wires or already connected to a JST-style connector; I cannot remember.  Regardless, I terminated each of the eight ws2811 strings with a female 4-pin JST connector like the one below.  I foam tape mounted an eight-terminal strip on top of the power supply, then connected eight wires to the input pins on the Arduino (see this diagram for details).  

NOT mounting the power terminal strip

In the below picture, attached to the power supply, is a terminal strip of red & black wires with capacitors mixed in.  When I first built the controller, the ws2811 strings on the mega tree would randomly "glitch" (bulbs would change to unexpected colors).  I tried placing capacitors between the power and ground connections to each string, but that did not fix the problem.  The true solution was placing 220-ohm resistors in-line the strings' data wire, absorbing "signal bounce".  Instead of removing the power terminal strip and capacitors (which didn't help anything), I lazily left it all there.  You do not have to wire this portion of the controller.

Wiring everything up

You can download the wiring diagram here.

Powering everything

First off, wire all components to power.  The computer power supply has 4-pin Molex hard drive female power connectors.  I connected a male Molex connector to that, then ran the red wire to the power terminal strip that I stuck to the top of the power supply.  This strip powers the ws2811 strings.  

I then ran the yellow wire from the Molex connector to a small power terminal that I stuck to the side of the computer power supply.  I also ran 5V and ground from the main power terminal to this smaller terminal.  Thus the smaller terminal provides "12V, 5V, and GND" connections.  This terminal is used to power the RGB strings and relays.  From this smaller terminal, wires from the 12V terminal runs to each RGB string (six wires).  The 5V and GND terminals runs wires to power and ground each of the three relays.  It also grounds the Arduino.

Lastly, I placed a 6V 2A DC "wall wart" in the box, then connected its power connector to the Arduino.  This provides a power source to the Arduino that is independent of the computer power supply, as the latter's voltage level could fluctuate when the strings were lit with different colors.  Also, since my computer power supply didn't quite produce 5V of power, the network board could not operate correctly.  Giving the Arduino a dedicated 6V power connection and powering the network board from the Arduino solved my problem with dropped network connections.

Important! Make sure that you use a male Molex connector with thick wires or multiple wires per pin, when connecting this plug to the computer power supply!  The eight ws2811 and six RGB strips pull more amps that I realized.

Grounding everything

The final step to powering everything is grounding everything.  The Arduino, network board, relays, and ws2811 & RGB strings need to share a common ground so that their circuitry works properly.  If you don't do this, the lights will behave unpredictably.  Thankfully, this is fairly easy to do.  The Arduino have multiple ground ports, so run a ground wire from that to the power terminal strip  The network board can be grounded to the GND pin on the Arduino.  The relays get their ground from the side mounted, smaller power terminal, which in-turn gets its ground from the main power terminal strip on top of the power supply.

Connecting the ws2811 strings to the Arduino

This is fairly easy to do.  Each of the eight ws2811 strings (for the mega tree) has a single data wire, a total of eight data wires.  I mounted a terminal strip to the lower-right top of the power supply with foam tape, then ran wires from the terminal to eight pins on the Arduino (see the above wiring diagram for pin number assignments).  On the other end of the terminal, I connected eight 220-ohm resistors.  I soldered the other end of the resistors to the green "data" wire on eight female JST connectors.  The in-line resistor for the strings' data line is important to absorb "signal bounce" that can cause glitching problems in the bulb colors.  

I ran the eight red "power" wires from the JST connectors to the 5V power terminal strip and the eight black ground wires from the JST connectors to the GND power terminal strip.  Since the amperage from eight ws2811 strings can be high, either use thick wires if your power and ground wires are sharing one terminal or scatter the 8 power/ground wires to several terminals on the power strip.  This prevents the wires from getting too hot and melting!  

I clustered all eight JST connectors together, then held them together with a wire clamp that is foam taped to the top of the power supply.  That keeps the connectors from pulling on the wiring as you connected/disconnect the strings to them.

On the ws2811 strings themselves, I soldered male JST connectors on them.  Each string has a 5V, data, and GND line, so make sure that you match these wires with the proper wires on the female plug in the controller.

Connecting the "dumb" RGB strings to the Arduino

These strings are analog in nature and require relays to properly light them.  So it's (sadly) a lot more work to connect them to the Arduino.  My controller box controls three trees that each have two strings of RGB lights on them.  Each RGB string uses four wires, a 12V wire and three ground wires.  Setting the ground signal in different combinations on these three ground wires is what changes the color on these strings (seven combinations). Each ground wire must be connected to the Arduino's data pins, which means there are 18 connections!

Even though the relay strips have eight relays on them, I am currently only using six relays per strip (this controls two RGB per strip).  Thus, in my case, each relay strip controls one tree (two strings per tree, six ground wires total).  

To start, connect six wires from the Arduino to pins IN3 through IN8 on each relay strip.  The GND pin on the strip goes to GND on the power terminal, while the VOC pin goes to 5V on the power terminal.  In the lower-right corner of my relay strip, there is a small set of pins labeled "GND VCC JD-VCC".  Run a wire from GND to GND on the power terminal, then use a jumper to connect VCC and JD-VCC together.

On each relay are three screw-down terminals.  The middle terminal is the "input" signal and the right terminal is the "output" signal.  The left-side terminal is not used.  The relays are used to send the GND signal from the Arduino to the ground wires on the RGB strings.  This is what controls the color combinations.  Run wires from the GND power terminal to the middle screw-down "input" terminals on all 18 relays.  It may be easier to run one GND wire from the power terminal to the first relay in the strip, then daisy-chain from that relay to each relay in the strip.

Next, connect three wires from six female JST connectors (18 wires total) to each of the right-side screw-down terminals on the 18 relays.  These are the "output" wires that send GND signals to the strings.

The four wire on the JST connector is to provide 12V power to the string.  Connect these wires (one wire per string, six wires total) to the 12V power terminal.  These are are not connected to the relays.  The relays are only switching GND off and on, not power.

That's it!  Connecting "dumb" RGB strings to the Arduino is a lot of work.  Overall, it's easier to use ws2811 strings for everything and not bother with "dumb" RGB at all.  :)  However, RGB strings require less processing power and memory on the Arduino, so it is easier to control lots of RGB strings than the same amount of ws2811 strings.

Avoiding "glitching"

You may find that bulbs light-up sporadically, changing to unwanted colors or not changing colors at all.  If your ws2811 strings are glitching (particularly as more strings are connected to the controller), consider adding 100-220 ohm resistors to the data lines between the Arduino and lights (closer to the Arduino).  This may help absorb "signal bounce" in the data lines, affecting the other strings.  

Programming the Arduino

When you create animations on your computer with xLights then hit "play" to playback the animations to your strings of lights, xLights sends commands in a language called "DMX".  These commands leave your computer, travel on Ethernet cables via a protocol called "E131", then are received by light controllers can speak the DMX language.  These controllers then animate the strings of lights connected to them.

You need to install a program on the Arduino that makes it become a DMX controller.  This program was written by Keith Westley, allowing inexpensive Arduino microcontrollers to replace expensive, dedicated DMX controllers costing hundreds of dollars.

To program the Arduino, you need to download the Arduino IDE.  This allows you to upload programs from your computer to the Arduino board.  Normally, you download Keith's DMX program, open it into the IDE, then upload the DMX program to the Arduino board.  This is trickier than it sounds, as Keith's program needs installed a special way into the IDE.  To save you time, you can download the Arduino IDE with Keith's program already installed from here.  Simply unzip this file into a folder on your computer.  Here are steps to compile the sketch:

1. Unzip the file into its own folder.
2. Run arduino.exe
3. From the menu, choose Tools > Board > "Arduino Mega or Arduino Mega 2560"
4. From the menu, choose File > Examples > DMXControllerWs2811"
5. On the toolbar, click the "checkmark" button (named "Verify") to compile.
6. Compiling has finished when you see "Done compiling" at the bottom of the window.

Configuring the DMX program

The next step is configuring the DMX program for your particular lights, such as the number of strings that are connected to the Arduino and the IP address that you will assign to the Arduino, which is important for xLights to "see" your controller.  To do this, edit the global.h file in the arduino-1.6.5-r2\examples\DMXControllerWs2811 folder with your favorite text editor.  These are the important lines that need changed:

#define UNIVERSE 

A "Universe" is a number that represents all of the strings connected to your Arduino.  In my case, I have two Arduinos, one set to universe 1 and the other set to universe 18.  These numbers are defined in xLights.  So when xLights is sending DMX commands to light-up strings in a particular universe, the Arduino is listening and acts upon commands only for its universe.  If you don't know the universe for your particular controller,first  read the section on setting up xLights on this website before continuing with these instructions.

#define MAXBULBS

If the strings of ws2811 lights connected to your Arduino have different number of bulbs on them, MAXBULBS indicates the number of bulbs on the longest string.

#define OUTPUTSTRINGS

This defines how many ws2811 strings are connected to the Arduino (a maximum of eight are allowed)

#define IP_BYTE_1 169
#define IP_BYTE_2 101
#define IP_BYTE_3 200
#define IP_BYTE_4 203

These four lines define the IP address for this Arduino.  This way, xLights on your computer can "find" your Arduino on your Ethernet network and send DMX commands to it.

Uploading the DMX program

The next step is sending the DMX program to the Arduino's memory.  To do this, open the folder that contains the Arduino IDE that you downloaded above.  Then run arduino.exe.  When the program starts, click File > Examples > DMXControllerWs2811.  A second Arduino IDE window will appear with the Keith's DMX program open.

Before connecting your Arduino, verify this first:

* Make sure that you are using the Arduino Mega 2560.  DMX program only works with this board.

* If you have strings of ws2811 and/or RGB ights connected to the Arduino, it is a good idea to temporarily disconnect them.  If the Arduino already has an older version of the DMX program and you connect the Arduino to your computer, the Arduino may draw too much power from the USB port to power the lights.

When you have met the above requirements, connect the Arduino to your computer via a USB cable.  If this is the first time you have connected the Arduino, Windows will attempt to install hardware drivers for it.  Depending on the version of Windows that you have and the brand of Arduino, the driver may install automatically or you may be prompted to provide the driver software (you may have to download the driver software for that particular brand of Arduino).  Either way, the drivers must be installed successfully before proceeding to the next step.

When you connect the Arduino via USB and the computer accepts the connection with no errors (indicating that the drivers are installed and functional), tell the Arduino IDE the type of Arduino you are using.  Click Tools > Board > "Arduino Mega or Arduino Mega 2560".  Next, choose Tools > Ports > COM x where "COM x" is the virtual communications port that was assigned by the driver.  If you see more that one listing under "Ports" and are not sure which one to choose, try the first one, then try uploading the DMX program as explained below.  If the upload fails, choose the next COM port under Ports, then try uploading again.

Next, verify that the DMX program code is valid by clicking the checkmark icon in the Arduino IDE toolbar (below the File menu).  You will see "Compiling sketch..." in the window's lower status bar while the program is verified.  This may take several moments.  If you see an orange message stating "Error compiling", then there is something wrong with the DMX program or perhaps there is a typo in the global.h file that you modified above.  In this case, you will need to close the Arduino IDE program, fix the problem, then open the Arduino IDE and try to verify the program again.

If the DMX program verifies correctly, you will see the "Done compiling" message in the status bar.  At this point, you can upload the DMX program to the Arduino via the Upload button (the right-arrow button next to the checkmark button in the toolbar).  When you click Upload, the DMX program will be verified again, then you will see "Uploading" in the lower status area.  A light on your Arduino will rapidly flash during the upload process.  When the upload is complete, you will see a message stating so in the status area.  You can disconnect the Arduino from the USB cable.

Checking communication

After the DMX program is uploaded to the Arduino, it will begin running the DMX program immediately.  We now need to see if the controller can be contacted on an Ethernet network.  To do this, connect one end of an Ethernet cable to the Arduino's network board and the other end to an Ethernet switch or hub.  Connect your computer to the Ethernet hub/switch via another cable.

Next, verify your computer's IP address.  It must be on the same subnet as the IP address that is assigned to your Arduino.  For instance, if your Arduino is assigned an IP address of 169.101.200.203, your computer's Ethernet card must be assigned a similar IP address of 169.101.200.x where "x" is a number from 1-254, but not 203.  Having a similar subnet on both your computer and the Arduino is important for them to "see" each other on the Ethernet network.

Then you can power-on your light controller.  Lights should appear on the Arduino.  On the end of the network cable that plugs into the Arduino's network board, there are two lights.  One should be solid, indicating a connection to the Ethernet hub/switch.  The second light should be flickering occasionally, indicating that the Arduino is sending/receiving information on the Ethernet network.

Install Rate Manager (optional)

If your light controllers do not involve Arduino, then please skip this step.  

My controllers do use Arduinos.  Arduinos are not very fast and get get overwhelmed with the vast amount of data that xLights or Falcon Player sends to them over the network.  To solve this problem, Keith Westley wrote a program called Rate Manager that intercepts all of the data going to the light controllers, reduces the data to a smaller size, then sends it to the light controllers.  Rate Manager act as a "middle man" to reduce the data size going to the controllers, making it easier for the Arduinos to handle the incoming flow.  Installing Rate Manager is a little trick, but once it's installed, it works like a charm.

Download and install Rate Manager

You can download Rate Manager here.  Unzip the file, revealing two files: e131ratemanager and E131RateManager.xml.  Follow these steps to copy the program from your home computer to the Raspberry Pi:

1. Download and copy Rate Manager to the Raspberry Pi
   1. In the Falcon Player web interface, choose "Content Setup > File Manager".
   2. When the File Manager screen appears, click the [Uploads] tab.
   3. In the "Upload Files" section, click the blue [Select Files] button.
   4. When prompted, open the folder that contains the two files that you downloaded above.  Select e131ratemanager, click the [Open] button.  
   5. Repeat Steps 3 & 4 for the and E131RateManager.xml file.
      
      
2. Install Rate Manager
   1. In the Falcon Player web interface, choose "Help > SSH Shell" from the menu.
   2. If your web browser shows a message that "Your connection is not private" or something like that, choose the Advanced link, then the "Proceed to..." link.
   3. When the "FPP login:" prompt is displayed, enter "fpp" then press [Enter].
   4. When the "Password: prompt is displayed, enter the password that you defined.  If you do not have a custom password, try "falcon" instead.
   5. Enter the following commands and press [Enter].  Note, the following commands are case-sensitive!
      
      1. mkdir /home/fpp/media/e131RateManager
      2. cd ~/media/upload 
      3. sudo chmod u+x e131ratemanager
      4. mv e131ratemanager /home/fpp/media/e131RateManager
      5. mv E131RateManager.xml /home/fpp/media/e131RateManager
         
         
3. Configure Rate Manager

    Rate Manager needs to know the IP addresses and universe assignments for your light controllers.  This way, the show commands it receives from Falcon Player can be passed by Rate Manager to the correct light controllers.  To configure Rate Manager, type the following command, then press [Enter]:
   
   

   sudo nano /home/fpp/media/e131RateManager/E131RateManager.xml

   
   The file shown is a copy of my Rate Manager configuration.  You can modify it to suit your needs.  Of note:
   

   There must be a separate <Controller> section for each of your Arduino controllers.Inside each <Controller> section:
   

   * <IPAddress> is for specifying your Arduino's IP address
   * <Id> is the last part of the Arduino's IP address.  For example, if the IP address is "169.101.200.201", the <Id> is "201"
   * <MaximumMillisBetweenSends> should be "0" for GECE controllers and "500" for ws2811/RGB controllers
   * In the <Universes> section, list all universes supported by that controller, one per line

   Press [Ctrl-O] (the letter "o") to save your changes, then press [Ctrl-X] to exit the text editor.

    

4. Start Rate Manager automatically
   
   You can configure the Raspberry Pi to start Rate Manager upon power-up.  This way, when Falcon Player starts, Rate Manager is ready to receive commands from it, of which the commands are passed to the light controllers
   
   
   1. Type the following command:
      sudo nano /etc/rc.local
      
      
   2. Add the following line to the bottom of the file, but above "exit 0":
      exec /home/fpp/media/e131RateManager/e131ratemanager -q &
      
      
   3. Press [Ctrl-O] (the letter "o") to save your changes, then press [Ctrl-X] to exit the text editor.
      
      
5. That's it!  Type "exit" to leave SSH Shell, returning you to the Falcon Player web interface.  Then click the [Reboot] button at the bottom to restart the Raspberry Pi.  Rate manager should be active at this point, waiting for commands from Falcon Player.
   
   If you want to see if Rate Manager is actually running, open the shell and login, then type "top".  Rate Manage should show as a running process near the top of the list.

All Done!

At this point, you are finished building the ws2811 & RGB light controller!  The next step is configuring xLights to "see" your light controller, then running a sample animation to determine if xLights can properly communicate with it.   If all goes well, the sample animation will begin flashing the ws2811 & RGB lights that are connected to your controller.  This is explained in the "How to test it" section on this website.

The brain of the WS2811 controller is an Arduino microcontroller.  One Arduino can control up to eight WS2811 strings of 50-bulbs each and eight strings of 50-bulb "dumb" RGB strings.  An network board is connected to the Arduino, allowing it to communicate on an Ethernet network.  

A program is installed on the Arduino (in Arduino lingo, a "sketch") that allows the Arduino to listen for DMX commands coming from xLights on a laptop computer (or from Falcon Player running on a Raspberry Pi).  These DMX commands originate from xLights or Falcon Player, travel through Ethernet, then enter the Arduino through it's network board.  The Arduino then changes the WS2811 and RGB lights that are connected to it.  

The ws2811 and RGB strings are powered from a computer power supply.  This provides 5V of power to the ws2811 strings and 12V of power to the RGB strings.  I discovered that this particular computer power supply did not provide quite enough 5V power (it was under 5V), so the Arduino and/or network board would occasionally crash and/or lose its network connection.  To solve this problem, I am powering the Arduino with a 6V DC "wall wart" power adapter, then the network board gets its power from the Arduino.

Connecting the ws2811 strings to the Arduino is easy as each string has a single data wire that connects to an output pin on the Arduino. Connecting the RGB strings to the Arduino is much more difficult.  The three data wires on the strings require 12V and also enough amps to drive the strings.  The Arduino can only provide low-amp 5V power on its output pins.  To solve this, I connected relays to the Arduino that to switch 12V on-and-off from from the computer power supply to the strings.  For six RGB strings that have three data wires each, that means wiring 18 relays!  It's a lot of work.

I discovered that the controller would randomly light-up the wrong bulbs on the ws2811 strings.  To fix this, I placed 220-ohm resistors between each string's data lines and the Arduino.  This absorbs "signal bounce" that causes stray signal from one string's data wire to affect the other strings' data wires.

WS2811 lights

WS2811 represents a wide variety of low-cost LED lights where each bulb can be individually controlled.  There are many different kinds of lights that "speak" the WS2811 language, from ribbons where bulbs are tiny squares attached along a strip, to bullet-style lights as shown below, to flood lights.  There are variations of the WS2811 language (a.k.a. "protocol"), including WS2812 and WS2812B.  I use the WS2811 bullet-style lights for my "mega tree".  

These lights are easy to work with.  There are only three wires involved: 5V power, data, and ground.  You can shorten a string by simply cutting it or add more bulbs by soldering strings together.

While there are commercial controllers available that allow WS2811 lights to work with xLights, it is possible to use a low-cost Arduino to control them. Each Arduino can drive up to eight strings of 50-bulb WS2811 lights.  That is enough to support my mega tree that uses 400 bulbs.

RGB lights

Another style of lights are called "RGB".  While each light on a WS2811 string can be individually controlled, RGB lights are much simpler in that the entire string changes to the same color.  WS2811 lights use a digital protocol to control them; only a single wire is needed.  RGB lights, however, are analog in nature.  They use four wires, three for controlling the strings' color and the fourth is ground.  To change the string's color, you apply ground (GND) to some of the three wires.  This means you can only choose from seven colors on an RGB string, whereas the digital WS2811 lights can be thousands of colors.  And finally, connecting RGB lights to an Arduino is complicated as relays are needed for the Arduino to switch GND on and off to each of the three wires.

One controller for both 

One Arduino can control up to eight strings of WS2811 lights (50-bulb strings) and eight strings of "dumb" RGB lights.  I use this controller to drive the 8-string "mega tree" and also three smaller trees that use two strings of RGB lights each.  A network board is connected to the Arduino, allowing it to communicate with xLights.