Introduction

Documentation Status Discord Build Status

CircuitPython module for the TLC5947 12-bit 24 channel LED PWM driver.

Dependencies

This driver depends on:

Please ensure all dependencies are available on the CircuitPython filesystem. This is easily achieved by downloading the Adafruit library and driver bundle.

Usage Example

See examples/tlc5947_simpletest.py for a demo of the usage.

Contributing

Contributions are welcome! Please read our Code of Conduct before contributing to help this project stay welcoming.

Building locally

To build this library locally you’ll need to install the circuitpython-build-tools package.

python3 -m venv .env
source .env/bin/activate
pip install circuitpython-build-tools

Once installed, make sure you are in the virtual environment:

source .env/bin/activate

Then run the build:

circuitpython-build-bundles --filename_prefix adafruit-circuitpython-tlc5947 --library_location .

Sphinx documentation

Sphinx is used to build the documentation based on rST files and comments in the code. First, install dependencies (feel free to reuse the virtual environment from above):

python3 -m venv .env
source .env/bin/activate
pip install Sphinx sphinx-rtd-theme

Now, once you have the virtual environment activated:

cd docs
sphinx-build -E -W -b html . _build/html

This will output the documentation to docs/_build/html. Open the index.html in your browser to view them. It will also (due to -W) error out on any warning like Travis will. This is a good way to locally verify it will pass.

Table of Contents

Simple test

Ensure your device works with this simple test.

examples/tlc5947_simpletest.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
# 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.
pwm0 = tlc5947.create_pwm_out(0)

# Set the channel 0 PWM to 50% (32767, or half of the max 65535):
pwm0.duty_cycle = 32767
# 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
# Again be sure to call write if you disabled auto_write.
#tlc5947.write()

adafruit_tlc5947

CircuitPython module for the TLC5947 12-bit 24 channel LED PWM driver. See examples/simpletest.py for a demo of the usage.

  • Author(s): Tony DiCola

Implementation Notes

Hardware:

Software and Dependencies:

class adafruit_tlc5947.TLC5947(spi, latch, *, auto_write=True)[source]

TLC5947 12-bit 24 channel LED PWM driver. Create an instance of this by passing in at least the following parameters:

Parameters:
  • spi – The SPI bus connected to the chip (only the SCK and MOSI lines are used, there is no MISO/input).
  • latch – A DigitalInOut instance connected to the chip’s latch line.

Optionally you can specify:

Parameters:auto_write – This is a boolean that defaults to True and will automatically write out all the channel values to the chip as soon as a single one is updated. If you set to false to disable then you MUST call write after every channel update or when you deem necessary to update the chip state.
class PWMOut(tlc5947, channel)[source]

Internal PWMOut class that mimics the behavior of CircuitPython’s PWMOut class but is associated with a channel on the TLC5947. You can get and set the instance’s duty_cycle property as a 16-bit PWM value (note there will be quantization errors as the TLC5947 is a 12-bit PWM chip, instead use the TLC5947 class item accessor notation for direct 12-bit raw PWM channel access). Note you cannot change the frequency as it is fixed by the TLC5947 to ~2.4-5.6 mhz.

duty_cycle

Get and set the 16-bit PWM duty cycle value for this channel.

frequency

Frequency of the PWM channel, note you cannot change this and cannot read its exact value (it varies from 2.4-5.6 mhz, see the TLC5947 datasheet).

create_pwm_out(channel)[source]

Create an instance of a PWMOut-like class that mimics the built-in CircuitPython PWMOut class but is associated with the TLC5947 channel that is specified. This PWMOut class has a duty_cycle property which you can read and write with a 16-bit value to control the channel. Note there will be quantization error as the chip only supports 12-bit PWM, if this is problematic use the item accessor approach to update the raw 12-bit channel values.

write()[source]

Write out the current channel PWM values to the chip. This is only necessary to call if you disabled auto_write in the initializer, otherwise write is automatically called on any channel update.

Indices and tables