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!


45 thoughts on “Getting PaPiRus to work (and then break it …)

  1. Do you know what it means if when I run sudo papirus-clock, I get this error:
    File “/usr/local/lib/python2.7/dist-packages/papirus/”, line 66, in __init__
    with open(os.path.join(self._epd_path, ‘version’)) as f:
    IOError: [Errno 2] No such file or directory: ‘/dev/epd/version’

    1. Thanks for this post by the way. I spent a few hours yesterday trying to get this to work and got stuck at the error above.

  2. Great work Fred! And sorry lol about the breakage.
    Just as a FYI, it’s possible to configure the setup scripts so that the uart pins remain unused- see the git for repaper that is called during setup.
    This has a the benefit that the pi and display can receive data via the uart pins that can be transcribed into display messages . I’ll post a blog on my setup when completed.

  3. Thanks,
    My Papirus kit turned up today without any instructions, but luckily i found your guide.
    All up an running now.

    I did find that I had a further error on the “hello world” test which was caused by incorrect indentation in the code (basically added another tab and it worked).

    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.

  4. Thanks,
    I am able to use my PaPiRus now.
    I have added a pull request on github for the command papirus-draw inspired by your example code image.
    So I don’t have to convert/resize/crop my image for displaying it on the screen.

      1. Since you have helped so many of us get started with the Papirus Hat do you think PI-Supply could give you one so that you can continue to lead on building a community around this cool hat?

  5. Thanks, helped me to get it working and now I have an fun project planned. Hadn’t enabled SPI after a fresh install and then I was having trouble with the import errors like you so your code got me off to a good start. Sorry to hear about your screen :(.

  6. Doh! 🙂 Thank you for your help.

    Next problem is solving what prints after I run “papirus-clock”

    Traceback (most recent call last):
    File “/usr/local/bin/papirus-clock”, line 26, in
    from papirus import Papirus as EPD
    File “/usr/local/lib/python2.7/dist-packages/papirus/”, line 2, in
    from text import PapirusText
    File “/usr/local/lib/python2.7/dist-packages/papirus/”, line 37

    1. I think that it’s referring to that line being mis-indented. If you go to the github page and look at one of the pull requests you’ll see that someone modified that line to be properly indented.

  7. Hello, me again :/

    I was wondering if I could get some advice. I’ve the software side of things running, however, nothing is appearing on the screen. I have not installed the pogo pin.

    Any thoughts. Help greatly appreciated. Thanks agian.

    1. Which application are you running? Does it show an error or runs properly? Have you verified the display is properly connected to the HAT?
      It should work without the pogo pin as far as I understood.

      1. No errors on run. The display looks correctly connected to the HAT. IS there a particular way to verify this? I may try soldering the pogo pin in.

        1. I’m not sure, and as my display is broken, there isn’t much I can try 🙁

          Make sure you are running the command with “sudo” and double check the ribbon cable of the display is properly connected and pushed all the way in the connector on the HAT. I’m not sure what else it could be if the code doesn’t return any errors.

          Perhaps worth posting on the Kickstarter page if you haven’t already done so.

  8. Frederick, thank you for making this comprehensive and complete manual for making this work. I finally found the time to test the display and I am very glad you wrote the manual.

    dank u wel 🙂

  9. You did an awesome write up. It’s too bad the PaPiRus GitHub page won’t accept pull requests or update their code. But thanks for this. Unfortunately I could not get it to work with my Pi 2B and 2.7″ PaPiRus. The code seemed to be working fine, as in there were no errors after I made the 3 main fixes, but the screen would never display anything or “power on”
    Related question, how important is the pogo pin? Again, thank you. Adam

    1. The pogo pin’s functionality is related to the wake on alarm functionality of the RTC, so it should not have impact on the display working or not.
      I assume you’ve double checked the connection of the flex cable to the HAT. If so, I’m not sure what could be wrong :s

      1. Thanks for the reply. My boss put the screen on, so let’s blame him. He ordered two of the 2.7’s, so I got the second (unopened) one from him, and it worked perfectly the first try. You rock!

  10. If you connect the buttons that’ll tell you if the hat is connected correctly.

    papirus-config should also confirm that the hat is working.

    You may also need to make sure that the hat matched the standard you set in config or in the code.

  11. Hello,

    any one knows how we could update the last version of the software?
    Means the git command for getting it and other command to update the setup.
    The pi-supply team was really active last weeks
    I have a version which don’t support the buttons, and is far from current one.

    Thank you very much in advance for helping

  12. i don’t know how to use git. when i make a google search i get x possible solution. which one is the best normally?

  13. Thanks your explanation got me up and running with mine after my first failed attempt following the instructions on the GitHub site 🙂

  14. I can’t find much about this PaPiRus, but it looks like an interesting addition. Can the HAT be used to display anything or is it only displaying specifically via these programs? What I would like to do is just set the Pi screen resolution to the 2.7″ version and display whatever the Pi would normally display, eg: web pages.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

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