Constructs a tlc5947 object with the given spi bus and config pins for
the tlc5947. The SPI object must be configured before it is given to
the constructor, this allows any SPI config to be used with this
module. The xlat/blank pins must also be configured before they
are passed to the constructor.
from tlc5947 import tlc5947
from pyb import SPI, Pin
spi = SPI(2, SPI.MASTER, baudrate=20000000)
xlat = Pin(Pin.board.TLC5947_XLAT, Pin.OUT_PP)
blank = Pin(Pin.board.TLC5947_BLANK, Pin.OUT_OD)
tlc = tlc5947(spi, xlat, blank)The SPI baudrate can be chosen anywhere at or below 20000000, since this is the fastest baudrate supported by the tlc5947. If possible it should be as chosen as high as possible.
The minimum SPI baudrate is calculated as follows:
frequency = 100 # see __call__
bits = 288 # the tlc buffer is 288 bits
minumum_baudrate = frequency * (bits + bits * 0.1)This leaves barely any room for other applications and should only be used when absolutely required.
This setup allows the tlc5947 object to be used without requiring
any knowledge about the xlat or blank pins or how to configure the
SPI peripheral.
This is the call() method of the tlc5947 object, it is the method that causes anything to happen, all other methods just read/write the internal state. When this method is called, every pattern is advanced one step forward all LED's are updated with their new colors if there are new colors, and then they are written out to the TLC5947 device and latched onto the Gray-scale registers.
This method should be called in regular intervals, the exact frequency depends on the particular application. The frequency must be a multiple of the fastest desired update rate.
example: If you want to fade an LED from one to another color in 100 steps, in 1 second, the frequency must be N*100Hz. N can be 1, there is no reason for a faster frequency if it is not needed. But be aware that any change will happen at this frequency.
from pyb import Timer
timer = Timer(7, freq=100) # call 100 times per second
timer.callback(tlc) # register the __call__ methodAny reference to tick in this documentation refers to this, in this
example the frequency of the timer is the tick rate of the driver.
This method just sets and clears the BLANK pin of the TLC5947 device. Use this method and not the pyb.Pin() directly, since this makes it possible for the driver to stop sending the data over the SPI bus while the driver is BLANK'ed.
This optimization is not implemented for now, but it is possible.
This method set's LED's or a single led to a specific pattern. The leds can be given as a single int representing an individual led, or a list of int's representing any number of led's.
The pattern is a string that must be a valid Pattern format. For a description of the pattern format see this.
pid1 = tlc.set(1, "#FF0000")
pid2 = tlc.set([2, 3, 4], "#FF0000")
pid3 = tlc.set([7], "#FF0000")This method returns a so called pattern_id. This pattern_id can be used in the next methods to refer back to the pattern set here.
This method can be used to replace an existing pattern with a new pattern while keeping the same pattern_id.
pid = tlc.set(1, "@;") # set a transparent and infinite pattern
# this basically reserves the pattern\_id
# do other stuff
tlc.replace(pid, "#F0F0F0;")This method returns the same pid that was passed in.
Why this method is usefull is described here.
This method deletes a pattern, returns true on success.
If this method returns false, the pattern_id either did not exist or was not valid.
Infinite patterns (see here) can only be removed directly with this method (Or by replacing it by a finite pattern).
This method return's the current color of the LED.
The color is taken directly from the internal copy of the tlc5947 buffer. If a pattern is running that changes the RGB value of the LED, this method can be used to get the current color.
from time import sleep
# color fade from red to black(off)
pid = tlc.set(1, "<5[#FF0000<10[|50\b-0.1-]>-|50]")
while tlc.exists(pid):
# Print the current RGB value of LED 1
print(tlc.get(1))
sleep(0.05)
This checks if the pattern_id given exists and is still in use. This can be used for timed patterns to see when they are finished.
# This pattern takes 50 ticks
pid1 = tlc.set(1, "#FF0000|50#0000FF")
while tlc.exists(pid):
pass
print("Pattern Done")It is important to keep in mind that pattern_id's while they are unique, meaning one pattern_id refers to one pattern, they can be reused. The pattern_id is a unsigned 16bit integer, the id's are sequential starting at 1 and once id 65535 is reached overflowing back to 1.
This method sets the internal white balance martix for the rgb driver.
The matrix parameter must be a list containing 3 numbers from 0->1 (automatically clamped).
The matrix is applied like this:
r = r * matrix[0]
g = g * matrix[1]
b = b * matrix[2]
This method sets the internal gamut martix for the rgb driver.
The values in each row of the matrix must be <= 1 combined.
The matrix is applied like this:
r = r * matrix[0][0] + g * matrix[0][1] + b * matrix[0][2]
g = r * matrix[1][0] + g * matrix[1][1] + b * matrix[1][2]
b = r * matrix[2][0] + g * matrix[2][1] + b * matrix[2][2]
This method allows the order of the LED's to be remapped to a different LED index.
The default configuration maps LED D1 to index 1 e.g.:
tlc.set(1, "#0000FF;") # LED D1
tlc.set(3, "#00FF00;") # LED D3
tlc.set(6, "#FF0000;") # LED D6If your application arranges the LED's differently, it may be easier
to address the LED's in a different order. This can be achieved with
the id_map.
map = [4, 3, 2, 1, -1, -1, 7, 8]
tlc.set_id_map(map)
tlc.set(1, "#0000FF;") # LED D4
tlc.set(3, "#00FF00;") # LED D2
tlc.set(6, "#FF0000;") # -> ValueError("led not in id_map")