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.

To install this library, unzip it into the libraries directory of your Arduino sketchbook folder. If there is not already a folder named libraries, create it.

You will need to modify TCL.h to choose between bit-bang mode on 2 digital IO pins or 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 you will use for Clock and Data, respectively.

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:

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.

In SPI mode, connect the wires as follows:

Be sure there is a common ground between the Arduino and the Total Control Lighting strand.

In order to use the library, your sketch should start with the following #include directives:

#include <SPI.h>
#include <TCL.h>

Initialize the SPI bus in setup():

TCL.begin();

Before sending a group of colors to your LEDs, send an empty frame to initialize the strand:

TCL.sendEmptyFrame();

You must also call this after every set of colors is sent to the strand.

To send an RGB color:

TCL.sendColor(byte red, byte green, byte blue);

For example, to send a yellow pixel:

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, finish with:

TCL.sendEmptyFrame();

Cool Neon also sells a developer shield which is a useful add-on for using Total Control Lighting with an Arduino. The shield includes a +5V DC power input cable with a 2.1mm jack (compatible with Cool Neon wall-wart power supplies, which will power the Arduino as well as the lights), a female Total Control Lighting output connector, four potentiometers, two momentary buttons, and two switches.

If you hold the developer shield with the two-position switches at the top and the potentiometers at the bottom, then going clockwise from upper-left:

• Potentiometers connect to analog input pins A0–A3
• Momentary switches (bottom to top) connect to digital pins D4 and D5
• Two-position switches (bottom to top) connect to digital pins D6 and D7

When closed, the switches connect the pin to ground, so internal pull-up resistors are required. The library configures the inputs correctly when you call:

TCL.setupDeveloperShield();

If you are using the metallic purple developer shield/Arduino case, the aliases correspond to the following silkscreened labels:

For example, to read the state of button 1:

state = digitalRead(TCL_MOMENTARY1);

state == HIGH means the button is open (not pressed); state == LOW means it is closed (pressed). All digital buttons and switches are pulled up to HIGH when open and go LOW when closed.

Several examples are available in the Arduino examples menu under CoolNeon TCL:

• blinky — Causes the lights to blink at slightly randomized times in random colors.
• color_designer — Uses the developer shield potentiometers to search for colors. Colors cascade down the strand as you turn the first three potentiometers (red, green, blue). Press the first momentary button to output the corresponding sendColor() command over the serial port (9600 bps).
• fire — Shows flickering with random colors (between yellow and red) and random intensity to simulate fire.
• rainbow — A static red, orange, yellow, green, blue repeating sequence sent to the strand.
• serialcontrol — Allows direct control of TCL pixels from a computer over a serial connection using a simple ASCII-based protocol. Used by the PixelPainter application.

Contributions are welcome via pull requests. Please follow these guidelines before submitting:

1. Update the version in library.properties following Semantic Versioning (e.g. version=1.3.0).
2. Update the revision history in CHANGELOG.md with a brief description of the change.
3. Test your changes on hardware before submitting.
4. Monitor PR checks — ensure all automated checks pass before requesting a review. Address any failures before the PR will be considered.
5. Monitor acceptance - Check the Arduino version scan logs for acceptance. They are updated hourly, so there may be a slight delay.