Tom Hammond

Tom Hammond

Falcon Player's purpose is to play shows created in xLights, controlling your lights.  These shows are saved as .fseq (sequence) files in xLights, then copied to Falcon Player on the Raspberry Pi.  Falcon Player is very flexible in playing back shows, you can combine multiple shows/fseq files into a "playlist" that plays one show after another, for more complex animations.

The idea is to allow people living in your neighborhood to watch your regular, fancy show, but allow the show to be temporarily interrupted by people on the Internet who want to control your lights.  When the Internet people have finished, your regular show starts again. 

My regular show is 8-1/2 minutes long.  For Internet control, I make a series of small shows, only 30 seconds long.  When someone from the Internet selects one of these mini shows, my regular show stops and the chosen mini show plays for 30 seconds.  When the mini show is finished, the regular show starts again.  Thus Internet people only have temporary control of your lights; when there is no one controlling them, your regular show plays for the people in your neighborhood as usual.  This is accomplished by setting up playlists in Falcon Player.

 

Uploading show/sequence files to Falcon Player

Falcon Player makes it easy to upload the show files that you created in xLights from your home computer to the Raspberry Pi.  You'll need to upload your regular/fancy show file (that your neighbors see) as well as the shorter "mini show" files (that Internet control people will see) to Falcon Player.  These show files are saved in the xLight's "show" directory.  Pressing [F9] in xLights will indicate where your show directory exists, but you will need to close xLights then open this folder with your operating system to reveal all of the .fseq files you have created.

In the Falcon Player menu, choose "Content Setup > File Manager", then click the Sequences tab.  The "Sequence Files" section should be empty as you haven't uploaded any sequence files yet.  Click the blue [Select Files] button, then browse your computer to the xLights show folder where your sequence (fseq) files are located.  When you select your fseq file from a show and then click [Open], the file is immediately uploaded to Falcon Player on the RPi.  Repeat these steps to upload your regular show file and all of your mini show fseq files.  The Sequence Files section should fill-up with all of the fseq files that you uploaded.

 

Creating playlists from the show/sequence files

Now that your show/sequence files are copied to Falcon Player, the next step is creating playlists that control how these shows are played.  The goal is that the regular/fancy show is in a playlist to itself.  This is what plays continuously until someone from the Internet requests control of your lights.  When this happens, a different playlist is started.  This other playlist will play a "mini show" for 30 seconds, then start playing the regular/fancy show again.  After the Internet control is finished, Falcon Player will continue playing the regular/fancy show for the neighborhood to enjoy.

