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.

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”:

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:

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:

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

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:

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).

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

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

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

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.

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!


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:

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.

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

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



Clearing the display can be done with the following command:


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.

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.

Made the script executable and ran it.

This returned an error. This time, my fault 😉

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-2019. 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.