If you want to expand the capabilities of the CharliePlex LED Matrix even more, we can add Pillow into the mix. So we'll show you how to add Pillow and then go over a couple of examples that use Pillow.
Additional Setup
If you haven't already installed the library, follow the setup section on the Python & CircuitPython page. If you have, then continue.
DejaVu TTF Font
Raspberry Pi usually comes with the DejaVu font already installed, but in case it didn't, you can run the following to install it:
sudo apt-get install ttf-dejavu
Pillow Library
We also need Pillow, also known as PIL, the Python Imaging Library, to allow using text with custom fonts. There are several system libraries that PIL relies on, so installing via a package manager is the easiest way to bring in everything:
sudo apt-get install python3-pil
That's it. You should be ready to go.
Speeding up the Display on Raspberry Pi
For the best performance, especially if you are doing fast animations, you'll want to tweak the I2C core to run at 1MHz. By default it may be 100KHz or 400KHz
To do this, edit the config with sudo nano /boot/config.txt
and add to the end of the file
dtparam=i2c_baudrate=1000000
Reboot to 'set' the change.
Scrolling Marquee Example
The first example, we're going to take a look at an example that will take some text, draw it in a TrueType font and then scroll the rendered text. Let's start by looking at the code in each section.
We start by importing the libraries we need which include the board and a few Pillow modules.
import board from PIL import Image, ImageDraw, ImageFont
Next we do the import for the IS31FL3731 driver for the matrix itself. Since the different boards have been split into their own modules, we just import the appropriate module and alias it as Display.
For instance, if you have the breakout instead of the bonnet, you'll want to uncomment that and comment out the bonnet line.
# uncomment next line if you are using Adafruit 16x9 Charlieplexed PWM LED Matrix # from adafruit_is31fl3731.matrix import Matrix as Display # uncomment next line if you are using Adafruit 16x8 Charlieplexed Bonnet from adafruit_is31fl3731.charlie_bonnet import CharlieBonnet as Display # uncomment next line if you are using Pimoroni Scroll Phat HD LED 17 x 7 # from adafruit_is31fl3731.scroll_phat_hd import ScrollPhatHD as Display
Next we set a couple of variables. We have the SCROLLING_TEXT variable. Go ahead and change the text if you would like. It shouldn't matter how long, though you probably shouldn't make it too long if you want to see it loop. You can set BRIGHTNESS as well, in case you want to adjust the intensity.
SCROLLING_TEXT = "You can display a personal message here..." BRIGHTNESS = 64 # Brightness can be between 0-255
Next we do the basic setup for the display by declaring the I2C object and passing that into the display.
i2c = board.I2C() display = Display(i2c)
Next we go ahead and load up the Deja Vu font into an object. We are going with an 8 pixel high font because that's the largest we can fit on the display and still see everything.
# Load a font
font = ImageFont.truetype('/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf', 8)
In this next part, we first start by getting the width and height of what the text would be when rendered with the font we chose. Then we create a virtual image of that width and height and draw the text onto it.
# Create an image that contains the text
text_width, text_height = font.getsize(SCROLLING_TEXT)
text_image = Image.new('L', (text_width, text_height))
text_draw = ImageDraw.Draw(text_image)
text_draw.text((0, 0), SCROLLING_TEXT, font=font, fill=BRIGHTNESS)
Next we create a virtual image that's the same size as the display. This will be where we draw what we want to actually display.
# Create an image for the display
image = Image.new('L', (display.width, display.height))
draw = ImageDraw.Draw(image)
Finally we get to our main loop. We start by drawing a rectangle to be sure we are not leaving any existing text behind. Then we paste our image of the text onto the image we are going to display using the value of x, which represents the left offset we want to use to give a nice scrolling effect. We have a for loop which will scroll the complete text plus empty display width by one iteration. That's all placed inside an infinite while loop for endless iterations.
while True:
for x in range(text_width + display.width):
draw.rectangle((0, 0, display.width, display.height), outline=0, fill=0)
image.paste(text_image, (display.width - x, display.height // 2 - text_height // 2 - 1))
display.image(image)
Now go ahead and run the example code.
python3 is31fl3731_pillow_marquee.py
You should see the display showing a message scrolling from right to left.
# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT
"""
Example to scroll some text as a marquee
This example is for use on (Linux) computers that are using CPython with
Adafruit Blinka to support CircuitPython libraries. CircuitPython does
not support PIL/pillow (python imaging library)!
Author(s): Melissa LeBlanc-Williams for Adafruit Industries
"""
import board
from PIL import Image, ImageDraw, ImageFont
# uncomment next line if you are using Adafruit 16x9 Charlieplexed PWM LED Matrix
# from adafruit_is31fl3731.matrix import Matrix as Display
# uncomment next line if you are using Adafruit 16x8 Charlieplexed Bonnet
from adafruit_is31fl3731.charlie_bonnet import CharlieBonnet as Display
# uncomment next line if you are using Pimoroni Scroll Phat HD LED 17 x 7
# from adafruit_is31fl3731.scroll_phat_hd import ScrollPhatHD as Display
SCROLLING_TEXT = "You can display a personal message here..."
BRIGHTNESS = 64 # Brightness can be between 0-255
i2c = board.I2C() # uses board.SCL and board.SDA
# i2c = board.STEMMA_I2C() # For using the built-in STEMMA QT connector on a microcontroller
display = Display(i2c)
# Load a font
font = ImageFont.truetype("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf", 8)
# Create an image that contains the text
text_width, text_height = font.getsize(SCROLLING_TEXT)
text_image = Image.new("L", (text_width, text_height))
text_draw = ImageDraw.Draw(text_image)
text_draw.text((0, 0), SCROLLING_TEXT, font=font, fill=BRIGHTNESS)
# Create an image for the display
image = Image.new("L", (display.width, display.height))
draw = ImageDraw.Draw(image)
# Load the text in each frame
while True:
for x in range(text_width + display.width):
draw.rectangle((0, 0, display.width, display.height), outline=0, fill=0)
image.paste(text_image, (display.width - x, display.height // 2 - text_height // 2 - 1))
display.image(image)
Animated GIF Example
Next let's take a look at an animated GIF player example. First we'll start by downloading an animated GIF and copying that into the same folder as the script as adafruit-star-rotating.gif. It looks tiny and that's because it is. It is 8x8 pixels which works out nicely for the CharliePlex matrix.
Now let's start with the first section, the imports. You may be surprised that this code uses fewer Pillow modules than the previous example. We are also adding sys, which we mostly use for passing the name of an animated gif.
import sys import board from PIL import Image import adafruit_is31fl3731
Next we do the usual setup for the CharliePlex display.
i2c = board.I2C() # uncomment line if you are using Adafruit 16x9 Charlieplexed PWM LED Matrix #display = adafruit_is31fl3731.Matrix(i2c) # uncomment line if you are using Adafruit 16x9 Charlieplexed PWM LED Matrix display = adafruit_is31fl3731.CharlieBonnet(i2c)
Now we make sure the user specified a gif file, so we have something to work with that's not hard-coded and open the file. If the file wasn't specified, we are using sys.exit(), since that is the preferred way to do it if you are importing sys anyways.
# Check that the gif was specified
if len(sys.argv) < 2:
print("No image file specified")
print("Usage: python3 is31fl3731_pillow_animated_gif.py animated.gif")
sys.exit()
# Open the gif
image = Image.open(sys.argv[1])
We need to check that this is an animated gif. While we could have just displayed it as a static gif in this case, the point was to show how to display the animation.
# Make sure it's animated
if not image.is_animated:
print("Specified image is not animated")
sys.exit()
Next we get some gif animation information such as the delay. Only the duration of the first frame is extractable at the time of this writing with Pillow.
# Get the autoplay information from the gif delay = image.info['duration']
The loop number is a little trickier because it means different things between the IS31FL3731 chip and an animated gif. With an animated gif, it is guaranteed to play at least once and then loop by the number of times is provided by the loop value, unless it is zero, which means forever.
With the IS31FL3731, loops mean exactly the number of loops to play the animation, unless it is zero, in which case it will play forever.
So if loop is 0, we just pass it on. If we only want to play the animation once, then loop is not provided in the image information. If it is more than once, we need to count the first time it plays plus the number of times to loop the animation.
# Figure out the correct loop count
if "loop" in image.info:
loops = image.info['loop']
if loops > 0:
loops += 1
else:
loops = 1
Next, we need to make sure these values are in the ranges that the driver likes. The number of frames in the animation is available from the property n_frames and the IS31FL3731 can handle a maximum of 8 frames, so if a longer animation is provided, only the first 8 frames are used.
# IS31FL3731 only supports 0-7
if loops > 7:
loops = 7
# Get the frame count (maximum 8 frames)
frame_count = image.n_frames
if frame_count > 8:
frame_count = 8
Now that we have a frame count, we will go through each of those frames and load the frame image into the IS31FL3731 using the paste function and center the image. First the frame is converted to a 256-grayscale image, which is what mode L is, and then it is copied into a centered position, which is calculated from the difference in size between the display and image. After that, it is inserted as the current frame number.
# Load each frame of the gif onto the Matrix
for frame in range(frame_count):
image.seek(frame)
frame_image = Image.new('L', (display.width, display.height))
frame_image.paste(image.convert("L"), (display.width // 2 - image.width // 2,
display.height // 2 - image.height // 2))
display.image(frame_image, frame=frame)
Finally, we call the auto_play function using the delay and loop information from the animated gif.
display.autoplay(delay=delay, loops=loops)
Now go ahead and run the example code.
python3 is31fl3731_pillow_animated_gif.py adafruit-star-rotating.gif
You should see the rotating star appear on the display.
Page last edited January 22, 2025
Text editor powered by tinymce.
