Using eInk Displays with the ZynqberryZero

After having to update my CircuitPython-compatible PetaLinux project for my Zynqberry boards from v2019.2 to 2022.1 in order to be able to install the CircuitPython EPD library, I finally got to the point of being able to hook up my ZynqberryZero to one of my eInk displays and test them out!

CircuitPython Setup

In my previous project post I detailed how to create a hardware design for the ZynqberryZero in Vivado 2022.1 to mirror the GPIO pinout of its Raspberry Pi Zero counterpart, the details behind creating a PetaLinux 2022.1 project for the ZynqberryZero, and finally installing a customized version of Adafruit's CircuitPython. This project assumes a starting point of where that post left off.

Set the current date so the SSL certificates can be correctly validated by pip when accessing pypi.org:

zynqberryzero_os:~$ sudo date -s "02 APR 2023 12:30:00"

Also be sure that the CircuitPython packages are installed for the petalinux user with sudo privileges. This is very important because the packages need root access but also need to be universally available in the system, otherwise the data won't be transferred properly across the SPI bus to the eInk display.

I learned this the hard way because I originally installed the packages separately for the petalinux and root users, but this was causing the SPI packets to get broken up in a weird way. So when I was trying to send the series of bytes for the image itself, the eInk display was interpreting each byte from the SPI bus as a new command rather than the series of bytes to make up the display image. Therefore it displayed nothing, thankfully the logic analyzer and protocol sniffer functionality in WaveForms with my ADP3450 helped me track this down.

I have updated my previous post on installing CircuitPython to show how to install CircuitPython packages for the petalinux user with sudo privileges:

zynqberryzero_os:~$ sudo pip3 install ./Zynqberry.GPIO-0.0.1-py3-none-any.whl 
zynqberryzero_os:~$ sudo pip3 install ./Adafruit_PlatformDetect-3.42.0-py3-none-any.whl
zynqberryzero_os:~$ sudo pip3 install ./Adafruit_Blinka-8.16.1-py3-none-any.whl

Pip does complain about about being run with sudo, but in this case it is necessary to guaranteed the expected behavior wanted.

CircuitPython for E-Paper Displays (EPD)

Once the customized Blinka and Platform Detect packages are installed, the vast majority of other CircuitPython packages can be installed directly without any extra modification. This includes the CircuitPython library for e-paper displays (EPD). Again, since this package is accessing the SPI bus, it does need to be installed with sudo:

zynqberryzero_os:~$ sudo pip3 install adafruit-circuitpython-epd

The Adafruit CircuitPython EPD package covers e-paper displays with the IL0373, IL91874, IL0398, SSD1608, SSD1675, SSD1680, SSD1681, and UC8151D chipsets. I'm using the 2.9" flexible 296x128 monochrome eInk display with the UC8151D chipset for my particular project, paired with the Adafruit eInk Breakout Friend with 32KB SRAM.

Although I'm not utilizing the SRAM on the Breakout Friend board since the ZynqberryZero has plenty of available memory (DDR), I'm using Breakout Friend for it's 24-pin connector for the eInk display.

To get started quickly and verify everything is working correctly, clone the Adafruit CircuitPython EPD repository on the ZynqberryZero in order to get the example scripts:

zynqberryzero_os:~$ git clone https://github.com/adafruit/Adafruit_CircuitPython_EPD.git

Change directories into examples and download the font5x8.bin font that Adafruit CircuitPython packages require into it:

zynqberryzero_os:~$ cd ./Adafruit_CircuitPython_EPD/examples/
zynqberryzero_os:~/Adafruit_CircuitPython_EPD/examples$ wget https://github.com/adafruit/Adafruit_CircuitPython_framebuf/raw/main/examples/font5x8.bin

The examples directory contains scripts for displaying bitmap images and drawing text/images with Pillow.

Displaying Bitmap Images

The bitmap images called by the EPD example scripts aren't in the Github repository so download them manually before attempting to run any of the scripts:

zynqberryzero_os:~/Adafruit_CircuitPython_EPD/examples$ wget https://raw.githubusercontent.com/adafruit/Adafruit_ImageReader/master/images/E-Ink%20Flexible%202.9/blinka.bmp
zynqberryzero_os:~/Adafruit_CircuitPython_EPD/examples$ wget https://raw.githubusercontent.com/adafruit/Adafruit_CircuitPython_IL0373/main/examples/display-ruler.bmp

