Getting PaPiRus to work (and then break it …)

Warning! The information in this post is quite old, dating back from the original PaPiRus Kickstarter campaign. In the mean time, the software has improved drastically and some parts of this post may no longer be relevant.

For the latest information and software, check the official PaPiRus documentation:

PaPiRus is an e-paper display for the Raspberry Pi by Pi Supply, that was funded via Kickstarter. It comes in three flavours: small (1.44″), medium (2.0″) and large (2.7″). PaPiRus also has additional features, including an onboard RTC, a digital temperature sensor and some push buttons. My Kickstarter reward arrived recently so I decided to give it a go.


No instructions were provided in the package, nor could I find any online. It was reported via a Kickstarter update that instructions and tutorials would become available in the near future though. That didn’t stop me from continuing, as with a bit of common sense, it was clear where to connect or solder the different components.



First thing to do was to solder on the push buttons and pogo pin.

The buttons are easy to solder on, as they snap on the board and remain in place while soldering. The pogo pin was trickier and gave me a bit of a hard time. Holding it in place with tweezers to not burn my fingers, I was able to apply solder to the base of the pin. Make sure it is soldered on straight, as it needs to make contact with the Pi. With that said, the pogo pin is not critical to the functionality of the display and could be omitted.

Tip from Paul! One tip for soldering the pin I found was to assemble the board onto the base PI and use that to hold the pin in the correct place while you solder it, that way it is ensured to be aligned correctly.



Once everything was soldered on, the display could be attached. … Using the four double-sided adhesive pads, the display can be attached to the top of the HAT. Finally, the HAT can be fixed to the Pi using the provided plastic standoffs and screws.



The software side proved to be the trickiest part of it all. The PaPiRus code and examples have some problems, but I suspect this will all be fixed in the near feature. In the mean time, you’ll find my workarounds below.

Operating System

For the operating system, I used the latest Raspbian Jessie (2015-11-21) and flashed it to a 8Gb microSD card.

Fredericks-Mac-mini:~ frederickvandenbosch$ sudo dd if=Downloads/2015-11-21-raspbian-jessie.img of=/dev/disk3 bs=1m
3752+0 records in
3752+0 records out
3934257152 bytes transferred in 1881.837422 secs (2090647 bytes/sec)

Once the microSD card was ready, I inserted it in the Raspberry Pi (in my case, model A+) and booted from it. Once booted, I set up the typical things such as wifi, expanded filesystem and software upgrade.

To expand the filesystem to make full use of the microSD card, execute following command in a terminal and select the first entry “Expand Filesystem”:

pi@raspberrypi:~ $ sudo raspi-config

Screen Shot 2016-01-26 at 20.30.25

You will be prompted to reboot. After reboot, in a terminal, the software upgrade commands can be entered:

pi@raspberrypi:~ $ sudo apt-get update
pi@raspberrypi:~ $ sudo apt-get upgrade

The Pi is now fully up-to-date, ready to start with the PaPiRus specific software.


The PaPiRus software can easily be installed using a single command:

pi@raspberrypi:~ $ curl -sSL | sudo bash

Once finished, several PaPiRus commands should be available. This can be tested by typing “papirus-” in a terminal and pressing the TAB key twice.

pi@raspberrypi:~ $ papirus-
papirus-clear papirus-clock papirus-config papirus-gol papirus-set papirus-setup papirus-write

The first command I used was the “papirus-set” to configure the size of my display. As I’m using the large display, the command was the following:

pi@raspberrypi:~ $ sudo papirus-set 2.7

With the software set up and the display configured, it was time for some tests!


I started by trying to run the papirus-clock example application. Unfortunately, that failed stating a certain module could not be found (EPD).

pi@raspberrypi:~ $ sudo papirus-clock
Traceback (most recent call last):
File "/usr/local/bin/papirus-clock", line 26, in 
from EPD import EPD
ImportError: No module named EPD

Going through the code and comparing applications, I got it to work by changing a singe line:

pi@raspberrypi:~ $ sudo nano /usr/local/bin/papirus-clock

Change “from EPD import EPD” to “from papirus import Papirus as EPD”

#from EPD import EPD
from papirus import Papirus as EPD

I tried running the application again, this time a different error popped up:

pi@raspberrypi:~ $ sudo papirus-clock
panel = EPD 2.7 264 x 176 version=4 COG=2 FILM=231
Traceback (most recent call last):
File "/usr/local/bin/papirus-clock", line 122, in 
File "/usr/local/bin/papirus-clock", line 69, in main
File "/usr/local/lib/python2.7/dist-packages/papirus/", line 152, in clear
File "/usr/local/lib/python2.7/dist-packages/papirus/", line 156, in _command
IOError: [Errno 103] Software caused connection abort

This error is due to the fact that the HAT communicates via SPI with the Pi. By default SPI is disabled, but it can easily be enabled using the “raspi-config” tool.

