PaPiRus

You can find here a variety of software, hardware and other resources for the PaPiRus range of ePaper eInk displays from Pi Supply. This repository is based on, and makes use of, the rePaper/gratis GitHub repository.

You can purchase one of the PaPiRus boards from our webshop or from a variety of resellers worldwide.

Setup PaPiRus

Auto Installation

Just run the following script in a terminal window and PaPiRus will be automatically setup.

# Run this line and PaPiRus will be setup and installed
curl -sSL https://pisupp.ly/papiruscode | sudo bash

Manual Installation

If you have any troubles with the auto installation or if for some reason you prefer to install PaPiRus manually, then follow the steps below.

Python 2 and Python 3 support

The library and examples work on both Python 2 and Python 3. Currently (July 2020) Python 2 is still the default Python in Raspbian. The Python 2 and Python 3 versions can be installed side by side.

Enabling SPI and I2C interfaces on Raspberry Pi

Before using PaPiRus, do not forget to enable the SPI and the I2C interfaces. You can enable the SPI by typing sudo raspi-config at the command line and then selecting Interfacing options > SPI and then selecting Enable. Without exiting the tool still in Interfacing options > I2C and then selecting Enable.

Install Python API (best to run all of these commands as root using sudo)

# Install dependencies
sudo apt-get install git bc i2c-tools fonts-freefont-ttf whiptail make gcc -y
# For Python 2
sudo apt-get install python-pil python-smbus python-dateutil -y
# For Python 3
sudo apt-get install python3-pil python3-smbus python3-dateutil python3-distutils -y

git clone --depth=1 https://github.com/PiSupply/PaPiRus.git
cd PaPiRus

# For Python 2
sudo python setup.py install    # Install PaPirRus python library
# For Python 3
sudo python3 setup.py install    # Install PaPirRus python library

Install Driver (Option 1) (best to run all of these commands as root using sudo)

sudo papirus-setup    # This will auto install the driver

Install Driver (Option 2) (best to run all of these commands as root using sudo)

# Install fuse driver
sudo apt-get install libfuse-dev -y

mkdir /tmp/papirus
cd /tmp/papirus
git clone https://github.com/repaper/gratis.git

cd /tmp/papirus/gratis
make rpi EPD_IO=epd_io.h PANEL_VERSION='V231_G2'
sudo make rpi-install EPD_IO=epd_io.h PANEL_VERSION='V231_G2'
sudo systemctl enable epd-fuse.service
sudo reboot

Select your screen size

sudo papirus-set [1.44 | 1.9 | 2.0 | 2.6 | 2.7 ]
or
sudo papirus-config

Python API

NOTE: In the following examples where rotation = rot rot should be one of the following values: 0, 90, 180 or 270 degrees, depending on the screen orientation. i.e. screen = Papirus([rotation = 90])

The Basic API

from papirus import Papirus

# The epaper screen object.
# Optional rotation argument: rot = 0, 90, 180 or 270 degrees
screen = Papirus([rotation = rot])

# Write a bitmap to the epaper screen
screen.display('./path/to/bmp/image')

# Perform a full update to the screen (slower)
screen.update()

# Update only the changed pixels (faster)
screen.partial_update()

# Update only the changed pixels with user defined update duration
screen.fast_update()

# Disable automatic use of LM75B temperature sensor
screen.use_lm75b = False

The Text API

from papirus import PapirusText

text = PapirusText([rotation = rot])

# Write text to the screen
# text.write(text)
text.write("hello world")

# Write text to the screen specifying all options
text.write(text, [size = <size> ],[fontPath = <fontpath>],[maxLines = <n>])
# maxLines is the max number of lines to autowrap the given text.
# New lines ('\n') in the text will not go to the next line, but are interpreted as white space.
# Use PapirusTextPos() instead which recognizes '\n'.

The Positional Text API (example 1)

from papirus import PapirusTextPos

# Same as calling "PapirusTextPos(True [,rotation = rot])"
text = PapirusTextPos([rotation = rot])

# Write text to the screen at selected point, with an Id
# "hello world" will appear on the screen at (10, 10), font size 20, straight away
text.AddText("hello world", 10, 10, Id="Start" )

# Add another line of text, at the default location
# "Another line" will appear on screen at (0, 0), font size 20, straight away
text.AddText("Another line", Id="Top")

# Update the first line
# "hello world" will disappear and "New Text" will be displayed straight away
text.UpdateText("Start", "New Text")