Then run the epd_bitmap.py script:

zynqberryzero_os:~/Adafruit_CircuitPython_EPD/examples$ sudo python3 epd_bitmap.py

I changed the filename called to display the ruler image just for fun!

Drawing Images with Pillow

The Python Imaging Library (Pillow) supports opening, manipulating, and saving many different image file formats. The Adafruit CircuitPython EPD package uses Pillow to facilitate drawing graphics/image and using text with custom fonts.

I covered how to install Pillow using PetaLinux in my previous post because the ZynqberryZero doesn't have enough memory for Pillow to be built/installed from its command line. Pillow is easier to use from a user perspective since.png and.jpg images can be used, rather than having to convert them to bitmaps first.

There are two example scripts for using Pillow to draw text/shapes and images in the examples directory in the Adafruit CircuitPython EPD repository. The epd_pillow_demo.py script calls a TTF font to write "Hello World" with a rectangle around it, and the epd_pillow_image.py script to display a.png image to the display.

Since Raspberry Pi OS usually comes with the DejaVu font already installed, that's a common font called on my CircuitPython scripts. However, any TTF font can be used and there are already some natively installed in Linux on a Zynq by PetaLinux, so CircuitPython just needs to be pointed to one.

Change the font loaded in line 87 in epd_pillow_demo.py from the default location of where the DejaVu font is installed in Raspberry Pi OS:

# Load a TTF Font
font = ImageFont.truetype("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf", FONTSIZE)

To the location of a font natively installed in the Linux image on the Zynq by PetaLinux, which is /usr/share/fonts/ttf/ (there are a few different fonts installed in this directory, any will work as long as they are .ttf):

# Load a TTF Font
font = ImageFont.truetype("/usr/share/fonts/ttf/LiberationMono-Regular.ttf", FONTSIZE)

Once the script has been pointed to a TTF font on the ZynqberryZero, run the epd_pillow_demo.py to write "Hello World" to the display with a rectangle around it:

zynqberryzero_os:~/Adafruit_CircuitPython_EPD/examples$ sudo python3 epd_pillow_demo.py

The epd_pillow_image.py script by default tries to open a.png file titled "blinka.png", which can be found on Adafruit's website in several different versions. I found one that typed out "2.9 E-Ink Flexible" with the little CircuitPython python.

Again the default blinka.png image called by the EPD example script isn't in the Github repository so download it manually before running the epd_pillow_image.py script to display it:

zynqberryzero_os:~/Adafruit_CircuitPython_EPD/examples$ wget wget https://github.com/adafruit/Adafruit_Learning_System_Guides/raw/master/EInk_Bonnet/blinka.png
zynqberryzero_os:~/Adafruit_CircuitPython_EPD/examples$ sudo python3 epd_pillow_image.py

Drawing Custom Images with Pillow

Like I mentioned previously, the great thing about Pillow is that it gives you pretty free rein to display whatever you want on your eInk display with minimal work! Since this is my goal for an upcoming project, I had to test it out with a.png I grabbed from the Google image search.

While not completely necessary, it's better to resize images to match the resolution of the target e-paper display. Based on the recommendations on the Adafruit website, I used ImageMagick to resize my.png for my 296x128 display:

~$ ./magick -size 296x128 <image_file_in>.png <image_file_out>.png

Upload the custom image file to the ZynqberryZero using a command like scp and place it in the examples directory:

~$ scp -O <image_file_out>.png petalinux@192.168.x.xxx:/home/petalinux/Adafruit_CircuitPython_EPD/examples

Then modify line 64 in the epd_pillow_image.py script to open the custom image:

zynqberryzero_os:~/Adafruit_CircuitPython_EPD/examples$ nano epd_pillow_demo.py

I just commented the call for the default image blinka.png and added my own so I could switch back and forth bit easier:

#image = Image.open("blinka.png")
image = Image.open("<image_file_out>.png")

Once the custom image is in place, rerun the epd_pillow_image.py script

zynqberryzero_os:~/Adafruit_CircuitPython_EPD/examples$ sudo python3 epd_pillow_image.py

And enjoy!