It's super simple to get started with the Adafruit Circuit Playground E-Ink Gizmo and CIrcuitPython using the Adafruit CircuitPython Gizmo module and CircuitPython's built in displayio.

You will need a board capable of running CircuitPython such as the Circuit Playground Express or Circuit Playground Bluefruit. The Circuit Playground Classic will only run Arduino sketches.

The Circuit Playground Express, which has a SAMD21 chip, may not be able to run the full example due to memory constraints. This is why we recommend using the Circuit Playground Bluefruit.
Circuit Playground Bluefruit is our third board in the Circuit Playground series, another step towards a perfect introduction to electronics and programming. We've...
$24.95
In Stock
Circuit Playground Express is the next step towards a perfect introduction to electronics and programming. We've taken the original Circuit Playground Classic and...
$24.95
In Stock

Circuit Playground Express with displayio

If you have a Circuit Playground Express board, you will need a special build that includes displayio to use the TFT Gizmo. Be sure to download the latest one. You can find it here:

CircuitPython Gizmo Library Installation

To use this display with displayio, you'll need to install the two required libraries onto your CircuitPython board.

First, make sure you are running the latest version of Adafruit CircuitPython for your board.

Next, you'll need to install the necessary library to use the hardware Carefully follow the steps to find and install the library from Adafruit's CircuitPython library bundle. Our introduction guide has a great page on how to install the library bundle.

You'll want to copy the following files and folders to the lib folder on your CIRCUITPY drive:

  • adafruit_il0373.mpy
  • adafruit_gizmo

Before continuing make sure your board's lib folder has the adafruit_il0373.mpy and adafruit_gizmo file and folder copied over.

CircuitPython Code

This example uses a bitmap image. Download display_ruler.bmp below and save it to your CIRCUITPY drive.

import time
import displayio
from adafruit_gizmo import eink_gizmo

display = eink_gizmo.EInk_Gizmo()

# Create a display group for our screen objects
display_group = displayio.Group()

# Display a ruler graphic from the root directory of the CIRCUITPY drive
file = open("/display-ruler.bmp", "rb")

picture = displayio.OnDiskBitmap(file)
# Create a Tilegrid with the bitmap and put in the displayio group
sprite = displayio.TileGrid(picture, pixel_shader=displayio.ColorConverter())
display_group.append(sprite)

# Place the display group on the screen
display.show(display_group)

# Refresh the display to have it actually show the image
# NOTE: Do not refresh eInk displays sooner than 180 seconds
display.refresh()
print("refreshed")

time.sleep(180)

Let's take a look at the code!

We begin by importing time, displayio and the eink_gizmo helper.

Download: file
import time
import displayio
from adafruit_gizmo import eink_gizmo

Next, we initialize the helper, which takes care of all the e-ink Gizmo IL0373 driver initialization for us.

Download: file
display = eink_gizmo.EInk_Gizmo()

Then we create a group to which we can add objects, such as the bitmap we want to display.

Download: file
display_group = displayio.Group()

Next we open the bitmap file.

Download: file
file = open("/display-ruler.bmp", "rb")

Then we convert the bitmap file into an object that displayio can work with, create a TileGrid with the bitmap object in it, and add it to the group we created.

Download: file
picture = displayio.OnDiskBitmap(file)
sprite = displayio.TileGrid(picture, pixel_shader=displayio.ColorConverter())
display_group.append(sprite)

Last, we use show to prepare the image to be displayed, and refresh to update the screen with the image. "refreshed" is printed to the serial console. Finally, we include a 180 second sleep due to the constraints of the e-ink display hardware - you should not update it more often than 180 second intervals!

Download: file
display.show(display_group)
display.refresh()
print("refreshed")
time.sleep(180)

After 180 seconds, the image will stop being displayed and you will see the latest serial output displayed. That's all there is to displaying a bitmap on the Circuit Playground E-Ink Gizmo with CircuitPython!

Further Information

Be sure to check out this excellent guide to CircuitPython Display Support Using displayio

This guide was first published on Dec 03, 2019. It was last updated on Dec 03, 2019.

This page (CircuitPython) was last updated on Nov 06, 2020.