Configuring ESP 8266 as a Pixel Controller for xLights

Please read these updated instructions here

Configuring Arduino as a Pixel Controller for xLights

Please read these updated instructions here.

(work-in-progress document)

Install BBB OS and Falcon Player in one step

• Good document that explains this: http://falconchristmas.com/forum/index.php?topic=2742.0
• Good document that talks about writing images to BBB in general: http://derekmolloy.ie/write-a-new-image-to-the-beaglebone-black/
  

1. Download image from http://sourceforge.net/projects/win32diskimager/files/latest/download onto microSD card
2. Insert card, hold down button S2, connect USB cable to power it on.
3. Keep holding button until blue lights start to flash
4. Wait about 20-25 minutes
5. When blue lights stop flashing, disconnect USB cable and remove microSD card
6. Connect network cable and empty flash drive, then connect power
7. Access FP web interface via http://fpp/
8. Allow FPP to automatically update to 1.8, then allow it to reboot and automatically update to v1.9

The tune-to sign works independently of the rest of your light show.  It does not use the animations created by xLights and is not controlled by Falcon Player.  Instead, when powered up, it reads a file named MESSAGES.TXT on a website that contains a list of holiday messages.  It then begins displaying these messages in a random order.  

Between messages, the tune-to sign reads a file named LOCATION.TXT on a website.  If you are using Internet controlled lights, this file displays the location of the Internet user who is currently controlling your lights.  If someone is actively controlling your lights, the tune-to-sign will display that person's location.  When no one is controlling your lights, the tune-to sign will resume displaying random holiday messages.

