andy4495/tlc591x

Library for Texas Instruments TLC5916 and TLC5917 constant current LED sink driver for Arduino.

TLC591x Library

This library is designed to interface with the Texas Instruments TLC5916 and TLC5917 8-Channel Constant-Current LED Sink Drivers.

A minimum of three I/O pins are required (SDI, CLK, LE). An optional fourth pin can be defined for the output enable signal (/OE). If not used, the library assumes that the pin is tied low (and the LED output is always enabled). The /OE pin is required if you want to switch the chip to Special Mode.

This library can use either a processor's built-in hardware SPI interface (by way of the Arduino SPI library), or a software serial interface which allows just about any I/O pin to be used to control the TLC591x chip.

Up to 254 TLC591x chips can be cascaded together to control various LED configurations: LED bar graph, common anode 7-segment displays, or individual LEDs.

Usage

See the sketches included in the examples folder.

1. Include the header file:

   #include <TLC591x.h>

2. Use a constructor to create an LED object:

   • For software SPI, use one of the following:

   TLC591x myLED(num_chips, SDI_pin, CLK_pin, LE_pin, OE_pin);  // OE pin controlled by library
   TLC591x myLED(num_chips, SDI_pin, CLK_pin, LE_pin);          // OE pin hard-wired low (always enabled)

   • For hardware SPI, use one of the following:

   TLC591x myLED(num_chips, LE_pin, OE_pin);  // OE pin controlled by library
   TLC591x myLED(num_chips, LE_pin);          // OE pin hard-wired low (always enabled)

   The num_chips parameter defines how many chips are cascaded together (maximum of 254). The chips include a serial data output (SDO) pin so that several chips can be connected in a daisy-chain configuration.

   If using the /OE pin, the default state is for the display to be turned off, so the enableDisplay() method needs to be called to turn on the display after powering up.

3. Once you have created a TLC591x object, the following methods can be used to control the LEDs.

• Print ASCII characters to 7-segment displays:

  void print(char* s)

  s is a char array with a size of at least num_chips containing ASCII characters. It is similar to a c-string but does not need to be null-terminated since its size is assumed to be num_chips as defined in the constructor. Any characters beyond the number of chips defined in the constructor are ignored.

  The most significant digit is in element 0 of the array.

  The library includes a pre-defined mapping for displaying ASCII characters (letters, numbers, symbols) from 32 - 127 and assumes that the TLC591x chip is connected to the 7-segment display as follows:

  TLC591x Pin  Display Segment
  -----------  ---------------
     OUT0            DP
     OUT1             A
     OUT2             B
     OUT3             C
     OUT4             E
     OUT5             G
     OUT6             F
     OUT7             D
  

  Note that a 7-segment display does not allow an accurate rendering of all ASCII characters and symbols.

• To control individual LEDs:

   void print(unsigned int n)

  The value n is shifted out to the TLC591x chip(s) one bit at a time. If a single-chip configuration was defined in the constructor, then only the least-significant 8 bits are shifted.

  This method only supports one or two TLC591x chips, and is included for backward compatibility with older versions of the library. If you are using more than two chips, then use printDirect() instead.

• To control individual LEDs, or directly control LED segments in a 7-segment display, use:

   void printDirect(const uint8_t* b)

  b is an array of size of at least num_chips. The values are shifted out right to left (i.e., b[0] is shifed out last).

• Control the output enable (/OE) signal. These methods only have an effect if the OE pin was defined in the constructor. Also, they override the brightness setting of displayBrightness().

  void displayEnable();

  Sets the output enable (/OE) signal low, which turns on the display. The default state of the /OE pin when defined in the constructor is disabled.

   void displayDisable();  

  Sets the output enable (/OE) signal high, which turns off the display.

• To put the TLC591x chip into Normal Mode (see datasheet for more info). This method overrides the brightness setting of displayBrightness():

  void normalMode();

  The chip is in normal mode by default when powered on.

