It's easy to use the TLC5947 and TLC59711 with Python or CircuitPython, and the Adafruit CircuitPython TLC5947 and Adafruit CircuitPython TLC59711 modules. These modules allows you to easily write Python code that controls the PWM outputs of these boards.
You can use this driver with any CircuitPython microcontroller board or with a computer that has GPIO and Python thanks to Adafruit_Blinka, our CircuitPython-for-Python compatibility library.
CircuitPython Microcontroller Wiring
First wire up your board exactly as shown on the previous pages for an Arduino. For example here's how to wire a TLC5947 to a Feather M0 using a standard hardware SPI connection:
- Board GND/ground to driver GND
- Board USB/5V to driver V+ and RGB LED anode (longest leg).
- Board SCK to driver CLK
- Board MOSI to driver DIN
- Board D5 to driver LAT (or use any other free digital I/O).
- RGB LED red leg to driver output 21 (or any other output).
- RGB LED green leg to driver output 22 (or any other output).
- RGB LED blue leg to driver output 23 (or any other output).
You might need to check your RGB LED's datasheet to find which legs are the red, green, blue inputs (or just experiment with turning them on off to find out). The longest leg will always be the anode, or positive voltage input. Be sure you're using a common anode and not common cathode RGB LED!
If you're using a TLC59711 here's how to wire it to a Feather M0 again using a standard SPI connection:
- Board GND to driver GND
- Board USB/5V to driver V+, driver VCC, and RGB LED anode (longest leg).
- Board SCK to driver CI
- Board MOSI to driver DI
- RGB LED red leg to driver output R3 (or any other R output).
- RGB LED green leg to driver output G3 (or any other G output).
- RGB LED blue leg to driver output B3 (or any other B output).
Again you might need to check your RGB LED's datasheet to find which legs are the red, green, blue inputs (or just experiment with turning them on off to find out). The longest leg will always be the anode, or positive voltage input. Be sure you're using a common anode and not common cathode RGB LED!
Python Computer Wiring
Since there's dozens of Linux computers/boards you can use we will show wiring for Raspberry Pi. For other platforms, please visit the guide for CircuitPython on Linux to see whether your platform is supported.
Here's the Raspberry Pi and TLC5947 wired with SPI:
-
Pi 5V to driver V+
- Pi GND to driver GND
- Pi MOSI to driver DIN
- Pi SCLK to driver CLK
- Pi GPIO5 to driver LAT (or use any other free digital I/O).
- RGB LED anode leg to driver V+
- RGB LED red leg to driver output 1 (or any other output).
- RGB LED green leg to driver output 2 (or any other output).
- RGB LED blue leg to driver output 3 (or any other output).
Check your RGB LED's datasheet to find out which legs are red, green and blue, or experiment with turning them on and off to find out. The longest leg will always be the anode, or positive voltage output. Be sure you're using a common anode and not common cathode RGB LED!
Here's the Raspberry Pi and TLC59711 wired with SPI:
-
Pi 5V to driver V+, driver VCC
- Pi GND to driver GND
- Pi MOSI to driver DI
- Pi SCLK to driver CI
- RGB LED anode leg to driver V+
- RGB LED red leg to driver output R0 (or any other R output).
- RGB LED green leg to driver output G0 (or any other G output).
- RGB LED blue leg to driver output B0 (or any other B output).
Check your RGB LED's datasheet to find out which legs are red, green and blue, or experiment with turning them on and off to find out. The longest leg will always be the anode, or positive voltage output. Be sure you're using a common anode and not common cathode RGB LED!
CircuitPython Installation of TLC5947 and TLC59711 Libraries
Next you'll need to install either the Adafruit CircuitPython TLC5947 or Adafruit CircuitPython TLC59711 module on your CircuitPython board, depending on which board you're using.
First make sure you are running the latest version of Adafruit CircuitPython for your board.
Next you'll need to install the necessary libraries to use the hardware--carefully follow the steps to find and install these libraries from Adafruit's CircuitPython library bundle. Our introduction guide has a great page on how to install the library bundle for both express and non-express boards.
Remember for non-Express boards, you'll need to manually install the necessary libraries from the bundle, either:
- adafruit_tlc5947.mpy
Or:
- adafruit_tlc59711.mpy
Before continuing make sure your board's lib folder or root filesystem has the adafruit_tlc5947.mpy or adafruit_tlc59711.mpy files copied over.
Next connect to the board's serial REPL so you are at the CircuitPython >>> prompt.
Python Installation of TLC5947 and TLC59711 Libraries
You'll need to install the Adafruit_Blinka library that provides the CircuitPython support in Python. This may also require enabling I2C on your platform and verifying you are running Python 3. Since each platform is a little different, and Linux changes often, please visit the CircuitPython on Linux guide to get your computer ready!
Once that's done, from your command line run the following command:
sudo pip3 install adafruit-circuitpython-tlc5947
Or:
sudo pip3 install adafruit-circuitpython-tlc59711
If your default Python is version 3 you may need to run 'pip' instead. Just make sure you aren't trying to use CircuitPython on Python 2.x, it isn't supported!
CircuitPython & Python Usage of TLC5947
To demonstrate the usage of the TLC5947 we'll initialize it and control PWM outputs using the Python REPL. First run the following code to initialize the SPI bus and other connections to the chip:
import board import busio import digitalio import adafruit_tlc5947 spi = busio.SPI(clock=board.SCK, MOSI=board.MOSI) latch = digitalio.DigitalInOut(board.D5) tlc5947 = adafruit_tlc5947.TLC5947(spi, latch)
Be sure to set latch to the right digital I/O pin connected to your TLC5947's latch input. The wiring and code above use pin D5.
Now you're ready to control any of the 24 PWM outputs from the board. There are two ways to control these outputs, the first is with direct access to each channels 12-bit PWM duty cycle. You just index into the TLC5947 object like an array and set or get the duty cycle value, for example to set output 21 to a 100% duty cycle (which should turn the LED on to full red intensity if wired as shown):
tlc5947[21] = 4095
Notice the LED turns bright red! You can drop it down to half red brightness by setting a smaller duty cycle. Any value from 0 (off/no intensity) to 4095 (maximum/full intensity) can be set. Try a value in-between like 2048:
tlc5947[21] = 2048
You can change the other colors of the LED too, like to set full green (output 22) and quarter intensity blue (output 23):
tlc5947[22] = 4095 tlc5947[23] = 1024
The other way to control the TLC5947 outputs is with a syntax similar to CircuitPython's built-in PWMOut object. This is useful if you have code meant to work with PWMOut objects, like a motor controller or other higher-level class. You can pass in a special TLC5947 PWMOut object and it will be controlled just like a regular CircuitPython PWMOut.
Create a PWMOut object by calling the create_pwm_out function and pass it the number of the output. For example to make a PWM out for the red channel of the LED (output 21) you would run:
red = tlc5947.create_pwm_out(21)
Now you can change the duty_cycle property of the red object to control the duty cycle of that channel on the TLC5947.
One thing to note is that the duty cycle for this PWMOut expects a 16-bit value just like the regular CircuitPython PWMOut! This means you instead need to use a range of values from 0 (off/no intensity) to 65535 (max/full intensity). Also there's a small chance you'll get little math errors because the TLC5947 only supports a 12-bit duty cycle so be aware if you need the most accurate PWM output you might want to use the direct channel access shown above.
To set the red channel to maximum intensity run:
red.duty_cycle = 65535
Or set any value from 0 - 65535 to change to an in-between duty cycle!
You might notice the PWMOut object also has a frequency property. Unlike CircuitPython's built-in PWMOut this property actually does nothing and cannot be changed. The TLC5947 has a fixed PWM frequency which is good for driving LEDs, not for servos. If you need control of PWM frequency you might need to use a native PWM output from your development board!
That's all there is to using the TLC5947 with CircuitPython! Here's a complete example of initializing the chip and pulsing (dimming and brightening) the LED. Save this as code.py on your board to run it.
# SPDX-FileCopyrightText: 2018 Tony DiCola for Adafruit Industries
# SPDX-License-Identifier: MIT
# Simple demo of controlling the TLC5947 12-bit 24-channel PWM controller.
# Will update channel values to different PWM duty cycles.
# Author: Tony DiCola
import board
import busio
import digitalio
import adafruit_tlc5947
# Define pins connected to the TLC5947
SCK = board.SCK
MOSI = board.MOSI
LATCH = digitalio.DigitalInOut(board.D5)
# Initialize SPI bus.
spi = busio.SPI(clock=SCK, MOSI=MOSI)
# Initialize TLC5947
tlc5947 = adafruit_tlc5947.TLC5947(spi, LATCH)
# You can optionally disable auto_write which allows you to control when
# channel state is written to the chip. Normally auto_write is true and
# will automatically write out changes as soon as they happen to a channel, but
# if you need more control or atomic updates of multiple channels then disable
# and manually call write as shown below.
# tlc5947 = adafruit_tlc5947.TLC5947(spi, LATCH, auto_write=False)
# There are two ways to channel channel PWM values. The first is by getting
# a PWMOut object that acts like the built-in PWMOut and can be used anywhere
# it is used in your code. Change the duty_cycle property to a 16-bit value
# (note this is NOT the 12-bit value supported by the chip natively) and the
# PWM channel will be updated.
# With an RGB LED hooked up to pins 0, 1, and 2, cycle the red, green, and
# blue pins up and down:
red = tlc5947.create_pwm_out(0)
green = tlc5947.create_pwm_out(1)
blue = tlc5947.create_pwm_out(2)
step = 10
start_pwm = 0
end_pwm = 32767 # 50% (32767, or half of the maximum 65535):
while True:
for pin in (red, green, blue):
# Brighten:
print("Brightening LED")
for pwm in range(start_pwm, end_pwm, step):
pin.duty_cycle = pwm
# Dim:
print("Dimming LED")
for pwm in range(end_pwm, start_pwm, 0 - step):
pin.duty_cycle = pwm
# Note if auto_write was disabled you need to call write on the parent to
# make sure the value is written (this is not common, if disabling auto_write
# you probably want to use the direct 12-bit raw access instead shown below).
# tlc5947.write()
# The other way to read and write channels is directly with each channel 12-bit
# value and an item accessor syntax. Index into the TLC5947 with the channel
# number (0-23) and get or set its 12-bit value (0-4095).
# For example set channel 1 to 50% duty cycle.
# tlc5947[1] = 2048
# Or set channel 23 (first channel from the end) to 2/3 duty cycle.
# tlc5947[-1] = 2730
# Again be sure to call write if you disabled auto_write.
# tlc5947.write()
CircuitPython & Python Usage of TLC59711
To demonstrate the usage of the TLC59711 we'll initialize it and control PWM outputs using the Python REPL. First run the following code to initialize the SPI bus and other connections to the chip:
import board import busio import digitalio import adafruit_tlc59711 spi = busio.SPI(clock=board.SCK, MOSI=board.MOSI) tlc59711 = adafruit_tlc59711.TLC59711(spi)
Now you're ready to start controlling the PWM outputs of the TLC59711. There are two ways to control these outputs. The first way is with a format that's very similar to controlling a strip of NeoPixels. For each of the R0, G0, B0, R1, G1, B1, etc. sets of PWM outputs they can be adjusted at once by indexing into the TLC59711 object. For example to set the R3, G3, B3 output to full red intensity run:
tlc59711[3] = (65535, 0, 0)
Notice you set the outputs using a 3-tuple of 16-bit values. These are the PWM duty cycle values to assign to the R3, G3, and B3 channels respectively. You could set the same outputs to moderate green/blue (half intensity of each) by running:
tlc59711[3] = (0, 32767, 32767)
The other way to control PWM outputs is with direct access to each output pin. The TLC59711 object has a property for each R0, G0, B0, R1, etc. output and you can set or get its 16-bit PWM duty cycle directly. For example to change R3 to full intensity:
tlc59711.r3 = 65535
This is handy if you're not controlling RGB LEDs and instead just want to control each channel independently.
Finally the TLC59711 supports a global red, green, and blue channel brightness control. These values adjust all of the associated color outputs, like the red brightness channel control changes the R0, R1, R2, and R3 outputs. Set this to a 7-bit value (0-127) with 0 being low intensity and 127 being maximum intensity. Both the channel brightness and the individual channel PWM duty cycle are used to set the final output of a channel. For example to dim all the red channels by half you can run:
tlc59711.red_brightness = 63
There's a similar green_brightness property that controls G0, G1, G2, G3 and blue_brightness property that controls B0, B1, B2, B3.
That's all there is to controlling the TLC59711 with CircuitPython! Below is a complete example of initializing communication with the chip and changing some of the PWM outputs as shown above. Save this as code.py on your board to have it run.
# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT
# simple demo of the TLC59711 16-bit 12 channel LED PWM driver.
# Shows the minimal usage - how to set pixel values in a few ways.
# Author: Tony DiCola
import board
import busio
import adafruit_tlc59711
print("tlc59711_simpletest.py")
# Define SPI bus connected to chip.
# You only need the clock and MOSI (output) line to use this chip.
spi = busio.SPI(board.SCK, MOSI=board.MOSI)
pixels = adafruit_tlc59711.TLC59711(spi, pixel_count=16)
# examples how to set the pixels:
# range:
# 0 - 65535
# or
# 0.0 - 1.0
# every pixel needs a color -
# give it just a list or tuple with 3 integer values: R G B
# set all pixels to a very low level
pixels.set_pixel_all((10, 10, 10))
# every chip has 4 Pixels (=RGB-LEDs = 12 Channel)
pixels[0] = (100, 100, 100)
pixels[1] = (0, 0, 100)
pixels[2] = (0.01, 0.0, 0.01)
pixels[3] = (0.1, 0.01, 0.0)
# if you are ready to show your values you have to call
pixels.show()
# there are a bunch of other ways to set pixel.
# have a look at the other examples.
Page last edited January 20, 2025
Text editor powered by tinymce.
