CircuitPython Usage

Save Subscribe
Check carefully to make sure you are running the right example and creating the matching library type for your display or you won't see anything happen on the EPD (or the image may be really weird looking).

CircuitPython eInk displayio Library Installation

To use displayio, you will need to install the appropriate library for your display. 

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

Next you'll need to install the necessary libraries to use the hardware--carefully follow the steps to find and install these libraries from Adafruit's CircuitPython library bundle.  The introduction guide has a great page on how to install the library bundle for both Express and non-Express boards.

You will need to copy the appropriate displayio driver from the bundle lib folder to a lib folder on your CIRCUITPY drive. The displayio driver contains the initialization codes specific to your display that are needed to for it to work. Since there is more than one driver, you will need to copy the correct file over. Here is a list of each of the displays and the correct driver for that display.

To use the eInk displays with displayio, you will need to use the latest version of CircuitPython and a board that can fit `displayio`. See the Support Matrix to determine if `displayio` is available on a given board: https://circuitpython.readthedocs.io/en/latest/shared-bindings/support_matrix.html

Adafruit_CircuitPython_IL91874

The EYESPI version of the 2.7" eInk Display uses the EK79686 chipset. The non-EYESPI version uses the IL91874.

The 2.7" Tri-Color shield and older 2.7" Tri-Color breakout (without the EYESPI connector) use the Adafruit_CircuitPython_IL91874 library. To easily get all the required files and libraries, you can click the Download Project Bundle link at the top of the appropriate example code below. Just unzip, open the folder that corresponds to the version of CircuitPython you have installed, and copy the contents to the CIRCUITPY drive.

Top down view of a Adafruit 2.7" Tri-Color eInk / ePaper Shield with SRAM - Red Black White.
Easy e-paper finally comes to microcontrollers, with this breakout that's designed to make it a breeze to add a tri-color eInk display. Chances are you've seen one of those...
Out of Stock
Out of Stock

Adafruit_CircuitPython_EK79686

The newer 2.7" Tri-Color Display breakout (with the EYESPI connector) use the Adafruit_CircuitPython_EK79686 library. To easily get all the required files and libraries, you can click the Download Project Bundle link at the top of the appropriate example code below. Just unzip, open the folder that corresponds to the version of CircuitPython you have installed, and copy the contents to the CIRCUITPY drive.

Angled shot of a Adafruit 2.7" Tri-Color eInk / ePaper Display with SRAM - Red Black White.
Easy e-paper finally comes to microcontrollers, with this breakout that's designed to make it a breeze to add a tri-color eInk display. Chances are you've seen one of those...
Out of Stock
Out of Stock

Image File

To show you how to use the eInk with displayio, below shows you how to draw a bitmap onto it. First start by downloading display-ruler.bmp

Copy display-ruler.bmp into the root directory of your CIRCUITPY drive.

Tri-Color Display Usage

2.7" 264x176 HD Tri-Color Breakout with EYESPI

In the examples folder for your EK79686 displayio driver, there should be a test for your display which we have listed here:

Download Project Bundle
Copy Code 
# SPDX-FileCopyrightText: 2017 Scott Shawcroft, written for Adafruit Industries
# SPDX-FileCopyrightText: Copyright (c) 2023 Melissa LeBlanc-Williams for Adafruit Industries
#
# SPDX-License-Identifier: Unlicense
"""
  Simple test script for 2.7" 264x176 Tri-Color display
  Supported products:
  * `Adafruit 2.7" Tri-Color eInk / ePaper Display
  with SRAM <https://www.adafruit.com/product/4098>`_

  This program only requires the adafruit_ek79686 library in /lib
  for CircuitPython 5.0 and above which has displayio support.
"""

import time
import board
import displayio
import adafruit_ek79686

# Used to ensure the display is free in CircuitPython
displayio.release_displays()

# Define the pins needed for display use on the Metro
spi = board.SPI()
epd_cs = board.D10
epd_dc = board.D9
epd_reset = board.D5
epd_busy = board.D6

# Create the displayio connection to the display pins
display_bus = displayio.FourWire(
    spi, command=epd_dc, chip_select=epd_cs, reset=epd_reset, baudrate=1000000
)
time.sleep(1)  # Wait a bit

