Using the Pixel Framebuf library is easy. The most complicated part of it is the initialization, because it can vary so widely with each specific setup, so start with that and then go over each of the functions available to you.


For initialization, we'll go over the different options and what the specific parameters mean so you can best determine which options to change for your setup.

  • pixels - (required) The NeoPixels or DotStars object that you initialized
  • width - (required) The width of the framebuf in pixels.
  • height - (required) The height of the framebuf in pixels.
  • orientation - The direction that the pixels are physically laid out in either columns or rows. The value is HORIZONTAL by default and you will need to import VERTICAL if you want to set the value to VERTICAL.

  • alternating - If the pixels zigzag, you will want to set this to True. If they are laid out in the same direction, you will want to set this to False. The default value is True.

  • reverse_x - Set this to True if you want to reverse the direction of all pixels horizontally.

  • reverse_y - Set this to True if you want to reverse the direction of all pixels vertically.

  • top - An optional tuple representing the top left pixel.

  • bottom - An optional tuple representing the bottom right pixel.

  • rotation - A value between 0 and 3 representing the initial rotation of the Framebuffer. This can also be set later with the rotation property.

Example Initializations

Here are the initializations for a few of the panels we have available. In these examples, it is assumed that you have done the necessary imports and setup as described on the Import and Setup page and that your NeoPixels or DotStars are named pixels.

32x8 Panel

pixel_framebuf = PixelFramebuffer(

16x16 Panel

pixel_framebuf = PixelFramebuffer(

NeoPixel FeatherWing

pixel_framebuf = PixelFramebuffer(

DotStar FeatherWing

pixel_framebuf = PixelFramebuffer(

Drawing Functions

All drawing functions are based on coordinates starting from the upper left-hand side as the starting point.

The display will need to be initialized prior to being able to use any of the drawing functions below.

Displaying the Framebuffer

Each time you want to display the current Framebuffer, you will need to call the display() function. This function takes no parameters and displays whatever is currently in memory.  We will show you how to use it in each of the drawing function example code snippets.


To fill in the entire Framebuffer with a specific color, you can use the fill() function. For instance, to fill it with Blue (0x0000FF), you would use the following command:


To turn all the pixels off, you can set them to 0x000000.


Pixel Drawing

To draw a pixel, you just need to use the pixel() function and provide the coordinates and color. For instance, if you wanted to draw a set the pixel at (4, 6) to red, you would use the following command:

pixel_framebuf.pixel(4, 6, 0xFF0000)

If you wanted to get the pixel's value, you would retrieve it like this:

color = pixel_framebuf.pixel(4, 6)

Line Drawing

To draw a line, you just need to to use the line() function and provide the starting coordinates, ending coordinates, and color. For instance, if you wanted to draw a line from (0, 0) to (7, 9) in red (0xFF0000), you would use the following command:

pixel_framebuf.line(0, 0, 7, 9, 0xFF0000)

Horizontal and Vertical Line Drawing

To draw horizontal or vertical, you can use the hline() and vline() functions. These are optimized for fast drawing because they don't need to calculate a slope. You just need to pass the x and y coordinates along with the length of the line in pixels and the color you wish to draw.

To use these functions, to draw a 5 pixel red line starting at (2, 3), you would use the following:

pixel_framebuf.hline(2, 3, 5, 0xFF0000)
pixel_framebuf.vline(2, 3, 5, 0xFF0000)

Rectangle Drawing

To draw a non-filled Rectangle, you will want to use the rect() function. You provide it starting coordinates, width, height, and line color. To draw a red rectangle at (2, 2) with a width of 8 and a height of 12, you would use:

pixel_framebuf.rect(2, 2, 8, 12, 0xFF0000)

To draw a filled rectangle, you would do the same thing with the fill_rect() function:

pixel_framebuf.fill_rect(2, 2, 8, 12, 0xFF0000)

Text Drawing

To draw text, you would use the text() function, provide the string, upper left coordinates of the text, and the color. For instance, to draw "Hi" at (3, 4) in green (0x00FF00), you would use the following:

pixel_framebuf.text("Hi", 3, 4, 0x00FF00)

Text can go off the screen and simply redrawing the text in different positions on top of the same background can produce an animated text effect.

This guide was first published on Sep 22, 2020. It was last updated on May 22, 2024.

This page (Usage) was last updated on Mar 08, 2024.

Text editor powered by tinymce.