Arduino Playground is read-only starting December 31st, 2018. For more info please look at this Forum Post 

TLS3008 Library for Arduino
Author:  Juan Manuel Fernandez Castro (DonJuanito)

Navigation

Current version

1.1.0 2012-11-27: Added pixel functions

History

1.0.0 2012-11-24: First release.
1.1.0 2012-11-27: Added some functions and constants

Description

The TLS3008 library allows control of the TLS3008 serial PWM RGB LEDs controllers from Terralane Semiconductor LTD. These drivers can be found on '3 wires' RGB LED strings found at webshops like DX. The LEDs on these strings are encapsulated in a silicone like plastic with a small PCB each holding a TLS3008 chip and its peripheral passive components. The serial protocol has to be precisely followed and the only available datasheet to be found on the manufacturer website is written in Chinese. I found a good interpretation of the protocol in this forum, so I decided to write a small library to ease the use of these LED strings. I'm also working on a SPI version, but time is scarce, so I cannot tell when, or even if, it will be completed.

V1.1.0: I included some pixel functions as proposed by Joseph Rautenbach on the DX user forum. Thanks for the ideas Joseph...

Download, install and import

Download here: TLS3008_V1_1_0.ZIP

Older version: TLS3008_20121124.ZIP

Put the TLS3008 directory in "~/Documents/Arduino/libraries (Mac) or "My documents\Arduino\libraries\ (Windows)" of Arduino IDE.

You can see an example sketch from "File -> Sketchbook -> Example -> TLS3008 -> FlashyLEDs_V1_1_0".

To create a new sketch, select from the menubar "Sketch->Import Library->TLS3008". Once the library is imported, an '#include <TLS3008.h>' line will appear at the top of your Sketch.

Creation

You need to create an instance of the TLS3008 class like this:

  1. // Create instance of object TL3008.
  2. // 11: Setup output pin to LEDs.
  3. // &RGBTable: Pointer to the start of the RGB buffer.
  4. // 150: Size of the table in bytes.
  5. TLS3008 pixels = TLS3008(11, (byte*) &RGBTable, 150);
[Get Code]

Constants

  1. //in TLS3008.h
  2. #define MAXFRAMESBEFORESYNC 20
  3.  
  4. #define RGB_RED 255, 0, 0
  5. #define RGB_GREEN 0, 255, 0
  6. #define RGB_BLUE 0, 0, 255
  7. #define RGB_YELLOW 255, 255, 0
  8. #define RGB_MAGENTA 255, 0, 255
  9. #define RGB_CYAN 0, 255, 255
  10. #define RGB_WHITE 255, 255, 255
  11. #define RGB_BLACK 0, 0, 0
[Get Code]

MAXFRAMESBEFORESYNC: This constant defines the number of data frames to be sent to the LED string before sending a syncing sequence. This is done to clear any serial accumulated error.

RGB_*: These constants define some basic colors at full luminosity.

Functions

  1. // setOutputPin: Call this to setup the pin used for serial LED output. bPin is the pin number.
  2. setOutputPin( byte bPin );
  3. // initCom: This MUST be called to initialize the communication with the LED string. Usually, this is done in the setup() function.
  4. void initCom();
  5. // sendEmptyFrame: Call this to send an empty DATA frame.
  6. void sendEmptyFrame();
  7. // sendRGBFrame: Call this to send a DATA frame.
  8. // ptRGB is a pointer to a 'byte' array containing RGB data. Format of array is byte R, byte G, byte B.
  9. // uiTableSize is the size in bytes of the array.
  10. void sendRGBFrame( byte* ptRGB, unsigned int uiTableSize );
  11. // setPixelColor: Set the RGB data for a single LED.
  12. //  pixel is the LED number to be set. Numbering begins at 0. THE VALUE IS NOT CHECKED BY THE CODE, so if you set an illegal value, RAM corruption WILL occur!
  13. //  bR, bG and bB are respectively the RED, GREEN and BLUE values.
  14. //  NOTE: This function only changes the buffered values. The data is not automatically sent to the LEDs...
  15. void setPixelColor(unsigned int pixel, byte bR, byte bG, byte bB);
  16. // fillPixels: Sets the RGB data for all LEDs.
  17. //  bR, bG and bB are respectively the RED, GREEN and BLUE values.
  18. //  NOTE: This function only changes the buffered values. The data is not automatically sent to the LEDs...
  19. void fillPixels(byte bR, byte bG, byte bB);
  20. // clearPixels: Sets all the LEDs to BLACK (OFF).
  21. //  NOTE: This function only changes the buffered values. The data is not automatically sent to the LEDs...
  22. void clearPixels();
[Get Code]

