Arduino Total Control Lighting Library Copyright 2011 Christopher De Vries This library allows you to control Cool Neon's Total Control Lighting using an Arduino. The library is built on SPI and requires that the Arduino SPI library also be included. Installation ------------ To install this library, unzip it into the "libraries" directory of your Arduino sketchbook folder. If there is not already a folder named "libraries" then create it. You will need to modify TCL.h to choose between bit-bang mode on 2 digital IO pins or if you want SPI mode by uncommenting ONE AND ONLY ONE of the #define statements for TCL_DIO or TCL_SPI. If you select TCL_DIO, you should also modify the #defines for TCL_CLOCKPIN and TCL_DATAPIN to select the pins that you will use for Clock and Data, respectively. Hardware -------- The Total Control Lighting strands use 4 wires to provide both power and communication. If you are using the Cool Neon connectors, the wires are designated with the following colors. Red: +5V Yellow: Clock Green: Data Blue: Ground If you're cutting and connecting individual LEDs, the color coding is somewhat different, with the following mappings: Red: +5V Green: Clock White: Data Blue: Ground If you are using a small number of LEDs the Arduino itself can provide power to the strand, but for a significant number of lights (greater than 5) an external power source should be attached. The Arduino will control the lights using the Clock and Data wires. The Clock wire should be connected to the SPI clock out of the Arduino. For an Arduino UNO this is digital IO Pin 13, for an Arduino Mega this is digital IO pin 52. The Data line should be connected to the SPI MOSI line, which for an Arduino UNO is digital IO Pin 11, and for an Arduino Mega is digital IO pin 51. Be sure there is a common ground between the Arduino and the Total Control Lighting and your LED strand should be ready to receive data. Software -------- In order to use the library, your sketch should start with the following #include directives: #include <SPI.h> #include <TCL.h> Before starting communication, initialize the SPI bus by issuing the command: TCL.begin(); Before sending a group of colors to your LEDs, you must send 4 bytes of 0s to initialize the strand. You can do this using the command: TCL.sendEmptyFrame(); You must also do this after every set of colors is sent to the strand. To send an RGB color, use the command: TCL.sendColor(byte red, byte green, byte blue); So, for example to send a yellow pixel, I would issue the command: TCL.sendColor(0xff,0xb0,0x00); The first color you send, will be the color of the first pixel (closest to the Arduino), the next will be the next pixel and so on down the line. When you are done sending colors, remember to finish with TCL.sendEmptyFrame(); Developer Shield ---------------- Cool Neon also sells a developer shield which is a very useful add-on to using Total Control Lighting with an Arduino. The shield includes a +5V DC power input cable with a 2.1mm jack, compatible with the wall-wart power supplies Cool Neon sells (which will power the Arduino as well as the lights). There is also a female total control lighting output, which can connect directly to the total control lighting pixel strands. What makes the shield special is it also comes with four potentiometers, two momentary buttons, and two switches which can be configured as inputs to the Arduino. If you hold the developer shield so that the two-position switches are at the top and the potentiometers are at the bottom, then going clockwise from upper-left the potentiometers connect to analog input pins 0, 1, 2, and 3. The momentary switches, moving from bottom to top connect to digital pins 4 and 5, and the two-position switches from bottom to top connect to digital pins 6 and 7. When closed, the switches connect the pin to ground, so you should configure them to use the internal pull-up resistors. The total control library configures the inputs correctly if you issue the command: TCL.setupDeveloperShield(); There are also defined aliases for each input device: TCL_POT1 : Potentiometer 1 (A0) TCL_POT2 : Potentiometer 2 (A1) TCL_POT3 : Potentiometer 3 (A2) TCL_POT4 : Potentiometer 4 (A3) TCL_MOMENTARY1 : Button 1 (D4) TCL_MOMENTARY2 : Button 2 (D5) TCL_SWITCH1 : Two-position Switch 1 (D6) TCL_SWITCH2 : Two-position Switch 2 (D7) If you are using the metallic purple developer shield/arduino case, then the aliases correspond to the following silkscreened outputs: TCL_POT1 : Pin 1 TCL_POT2 : Pin 0 TCL_POT3 : Pin 2 TCL_POT4 : Pin 3 TCL_MOMENTARY1 : Pin 5 TCL_MOMENTARY2 : Pin 4 TCL_SWITCH1 : Pin 6 TCL_SWITCH2 : Pin 7 So, for example to read the state of button 1 I would issue the command: state = digitalRead(TCL_MOMENTARY1); It would return state==HIGH if the button was open (not being pressed) and state==LOW if the button was closed (being pressed). The digital buttons and switches are pulled-up to the HIGH state when the switches are open and are LOW when closed. Example Code ------------ Several examples are loaded into the Arduino examples menu under "TCL." These examples include the following: blinky - A sketch that causes the lights to blink at slightly randomized times in random colors. color_designer - A sketch that lets you use to the developer shield potentiometers to search for colors. The colors will cascade down the lighting strand as you turn the first three potentiometers. The first one adjusts the amount of red, the second the amount of green, and the third the amount of blue. If you find a color you like just hit the first momentary button and it will send the appropriate "sendColor" command over the serial port so you can add it to your own code. Be sure to use the serial monitor set to 9600 bps in order to use this feature. fire - A sketch that shows flickering with random colors (between yellow and red) and random intensity meant to simulate fire. rainbow - A static red,orange,yellow,green,blue repeating sequence sent onto the strand. serialcontrol - A sketch which allows for direct control of the total control lighting pixels from a computer over a serial connection to the arduino. It uses a simple ASCII based protocol. This sketch is used by the PixelPainter application and a little more information about it can be found in the comments within the sketch. Revision History ---------------- January 2, 2012 - Version 1.2 - Added support for the Cool Neon developer shield as well as a color designer in the example code and a sketch that allows for control of pixels over a serial line to the computer. December 11, 2011 - Version 1.1 - Library was updated to work on the Version 1.0 Arduino IDE. August 16, 2011 - Version 1.0 - Library works using the Arduino SPI library to control generation 1 total control lighting strands on pre-Arduino 1.0 IDE.