The tune-to sign is meant to be seen by cars passing by.  Therefore the enclosure is large (16 feet wide) and the characters are large (about 10.5" tall).  To save power and keep the sign affordable, it uses only seven strips of LEDs at 135 lights each, totaling 945 lights.  Instead of combining many lights to make large letters, I use fewer lights that are magnified with honeycomb-like channels that reflect and amplify each light within each channel.  That way the entire sign can be driven by an inexpensive Arduino and a regular 400-watt computer power supply.

The enclosure is a long, narrow box that houses the power supply and Arduino on the left (as you are facing the sign) in a compartment.  The compartment has removable face to allow access to this hardware.  Seven strips of LEDs line the rest of the enclosure in the second compartment, the front of which is covered with plastic diffuser used to cover drop-ceiling lights.

Building the Enclosure

The build plans are here.  The build plans above provide dimensions for enclosures using 1/2" or 1/4" thick wood.  My actual enclosure uses 3/4" thick wood because it was cheaper at the home improvement store.  I used poplar, but discovered that it becomes soft in wet/snowy weather, so the screw fasteners tear apart.  Use a harder wood for your enclosure.

The enclosure consists of 3/4" wood for the top, bottom, sides, and compartment divider.  I used 1/8" plywood for the backing.  In additional to the poplar being too soft, the plywood backing warps badly in moist weather.

For the panel that covers the hardware compartment, I cut a piece of metal roofing and attached a wooden strip to become the handle.  Between the short electronics compartment and the long LED strip compartment, I installed a wooden divider.  I made the divider "float" above the back of the enclosure so that the wires from the LED strip in the long compartment can pass through to the electronics compartment.

To install the frosted diffuser, I used a table saw to cut tracks in to the top, bottom, and side walls, then slid the diffuser in the tracks.

Installing the LED strips

The LED strips can be purchased from Amazon, eBay, AliExpress, etc.  You can do a search for "ws2812b 5050 led strip 5v" to find them.  Make sure that they have 30 LEDs per meter; buy a 5M strip that has 150 LEDs on it.  The strip should be rated for 5V.  If you accidentally purchase a 12V strip, the LEDs are sometimes groups in threes and are not individually controllable.  Here is what they look like:

Trim each strip to 135 LEDs (if you are using a 16' enclosure like I am).  The strips usually have an adhesive backing, thought I've found that it doesn't stick to painted wood that well.  Run the seven strips of LEDs along the enclosure, spacing them evenly so that the LEDs form square distances from each other.  Then secure the strips better with white or clear tape.  In my enclosure, I actually ran eight strips, but the eighth strip is not used.  It is for future expansion that is not implemented yet.

Installing the power supply

As mentioned above, I use a 400W computer power supply to power the tune-to sign.  I found a 3D printed bracket on www.thingiverse.com to mount it in the enclosure (the purple bracket in the picture below).  

Because my power supply does not have a power switch (ATX power supplies typically do not), I shorted the green pin on the large motherboard connector to one of the black pins on that connector using a thick wire or bent nail.  This way, when the power cord is plugged in the power supply, it instantly powers on. Here are instructions on how to do this.

To power the LED strips, each LED strip has a red wire for power and a white wire for ground.  Your strip's wire colors may be different, so look closely at the strip to see which wires are power & ground; they should be labeled.  I soldered all seven red (power) wires together to a single, thick red wire.  I also attached an eighth red wire into this bundle; this will be used to power the Arduino.  I did the same for the white (ground) wires, soldering them together to a thick, black wire (with an extra eighth wire to ground the Arduino).  On the other end each thick wire, I crimped a cut-off nail.  I then plugged these two wires into the 5V and GND pins on the power supply's motherboard connector, respectively.  The nails were thick enough to make a snug connection.

Installing the Arduino

The tune-to sign is controlled by an Arduino Mega 2560.  These can be found easily on Amazon, eBay, etc.  The Mega 2560 model is required because it has enough RAM memory to hold the program and store the messages it will display. 

I found a 3D printed mounting bracket on www.thingiverse.com, then mounted the Arduino into the enclosure.  I connected the power and ground wires from the power supply to the 5V and GND pins on the Arduino (see picture below).

For a wiring diagram, please click here.

On my LED strips, the data wire is green.  Your strip's data wire color may be different, so look closely at the strip to see which wire is for data; it should be labeled.  I soldered a 220-ohm resistor to each data wire, then soldered a female connector to the other end of the resistor.  I then used heat shrink to protect the resistor and soldered connections on each end of it.  The resistor is used to reduce interference caused by "signal bounce".  Signal bounce can cause your LED strips to light-up unexpectedly.

For each of the seven data wires, I plugged them into pins 23-29 on the Arduino, with pin 23 for the bottom strip of the tune-to sign.  So the Arduino now has seven data wires, a 5V power wire, and a ground wire plugged into it.  With the picture below, I also connected a voltage display to the 5V and GND pins.  This tells me the voltage of the power supply that is helpful for diagnosing problems.

Lastly, I attached an Ethernet "shield" to the Arduino, like this one.  This allows the Arduino to have Internet access from my home network's router.  This can be easily found on eBay & Amazon; search for "Ethernet Shield W5100 Arduino 2560".  Be sure that the shield is model W5100 and supports the Arduino 2560.  Below is a picture of an Arduino Mega 2560 with an Ethernet shield attached to it:

And below is a picture of my Arduino with the shield and wires connected to it:

Programming the Arduino

You need to install a program on the Arduino that makes it become a tune-to sign controller.  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 the tune-to sign program, open it into the IDE, then upload the tune-to sign program to the Arduino board.  This is trickier than it sounds, as the program needs installed a special way into the IDE.  To save you time, you can download the Arduino IDE with the tune-to sign program already installed from here.  Simply unzip this file into a folder on your computer.

Configuring the tune-to sign program

The next step is configuring the tune-to sign program for your particular lights, such as the website where the Christmas messages are retrieved from.  To do this, edit the TomsTuneToSignProgram.ino file in the arduino-1.6.5-r2\examples\TomsTuneToSign folder with your favorite text editor.  These are the important lines that need changed:

byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };

The Ethernet shield may have a sticker on it with its MAC address.  This is a 16-character code, usually divided into eight 2-character pieces.  The MAC address is a like a house address in your neighborhood; it is a unique number that is different than other devices on your home network.  If your shield does not have this information printed on it, you may be able to skip modifying the above line.

char server[] = "itwinkle.org";  

This defines the website where the tune-to sign will find the LOCATION.TXT and MESSAGES.TXT files.  My website is "itwinkle.org", change this to your website instead.

int scrollSpeed=35;
int delayBetweenMessages=5000;

If the messages scroll too fast on your display, you can change the above "35" to a different number to speed it up or slow it down.  Normally, there is a five-second delay between each messages.  You can change this delay from "5000" (milliseconds) to a different number.

#define PIXELS 135 

If the strips of LEDs on your tune-to sign have more or less than 135 pixels per strip, change the above number accordingly.

int loopLocationDisplayDuration = 30;

If you are using Internet Controlled lights, the above number reflects the length (in seconds) of your animation files that website visitors choose.  In my case, my Internet controllable animations run 30 seconds each. 

Uploading the tune-to sign program

The next step is sending the tune-to sign 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 > TomsTuneToSignProgram.  A second Arduino IDE window will appear with the tune-to sign program open.

Before connecting your Arduino, verify this first:

* Make sure that you are using the Arduino Mega 2560.  The tune-to sign program only works with this board.

* If you have the LED strips connected to the Arduino, it is a good idea to temporarily disconnect them.  If the Arduino already has an older version of the tune-to sign 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 tune-to sign program verifies correctly, you will see the "Done compiling" message in the status bar.  At this point, you can upload the tune-to sign 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 tune-to sign 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.

Preparing your website for the tune-to sign

When powered on, the tune-to sign retrieves its list of holiday messages from a file on a website called MESSAGES.TXT into its temporary memory.  If you want to change the messages the tune-to sign uses, simply update the MESSAGES.TXT file on your website, power off the tune-to sign, then turn it back on.  You may have up to 58 messages in this file with each message no longer than 75 characters.  If you store more (or lengthier) messages than indicated, the tune-to sign will not start properly.

Each message can be displayed in a variety of colors, specified as three-letter codes before the message.  For instance, here is a MESSAGES.TXT file with three colored messages in it:

<messages>
WHILet It Snow, Let It Snow, Let It Snow! 
REDIt's beginning to look a lot like Christmas
BLUIt is Christmas in the heart that puts Christmas in the air
</messages>

The color codes are: GRE (green), WHI (white), RED (red), BLU (blue), BRO (brown), YEL (yellow), CYA (cyan), PUR (purple), VIO (violet), LPI (light pink), MAR (?), TAN (tan), GOL (gold), LIM (lime green), LBL (light blue), ORA (orange), PIN (pink),

If your lights are Internet controllable similar to mine, my website creates a file called LOCATION.TXT and updates it with the current Internet user who is controlling the lights.  This file contains the location of the user, such as the following:

<location>
8575
Czech Republic
</location>

After the tune-to-sign displays a random holiday messages, it looks for the LOCATION.TXT file on your website.  If someone is actively controlling your lights, the tune-to sign will display the location (in this case "Czech Repulic") on the sign, telling people in your neighborhood where your Internet visitors are from.  If you do not have Internet controlled lights (there is no LOCATION.TXT file on your website), the tune-to sign will simply display random holiday messages.

Checking communication

After the tune-to sign program is uploaded to the Arduino, it will begin running the tune-to sign 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.

Then you can power-on your tune-to sign.  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.

As soon as you power the tune-to sign, it will contact the website that contains MESSAGES.TXT, then save the holiday messages therein to the Arduino's temporary memory.  It will then begin displaying these messages on your sign!