To create the regular/fancy playlist:

  1. Click the Content Setup > Playlists menu in Falcon Player.  In the New Playlist field, enter a name (I chose to call my regular playlist the word "on", it's not a very good name), then click the [Add] button.  

  2. Scroll to the bottom of the window to the Playlist Details section.

  3. For the Type field, choose "Sequence Only".

  4. For the Sequence field, choose your regular/fancy show/fseq file from the drop-down list, then click the [Add] button.

  5. Click the [Save] button to save the playlist.

Next, create playlists for each of your "mini shows" that Internet visitors can control.  The process a little different than creating the regular/fancy playlist, so follow these steps instead:

  1. Click the Content Setup > Playlists menu in Falcon Player.  In the New Playlist field, enter a name (I chose to call my regular playlist the word "on", it's not a very good name), then click the [Add] button.  

  2. Scroll to the bottom of the window to the Playlist Details section.

  3. For the Type field, choose "Sequence Only".

  4. For the Sequence field, choose the mini show fseq file from the drop-down list, then click the [Add] button.

  5. Repeat Step 4, but choose your regular/fancy show/fseq file from the drop-down list, then click the [Add] button.

  6. In the list at the bottom of the Playlist Details section, you should see two shows: the regular/fancy show and the mini show.

  7. Place a checkmark in the "Play first entry only once" checkbox.

  8. Click the [Save] button to save the playlist.

Now repeat the above steps for additional mini shows that you wish Internet visitors to control.

 

Securing Falcon Player from Internet hackers

As of version 1.8 of Falcon Player, it was not designed to made open to the world for Internet users to control it.  The original intention of Falcon Player was for the home owner to play shows using a low-cost, low-power computer and an easy-to-use web interface, all from your home network.  That being said it, it is possible to add a small amount of security to make it work safely from the Internet.  It is a far cry from being totally secure, but the steps below work well enough.  If you leave your Raspberry Pi with Falcon Player powered on for only the holiday season, the security is good enough.  But don't leave Falcon Player running and connected to the Internet 365 days a year, otherwise it could get hacked and damaged.

 

Set password for Falcon Player web interface

  1. Under the "Status/Control > Set UI Password" menu in Falcon Player, Click the "Enabled" field.

  2. Specify a password in the "Password" and "Confirm password" fields.  Try to make the password difficult to figure out.  For instance, do not use real words or names, add numbers and special characters, etc.

  3. Click the [Submit] button to save the password.

Once the password is saved and enabled, you will be required to enter the login name of "admin" and your password to access the Falcon Player web interface.  Write down this password and don't lose it!

Note: If you change this password in the future, it will erase modifications made to the .htaccess file in the "Configure Falcon Player to receive commands from the Internet" instructions below.  So whenever you change this password, be sure to fix the .htaccess file as well!

 

Set password for Raspberry Pi operating system

This step prevents hackers from bypassing Falcon Player and attempting to login to your Raspberry Pi directly.  If hackers can login with the "fpp" account, they can damage files on your Raspberry Pi!

  1. In the Falcon Player web interface, choose "Help > SSH Shell" from the menu.ke that, choose the Advanced link, then the "Proceed to..." link.

  2. When the "FPP login:" prompt is displayed, enter "fpp" then press [Enter].

  3. When the "Password: prompt is displayed, enter "falcon".  
    1. Note: If this password does not work, try the Falcon Player web interface password that you set in the instructions above.

  4. If the working password was  "falcon", change it to another password by typing the following command and press [Enter]:
    1. sudo passwd fpp
    2. When prompted, enter a new password twice (you can use the same password as the Falcon Player web interface, if you like).

  5. Type "exit" and press [Enter] to exit the SSH Shell.

 

Disable "root" login for Raspberry Pi operating system

This step also prevents hackers from bypassing Falcon Player and attempting to login to your Raspberry Pi directly.  If hackers can login with the "root" account, they can have complete access of everything on your Raspberry Pi!  Do the following steps: 

  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 in the instructions above.

  5. Enter the following command and press [Enter]:
    1. sudo nano /etc/ssh/sshd_config
    2. A screen full of text will appear.  
    3. About 27 lines down is a line that begins with "PermitRootLogin".  If the word after it is "yes", change it to "no".
    4. Press [Ctrl-O] (the letter "o") to save your changes.
    5. Press [Ctrl-X] to exit the text editor.

  6. Type "exit" and press [Enter] to exit the SSH Shell.

 

Backing up Falcon Player settings

There is a lot of settings you have made to Falcon Player at this point.  It is possible to save Falcon Player's configuration to a backup file.  This way, if the settings are damaged or accidentally changed, they can be restored from the backup.  Here is how you do it:

  1. In the Falcon Player menu, choose Choose Status/Control > FPP Backup.
  2. Remove the checkmark from "Protect sensitive data".
  3. Click the [Download configuration] button.
  4. In a moment, a file will download to your computer containing most of Falcon Player's setting.  Store this file in a safe place.

    Note that the json file does not restore the UI login name & password as “admin” and “r00123456fpp” and the SSH name & password is “fpp” and “r00123456fpp”. These need to be set manually after restoring. 

 

Configure Falcon Player to receive commands from the Internet

Normally, setting a password to access the Falcon Player web interface prevents scripts from running without that password.  The following steps are needed so that shows can be played via scripts.  This is necessary for Internet control of your lights.

  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 in the instructions above.

  5. Enter the following command and press [Enter]:
    1. sudo nano /opt/fpp/www/.htaccess

  6. Add the following lines to the bottom of this file:
           <Files "runEventScript.php">
           Allow from all
           Satisfy any
           </Files>

  7. Press [Ctrl-O] (the letter "o") to save your changes.

  8. Press [Ctrl-X] to exit the text editor.

  9. Type "exit" and press [Enter] to exit the SSH Shell.

  10. Reboot Falcon Player by clicking the [Reboot] button at the bottom of the web interface

Getting Started

Most people create their animations using xLights (also called "sequences" or "shows"), then also use xLights to animate the lights themselves with the show that you created.  For Internet control, you still use xLights on your home computer to create animations, but the show playback files (.fseq) are saved to a Raspberry Pi computer (RPi).  The RPi computer then plays back the animations.

To do this, you will need a Raspberry Pi computer.  I recommend Model 2 or Model 3; they are much faster than the original RPi and should be able to handle controlling many lights.  You will also need a memory card (I am using a 16 gigabyte microSD card, but probably 8G is enough).  You will also need a 2A DC power supply with a micro USB connector.  If you search for "Raspberry Pi" on Amazon, you will find lots of kits there with these components together, including a case that keeps the RPi protected.  Lastly, you will need an empty flash drive (2G or more) at least temporarily.

 

Installing the software

First, you need to install the RPi operating system and Falcon Player onto the memory card.  Normally these are two separate, complicated steps.  But there is a method that combines both into one step. Using your home computer (not the RPi), click this link to download the "image file" for the RPi operating system and Falcon Player.

Note, the version of Falcon Player may be out-of-date by now (v1.8), but it is what I am using and works fine on a Raspberry Pi 2.  It should also work on a RPi 3, but I have not tried that.  You can check this link for the latest version of the image file.  Insert the microSD card into your home computer (you may need a memory card reader).  Next, unzip the file that you downloaded onto the microSD card.  When this process is complete, your memory card should have lots of files and folders on it.

To prepare your RPi for its first power-on, do the following before connecting its power cable:

  1. Insert the memory card into the RPi
  2. Connect your TV to the RPi using an HDMI cable
  3. Set your TV's input to that HDMI port
  4. Connect a USB keyboard and mouse to the RPi
  5. Connect an Ethernet cable that allows the RPi to access the Internet and your home computer via your router

After you have completed the above steps, connect the RPi's power cable to the RPi, then plug the power cable into a power outlet.  The TV should start displaying information!  It is installing the Raspberry Pi operating system and Falcon Player automatically.  This process may take a while.  

Important: When the installation is complete, it will prompt to reboot the RPi.  Before doing this, insert the empty flash drive into the RPi's USB port.  This is important as the flash drive is required while booting the RPi operating system for the first time.

 

Configuring the RPi operating system

The first time that your RPi boots into its operating system, it will request an IP address from your router's DHCP server.  Open your router's configuration application to determine the IP address that was assigned to your RPi.  You can then configure Falcon Player on the RPi using a web browser on your home computer.  Simply open a web browser, then go to the IP address.  

Note: Your home computer and RPi must be connected to the same router via Ethernet cables in order for them to "see" each other.

 

Setting up a static IP address

The first time that your RPi boots into its operating system, it will request an IP address from your router's DHCP server.  DHCP IP addresses can change from time to time, however.  For Internet control to work, your RPi must use a static (permanent) IP address instead.  To set a static address, do the following:

  1. Open a web browser and go to the IP address that your router assigned to your RPi.  

  2. You may be prompted for a login name & password.  The default password is "fpp" and the password is "falcon".

  3. When the Falcon Player - FPP" window appears, go to "Status/Control > Network" in the menu.  

  4. Set "Interface Mode" to "Static".

  5. In my case, I set the IP address to "169.101.200.200", a Netmask of "255.255.255.0" and a Gateway of "169.101.200.1".  

  6. In your case, you need to change these numbers to your own computer's subnet.  
    1. In Windows, open a Command Prompt, then type this command:
      ipconfig /all
    2. In the information shown, scroll to the top of the information to find the "IPv4 Address" line.  The first three numbers are your subnet.  Replace the "169.101.200" subnet in my example with your own subnet for the IP Address and Gateway.  
    3. The fourth number in the IP Address can be any number from 2-254, but it should not conflict with your home computer's IP address nor IP addresses used by any other device on your network.  
    4. The fourth number on the Gateway should always end with a "1".

  7. Lastly, click [Update Interface] to save your settings.

At this point, you may lose access to the RPi from your web browser, as the IP address is changed.  Simply type the new, static IP address into your web browser and you should be able to login to Falcon Player interface again.

 

Disabling the flash drive (optional)

Falcon Player normally saves its configuration information, the show playback (.fseq) files, etc. on the flash drive that is inserted in the RPi during installation.  I chose to save this information on the microSD memory card where the operating system and Falcon Player are.  To me; it's one less thing to worry about by not having a flash drive.  To tell Falcon Player use the memory card for everything (and not the flash drive), go to "Status/Control > FPP Settings" in the Falcon Player menu, then set the External Storage Device to the memory card.  This should be listed as “mmcblk0p7 - 13.7GB (boot device)”.  13.7GB may be a different number in your case, depending on the overall size of your memory card.  You may need to reboot Falcon Player to effect the change.

 

Setting up the time zone

It is good idea to tell Falcon Player which time zone that you live in.  This is important so that Falcon Player starts your light show at the correct time each evening.  In the Falcon Player interface, click the "Status/Control > Config/Set Time" menu, then choose your time zone from the drop-down list under "Time Zone".  Click the [Submit] button to save your settings.

 

Disable Falcon Player's "Auto Update" feature 

I do this as a precaution if a future version of Falcon Player change enough to perhaps break the Internet control feature that I have setup.  To disable Auto Update, go to the Help > About menu in Falcon Player, then place a checkmark in the "Disable Auto Update" field.

 

Configuring Falcon Player to communicate with your light controllers 

When Falcon Player is "playing" a show, it sends commands to the light controllers, telling them which lights should display various colors in the show.  Falcon Player and the light controllers communicate via Ethernet cables using a special language called DMX.  The Raspberry Pi has an IP address and your controllers have IP addresses, this is how they find each other in the network.

If you were not using Falcon Player nor the Raspberry Pi, you would use xLights on your home computer to send commands to the light controllers.  The [Setup] tab display all of your light controllers, like the screen below:

Here are the important columns in this list:

Port

These are the IP addresses of your light controllers.  This way, xLights can find your various controllers on the network and send commands to them.  

In my case, you'll notice that all of the IP addresses are the same.  Normally, all of my Arduino light controller have unique IP addresses.  Arduinos are not very fast and get get overwhelmed with the vast amount of data that xLights sends to them over the network.  To solve this problem, Keith 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.  That is why the IP addresses in the Port column are the same; xLights is sending all of its data to Rate Manager which is running on the Raspberry Pi.  If you are not using Arduino based light controllers, you do not need Rate Manager; you would put unique IP addresses for each of your controllers in the Ports column instead.

Baud Rate or E1.31 Universe

A light controller usually has multiple strings of lights attached to it.  In its simplest terms, each string is defined as a "universe", at least with my lights setup.  For instance, my GECE light controller (with two Arduinos controlling 16 strings), controls universes 1-8 and 18-25.  The Arduino running the ws2811 mega tree and RGB "three trees" controls 8+6 strings of lights, respectively, as universes 9-17 (the 17th universe can control all six strings of "dumb" RGB lights).  These universe numbers are saved into the Arduino's memory.  When xLights sends commands to certain universes, the correct Arduino knows when commands have arrived for its universes.

Num Channels

This number represents how many unique lights are in each string.  With GECE and ws2811 lights, each bulb contains three LED lights: red, green, and blue.  By mixing these three lights, you have hundreds of thousands of color possibility.  To xLights, a single bulb has three channels (red, green, and blue).  Therefore a string of 50 bulbs has 150 channels.  A string "Dumb" RGB lights can only be one color for the entire string.  Only three channels (red, green, and blue) are needed for each of these strings.

xLights/Vixen/FPP Mapping

Each light in your display has a unique "serial number" assigned to it.  That way xLights can easily control specific lights.  If your first string has 50 bulbs, there are three lights per bulb, so 150 lights would have serial numbers of 1-150.  The second string of lights would have serial numbers of 151-300, and so on.  Again, with "dumb" RGB lights, there are only three serial numbers (red, green, and blue) per string.

 

Since Falcon Player will be controlling your lights (not xLights), you need to copy the above ports, universes, and channels into Falcon Player.  Newer versions of xLights and/or Falcon Player can do this automatically, but I had an older version and manually copied the information to this in Falcon Player (via the "Input/Output Setup > Channel Outputs" menu):

 Also be sure to set the checkbox for "Enable E1.31 Output" above.  Be sure to click the [Save] button when you are finished!

 

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.

Create a variety of xLights animations as multiple playback files

To animate your lights, you create special effects in the xLights program, then save these effects as a "sequence file" (also called a "show").  The show can be as fancy and you like and can run a long time.  This page doesn't explain how to create shows in xLights, you can read how to do this in the xLights instruction manual here.

For Internet control of your Christmas lights, the idea is to allow people living in your neighborhood to watch your fancy show, but allow the show to be temporarily interrupted by people on the Internet who want to control your lights.  When the Internet people have finished, your regular show starts again.

When you save a show in xLights, two files are created: an .xml file that allows you to edit the show later (adding or removing animations) and a .fseq file that is used for animating your actual lights.  The fseq file tells which bulbs need to be which colors at any point in time during the show playback.  It is like a canned recording of the animation.

My regular show is 8-1/2 minutes long.  For Internet control, I make a series of small shows, only 30 seconds long.  I save these as individual files (.xml and .fseq for each "mini show").  When someone from the Internet selects one of these mini shows, my regular show stops and the chosen mini show plays for 30 seconds.  When the mini show is finished, the regular show starts again.  Thus Internet people only have temporary control of your lights; when there is no one controlling them, your regular show plays for the people in your neighborhood as usual.

So, create a regular show (one large .fseq file) and lots of mini shows (multiple, smaller .fseq files).  These files are saved in the xLight's "show" directory.  Pressing [F9] in xLights will indicate where your show directory exists, but you will need to close xLights then open this folder with your operating system to reveal all of the .fseq files you have created.

The next step is setting up a Raspberry Pi computer to play these .fseq files, in the next part of these instructions.

Here is a slideshow on how to build Internet Controllable Christmas lights, a full-color version and a printable version.  Below is an introductory video to get you started!

 

Setting up Internet control of your lights involves these steps:

  1. Create a variety of xLights animations as multiple playback files

  2. Install Falcon Player onto a Raspberry Pi computer

  3. Configure Falcon Player to be Internet control capable 
    1. Uploading show/sequence files from xLights to Falcon Player
    2. Secure Falcon Player from Internet hackers
    3. Configure Falcon Player to receive commands from the Internet

  4. Setup an outdoor webcam that allows website visitors to see your house lights as they control them

  5. Configure your home Internet router to allows the outside world to contact your Raspberry Pi

  6. Setup a "Dynamic DNS" service so that the Raspberry Pi and webcam can be easily accessed from the Internet

  7. Setup a webpage that allows visitors to send commands to the Raspberry Pi, playing chosen animations

 

Suppose someone visits your webpage and clicks the "Candy Cane" animation.  Here is what happens:

  1. When the Candy Cane button is clicked, a php file is activated from the webpage.  

  2. This php file activates another php file on your Raspberry Pi (runEventScript.php).  The webpage can "find" your Raspberry Pi through the domain name that you created via Dynamic DNS.  

  3. The runEventScript.php file is used by Falcon Player to execute operating system commands via a "bash script".  In this case, Falcon Player is told to stop whatever animation is was currently playing, then being playing the animation that was chosen by the webpage visitor.

  4. A video of your webcam is also shown on the webpage so that visitors can view the animation that they chose.  The video feed on the webpage also "finds" your webcam via the domain name setup through Dynamic DNS.

 

There are two major parts of this "magic".  The first is how Dynamic DNS allows your Raspberry Pi and webcam be "seen" by outside users.  For those technically minded, Falcon Player is "seen" through port 80 from the Dynamic DNS domain name, while port 81 also allows the camera to be "seen", both sharing the same domain name.

The second part is Falcon Player's built-in runEventScript feature that allows outside users to control how Falcon Player functions.  

 

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.  

 

 

 

 

The Enclosure

Because my controller will be indoors, the enclosure did not have to be waterproof.  I chose a plastic Sterilite container with a removable lid.  I cut holes on the ends to allow Ethernet cables to be plugged into the network boards, USB cables to be plugged into the Arduinos for reprogramming, power supply fan ventilation, power supply power cord, a hole for the power switch, and a long slot for the switch's eight Ethernet ports.

 

Mounting the Arduino and network boards

Use only Arduino Mega 2560 boards for the GECE light controller.  This is necessary as these boards have additional RAM and plenty of output pins on them.  I used four bolts to attach the Arduino to the enclosure, screwing the bolts from bottom of the case through the holes in the Arduino's board corners.  Because the enclosure's bottom has curved edges, the Ethernet jacks would be too far inside the floor to easily connect/disconnect the Ethernet cables.  So I mounted the network boards to the side of the enclosure, inserting the boards in a 3D printed bracket that bolts to the enclosure'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 dedicated 5V power supply.  It is a long supply that barely fits in the enclosure.  I placed the power supply on a block of wood to raise its connectors above the Arduino boards so that things aren't too cramped.  I also attached an inexpensive voltage display to the enclosure'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.

 

Mounting the GECE jacks

The controller is placed in the living room, though the 16 GECE strings are attached all over the house (windows, roof, driveway, house corners, etc.).  Because some strings could originate up to 200 feet from the controller, I chose to extend the strings with 16-gauge power extension cords.  These cords have three conductors, perfect for interfacing wtih the GECE strings.  These strings also have three conductors for 5V, ground, and data.  I cut-off the female extension cord plug, then wired the cord directly to the GECE string (described more below).  To interface the extension cord to the light controller, I mounted inexpensive house outlet receptacles to the enclosure's lid.  I mounted each receptacle, each offering two outlets for a total of 16 outlets.  The two holes that normally mount the jacks to outlet boxes allow the receptacles to be bolted to the enclosure lid.

 

Mounting the Ethernet switch

Even though the GECE light controller only needs two Ethernet cables to control the lights, I mounted an eight-power Ethernet switch into the lid of the controller.  I did this simply as a convenience, that way I wouldn't have to have the switch box outside laying around.  The switch is powered by the dedicated 5V power supply that drives the lights, Arduinos, and network boards. The switch hangs from the inside bottom of the lid via a 3D printed bracket that bolts to the lid.  Here is where you can download the bracket if you wish to print your own.

 

Wiring everything up

You can download the wiring diagram here.  

Powering everything

First off, wire all of the components to power.  My power supply has three 5V connectors (V+) and three GND (V-) connectors, so I spread the wires among these connectors.  Run a wire from 5V (V+) on the power supply to Vin on each Arduino.  Then run a wire from power supply ground (V-) to GND on each Arduino.  Do the same to both network boards (the power pin is labeled 5V instead of Vin on the network boards).  

Note: If you choose to power the Arduino with a larger voltage, do not go higher than 7V!  Higher voltage will make the Arduino's voltage regulator overheat.  The Arduino could start crashing from overheating.

Note: When connecting wires to the power supply and receptacles, I crimp wires onto red spade connectors.  That save a lot of unnecessary soldering!

To power the receptacles, run a heavy-gauge wire from 5V on the power supply to the bronze terminals on the receptacles.  To ground the receptacles, run a heavy-gauge wire from ground on the power supply to the green terminals on the receptacles.  You can daisy chain the ground wire from receptacle to receptacle, requiring only one wire back to the power supply.  However, if you plan to daisy chain the power wire, daisy chain only 2-3 receptacles per power supply wire.  This allows the amps consumed by the lights doesn't overload the wires.

To power the Ethernet hub, my particular hub used a 5V AC to DC adapter.  I originally powered the switch directly from the 5V power supply.  This is acceptable, but later I chose to power the switch with its original adapter, wiring into the 5V power supply's AC input.  This way, if the lights causes the power supply's 5V level to fluctuate, it doesn't affect the reliability of the hub.

The power supply requires an AC input.  I removed a computer power supply's female port, then mounted it to the enclosure's side.  This allows me to use a standard computer power cord to connect the controller to an AC power outlet.  I attached the AC cord's green wire to the AC ground input on the power supply and the AC cord's white wire to the neutral input on the power supply.  I connected the AC cord's black wire to a two-pole switch, then continued the wire to the line input on the power supply.  This allows me to switch the power supply on and off from outside the controller, as the switch is mounted to the enclosure's side.

The final step to powering everything is grounding everything.  The two Arduinos, two network boards, and GECE 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 between the Arduinos.  The network boards also have multiple ground ports, so run wires from the network boards to the GND ports on the Arduinos.  If you are powering the Ethernet hub through it's AC to DC adapter, you don't need to share a ground with everything else.  With the thick ground wire coming from the recepticles to the power supply, splice an extra wire to the thick wire, then run the splice wire to the GND pins on the Arduinos.

 

Connecting GECE strings to the Arduinos

Each of the eight receptacles has two outlets.  Therefore eight receptacle supports 16 strings of GECE lights.  These are the silver terminals on the receptacles.  Simply run 16 wires from each silver receptacle terminal to the data ports on the Arduino (see the diagram for Arduino pin numbers).  Each Arduino supports eight 50-bulb strings of GECE lights (400 bulbs per Arduino).  Therefore I run eight strings to one Arduino, then the other eight strings to the second Arduino.

Look at the receptacles closely as the pair silver terminals may be joined with a metal tab.  Be sure to break-off this tab with pliers to ensure that each silver terminal is electrically isolated.

 

Connecting network boards to the Arduinos

There are variations of the ENC28J60 Arduino-compatible Ethernet network boards.  Some use 3.3V to power them, some use 5V, and some can use either.  Be sure to use boards that use 5V; they seem to be more stable.  Also, it is important not to power the network board from the Arduino; they cannot provide enough amps and will cause the network connection to sporadically fail.  Power the network boards from the dedicated power supply, ensuring that the network board ground shares the power supply ground and Arduino ground (see "Powering everything" section above).

For the rest of the wires that need connected between the network board and the Arduino, refer to this diagram for pin numbers).

 

Avoiding "glitching"

You may find that bulbs light-up sporadically, changing to unwanted colors or not changing colors at all.  If your GECE 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.  I have not tried this idea yet on my GECE controller.  Also, adding 220 uF capacitors between the power and ground to each string may help as well (reduces interference), but I haven't tried this on my GECE controller yet, either.

 

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 > DMXControllerColorEffects"
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\DMXControllerColorEffects 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 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 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 201

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.

Note: You'll see that my particular setup has three global.h files: global.h, global (driveway).h, and global (house).h.  The important file is global.h.  Because I have two Arduino controllers that have different settings (the IP addresses are different, for example), the latter two files contain these differences.  When I am ready to upload the DMX program to one of the Arduinos, I copy one of the latter two files to global.h, then upload the program.  It's simply a convenience for me.  

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 > DMXControllerColorEffects.  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 GECE lights 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.201, 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 201.  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 GECE 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 GECE lights that are connected to your controller.  This is explained in the "How to test it" section on this website.

How It Works

The brain of the GECE controller is an Arduino microcontroller.  One Arduino can control up to eight GECE strings of 50-bulbs each.  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 GECE lights that are connected to it.  

My particular controller uses two Arduino microcontrollers, allowing 16 strings of GECE lights to be controlled (eight strings per controller).  There are two network boards, one board connected to each Arduino.  Therefore two Ethernet cables are needed to control the lights.  The Arduino, network boards, and GECE strings are powered from a dedicated 5V power supply.  I also integrated an eight-port Ethernet switch into the controller, just as a convenience.  This way, everything plugged into the switch can "see" each other through Ethernet.

Page 4 of 5
Go to top
JSN Boot template designed by JoomlaShine.com