The Pixel Framebuf library is designed to make adding text and graphics super simple. It is built on top of the very capable LED Animation and framebuf libraries and because of the flexibility provided by those libraries, it works on a wide variety of NeoPixel and DotMatrix displays and layouts.

CircuitPython Setup

To get the required libraries for this guide, download the latest CircuitPython library bundle from circuitpython.org.

Open the downloaded zip and find the following folder and files within the lib folder:

• adafruit_pixel_framebuf.mpy
• adafruit_framebuf.mpy
• adafruit_led_animation

If you are using NeoPixels, you will also need:

• neopixel.mpy

Or if you are using DotStar LEDs, you will need:

• adafruit_dotstar.mpy

Drag this folder and files to the lib folder on your CIRCUITPY drive.

Python Setup

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!

Run NeoPixels on the Raspberry Pi requires the sudo command, so you will need to make sure you have the necessary libraries installed using sudo pip3.

Since Pip does a great job of handling dependencies, there's only a few commands you will need to run to get this set up:

• sudo pip3 install adafruit-circuitpython-pixel-framebuf

If you are running NeoPixels, you will also need the NeoPixel library:

• sudo pip3 install adafruit-circuitpython-neopixel

If you are running DotStars, you will also need the DotStar library:

• sudo pip3 install adafruit-circuitpython-dotstar

You will also need the Pillow library if you want to make use of the image() function:

• sudo pip3 install Pillow

Raspberry Pi requires a hardware PWM pin to drive the NeoPixels. We recommend D18, so you will need to change that in the code below if you any place you see D6.

Font File

If you want to display text, you will also need to include the font file. This font is included in the adafruit_framebuf library examples.

Place the font file in the same folder as you code.

Import and Object Setup

This library should work with either NeoPixels or DotStar LEDs. We are going to start by showing you how to use them with NeoPixels.

NeoPixels

The first thing you will need to do to run this library is to import the necessary libraries. An example of import and setup for the NeoPixel FeatherWing is as follows:

import board
import neopixel
from adafruit_pixel_framebuf import PixelFramebuffer

pixel_pin = board.D6
pixel_width = 8
pixel_height = 4

pixels = neopixel.NeoPixel(
    pixel_pin,
    pixel_width * pixel_height,
    brightness=0.1,
    auto_write=False,
)

import board
import neopixel
from adafruit_pixel_framebuf import PixelFramebuffer

pixel_pin = board.D6
pixel_width = 8
pixel_height = 4

pixels = neopixel.NeoPixel(
    pixel_pin,
    pixel_width * pixel_height,
    brightness=0.1,
    auto_write=False,
)

First you import board and neopixel.  Next import the PixelFramebuffer module. On certain NeoPixel displays, you may also need to import VERTICAL as well, which we'll cover in the Initialization section.

Next you'll want to set a few convenience variables including the pixel_pin, which is the pin that the NeoPixel data line is connected to. The pixel_width and pixel_height are there to help make the code more readable and correspond to the number of pixels wide and number of pixels high.

Finally, create the pixel object. You'll want to make sure auto_write is set to False so you don't see every single time an individual pixel is changed, which can be quite slow.

This guide will use NeoPixels for all the examples, but the Pixel Framebuf library works equally well with DotStar LEDs.

DotStar LEDs

The only change you would need to make to use this library with DotStar LEDs would be to initialize the DotStar library instead of the NeoPixel library. An example of import and setup for the DotStar FeatherWing is as follows:

import board
import adafruit_dotstar
from adafruit_pixel_framebuf import PixelFramebuffer

pixel_pin = board.D6
pixel_width = 12
pixel_height = 6

pixels = adafruit_dotstar.DotStar(
    board.D13,
    board.D11,
    pixel_width * pixel_height,
    brightness=0.3,
    auto_write=False,
)

import board
import adafruit_dotstar
from adafruit_pixel_framebuf import PixelFramebuffer

pixel_pin = board.D6
pixel_width = 12
pixel_height = 6

pixels = adafruit_dotstar.DotStar(
    board.D13,
    board.D11,
    pixel_width * pixel_height,
    brightness=0.3,
    auto_write=False,
)

This example imports the necessary modules and assigns the appropriate pins and number of pixels to use 72 DotStar LEDs connected to D13 and D11.