PaPiRus E-ink Display

Pi Gets 'Ink' Done

YotaPhone have already taken on this type of display in mobile technology and with phones only lasting about a day from full charge it's obvious why this market is looking for something new.
The low power (or no power) requirements of the display mean it only needs to change with new information.

The PaPiRus display brings this to the hands of the tinkers and future innovators.





Find the original kickstarter page at

https://www.kickstarter.com/projects/pisupply/papirus-the-epaper-screen-hat-for-your-raspberry-p/posts/1470013

Installation

I have a version 1.8 board which doesn't seem to be listed on the hardware version Excel sheet. I guess this quite new and from reading the message boards the documentation should be out very soon. I'm not a kickstarter backer so I'm surprised that this doesn't come with good user documentation. I hope this helps in the meantime to explain how the display works.

Get over to the git home page at

https://github.com/PiSupply/PaPiRus

This is the latest source for the Pi hat.

Prerequisites

Ensure the SPI is enabled
If you don't have it already get GIT and imaging library for Python

> sudo apt-get install git

> sudo apt-get install python-imaging

Get the fuse library if not already installed

> sudo apt-get install libfuse-dev

If you want to run some of the demos with Gratis and you don't have fonts installed then run

> sudo apt-get install fonts-freefont-ttf

Hardware

All screens connect up in the same way. Just lift the plastic connector and insert the ribbon. Push down the connector to secure in place.

The screen folds over the back of the board so ensure you have it the right way around before inserting

Getting Python code and installing

You will need to download the latest source for the PaPiRus

> git clone https://github.com/PiSupply/PaPiRus.git

> cd PaPiRus

> sudo python setup.py install    

> papirus-setup

Gratis is the beating heart of the setup. If you just want to get straight into the workings of the display then Gratis is all you really need.
https://github.com/repaper/gratis

Get the gratis driver

> git clone https://github.com/repaper/gratis.git

Note that the next lines are for the latest V321 G2 panel, but I guess this will be most new users

> cd gratis/PlatformWithOS

> make PANEL_VERSION=V231_G2 rpi-epd_fuse

> sudo make PANEL_VERSION=V231_G2 rpi-install

> sudo service epd-fuse start

The setup installs libfuse and fonts from fonts-freefont-ttf.

My first thoughts were, why do I need all this extra code baggage. If I'm using a display I usually just directly interface and I'm done.
It's not a tight kernel driver, but it works in user space world and an e-ink isn't going to complain about performance code issues.

Checking everything works

Fix broken code

> sudo nano /usr/local/lib/python2.7/dist-packages/papirus/text.py

Indent line 37 with an extra tab. Save back to original file

> sudo nano /usr/local/bin/papirus-write

Change line 39 to 

font = ImageFont.truetype('/usr/share/fonts/truetype/freefont/FreeMono.ttf', size)

Run 

> sudo papirus-config

Set screen size

The display should be good to go with the code now

> papirus-write "Test"

Should correctly write to e-ink display, if not check previous steps and SPI is enabled.

Run clock test

Fix the clock code by editing

> sudo nano /usr/local/bin/papirus-clock

Change 

from EPD import EPD

to

from papirus import Papirus as EPD

Run clock and you should see the time and date display. This refreshes every 5 seconds

> sudo papirus-clock

Included demos

PiSupply demo files

These were already run in the test above to check things are working. The install of these files puts all copies into /usr/local/bin

> papirus-write "Hello World"

> sudo papirus-clock

> sudo papirus-gol 2.7

> papirus-clear

You'll note that sudo is used on some of these examples. As far as I know this isn't really necessary as the main purpose of the epd_fuse service is to provide an interface in normal user land. Check out the gratis examples for clarity. 

Gratis python demonstration files

Python demonstration files exist in the PlatformWithOS/demo folder. These are further python scripts which can be run (ensure the epd-fuse service is running)

This is a full screen digital clock.
> python Clock27.py

Gratis C demonstration files

These files directly access the hardware and do not use the fuse service. This is actually to test the code in the service so strictly these are not examples or demos, but good to see.

The install doesn't build these by default so a further make command is needed.

Access the PlatformWithOS from within the gratis downloaded GIT repository.

> cd PlatformWithOS

For the 2.7 panel type:

> make PANEL_VERSION=V231_G2 rpi

Other older panel versions are V110_G1 and V230_G2, only use if you know you have these older panels.

Change directory to driver-common
> cd driver-common

Run the test file as root and specify the panel size.
> sudo ./epd_test 2.7

This loops through some test images which are good examples of display.
Root access is needed for this test file because it directly accesses the hardware.

Gratis driver

Fuse driver provides device files in /dev/epd directory. These can be seen when the epd service is running
> sudo /etc/init.d/epd-fuse start

The README.md file explains what the files do and if they are read or write

Example
> cat /dev/epd/version
Will give you the driver version

Whilst in the gratis driver-common directory (see example above) the epd_fuse service can also be called with the same test images without needing root. Note that it doesn't matter if you haven't built the epd_test file to do this. Actually any test XBM matching the screen dimensions can be used.

> ./xbm2bin < cat_2_7.xbm > /dev/epd/display
> echo U > /dev/epd/command

This switches to the cat image or any other image chosen in the test folder.

Sum up of the display

E-ink displays cannot be compared directly to other display types as the screen cannot rapidly change like an LCD or OLED. Images displayed are clear and sharp for text displays. Graphics require dithering because there's no grey scale which can be set.

I hope there's further improvements down the road for the driver and display. Rapid changes to the screen are possible but ghosting is a problem until a full screen refresh has been performed. 

Check out the game of life code to see ghosting examples

> sudo papirus-gol

When this has run for a few iterations there's clear ghosting on the screen. This isn't too bad and may be something that some smart folks who now have this display on their Pi can help improve. 

Driving the display is really easy with the existing software. Simple scripts can be used easily to set the screen. 

I can't really figure out what is going on with the 4 optional buttons that came with the display. I ran some simple GPIO code to see if they were just forwarded straight to the Pi pins but this doesn't seem to be the case. 
UPDATE - The buttons connect to GPIO pins 16, 26, 20 and 21. 

The real time clock and wake functions are not clear. I didn't install the pogo pin as my current case doesn't allow the connection through to the Pi board. There's no example code to show how it works so I'm hoping this appears soon.

Finally I'm not quite sure the temperature sensor feature actually works with the Pi. There's only snippets of information in the included documentation, but it seems to indicate that an ADC would be needed for the Pi and since this isn't possible out-of-the-box I can't see how it can be read. Primarily the temperature sensor is for the display to set the PWM. 

Overall it does what it should do. I'm looking forward to some cool ideas from the user community. I think a dedicated case to house the display and Pi would be great for applications.