• To put the TLC591x chip into Special Mode (see datasheet for more info). This method overrides the brightness setting of displayBrightness():

  void specialMode();

  The chip must have the /OE signal connected to the microcontroller (and defined in the constructor) for this method to have an effect. While in Special Mode, the display is disabled. Once the chip is in special mode, the Configuration Latch can be written using the printDirect() method.

• To conntrol the display brightness:

  void displayBrightness(byte b);

  Uses PWM on /OE pin to control display brightness. This method requires that the /OE pin is a PWM-capable pin and is defined in the constructor. Note that since /OE is active low, a value of zero is brightest and 255 is dimmest.

  This method enables the display, so that if the display was previously disabled with displayDisable(), the display will be turned on. The brightness setting is overwritten by any of the following methods: enableDisplay(), disableDisplay(), normalMode(), specialMode().

  This command should only be used while the display is in normal mode. Unexpected results may occur if this method is called while in special mode.

Hardware Design

A reference design incorporating two TLC5916/7 chips and various LEDs configurations is available in the extras/hardware folder.

Hardware and Software SPI Compatibility

The library has been tested with AVR, MSP430, MSP432, and Tiva processors using both hardware and software SPI.

When configured to use software SPI, this library should work with any processor that is supported by the Arduino IDE, because it uses platform-agnostic digitalWrite() functions to control the hardware.

While the library has been tested with the hardware platforms listed above, there could potentially be compatibility issues with other platforms when using hardware SPI.

References

• TLC591x datasheet

License

The software and other files in this repository are released under what is commonly called the MIT License. See the file LICENSE.txt in this repository.

tlc591x's Issues

Possible issue with index out of array bounds

Review print(char*) method, may be indexing out of array bounds: starting at 2 and decrement to 1 and 0.
Check other array usage while you are at it.

How to control individual LEDS intensity?

Hi
Great library!
But I'm having dificulty figuring out how to control a LED intensity without turning the other Off.
All I want is to be able to have and LED at 50% for example and another at 75%, but every time I change an LED intensity, the other turn off.
For example, trying to have OUT0 and OUT1 On, but with different intensities, in a single TLC5917:

//Setting an intensity on OUT0:
  myLED.normalMode();
  n[0] = 0x80;
  myLED.print(n[0]);
  delay(5000);
  myLED.specialMode();
  Bright[0] = 0xff;
  myLED.specialMode();
  Bright[0] = 0xff;
  myLED.printDirect(Bright);
  myLED.normalMode();

//Now setting an intensity on OUT1:
  n[0] = 0x60;
  myLED.print(n[0]);
  delay(5000);
  myLED.specialMode();
  Bright[0] = 0xff;
  myLED.specialMode();
  Bright[0] = 0xcc;
  myLED.printDirect(Bright);
  myLED.printDirect(Bright);
  myLED.normalMode();

//Now only LED OUT1 is ON =\

Either I got the datasheet wrong or I'm missing something here.

Hopefully its something simple.

Thank you.

Cheers, Luís Pereira.

Compile errors when using ESP32 Dev Module

I'm getting a compile error when compiling TLC591x_library_example.ino for a ESP32 Dev Module. I think it's due to ESP32 using DISABLED as a #define preprocessor.

example project: TLC591x_library_example.ino
environment: Arduino IDE 2.2.1
board: ESP32 Dev Module

Compiler output:

In file included from C:\Users\sam\AppData\Local\Arduino15\packages\esp32\hardware\esp32\2.0.12\cores\esp32/esp32-hal.h:83,
                 from C:\Users\sam\AppData\Local\Arduino15\packages\esp32\hardware\esp32\2.0.12\cores\esp32/Arduino.h:36,
                 from C:\Users\sam\AppData\Local\Temp\arduino\sketches\7166EE4EC2607248BBD2B5EB8D32197D\sketch\TLC591x_ESP32.ino.ino.cpp:1:
C:\Users\sam\AppData\Local\Arduino15\packages\esp32\hardware\esp32\2.0.12\cores\esp32/esp32-hal-gpio.h:58:19: error: expected identifier before numeric constant
 #define DISABLED  0x00
                   ^~~~
