Library Installation

You'll need to install the Adafruit CircuitPython EPD library on 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 libraries to use the hardware--carefully follow the steps to find and install these libraries from Adafruit's CircuitPython library bundle.  Our introduction guide has a great page on how to install the library bundle for both express and non-express boards.

You'll need to manually install the necessary libraries from the bundle:

  • adafruit_epd
  • adafruit_bus_device
  • adafruit_framebuf.mpy

Before continuing, make sure your board's lib folder or root filesystem has the library files and folders listed above copied over.

Next connect to the board's serial REPL so you are at the CircuitPython >>> prompt.

Adafruit EPD Bitmap Example

Here's the complete example of how to display a bitmap image on your display. Note that any .bmp image you want to display must be exactly 212 pixels by 104 pixels and 24-bit. We will be using the image below. Click the button below to download the image and save it as blinka.bmp on your CIRCUITPY drive.

Upload The Code

Copy and paste the code below into a new text document (we recommend using Mu as your editor, which is designed for CircuitPython). Save the file to the CIRCUITPY drive and name it as

# SPDX-FileCopyrightText: 2019 Noe Ruiz for Adafruit Industries
# SPDX-License-Identifier: MIT

import digitalio
import busio
import board
from adafruit_epd.epd import Adafruit_EPD
from adafruit_epd.il0373 import Adafruit_IL0373

# create the spi device and pins we will need
spi = busio.SPI(board.SCK, MOSI=board.MOSI, MISO=board.MISO)
ecs = digitalio.DigitalInOut(board.D9)
dc = digitalio.DigitalInOut(board.D10)
srcs = None
rst = None
busy = None

# give them all to our driver
print("Creating display")
display = Adafruit_IL0373(104, 212, spi,         # 2.13" Tri-color display
                          cs_pin=ecs, dc_pin=dc, sramcs_pin=srcs,
                          rst_pin=rst, busy_pin=busy)

display.rotation = 3

FILENAME = "blinka.bmp"

def read_le(s):
    # as of this writting, int.from_bytes does not have LE support, DIY!
    result = 0
    shift = 0
    for byte in bytearray(s):
        result += byte << shift
        shift += 8
    return result

class BMPError(Exception):

def display_bitmap(epd, filename):
    # pylint: disable=too-many-locals, too-many-branches
        f = open("/" + filename, "rb")
    except OSError:
        print("Couldn't open file")

    print("File opened")
        if != b'BM':  # check signature
            raise BMPError("Not BitMap file")

        bmpFileSize = read_le(  # Read & ignore creator bytes

        bmpImageoffset = read_le(  # Start of image data
        headerSize = read_le(
        bmpWidth = read_le(
        bmpHeight = read_le(
        flip = True

        print("Size: %d\nImage offset: %d\nHeader size: %d" %
              (bmpFileSize, bmpImageoffset, headerSize))
        print("Width: %d\nHeight: %d" % (bmpWidth, bmpHeight))

        if read_le( != 1:
            raise BMPError("Not singleplane")
        bmpDepth = read_le(  # bits per pixel
        print("Bit depth: %d" % (bmpDepth))
        if bmpDepth != 24:
            raise BMPError("Not 24-bit")
        if read_le( != 0:
            raise BMPError("Compressed file")

        print("Image OK! Drawing...")

        rowSize = (bmpWidth * 3 + 3) & ~3  # 32-bit line boundary

        for row in range(bmpHeight):  # For each scanline...
            if flip:  # Bitmap is stored bottom-to-top order (normal BMP)
                pos = bmpImageoffset + (bmpHeight - 1 - row) * rowSize
            else:  # Bitmap is stored top-to-bottom
                pos = bmpImageoffset + row * rowSize

            # print ("seek to %d" % pos)
            rowdata =*bmpWidth)
            for col in range(bmpWidth):
                b, g, r = rowdata[3*col:3*col+3]  # BMP files store RGB in BGR
                if r < 0x80 and g < 0x80 and b < 0x80:
                    epd.pixel(col, row, Adafruit_EPD.BLACK)
                elif r >= 0x80 and g >= 0x80 and b >= 0x80:
                    pass  # epd.pixel(row, col, Adafruit_EPD.WHITE)
                elif r >= 0x80:
                    epd.pixel(col, row, Adafruit_EPD.RED)
    except OSError:
        print("Couldn't read file")
    except BMPError as e:
        print("Failed to parse BMP: " + e.args[0])
    print("Finished drawing")

# clear the buffer
display_bitmap(display, FILENAME)


Reference the screenshot image for the files and folders that should be on your CIRCUITPY drive.

This guide was first published on Apr 03, 2019. It was last updated on Sep 26, 2023.

This page (CircuitPython Code) was last updated on Sep 25, 2023.

Text editor powered by tinymce.