Sunday, February 12, 2017

Pi Supply / Adafruit PaPiRus Zero ePaper/eInk pHAT v1.2 Setup

I recently bought a Pi Supply PaPiRus Zero ePaper/eInk pHAT v1.2 from Adafruit. I went to the Pi Supply website but the documentation was not so good. And even going through the PaPiRus GitHub instructions, I had issues with my board not working right that required tech support from Pi Supply. I finally got it to work, so I'll list my success for others.

If you have any other driver board that is not the Pi Supply PaPiRus Zero ePaper pHAT v1.2, you'll want to look at the end of this post for pointers to resources that might apply.

Measure the Display Size

The display and board Adafruit currently sells is the 2.0 inch board. I had originally thought it was the small 1.44 as that is what the Pi Supply site had on it but I hadn't measured the display (Adafruit correctly says 2.0"). Here is the diagonal display measurement you should make. If you don't have an inch ruler, divide the number of centimeters by 2.54 to get inches. The PaPiRus Zero should have a 2.0 inch display.

Measure your display from far corner to far corner diagonally. This one is 2.0 inches. Ruler by Adafruit.
If your display measures different from 2.0 inches, your settings and configuration may need changing.

Jumper Setting

It is important to set the jumper across the pins on connector CN2 correctly so that the board handles your display correctly. If this is set wrong you'll get unwanted lines or behavior of the display.

  • Jumper pins 2 and 3 for a 1.44" or 2.0" display
  • Jumper pins 1 and 2 for a 2.7" display
  • Take the jumper off (or just have it on pin 1 and off 2 and 3) for a 1.9" or 2.6" display

The board Adafruit ships is the 2.0 inch. So you want the jumper looking like this:

Board to Display Connection

To open the connector at the back of the PaPiRus board you need to lift the dark brown clip on CN1 by using your fingernail to grab the dark brown part on the end of the board and rotating up gently allow it to rotate over its hinges until it is perpendicular to the board. The brown part clips on the beige one so it is normal for it to give a slight resistance when opening the connector. The pictures are copyright so you'll have to look at them on the link below:

See the pictures on the Pi Supply PaPiRus Assembly Tips and Gotchas page.

With the connector open, slide the cable on the beige part of the connector and gently push it so that it reaches underneath the brown clip. Make sure that the cable is inserted evenly so that when the clip is rotate back into the closed position the two dots shown in the picture are parallel with the connector.

This is one of the main causes of the screen not operating correctly so make sure you pay particular care when plugging the screen into the ribbon connector CN1.

Once the cable is in the correct position, rotate the brown clip into the closed position. You will notice that it will provide some resistance but this is absolutely normal.

See the pictures on the Pi Supply PaPiRus Assembly Tips and Gotchas page.

Standoffs and Sticky Tape

Take the two bits of sticky take and put them so they hold the display down. Be careful, removing the tape later is very hard and not recommended.
You have two squares of tape to hold the display down.
Connect the two plastic standoffs to the display pHat board (be careful to not damage the display).

At this point, your Pi Zero must have the GPIO pins added. You need to order this separately from the Pi Zero and the display pHat. At Adafruit it is part number 3335, at Pi Supply it is here.

You can follow this Instructable on soldering the header onto your Pi Zero. You will need solder, a soldering iron with a fine tip, some tape or Blu Tack to hold the header while soldering and some patience.

When you have the header soldered onto the Pi Zero, you can connect the display pHat board to the Pi Zero GPIO header to make a circuit board sandwich. Ensure the pins of the Pi line up with the pHat socket. Use the last two plastic screws to secure the Pi to the standoffs. The boards should be well connected now.

Software Installation

Install Raspbian on a micro SD card

If you don't have a micro SD card set up with the Raspbian Linux operating system, see this Adafruit tutorial on how to get it and set it up. Other operating systems like Arch Linux are not supported by the software driver, if you don't use Raspbian you're on your own.

You'll need to do some more set up for the display below. 

Connect a display and keyboard to your Pi Zero (Adafruit and Pi Supply, among other shops, have adapter cables for mini-USB to USB/VGA and micro USB to USB). For advanced users, you can log in via another computer via the SSH protocol with a USB to micro USB cable, tutorial here

Log into your Pi Zero, the default is username Pi, password Raspberry. Best to change the password at some point, remember the password if you do change it.

Enabling SPI and I2C interfaces on Raspberry Pi

Before using PaPiRus, you need to enable the SPI and the I2C interfaces which talk between the Pi and the display. You can enable the SPI by typing sudo raspi-config at the command line and then selecting Interfacing options > SPI and then selecting Enable. Without exiting the tool still in Interfacing options > I2C and then selecting Enable.

Setup PaPiRus Software

Run this line and PaPiRus will be setup and installed

curl -sSL | sudo bash

You'll see alot of text scroll by as the software installs, that's normal.

All of the software will install in a directory named PaPiRus

Commands to Run

Select your screen size for the 2.0" display

sudo papirus-set 2.0

For other sizes, it works with papirus-set [1.44 | 1.9 | 2.0 | 2.6 | 2.7 ]

Write data to the screen

papirus-write "Some text to write"

Clear the screen


Draw image on the screen

papirus-draw /path/to/image -t [resize | crop]

The PaPiRus can only display Bitmap images (.BMP) in black and white (1 bit colour). If you pass an image to PaPiRus that is not a 1 Bit Bitmap, it will automatically be converted to this by the software. However, for best results and higher image quality we would recommend that you convert the image to a 1 Bit Bitmap before pushing to the PaPiRus screen using GIMP or Photoshop or similar photo editing tools.

The default bitmap sizes for the different displays:

1.44"     128 x 96
1.9"      144 x 128
2.0"      200 x 96 - The Raspberry Pi Zero kit at Adafruit
2.6"      232 x 128
2.7"      264 x 176

More commands are listed in the Github repository.


For using the display with Python see the official GitHub software repository.

The documentation is on both the README and in the repository wiki.


I hope this has been useful. Here are some resources this is drawn from: