Low power and great visibility for the popular computing platform
ePaper, or E-ink, displays have been around for some time, popularised by the e-reader and finding their way into mobile phones, watches and even shop displays. They require very low power and reflect light rather than emitting it, meaning they can be easily read in bright sunlight and have a wide viewing angle.
PaPiRus is an add-on board, or HAT, for the Raspberry Pi that comes bundled with three different sizes of ePaper screen, making for a flexible prototyping solution. In this post we will assemble and connect one of the displays to a Raspberry Pi 3.
Included in the box is the PaPiRus board, mounting hardware, the three different displays and a handful of stickers. Also included is a 'Pogo Pin' connector that is intended to connect to a pad on the Pi. Adding this pin is optional and is intended to allow for wake-on-alarm feature using the on-board RTC, though this will only work with the Pi 2, as the Pi 3 does not have this pad.
The ePaper screens chosen for the PaPiRus are manufactured by Pervasive Displays, a company that also supplies displays for many of the other development tools compatible with the popular Pi and Arduino platforms. Though delicate, the units are of high quality and a popular choice with other manufacturers of development kits.
In 2014, Pervasive Displays launched RePaper.org, a resource including sample programs and documentation on hardware and driver board schematics released under various permissive licenses, to encourage innovation with their ePaper products. This is fantastic to see and I believe something that more companies should be doing to support their products and those wanting to make use of them.
As well as driving an ePaper display, the PaPiRus also has an on-board temperature sensor and real-time clock (RTC) that can be accessed over the i2c bus.
Putting it together
With the parts out of the box and neatly arranged on the workbench, assembly can begin. Firstly, should you have a soldering iron to hand you may wish to solder the four buttons to the PaPiRus board. Doing so is optional, but soldering before attaching an ePaper display seems like the sensible thing to do, and extra buttons attached to the GPIO can come in handy. If using the PaPiRus with a Pi3, soldering on the Pogo Pin is not necessary.
Before attaching a display to the board, take four of the included M2.5 x 5mm nylon screws and the four threaded standoffs/spacers and attach them to the PaPiRus board as shown. This is best done now as the largest display partially covers the screws when fixed into place.
Next, a decision must be made. Which display size to try out first? I plumped for the largest and carefully plugged the ribbon cable into the on-board connector. Sticky foam pads are provided to attach the screen to the board, but the quantity provided seems like overkill for just one display, especially since you may want to be able to easily swap to a different size. An effective solution is to simply use one of the pads cut into four pieces.
At this point the PaPiRus board can be added to the Pi by aligning the GPIO header pins and carefully pushing the two together. The remaining four screws can be used to secure the PaPiRus into place, though this does take up all four of the Pi's mounting holes. To allow for mounting of the Pi, a solution is to purchase or make a mounting plate and use longer screws.
To improve the robustness of the assembly as a whole, and reduce the likelihood of damaging the display, I quickly designed and laser cut a simple housing, the files for which can be found here.
Configuring the Pi
Starting with a fresh Raspbian image, ensure the system is up-to-date with the following two commands:
$ sudo apt-get udpate
$ sudo apt-get upgrade
The README file in the PaPiRus GitHub repository gives guidance on getting the displays working. Following these instructions, first enable SPI using the raspi-config utility, and then reboot the system:
- $ sudo raspi-config
- $ sudo reboot
Next you can either run the script provided or choose to install each component manually, we will do the latter.
- Install git and software dependencies
- $ sudo apt-get install git python-imaging
- Clone the PaPirus repository
- $ git clone https://github.com/PiSupply/PaPiRus.git
- Change into directory and install PaPiRus Python library
- $ cd PaPiRus
- $ sudo python setup.py install
- Install the driver, here we will use the script provided rather than manually performing each step
- $ papirus-setup
Trying out the display
With the above steps completed we need to set the screen size before testing the display. The script to do so must be run as root:
$ sudo papirus-set 2.7
Confirmation of screen size will be printed to the terminal. Now we can test the functionality of the display with the demo papirus-clock tool, which must also be run as root:
$ sudo papirus-clock
When I ran this demo for the very first time, I noticed some 'graininess' to the display and was concerned I may not have connected it to the PaPiRus board correctly. However, after some time, perhaps 15 minutes or so, this graininess disappeared and has since not returned.
Once confident that the screen is working correctly, you may wish to try and display an image in order to see what is possible, given the limitations of ePaper versus more traditional screens. We can use GIMP – the free cross-platform image manipulation program – to do so, though other graphics packages of similar capability would also be suitable.
In brief, the image file should have the following attributes:
Correct resolution (264 x 176 px for the largest display, 200 x 96 px for medium, 128 x 96 px for the small)
- 1-bit palette (this can be set in GIMP in Image > Mode > Indexed and choosing 'black and white (1-bit) palette')
Once edited using a desktop computer the image file can be saved and copied to the Pi with the PaPiRus display. There is an example python script in the /bin/ folder in the repository that we can use to send the image, though for simplicity we will make it executable. From the /bin/ folder:
$ sudo chmod +x papirus-draw
Then execute the command with the image filename as an argument:
$ sudo ./papirus-draw /imagePath/ImageName
This should display the image and print confirmation to the terminal.
Python and PaPiRus
As well as the provided examples, there is a Python API for using the PaPiRus from within your own Python scripts. The API reference in the GitHub README is however, at the time of writing under development and so I decided to look at the code in the papirus-write example to see how it worked.
By combining lines from papirus-write and a previous project, I was able to put together a simple script that subscribes to an MQTT topic and writes the payload of the most recent message to the PaPiRus. (MQTT is a popular Machine-to-Machine (M2M) or Internet of Things (IoT) messaging protocol designed to be lightweight and reliable.)
The code for the above is available here and further information on working with Python and MQTT can be found in the project link above.
PaPiRus is a worthy addition to the Raspberry Pi HAT family and a great introduction to working with ePaper. Choosing the Pervasive Displays range of modules means access to their solid foundation of open information and examples, a strong benefit that is all too easy to overlook.
With PaPiRus, going from components in a box to functioning Pi display is quick and simple, despite some gaps in the online documentation. Once these gaps have been filled it will be easier than ever to integrate ePaper into your Pi projects. Which screen size will you choose first?