This example displays text on the eInk display, the "Hello World" for eInk so to speak. Text can be placed anywhere and scaled larger.
Code
The code below will use the internal terminalio font to display a single line of text on the eInk display. You can set the foreground and background color. See the comments for how each step contributes to the process.
Please select the code specific to your display and microcontroller as the two code blocks below are not interchangeable for both sets of hardware. The examples are nearly identical though.
2.13" eInk FeatherWing Example
The pins reflect the combination of the FeatherWing eInk display and a Feather M4. It also has the pixel dimensions for the 2.13" display.
# SPDX-FileCopyrightText: 2019 Anne Barela for Adafruit Industries
#
# SPDX-License-Identifier: MIT
"""
Simple text script for Adafruit 2.13" 212x104 tri-color display
Supported products:
* Adafruit 2.13" Tri-Color Display Breakout
* Adafruit 2.13" Tri-Color Display FeatherWing
https://www.adafruit.com/product/4086 (breakout) or
https://www.adafruit.com/product/4128 (FeatherWing)
This program requires the adafruit_il0373 library and the
adafruit_display_text library in the CIRCUITPY /lib folder
for CircuitPython 5.0 and above which has displayio support.
"""
import time
import board
import displayio
import adafruit_il0373
import terminalio
from adafruit_display_text import label
BLACK = 0x000000
WHITE = 0xFFFFFF
RED = 0xFF0000
# Change text colors, choose from the following values:
# BLACK, RED, WHITE
FOREGROUND_COLOR = RED
BACKGROUND_COLOR = WHITE
# Used to ensure the display is free in CircuitPython
displayio.release_displays()
# Define the pins needed for display use
# This pinout is for a Feather M4 and may be different for other boards
spi = board.SPI() # Uses SCK and MOSI
epd_cs = board.D9
epd_dc = board.D10
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_WIDTH = 212
DISPLAY_HEIGHT = 104
display = adafruit_il0373.IL0373(display_bus, width=DISPLAY_WIDTH,
height=DISPLAY_HEIGHT,
rotation=90, busy_pin=epd_busy,
highlight_color=0xff0000)
# Create a display group for our screen objects
g = displayio.Group()
# Set a background
background_bitmap = displayio.Bitmap(DISPLAY_WIDTH, DISPLAY_HEIGHT, 1)
# Map colors in a palette
palette = displayio.Palette(1)
palette[0] = BACKGROUND_COLOR
# Create a Tilegrid with the background and put in the displayio group
t = displayio.TileGrid(background_bitmap, pixel_shader=palette)
g.append(t)
# Draw simple text using the built-in font into a displayio group
text_group = displayio.Group(scale=2, x=20, y=40)
text = "Hello World!"
text_area = label.Label(terminalio.FONT, text=text, color=FOREGROUND_COLOR)
text_group.append(text_area) # Add this text to the text group
g.append(text_group)
# Place the display group on the screen
display.show(g)
# Refresh the display to have everything show on the display
# NOTE: Do not refresh eInk displays more often than 180 seconds!
display.refresh()
time.sleep(120)
while True:
pass
2.7" eInk Shield Example
The pins reflect the combination of the shield eInk display and a Metro M4. It also has the pixel dimensions of the 2.7" display.
# SPDX-FileCopyrightText: 2019 Anne Barela for Adafruit Industries
#
# SPDX-License-Identifier: MIT
"""
Simple text 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 requires the adafruit_il91874 and the
adafruit_display_text library in /lib on the CIRCUITPY drive
for CircuitPython 5.0 and above which has displayio support.
"""
import time
import board
import displayio
import adafruit_il91874
import terminalio
from adafruit_display_text import label
BLACK = 0x000000
WHITE = 0xFFFFFF
RED = 0xFF0000
# Change text colors, choose from the following values:
# BLACK, WHITE, RED (note red on this display is not vivid)
FOREGROUND_COLOR = BLACK
BACKGROUND_COLOR = WHITE
# 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
# Create the displayio connection to the display pins
display_bus = displayio.FourWire(spi, command=epd_dc, chip_select=epd_cs,
baudrate=1000000)
time.sleep(1) # Wait a bit
# Create the display object - the third color is red (0xff0000)
DISPLAY_WIDTH = 264
DISPLAY_HEIGHT = 176
# Create the display object - the third color is red (0xff0000)
display = adafruit_il91874.IL91874(display_bus, width=DISPLAY_WIDTH,
height=DISPLAY_HEIGHT,
highlight_color=0xff0000, rotation=90)
# Create a display group for our screen objects
g = displayio.Group()
# Set a white background
background_bitmap = displayio.Bitmap(DISPLAY_WIDTH, DISPLAY_HEIGHT, 1)
# Map colors in a palette
palette = displayio.Palette(1)
palette[0] = BACKGROUND_COLOR
# Create a Tilegrid with the background and put in the displayio group
t = displayio.TileGrid(background_bitmap, pixel_shader=palette)
g.append(t)
# Draw simple text using the built-in font into a displayio group
text_group = displayio.Group(scale=2, x=40, y=40)
text = "Hello World!"
text_area = label.Label(terminalio.FONT, text=text, color=FOREGROUND_COLOR)
text_group.append(text_area) # Add this text to the text group
g.append(text_group)
# Place the display group on the screen
display.show(g)
# Refresh the display to have everything show on the display
# NOTE: Do not refresh eInk displays more often than 180 seconds!
display.refresh()
time.sleep(180)
while True:
pass
Code Review
For an overview of using displayio for displays with CircuitPython, the excellent guide CircuitPython Display Support Using displayio is your first stop. If you would like a deeper dive into the model used for displays, refer to this guide.
Adafruit suggests using the displayio.release_displays() function before looking to execute additional code to ensure displays connected to the hardware are released by CircuitPython.
Next is to let displayio know which pins are used on the display. The specific pins used are very display dependent, it is suggested the guide on the display be referred to for known a known, working configuration prior to looking to change things up. displayio.FourWire sets up the displayio connection to the display bus.
With the bus, the program establishes the connection to the display driver adafruit_il0373. The size of the display (width and height), the orientation (rotation), busy pin, and the highlight color are given. For this tri-color display, red (0xff0000) is specified.
The rest of the code follows the standard displayio display setup and use:
- Create a display group
- Set the desired background color as a bitmap
- Create a TileGrid to put objects in with the bitmap and append the tile group to the display group
- Add a display group item for text and use "Hello World!" as the sample text. Text is scaled by two in size and located at
x=40,y=40to move it from the upper left down and to the right. - Show the display on the screen
- Refresh the screen
Finally the program waits 3 minutes (the minimum refresh time. Then the program uses while True: and pass statements to keep what's on the display until the processor is reset.
