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.

shot of a Black woman's neon-green manicured hand holding up a Circuit Playground Bluefruit glowing rainbow LEDs.

Circuit Playground Bluefruit - Bluetooth Low Energy

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

Add to Cart

A Black woman's manicured hand holds a round microcontroller with lit up LEDs.

Circuit Playground Express

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

Add to Cart

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 for Circuit Playground Express with displayio

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_ssd1681.mpy
adafruit_gizmo

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

CircuitPython Code

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

Download display-ruler.bmp

Download Project Bundle

Copy Code

# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT

import time
import displayio
from adafruit_gizmo import eink_gizmo

display = eink_gizmo.EInk_Gizmo()
# Use the below line instead for the 200x200 E-Ink Gizmo
# display = eink_gizmo.EInk_HD_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
with open("/display-ruler.bmp", "rb") as file:
    picture = displayio.OnDiskBitmap(file)
    # Create a Tilegrid with the bitmap and put in the displayio group
    # CircuitPython 6 & 7 compatible
    sprite = displayio.TileGrid(
        picture,
        pixel_shader=getattr(picture, "pixel_shader", displayio.ColorConverter()),
    )
    # CircuitPython 7 compatible only
    # sprite = displayio.TileGrid(picture, pixel_shader=bitmap.pixel_shader)
    display_group.append(sprite)

    # Place the display group on the screen
    display.root_group = 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)

# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT

import time
import displayio
from adafruit_gizmo import eink_gizmo

display = eink_gizmo.EInk_Gizmo()
# Use the below line instead for the 200x200 E-Ink Gizmo
# display = eink_gizmo.EInk_HD_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
with open("/display-ruler.bmp", "rb") as file:
    picture = displayio.OnDiskBitmap(file)
    # Create a Tilegrid with the bitmap and put in the displayio group
    # CircuitPython 6 & 7 compatible
    sprite = displayio.TileGrid(
        picture,
        pixel_shader=getattr(picture, "pixel_shader", displayio.ColorConverter()),
    )
    # CircuitPython 7 compatible only
    # sprite = displayio.TileGrid(picture, pixel_shader=bitmap.pixel_shader)
    display_group.append(sprite)

    # Place the display group on the screen
    display.root_group = 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

Copy Code

import time
import displayio
from adafruit_gizmo import eink_gizmo

import time
import displayio
from adafruit_gizmo import eink_gizmo

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

Download File

Copy Code

display = eink_gizmo.EInk_Gizmo()

display = eink_gizmo.EInk_Gizmo()

If you have the 200x200 e-Ink Gizmo, you would instead create an EInk_HD_Gizmo() object, which takes care of the new HD e-ink Gizmo SSD1681 driver initialization:

Download File

Copy Code

display = eink_gizmo.EInk_HD_Gizmo()

display = eink_gizmo.EInk_HD_Gizmo()

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

Download File

Copy Code

display_group = displayio.Group()

display_group = displayio.Group()

Next we open the bitmap file.

Download File

Copy Code

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

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

Copy Code

picture = displayio.OnDiskBitmap(file)
sprite = displayio.TileGrid(picture, pixel_shader=getattr(picture, "pixel_shader", displayio.ColorConverter()))
display_group.append(sprite)

picture = displayio.OnDiskBitmap(file)
sprite = displayio.TileGrid(picture, pixel_shader=getattr(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

Copy Code

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

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!