# Create the display object - the third color is red (0xff0000)
display = adafruit_ek79686.EK79686(
    display_bus,
    width=264,
    height=176,
    busy_pin=epd_busy,
    highlight_color=0xFF0000,
    rotation=90,
)

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


# Display a ruler graphic from the root directory of the CIRCUITPY drive
with open("/display-ruler.bmp", "rb") as f:
    pic = displayio.OnDiskBitmap(f)
    # Create a Tilegrid with the bitmap and put in the displayio group
    # CircuitPython 6 & 7 compatible
    t = displayio.TileGrid(
        pic, pixel_shader=getattr(pic, "pixel_shader", displayio.ColorConverter())
    )
    # CircuitPython 7 compatible only
    # t = displayio.TileGrid(pic, pixel_shader=pic.pixel_shader)
    g.append(t)

    # Place the display group on the screen (does not refresh)
    display.show(g)

    # Show the image on the display
    display.refresh()

    print("refreshed")

    # Do Not refresh the screen more often than every 180 seconds
    #   for eInk displays! Rapid refreshes will damage the panel.
    time.sleep(180)
View on GitHub

2.7" 264x176 HD Tri-Color Shield and non-EYESPI Breakout

In the examples folder for your IL91874 displayio driver, there should be a test for your display which we have listed here:

Download Project Bundle
Copy Code 
# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT

"""
  Simple test script for 2.7" 264x176 Tri-Color display shield
  Supported products:
  * Adafruit 2.7" Tri-Color ePaper Display Shield
    https://www.adafruit.com/product/4229

  This program only requires the adafruit_il91874 library in /lib
  for CircuitPython 5.0 and above which has displayio support.
"""

import time
import board
import displayio
import adafruit_il91874

# Used to ensure the display is free in CircuitPython
displayio.release_displays()

# Define the pins needed for display use on the Metro
spi = board.SPI()
epd_cs = board.D10
epd_dc = board.D9
epd_reset = board.D5
epd_busy = board.D6

# Create the displayio connection to the display pins
display_bus = displayio.FourWire(
    spi, command=epd_dc, chip_select=epd_cs, reset=epd_reset, baudrate=1000000
)
time.sleep(1)  # Wait a bit

# Create the display object - the third color is red (0xff0000)
display = adafruit_il91874.IL91874(
    display_bus,
    width=264,
    height=176,
    busy_pin=epd_busy,
    highlight_color=0xFF0000,
    rotation=90,
)

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

# Display a ruler graphic from the root directory of the CIRCUITPY drive
with open("/display-ruler.bmp", "rb") as f:
    pic = displayio.OnDiskBitmap(f)
    # Create a Tilegrid with the bitmap and put in the displayio group
    # CircuitPython 6 & 7 compatible
    t = displayio.TileGrid(
        pic, pixel_shader=getattr(pic, "pixel_shader", displayio.ColorConverter())
    )
    # CircuitPython 7 compatible only
    # t = displayio.TileGrid(pic, pixel_shader=pic.pixel_shader)
    g.append(t)

    # Place the display group on the screen (does not refresh)
    display.root_group = g

    # Show the image on the display
    display.refresh()

    print("refreshed")

    # Do Not refresh the screen more often than every 180 seconds
    #   for eInk displays! Rapid refreshes will damage the panel.
    time.sleep(180)
View on GitHub

Update the Settings

In either example, you will want to double-check your settings.

For the breakout, you will want to change the epd_reset and epd_busy to the correct values. If you wired it up as shown on the Wiring page, you will want to change it to these values:

Download File
Copy Code 
epd_reset = board.D8
epd_busy = board.D7

For the shield, you will want to change both of these values to None:

Download File
Copy Code 
epd_reset = None
epd_busy = None

The rotation of the breakout is 180 degrees different from the shield, so you may want to change the rotation value from 90 to 270:

Download File
Copy Code 
rotation=270

Save it to your CIRCUITPY drive as code.py and it should automatically run. Your display will look something like this:

raspberry_pi_IMG_4239.jpeg
 Arduino Bitmaps Python Setup 

This guide was first published on May 17, 2022. It was last updated on Dec 08, 2023.

This page (CircuitPython Usage) was last updated on Dec 08, 2023.

Text editor powered by tinymce.