d:\Documents\Arduino\libraries\TLC591x\src/TLC591x.h:52:29: note: in expansion of macro 'DISABLED'
   enum EN_DIS {ENABLED = 0, DISABLED = 255};
                             ^~~~~~~~
C:\Users\sam\AppData\Local\Arduino15\packages\esp32\hardware\esp32\2.0.12\cores\esp32/esp32-hal-gpio.h:58:19: error: expected '}' before numeric constant
 #define DISABLED  0x00
                   ^~~~
d:\Documents\Arduino\libraries\TLC591x\src/TLC591x.h:52:29: note: in expansion of macro 'DISABLED'
   enum EN_DIS {ENABLED = 0, DISABLED = 255};
                             ^~~~~~~~
In file included from D:\Documents\Arduino\TLC591x_ESP32.ino\TLC591x_ESP32.ino.ino:16:
d:\Documents\Arduino\libraries\TLC591x\src/TLC591x.h:52:15: note: to match this '{'
   enum EN_DIS {ENABLED = 0, DISABLED = 255};
               ^
In file included from C:\Users\sam\AppData\Local\Arduino15\packages\esp32\hardware\esp32\2.0.12\cores\esp32/esp32-hal.h:83,
                 from C:\Users\sam\AppData\Local\Arduino15\packages\esp32\hardware\esp32\2.0.12\cores\esp32/Arduino.h:36,
                 from C:\Users\sam\AppData\Local\Temp\arduino\sketches\7166EE4EC2607248BBD2B5EB8D32197D\sketch\TLC591x_ESP32.ino.ino.cpp:1:
C:\Users\sam\AppData\Local\Arduino15\packages\esp32\hardware\esp32\2.0.12\cores\esp32/esp32-hal-gpio.h:58:19: error: expected unqualified-id before numeric constant
 #define DISABLED  0x00
                   ^~~~
d:\Documents\Arduino\libraries\TLC591x\src/TLC591x.h:52:29: note: in expansion of macro 'DISABLED'
   enum EN_DIS {ENABLED = 0, DISABLED = 255};
                             ^~~~~~~~
In file included from D:\Documents\Arduino\TLC591x_ESP32.ino\TLC591x_ESP32.ino.ino:16:
d:\Documents\Arduino\libraries\TLC591x\src/TLC591x.h:53:3: error: 'EN_DIS' does not name a type; did you mean 'FM_DIO'?
   EN_DIS enableState;
   ^~~~~~
   FM_DIO
d:\Documents\Arduino\libraries\TLC591x\src/TLC591x.h:54:3: error: 'EN_DIS' does not name a type; did you mean 'FM_DIO'?
   EN_DIS pwmMode;       // Used to keep track of whether the displayBrightness() method was used
   ^~~~~~
   FM_DIO
d:\Documents\Arduino\libraries\TLC591x\src/TLC591x.h:62:1: error: expected declaration before '}' token
 };
 ^

exit status 1

Compilation error: exit status 1

Hardware SPI

@Andy4495,

I tweaked your library to support hardware SPI. It's not a major improvement, but as I happened to have a rudimentary sketch for the STP08DP05 (very similar to the TLC5916) that used SPI, I had to give it a try. Another enhancement of mine -- perhaps a more worthwhile one -- is PWM output on /OE, which allows you to set the brightness of the LEDs.

I tested the tweaked library on a WeMos D1 R2 (an Arduino form-factor ESP8266). The display is self-made, with four 1" 7-segment LEDs.

Let me know if you want to review the code.

Hardware SPI incompatibilities with MSP432 and Tiva platforms

The SPI library included with MSP432 and Tiva platform cores do not currently work with this library.

Further investigation is needed to see if there is a way to support hardware SPI for these platforms, probably through the use of conditional compilation.

One of the issues is related to the definition of the SCK pin, so one approach may be to disable the normalMode() and specialMode() methods when using hardware SPI.

Generalize for arbitrary number of digits.

Consider effort to make this work for arbitrary (or some finite number > 2) number of digits. This may not be very useful, since displays > 2 digits generally are multiplexed. But this would allow manually creating a larger display from single digit modules.