pi@raspberrypi:~ $ sudo raspi-config

Screen Shot 2016-01-26 at 22.00.14 Screen Shot 2016-01-26 at 22.00.24

After rebooting, I ran the application again, and there it was, a first sign of life!

pi@raspberrypi:~ $ sudo papirus-clock
panel = EPD 2.7 264 x 176 version=4 COG=2 FILM=231


Note from Derwent! There is an indentation issue on line 37 and 39 of /usr/local/lib/python2.7/dist-packages/papirus/ For some reason I didn’t encounter it, but if you do, you now know where to look.


The second example application allows to write text on the display by passing it via the command line. Unfortunately, this too gave an error:

pi@raspberrypi:~ $ sudo papirus-write "hello world"
Writing to Papirus.......
Traceback (most recent call last):
File "/usr/local/bin/papirus-write", line 67, in 
File "/usr/local/bin/papirus-write", line 27, in main
write_text(papirus, args.content, args.fsize)
File "/usr/local/bin/papirus-write", line 39, in write_text
font = ImageFont.truetype('Pillow/Tests/fonts/FreeMono.ttf', size)
File "/usr/lib/python2.7/dist-packages/PIL/", line 240, in truetype
return FreeTypeFont(font, size, index, encoding)
File "/usr/lib/python2.7/dist-packages/PIL/", line 137, in __init__
self.font = core.getfont(font, size, index, encoding)
IOError: cannot open resource

From the error message, it was clear the font file would not be found. I searched to see if it was on the system and if so, in which location.

pi@raspberrypi:~ $ sudo find / -name FreeMono.ttf

I then edited the application to update the path to the font, as it was different.

pi@raspberrypi:~ $ sudo nano /usr/local/bin/papirus-write
#font = ImageFont.truetype('Pillow/Tests/fonts/FreeMono.ttf', size)
font = ImageFont.truetype('/usr/share/fonts/truetype/freefont/FreeMono.ttf', size)

I ran the application again, and yes … it worked.



Clearing the display can be done with the following command:

pi@raspberrypi:~ $ sudo papirus-clear
Clearing Papirus....... Finished!


Sample code is provided on the PaPiRus GitHub page to display an image. I updated the path to my image file and tried to run it.

from papirus import PapirusImage

image = PapirusImage()

# easy write image to screen
# image.write(path)
pi@raspberrypi:~ $ sudo python
Traceback (most recent call last):
File "", line 1, in 
from papirus import PapirusImage
ImportError: cannot import name PapirusImage

It failed to import the PapirusImage module. Instead of spending time looking for the actual problem, I changed the code to something that worked in the other applications.

pi@raspberrypi:~ $ sudo nano

from papirus import Papirus
from PIL import Image
papirus = Papirus()

image ='/home/pi/logo.bmp')

Made the script executable and ran it.

pi@raspberrypi:~ $ sudo chmod +x
pi@raspberrypi:~ $ ./

This returned an error. This time, my fault 😉

pi@raspberrypi:~ $ ./

Traceback (most recent call last):
File "./", line 9, in 
image ='/home/pi/logo.bmp')
File "/usr/lib/python2.7/dist-packages/PIL/", line 2264, in open
im = factory(fp, filename)
File "/usr/lib/python2.7/dist-packages/PIL/", line 97, in __init__
File "/usr/lib/python2.7/dist-packages/PIL/", line 181, in _open
File "/usr/lib/python2.7/dist-packages/PIL/", line 132, in _bitmap
raise IOError("Unsupported BMP bitfields layout")
IOError: Unsupported BMP bitfields layout

The BMP file is provided was still in full color. It needs to be changed to 1-bit color (black & white). I know this can be done through code in Python, but as I only quickly wanted to test this, I used GIMP to change the colors. I also made sure the image was the correct resolution for my display (264×176).

Screen Shot 2016-01-26 at 22.27.57 Screen Shot 2016-01-26 at 22.28.05

I uploaded the updated image and ran the script again, et voila:



Things were going so well, something had to go wrong. And it did. I accidentally dropped my Pi when disconnecting the HDMI and power cable. Of course, it fell on the display and cracked it badly!

IMG_0734 IMG_0736

Don’t do like me, don’t drop your Pi and PaPiRus. Now I need to find a new display …

Anyway, I hope this blog post is helpful until the PaPiRus code and examples are fixed.

12/02/2016 UPDATE!

Colin Deady from was kind enough to send me his displays from when he was evaluating the PaPiRus for Pi-Supply. Thank you Colin, I’ll now be able to resume my adventures with this display!


© Frederick Vandenbosch, 2014-2021. Unauthorised use and/or duplication of this material without express and written permission from this blog’s author and owner is strictly prohibited. Excerpts and links may be used, provided that full and clear credit is given to Frederick Vandenbosch with appropriate and specific direction to the original content.