Introduction: XBee Programmable Christmas Lights
About: Software Engineer that likes to tinker with embedded devices, ZigBee networks, and Python. I recently started a consulting/contracting company with a close friend, Null Squared LLC. We specialize in ZigBee, …
By following these steps, you will be able to control a strand of 50 tri-color Christmas lights wirelessly using a Programmable XBee.
My family has always been into Christmas lights and creating custom decorations, so when I read this blog post on how to hack GE Color Effects Christmas lights, I knew I needed to try it out myself. I decided to use an XBee Programmable so that I could control the lights wirelessly and try out the new built-in Freescale co-processor.
For this project I'm sending RGBA (Red Green Blue Alpha) values for each LED over a ZigBee network to the FreeScale co-processor built into the XBee Programmable. The code on the co-processor uses a PWM to send the RGB values on a data line to the LEDs in the strand. Each LED on the strand has an 8051 microprocessor in it that decodes the signal and sets the LED color and brightness. Voila, wireless control of 50 tri-color LEDs. The strands themselves support a refresh rate of up to ~24Hz when setting all 50 LEDs (faster if you are setting fewer LEDs). Using a compact over the air representation for the LED values (removing the brightness or ALPHA portion), I can get ~10Hz refresh rates in real time over the wireless network.
My family has always been into Christmas lights and creating custom decorations, so when I read this blog post on how to hack GE Color Effects Christmas lights, I knew I needed to try it out myself. I decided to use an XBee Programmable so that I could control the lights wirelessly and try out the new built-in Freescale co-processor.
For this project I'm sending RGBA (Red Green Blue Alpha) values for each LED over a ZigBee network to the FreeScale co-processor built into the XBee Programmable. The code on the co-processor uses a PWM to send the RGB values on a data line to the LEDs in the strand. Each LED on the strand has an 8051 microprocessor in it that decodes the signal and sets the LED color and brightness. Voila, wireless control of 50 tri-color LEDs. The strands themselves support a refresh rate of up to ~24Hz when setting all 50 LEDs (faster if you are setting fewer LEDs). Using a compact over the air representation for the LED values (removing the brightness or ALPHA portion), I can get ~10Hz refresh rates in real time over the wireless network.
Step 1: Assemble the Parts
In this step we are going to start acquiring the necessary hardware and software.
First you need a strand of GE color effects G-35 Christmas lights. I'd suggest trying to find a strand with 50 lights in it, but one of the 36 light strands will also work. If you can find them at Costco, they are usually available for ~$60 as apposed to the full retail price of ~$100.
Next you need to get an XBee Programmable and programmer for the FreeScale co-processor. I suggest checking out Digi's Getting Started for more information. You'll also need a second XBee (series 2) connected to your PC to send data to the programmable XBees. You can download the required software, drivers, and getting started guide here.
The example computer programs are written in Python. You'll need to download Python 2.7 and then install pySerial. All of my code and the XBee profiles are located on GitHub at: https://github.com/mrsutherland/lightshow.
You may need a 1kOhm resistor and 10pF ceramic capacitor to reduce noise on the data line for the Christmas lights. It doesn't appear to always be necessary, but I've had some issues without them.
Finally, you'll need some misc components to wire everything up without using the XBIB board:
* 1 small prototyping board or breadboard
* 1 XBee breakout board from Sparkfun.
* 1 LN1117T - 3.3V linear regulator to provide 3.3V to the XBee from the 5V off the Christmas lights
* 2 10uF radial caps - for the linear regulator
* 1 LED - association LED isn't strictly necessary, but very useful.
* 1 1kOhm resistor for the LED
* optional enclosure
First you need a strand of GE color effects G-35 Christmas lights. I'd suggest trying to find a strand with 50 lights in it, but one of the 36 light strands will also work. If you can find them at Costco, they are usually available for ~$60 as apposed to the full retail price of ~$100.
Next you need to get an XBee Programmable and programmer for the FreeScale co-processor. I suggest checking out Digi's Getting Started for more information. You'll also need a second XBee (series 2) connected to your PC to send data to the programmable XBees. You can download the required software, drivers, and getting started guide here.
The example computer programs are written in Python. You'll need to download Python 2.7 and then install pySerial. All of my code and the XBee profiles are located on GitHub at: https://github.com/mrsutherland/lightshow.
You may need a 1kOhm resistor and 10pF ceramic capacitor to reduce noise on the data line for the Christmas lights. It doesn't appear to always be necessary, but I've had some issues without them.
Finally, you'll need some misc components to wire everything up without using the XBIB board:
* 1 small prototyping board or breadboard
* 1 XBee breakout board from Sparkfun.
* 1 LN1117T - 3.3V linear regulator to provide 3.3V to the XBee from the 5V off the Christmas lights
* 2 10uF radial caps - for the linear regulator
* 1 LED - association LED isn't strictly necessary, but very useful.
* 1 1kOhm resistor for the LED
* optional enclosure
Step 2: Setup and Join the XBees
In this step we are going to update the XBee firmware, configure the XBees and join them together into a wireless network.
The first thing we want to do with the XBee is make sure the ZB firmware is up to date. If you have Windows, you can download and run X-CTU. One of the tricky things about working with a programmable XBee is that the FreeScale (programmable) co-processor sits between the serial port and the Ember (ZigBee) processor. To talk to the Ember processor, you need to access the boot-loader on the FreeScale and put it into bypass mode (use these instructions for X-CTU). Now that you are in bootloader mode, go to "modem configuration" tab and click the load button under "Profile". This will open a file dialog. Use the ".pro" files located on github to configure the XBees: "xmas_lights_pxbee.pro" is for the Programmable XBee connected to the Christmas light strand and "xmas_lights_coord.pro" is for the series two XBee connected to your computer. With these default settings, the two XBees should automatically join together when you power them on at the same time. You will know they are joined when both the XBees blink their association LEDs.
The first thing we want to do with the XBee is make sure the ZB firmware is up to date. If you have Windows, you can download and run X-CTU. One of the tricky things about working with a programmable XBee is that the FreeScale (programmable) co-processor sits between the serial port and the Ember (ZigBee) processor. To talk to the Ember processor, you need to access the boot-loader on the FreeScale and put it into bypass mode (use these instructions for X-CTU). Now that you are in bootloader mode, go to "modem configuration" tab and click the load button under "Profile". This will open a file dialog. Use the ".pro" files located on github to configure the XBees: "xmas_lights_pxbee.pro" is for the Programmable XBee connected to the Christmas light strand and "xmas_lights_coord.pro" is for the series two XBee connected to your computer. With these default settings, the two XBees should automatically join together when you power them on at the same time. You will know they are joined when both the XBees blink their association LEDs.
Step 3: Load Christmas Light Code on the XBee Programmable.
Download and install the Digi version of CodeWarrior for the programmable XBee.
Put the XBee Programmable into the USB XBIB board and connect the FreeScale programmer. Connect both the XBIB and the programmer to your PC. You may need to download USB drivers for both boards. Open CodeWarrior and create a new XBee Application Project. You now need to overwrite three of the files with files from the XBee folder of the GitHub repository.
NOTE: "irq_vectors.c" is shared with all of the CodeWarrior XBee projects. Be sure to restore this file when you are working on another project.
config.xml -> /config.xml - this files sets the configuration of project.
main.c -> /Sources/main.c - this is the main project file
irq_vectors.c -> /Sources/cpu/irq_vectors.c - this is a linked file that sets the interrupt vectors for the program.
Once you've overwritten the three files, open main.c in CodeWarrior by double clicking on it. Now compile and load the program to the XBee by hitting the play/run button.
Put the XBee Programmable into the USB XBIB board and connect the FreeScale programmer. Connect both the XBIB and the programmer to your PC. You may need to download USB drivers for both boards. Open CodeWarrior and create a new XBee Application Project. You now need to overwrite three of the files with files from the XBee folder of the GitHub repository.
NOTE: "irq_vectors.c" is shared with all of the CodeWarrior XBee projects. Be sure to restore this file when you are working on another project.
config.xml -> /config.xml - this files sets the configuration of project.
main.c -> /Sources/main.c - this is the main project file
irq_vectors.c -> /Sources/cpu/irq_vectors.c - this is a linked file that sets the interrupt vectors for the program.
Once you've overwritten the three files, open main.c in CodeWarrior by double clicking on it. Now compile and load the program to the XBee by hitting the play/run button.
Step 4: Cut the Cords
Now it's time to ruin a perfectly good set of Christmas lights. NOTE: make sure all of the lights work first, I had to return a strand with an LED that didn't have any red component.
You need to cut out the existing control box on GE color effects to insert your own. Once you cut out the box, strip back the wires on both cables to be able to insert on your breadboard or prototyping board. We will be connecting the +5V and GND from the power supply to the Christmas lights directly. We'll then hook the GND to the XBee and supply it with +3.3V from either a dev board or a linear regulator. Finally we hook up the data line and optionally add an associate LED.
Use a multi-meter to figure out which of the two wires connected to the power supply is ground and which is +5V. Put those aside. Now, holding the first LED in the strand upright with the cut end facing you, the three wires from left to right are +5V, data, and ground (There is a nice picture in the original blog post). Connect the +5V and GND from the power supply to the +5V and GND on the Christmas light strand. Now for the XBee. Connect the ground from the power supply to the Programmable XBee (pin 10 labeled "GND" on breakout board). Power the XBee (+3.3V on pin1, labeled "VCC" on breakout board) either from the XBIB board with +3.3V or use the linear regulator to create a +3.3V supply from the +5V and ground. If you are using the LM1117T, you should also use a of 10uF capacitors from GND to +5V and from GND to +3.3V to reduce noise. Now for the data line. I've had the best results connecting the data line from the Christmas lights to pin 13 on the XBee (labeled "ON" on the sparkfun breakout board) using a 1kOhm resistor. I then added a 10pF cap between the data line and ground. This will help prevent data corruption on the line (although I've seen it work fine without it). Finally, If you are not using the XBIB board, you might want to add an LED to pin 15 (labeled "AD5" on the sparkfun breakout board). I connect the low end of the LED (the flat side on some packages) to the XBee pin. Don't forget to use a resistor with your LED as well.
You need to cut out the existing control box on GE color effects to insert your own. Once you cut out the box, strip back the wires on both cables to be able to insert on your breadboard or prototyping board. We will be connecting the +5V and GND from the power supply to the Christmas lights directly. We'll then hook the GND to the XBee and supply it with +3.3V from either a dev board or a linear regulator. Finally we hook up the data line and optionally add an associate LED.
Use a multi-meter to figure out which of the two wires connected to the power supply is ground and which is +5V. Put those aside. Now, holding the first LED in the strand upright with the cut end facing you, the three wires from left to right are +5V, data, and ground (There is a nice picture in the original blog post). Connect the +5V and GND from the power supply to the +5V and GND on the Christmas light strand. Now for the XBee. Connect the ground from the power supply to the Programmable XBee (pin 10 labeled "GND" on breakout board). Power the XBee (+3.3V on pin1, labeled "VCC" on breakout board) either from the XBIB board with +3.3V or use the linear regulator to create a +3.3V supply from the +5V and ground. If you are using the LM1117T, you should also use a of 10uF capacitors from GND to +5V and from GND to +3.3V to reduce noise. Now for the data line. I've had the best results connecting the data line from the Christmas lights to pin 13 on the XBee (labeled "ON" on the sparkfun breakout board) using a 1kOhm resistor. I then added a 10pF cap between the data line and ground. This will help prevent data corruption on the line (although I've seen it work fine without it). Finally, If you are not using the XBIB board, you might want to add an LED to pin 15 (labeled "AD5" on the sparkfun breakout board). I connect the low end of the LED (the flat side on some packages) to the XBee pin. Don't forget to use a resistor with your LED as well.
Step 5: Power on Test
Power on the Christmas lights and then the Programmable XBee. All of the Christmas lights should turn a dim blue.
Trouble-shooting:
* Make sure to turn on the XBee before the Christmas light strand. The first thing the XBee does in enumerate the lights on the strand. If the strand isn't on, this won't happen. There is a delay, so turning them on at the same time shouldn't be an issue.
* Make sure the association LED for the XBee is blinking. This indicates that the XBee is powered and joined to a network.
* Check your connections - Christmas strand has +5V and ground connected? XBee has +3.3V and ground? XBee is connected to data line on the Christmas lights? All of the grounds are connected together?
Trouble-shooting:
* Make sure to turn on the XBee before the Christmas light strand. The first thing the XBee does in enumerate the lights on the strand. If the strand isn't on, this won't happen. There is a delay, so turning them on at the same time shouldn't be an issue.
* Make sure the association LED for the XBee is blinking. This indicates that the XBee is powered and joined to a network.
* Check your connections - Christmas strand has +5V and ground connected? XBee has +3.3V and ground? XBee is connected to data line on the Christmas lights? All of the grounds are connected together?
Step 6: Run a Sample Program From Your Computer
Download the sample Python code from the patterns folder in the GitHub repository. You should already have installed Python 2.7 and pySerial.
Open the file settings.json and set the com_port to the COM port of the XBee connected to your computer.
Now run the Python script twinkle.py. You should see the LEDs in the Christmas lights randomly fading in and out.
There are other sample programs to explore as well.
I've included the csv and Python file from the light show set to Dance of the Sugar Plum Fairies. I don't have distribution rights to the mp3 file, so it is not included. I used Audacity to manually extract timestamps and create the csv file. The Python file uses a library called mp3play to play the mp3 from Python.
Open the file settings.json and set the com_port to the COM port of the XBee connected to your computer.
Now run the Python script twinkle.py. You should see the LEDs in the Christmas lights randomly fading in and out.
There are other sample programs to explore as well.
I've included the csv and Python file from the light show set to Dance of the Sugar Plum Fairies. I don't have distribution rights to the mp3 file, so it is not included. I used Audacity to manually extract timestamps and create the csv file. The Python file uses a library called mp3play to play the mp3 from Python.
Step 7: Wrap Up
I hope you enjoy controlling your Christmas lights wirelessly!
Note that you can control multiple strands of Christmas lights from a PC using a single attached XBee. The available bandwidth has to be shared between the different strands, so the maximum refresh rate is decreased when more strands are added.
The next stage for this project is to add a serial flash to the XBee board to store patterns of data. The ZigBee network would then only be used to upload programs, synchronize time between the XBees, and execute the patterns. This would be the best way to create a Christmas light show that synchronizes to music that uses multiple strands of lights.
You can contact me at Mike@nullsquared.com or visit my website at nullsquared.com.
Note that you can control multiple strands of Christmas lights from a PC using a single attached XBee. The available bandwidth has to be shared between the different strands, so the maximum refresh rate is decreased when more strands are added.
The next stage for this project is to add a serial flash to the XBee board to store patterns of data. The ZigBee network would then only be used to upload programs, synchronize time between the XBees, and execute the patterns. This would be the best way to create a Christmas light show that synchronizes to music that uses multiple strands of lights.
You can contact me at Mike@nullsquared.com or visit my website at nullsquared.com.