# Remove The second line of text
# "Another line" will be removed from the screen straight away
text.RemoveText("Top")

# Clear all text from the screen
# This does a full update so is a little slower than just removing the text.
text.Clear()

The Positional Text API (example 2)

from papirus import PapirusTextPos

# Calling PapirusTextPos this way will mean nothing is written to the screen by default
text = PapirusTextPos(False [,rotation = rot])

# Write text to the screen at selected point, with an Id
# Nothing will show on the screen
text.AddText("hello world", 10, 10, Id="Start" )

# Add another line of text, at the default location
# Nothing will show on the screen
text.AddText("Another line", Id="Top")

# Now display BOTH lines on the screen
text.WriteAll()

# Update the first line
# No change will happen on the screen
text.UpdateText("Start", "New Text")

# Remove the second line of text
# The text won't be removed from the screen yet
text.RemoveText("Top")

# Now update the screen to show the changes
text.WriteAll()

The Positional Text API (example 3)

from papirus import PapirusTextPos

# Same as calling "PapirusTextPos(True)"
text = PapirusTextPos()

# Write text to the screen at selected point, with an Id
# This will write "hello world" to the screen with white text and a black background
text.AddText("hello world", 10, 10, Id="Start", invert=True)

Notes

PapirusTextPos will take into account \n as a line break (or multiple line breaks) Meaning text will be aligned to the X position given, it will not return to x=0 for the start of the next line.

When the text is longer than will fit on a single line, PapirusTextPos will break the text into multiple lines. You can limit the number of lines by specifying the parameter maxLines in the AddText() method.

When using the PapirusTextPos, in either mode, setting the "partialUpdates" property to True will cause partial updates to be done, meaning only the section of the PaPiRus screen that has been changed will be updated. These can be vastly quicker than a full update for each piece of text.

If not using the "partialUpdates" property, calling WriteAll(True) will do the same thing on a one off basis.

Unicode Support in the Text API

from papirus import PapirusText

text = PapirusText()

# Write text to the screen, in this case forty stars alternating black and white
# note the use of u"" syntax to specify unicode (needed for Python 2, optional for Python 3 since unicode is default in Python 3)
text.write(u"\u2605 \u2606 \u2605 \u2606 \u2605 \u2606 \u2605 \u2606 \u2605 \u2606 \u2605 \u2606 \u2605 \u2606 \u2605 \u2606 \u2605 \u2606 \u2605 \u2606 \u2605 \u2606 \u2605 \u2606 \u2605 \u2606 \u2605 \u2606 \u2605 \u2606 \u2605 \u2606 \u2605 \u2606 \u2605 \u2606 \u2605 \u2606 \u2605 \u2606")

Note

The default font, FreeMono, has limited unicode support, so you may want to specify an alternate font to use a fuller range characters.

The Image API

from papirus import PapirusImage

image = PapirusImage([rotation = rot])

# easy write image to screen
# image.write(path)
image.write('/path/to/image')

The composite API (Text and image)

from papirus import PapirusComposite

# Calling PapirusComposite this way will mean nothing is written to the screen until WriteAll is called
textNImg = PapirusComposite(False [, rotation = rot])

# Write text to the screen at selected point, with an Id
# Nothing will show on the screen
textNImg.AddText("hello world", 10, 10, Id="Start" )

# Add image
# Nothing will show on the screen
# textNImg.AddImg(path, posX,posY,(w,h),id)
textNImg.AddImg("/path/to/image",20,20,(25,25), Id="BigImg")

# Add image to the default place and size
# Nothing will show on the screen
textNImg.AddImg("/path/to/image", Id="Top")

# Now display all elements on the screen
textNImg.WriteAll()

# Update the first line
# No change will happen on the screen
textNImg.UpdateText("Start", "New Text")

# Update the BigImg
# No change will happen on the screen
textNImg.UpdateImg("BigImg", "/path/to/new/images")

# Remove top image
# The images won't be removed from the screen yet
textNImg.RemoveImg("Top")

# Now update the screen to show the changes
textNImg.WriteAll()

Code versioning

For PaPiRus we have adopted a common definition for the major.minor.micro version number. Whenever submitting code make sure to update the version number if applicable.

• The major number should be increased whenever the API changes in an incompatible way.
• The minor number should be increased whenever the API changes in a compatible way.
• The micro number should be increased whenever the implementation changes, while the API does not.

You can change the version in the init.py.

Font family

PaPiRusText and PaPiRusTextPo