Introduction¶
CircuitPython driver for the IS31FL3731 charlieplex IC.
This driver supports the following hardware:
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.
Installing from PyPI¶
On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally from PyPI. To install for current user:
pip3 install adafruit-circuitpython-is31fl3731
To install system-wide (this may be required in some cases):
sudo pip3 install adafruit-circuitpython-is31fl3731
To install in a virtual environment in your current project:
mkdir project-name && cd project-name
python3 -m venv .env
source .env/bin/activate
pip3 install adafruit-circuitpython-is31fl3731
Usage Example¶
Matrix:
from adafruit_is31fl3731.matrix import Matrix
import board
import busio
with busio.I2C(board.SCL, board.SDA) as i2c:
display = Matrix(i2c)
display.fill(127)
Charlie Wing:
from adafruit_is31fl3731.charlie_wing import CharlieWing
import board
import busio
with busio.I2C(board.SCL, board.SDA) as i2c:
display = CharlieWing(i2c)
display.fill(127)
# Turn off pixel 4,4, change its brightness and turn it back on
display.pixel(4, 4, 0) # Turn off.
display.pixel(4, 4, 50) # Low brightness (50)
display.pixel(4, 4, 192) # Higher brightness (192)
Contributing¶
Contributions are welcome! Please read our Code of Conduct before contributing to help this project stay welcoming.
Documentation¶
For information on building library documentation, please check out this guide.
Table of Contents¶
Simple test¶
Ensure your device works with this simple test.
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 | # SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT
import board
import busio
# uncomment next line if you are using Feather CharlieWing LED 15 x 7
from adafruit_is31fl3731.charlie_wing import CharlieWing as Display
# 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
# uncomment next line if you are using Pimoroni 11x7 LED Matrix Breakout
# from adafruit_is31fl3731.matrix_11x7 import Matrix11x7 as Display
# uncomment this line if you use a Pico, here with SCL=GP21 and SDA=GP20.
# i2c = busio.I2C(board.GP21, board.GP20)
i2c = busio.I2C(board.SCL, board.SDA)
display = Display(i2c)
# draw a box on the display
# first draw the top and bottom edges
for x in range(display.width):
display.pixel(x, 0, 50)
display.pixel(x, display.height - 1, 50)
# now draw the left and right edges
for y in range(display.height):
display.pixel(0, y, 50)
display.pixel(display.width - 1, y, 50)
|
Matrix Examples¶
Other examples working on matrix display.
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 | # SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT
import board
import busio
# uncomment next line if you are using Feather CharlieWing LED 15 x 7
from adafruit_is31fl3731.charlie_wing import CharlieWing as Display
# 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
# uncomment next line if you are using Pimoroni 11x7 LED Matrix Breakout
# from adafruit_is31fl3731.matrix_11x7 import Matrix11x7 as Display
# uncomment this line if you use a Pico, here with SCL=GP21 and SDA=GP20.
# i2c = busio.I2C(board.GP21, board.GP20)
i2c = busio.I2C(board.SCL, board.SDA)
# array pattern in bits; top row-> bottom row, 8 bits in each row
an_arrow = bytearray((0x08, 0x0C, 0xFE, 0xFF, 0xFE, 0x0C, 0x08, 0x00, 0x00))
display = Display(i2c)
offset = (display.width - 8) // 2
# first load the frame with the arrows; moves the an_arrow to the right in each
# frame
display.sleep(True) # turn display off while updating blink bits
display.fill(0)
for y in range(display.height):
row = an_arrow[y]
for x in range(8):
bit = 1 << (7 - x) & row
if bit:
display.pixel(x + offset, y, 50, blink=True)
display.blink(1000) # ranges from 270 to 2159; smaller the number to faster blink
display.sleep(False) # turn display on
|
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 | # SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT
import time
import board
import busio
# uncomment next line if you are using Feather CharlieWing LED 15 x 7
from adafruit_is31fl3731.charlie_wing import CharlieWing as Display
# 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
# uncomment next line if you are using Pimoroni 11x7 LED Matrix Breakout
# from adafruit_is31fl3731.matrix_11x7 import Matrix11x7 as Display
# uncomment this line if you use a Pico, here with SCL=GP21 and SDA=GP20.
# i2c = busio.I2C(board.GP21, board.GP20)
i2c = busio.I2C(board.SCL, board.SDA)
# arrow pattern in bits; top row-> bottom row, 8 bits in each row
arrow = bytearray((0x08, 0x0C, 0xFE, 0xFF, 0xFE, 0x0C, 0x08, 0x00, 0x00))
display = Display(i2c)
# first load the frame with the arrows; moves the arrow to the right in each
# frame
display.sleep(True) # turn display off while frames are updated
for frame in range(display.width - 8):
display.frame(frame, show=False)
display.fill(0)
for y in range(display.height):
row = arrow[y]
for x in range(8):
bit = 1 << (7 - x) & row
# display the pixel into selected frame with varying intensity
if bit:
display.pixel(x + frame, y, frame ** 2 + 1)
display.sleep(False)
# now tell the display to show the frame one at time
while True:
for frame in range(8):
display.frame(frame)
time.sleep(0.1)
|
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 49 50 51 52 53 54 55 56 57 58 59 | # SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT
import board
import busio
import adafruit_framebuf
# uncomment next line if you are using Feather CharlieWing LED 15 x 7
# from adafruit_is31fl3731.charlie_wing import CharlieWing as Display
# 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
# uncomment next line if you are using Pimoroni 11x7 LED Matrix Breakout
# from adafruit_is31fl3731.matrix_11x7 import Matrix11x7 as Display
# uncomment this line if you use a Pico, here with SCL=GP21 and SDA=GP20.
# i2c = busio.I2C(board.GP21, board.GP20)
i2c = busio.I2C(board.SCL, board.SDA)
display = Display(i2c)
text_to_show = "Adafruit!!"
# Create a framebuffer for our display
buf = bytearray(32) # 2 bytes tall x 16 wide = 32 bytes (9 bits is 2 bytes)
fb = adafruit_framebuf.FrameBuffer(
buf, display.width, display.height, adafruit_framebuf.MVLSB
)
frame = 0 # start with frame 0
while True:
for i in range(len(text_to_show) * 9):
fb.fill(0)
fb.text(text_to_show, -i + display.width, 0, color=1)
# to improve the display flicker we can use two frame
# fill the next frame with scrolling text, then
# show it.
display.frame(frame, show=False)
# turn all LEDs off
display.fill(0)
for x in range(display.width):
# using the FrameBuffer text result
bite = buf[x]
for y in range(display.height):
bit = 1 << y & bite
# if bit > 0 then set the pixel brightness
if bit:
display.pixel(x, y, 50)
# now that the frame is filled, show it.
display.frame(frame, show=True)
frame = 0 if frame else 1
|
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 | # SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT
import board
import busio
# uncomment next line if you are using Feather CharlieWing LED 15 x 7
from adafruit_is31fl3731.charlie_wing import CharlieWing as Display
# 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
# uncomment next line if you are using Pimoroni 11x7 LED Matrix Breakout
# from adafruit_is31fl3731.matrix_11x7 import Matrix11x7 as Display
# uncomment this line if you use a Pico, here with SCL=GP21 and SDA=GP20.
# i2c = busio.I2C(board.GP21, board.GP20)
i2c = busio.I2C(board.SCL, board.SDA)
# fmt: off
sweep = [ 1, 2, 3, 4, 6, 8, 10, 15, 20, 30, 40, 60,
60, 40, 30, 20, 15, 10, 8, 6, 4, 3, 2, 1, ]
# fmt: on
frame = 0
display = Display(i2c)
while True:
for incr in range(24):
# to reduce update flicker, use two frames
# make a frame active, don't show it yet
display.frame(frame, show=False)
# fill the display with the next frame
for x in range(display.width):
for y in range(display.height):
display.pixel(x, y, sweep[(x + y + incr) % 24])
# show the next frame
display.frame(frame, show=True)
if frame:
frame = 0
else:
frame = 1
|
Pillow Examples¶
Examples that utilize the Python Imaging Library (Pillow) 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)!
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 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 | # SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT
"""
Example to extract the frames and other parameters from an animated gif
and then run the animation on the display.
Usage:
python3 is31fl3731_pillow_animated_gif.py animated.gif
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 sys
import board
from PIL import Image
# 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
i2c = board.I2C()
display = Display(i2c)
# Open the gif
if len(sys.argv) < 2:
print("No image file specified")
print("Usage: python3 is31fl3731_pillow_animated_gif.py animated.gif")
sys.exit()
image = Image.open(sys.argv[1])
# Make sure it's animated
if not image.is_animated:
print("Specified image is not animated")
sys.exit()
# Get the autoplay information from the gif
delay = image.info["duration"]
# Figure out the correct loop count
if "loop" in image.info:
loops = image.info["loop"]
if loops > 0:
loops += 1
else:
loops = 1
# 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
# 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)
display.autoplay(delay=delay, loops=loops)
|
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 49 50 51 52 | # 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()
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)
|
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 | # SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT
"""
Example to utilize the Python Imaging Library (Pillow) and draw bitmapped text
to 8 frames and then run autoplay on those frames.
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
BRIGHTNESS = 32 # Brightness can be between 0-255
i2c = board.I2C()
display = Display(i2c)
display.fill(0)
# 256 Color Grayscale Mode
image = Image.new("L", (display.width, display.height))
draw = ImageDraw.Draw(image)
# Load a font in 2 different sizes.
font = ImageFont.truetype("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf", 10)
# Load the text in each frame
for x in range(8):
draw.rectangle((0, 0, display.width, display.height), outline=0, fill=0)
draw.text((x + 1, -2), str(x + 1), font=font, fill=BRIGHTNESS)
display.image(image, frame=x)
display.autoplay(delay=500)
|
Led Shim Example¶
Example that work on the RGB Led Shim.
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 | # SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT
import time
import board
import busio
from adafruit_is31fl3731.led_shim import LedShim as Display
i2c = busio.I2C(board.SCL, board.SDA)
# initial display if you are using Pimoroni LED SHIM
display = Display(i2c)
# fmt: off
# This list 28 colors from a rainbow...
rainbow = [
(255, 0, 0), (255, 54, 0), (255, 109, 0), (255, 163, 0),
(255, 218, 0), (236, 255, 0), (182, 255, 0), (127, 255, 0),
(72, 255, 0), (18, 255, 0), (0, 255, 36), (0, 255, 91),
(0, 255, 145), (0, 255, 200), (0, 255, 255), (0, 200, 255),
(0, 145, 255), (0, 91, 255), (0, 36, 255), (18, 0, 255),
(72, 0, 255), (127, 0, 255), (182, 0, 255), (236, 0, 255),
(255, 0, 218), (255, 0, 163), (255, 0, 109), (255, 0, 54),
]
# fmt: on
for y in range(3):
for x in range(28):
display.pixel(x, y, 255)
time.sleep(0.1)
display.pixel(x, y, 0)
while True:
for offset in range(28):
for x in range(28):
r, g, b = rainbow[(x + offset) % 28]
display.pixelrgb(x, r, g, b)
|
adafruit_is31fl3731
¶
CircuitPython driver for the IS31FL3731 charlieplex IC.
Base library.
- Author(s): Tony DiCola, Melissa LeBlanc-Williams, David Glaude
Implementation Notes¶
Hardware:
- Adafruit 16x9 Charlieplexed PWM LED Matrix Driver - IS31FL3731
- Adafruit 15x7 CharliePlex LED Matrix Display FeatherWings
- Adafruit 16x8 CharliePlex LED Matrix Bonnets
- Pimoroni 17x7 Scroll pHAT HD
- Pimoroni 28x3 (r,g,b) Led Shim
- Pimoroni LED SHIM
- Pimoroni Keybow 2040
- Pimoroni 11x7 LED Matrix Breakout
Software and Dependencies:
- Adafruit CircuitPython firmware for the supported boards: https://github.com/adafruit/circuitpython/releases
-
class
adafruit_is31fl3731.
IS31FL3731
(i2c, address=116)[source]¶ The IS31FL3731 is an abstract class contain the main function related to this chip. Each board needs to define width, height and pixel_addr.
Parameters: - i2c_device (i2c_device) – the connected i2c bus i2c_device
- address – the device address; defaults to 0x74
-
audio_play
(sample_rate, audio_gain=0, agc_enable=False, agc_fast=False)[source]¶ Controls the audio play feature
-
autoplay
(delay=0, loops=0, frames=0)[source]¶ Start autoplay
Parameters: - delay – in ms
- loops – number of loops - 0->7
- frames – number of frames: 0->7
-
fade
(fade_in=None, fade_out=None, pause=0)[source]¶ Start and stop the fade feature. If both fade_in and fade_out are None (the default), the breath feature is used for fading. if fade_in is None, then fade_in = fade_out. If fade_out is None, then fade_out = fade_in
Parameters: - fade_in – positive number; 0->100
- fade-out – positive number; 0->100
- pause – breath register 2 pause value
-
fill
(color=None, blink=None, frame=None)[source]¶ Fill the display with a brightness level
Parameters: - color – brightness 0->255
- blink – True if blinking is required
- frame – which frame to fill 0->7
-
frame
(frame=None, show=True)[source]¶ Set the current frame
Parameters: - frame – frame number; 0-7 or None. If None function returns current frame
- show – True to show the frame; False to not show.
-
image
(img, blink=None, frame=None)[source]¶ Set buffer to value of Python Imaging Library image. The image should be in 8-bit mode (L) and a size equal to the display size.
Parameters: - img – Python Imaging Library image
- blink – True to blink
- frame – the frame to set the image
adafruit_is31fl3731.charlie_bonnet
¶
CircuitPython driver for the IS31FL3731 charlieplex IC.
- Author(s): Tony DiCola, Melissa LeBlanc-Williams
Implementation Notes¶
Hardware:
Software and Dependencies:
- Adafruit CircuitPython firmware for the supported boards: https://github.com/adafruit/circuitpython/releases
adafruit_is31fl3731.charlie_wing
¶
CircuitPython driver for the IS31FL3731 charlieplex IC.
- Author(s): Tony DiCola, Melissa LeBlanc-Williams
Implementation Notes¶
Hardware:
Software and Dependencies:
- Adafruit CircuitPython firmware for the supported boards: https://github.com/adafruit/circuitpython/releases
adafruit_is31fl3731.matrix
¶
CircuitPython driver for the IS31FL3731 charlieplex IC.
- Author(s): Tony DiCola, Melissa LeBlanc-Williams
Implementation Notes¶
Hardware:
Software and Dependencies:
- Adafruit CircuitPython firmware for the supported boards: https://github.com/adafruit/circuitpython/releases
adafruit_is31fl3731.scroll_phat_hd
¶
CircuitPython driver for the Pimoroni 17x7 Scroll pHAT HD.
- Author: David Glaude
Implementation Notes¶
Hardware:
Software and Dependencies:
- Adafruit CircuitPython firmware for the supported boards: https://github.com/adafruit/circuitpython/releases
adafruit_is31fl3731.led_shim
¶
CircuitPython driver for the IS31FL3731 charlieplex IC.
- Author: David Glaude
Implementation Notes¶
Hardware:
Software and Dependencies:
- Adafruit CircuitPython firmware for the supported boards: https://github.com/adafruit/circuitpython/releases