Usually, the following functions should not have to be used:

  1. // setPulseLength: Manchester half period length in microseconds
  2. void setPulseLength( byte bPulse );
  3. // setEOSyncDelay: Call this to change the default delay after sending a SYNC frame. Delay is in milliseconds.
  4. void setEOSyncDelay( byte bEOSD );
  5. // setEOResetDelay: Call this to change the default delay after sending a RESET frame. Delay is in milliseconds.
  6. void setEOResetDelay( byte bEOR );
  7. // setEOEmptyFrameDelay: Call this to change the default delay after sending an empty DATAHEADER frame. Delay is in milliseconds.
  8. void setEOEmptyFrameDelay( byte bEOEF );
  9. // setEOEmptyFrameDelay: Call this to change the default delay after sending a DATA frame. Delay is in milliseconds.
  10. void setEOFrameDelay( byte bEOF );
[Get Code]

Example

  1. // TLS3008 based 50 RGB LEDs string test application for 16MHz Arduino
  2. // V1.1.0 library example code
  3. //
  4. // - DonJuanito99 -
  5.  
  6. #include <TLS3008.h>
  7.  
  8. // Number of times to repeat each 50 LEDs frame. Usually works OK with '1', but the LEDs are only updated on the next data transmission.
  9. // You can set the repeat count to 2 or more to immediately update the LEDs.
  10. // Alternatively, you can keep it to '1' and uncomment the FORCEIMMEDIATEUPDATE line to force the update of the LEDs.
  11. // You can see the results of these different settings by visually checking the timings of the LEDs...
  12. #define FRAMERPTCNT 1
  13. //#define FORCEIMMEDIATEUPDATE
  14.  
  15. byte RGBTable[50][3];  // RGB Values Table. Use type casting (byte*) to pass as a pointer to the sendRGBFrame function.
  16.  
  17. // Create instance of object TL3008.
  18. // 11: Setup output pin to LEDs.
  19. // &RGBTable: Pointer to the start of the RGB buffer.
  20. // 150: Size of the table in bytes.
  21. TLS3008 pixels = TLS3008(11, (byte*) &RGBTable, 150);
  22.  
  23. void setup()
  24. {
  25.   pixels.initCom(); // Initilize the communication with the LEDs
  26.   randomSeed(analogRead(5)); // Get a ramdom seed to initialize the random number generator
  27. }
  28.  
  29. void loop()
  30. {
  31.   byte ii;
  32.  
  33.   // Light all LED to flashy colors for 1 second ==============================================
  34.   pixels.setPixelColor(0, RGB_RED);     // Set pixel 0 to RED
  35.   pixels.setPixelColor(1, RGB_BLUE);    // Set pixel 1 to BLUE
  36.   pixels.setPixelColor(2, RGB_GREEN);   // Set pixel 1 to GREEN
  37.   pixels.setPixelColor(3, RGB_YELLOW);  // Set pixel 3 to YELLOW
  38.   pixels.setPixelColor(4, RGB_CYAN);    // Set pixel 4 to CYAN
  39.   pixels.setPixelColor(5, RGB_MAGENTA); // Set pixel 5 to MAGENTA
  40.   pixels.setPixelColor(6, RGB_BLACK);   // Set pixel 6 to BLACK (OFF)
  41.   pixels.setPixelColor(7, RGB_WHITE);   // Set pixel 7 to WHITE
  42.   for (ii=8;ii<50;ii++)  { // Set the rest of the LEDs to random flashy colors
  43.     RGBTable[ii][0] = (byte) (random(2)*255); // R
  44.     RGBTable[ii][1] = (byte) (random(2)*255); // G
  45.     RGBTable[ii][2] = (byte) (random(2)*255); // B
  46.   }
  47.   for(ii=0;ii<FRAMERPTCNT;ii++)
  48.     pixels.sendRGBFrame(); // Send buffer to pixels
  49. #ifdef FORCEIMMEDIATEUPDATE
  50.   pixels.sendEmptyFrame(); // *** Force the update of the LEDs ***
  51. #endif
  52.   delay(1000);  
  53.  
  54.   // Flash all LEDs to WHITE for 100 ms =======================================================
  55.   pixels.fillPixels(255, 255, 255); // Fill all pixels white (255, 255, 255)
  56.   for(ii=0;ii<FRAMERPTCNT;ii++)
  57.     pixels.sendRGBFrame(); // Send buffer to pixels
  58. #ifdef FORCEIMMEDIATEUPDATE
  59.   pixels.sendEmptyFrame(); // *** Force the update of the LEDs ***
  60. #endif
  61.   delay(100);
  62.  
  63.   // Turn off all LEDs for 500 ms =============================================================
  64.   pixels.clearPixels(); // Clear all pixels (actually fills them with (0, 0, 0))
  65.   for(ii=0;ii<FRAMERPTCNT;ii++)
  66.     pixels.sendRGBFrame(); // Send buffer to pixels
  67. #ifdef FORCEIMMEDIATEUPDATE
  68.   pixels.sendEmptyFrame(); // *** Force the update of the LEDs ***
  69. #endif
  70.   delay(500);
  71. }
[Get Code]

Information about this page

As Juan Hernandez did for his shiftOutX library page with NeoCat's Twitter library page, I also used his page as a template. I hope neither one will mind my borrowing :) - donjuanito99 at gmail dot com -

Last Modified: November 28, 2012, at 03:29 PM
By: DonJuanito