Package: papirus
PaPiRusYou can find here a variety of software, hardware and other resources for thePaPiRusrange of ePaper eInk displays fromPi Supply. This repository is based on, and makes use of, therePaper/gratis GitHub repository.You can purchase one of the PaPiRus boards fromour webshopor from a variety of resellers worldwide.Setup PaPiRusAuto InstallationJust run the following script in a terminal window and PaPiRus will be automatically setup.# Run this line and PaPiRus will be setup and installedcurl-sSLhttps://pisupp.ly/papiruscode|sudobashManual InstallationIf 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 supportThe 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 PiBefore using PaPiRus, do not forget to enable the SPI and the I2C interfaces.
You can enable the SPI by typingsudo raspi-configat the command line and then selectingInterfacing options>SPIand then selecting Enable. Without exiting the tool still inInterfacing options>I2Cand then selecting Enable.Install Python API (best to run all of these commands as root using sudo)# Install dependenciessudoapt-getinstallgitbci2c-toolsfonts-freefont-ttfwhiptailmakegcc-y# For Python 2sudoapt-getinstallpython-pilpython-smbuspython-dateutil-y# For Python 3sudoapt-getinstallpython3-pilpython3-smbuspython3-dateutilpython3-distutils-y

gitclone--depth=1https://github.com/PiSupply/PaPiRus.gitcdPaPiRus# For Python 2sudopythonsetup.pyinstall# Install PaPirRus python library# For Python 3sudopython3setup.pyinstall# Install PaPirRus python libraryInstall Driver (Option 1) (best to run all of these commands as root using sudo)sudopapirus-setup# This will auto install the driverInstall Driver (Option 2) (best to run all of these commands as root using sudo)# Install fuse driversudoapt-getinstalllibfuse-dev-y

mkdir/tmp/papiruscd/tmp/papirus
gitclonehttps://github.com/repaper/gratis.gitcd/tmp/papirus/gratis
makerpiEPD_IO=epd_io.hPANEL_VERSION='V231_G2'sudomakerpi-installEPD_IO=epd_io.hPANEL_VERSION='V231_G2'sudosystemctlenableepd-fuse.service
sudorebootSelect your screen sizesudopapirus-set[1.44|1.9|2.0|2.6|2.7]or
sudopapirus-configPython APINOTE:In the following examples whererotation = rotrot 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 APIfrompapirusimportPapirus# The epaper screen object.# Optional rotation argument: rot = 0, 90, 180 or 270 degreesscreen=Papirus([rotation=rot])# Write a bitmap to the epaper screenscreen.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 durationscreen.fast_update()# Disable automatic use of LM75B temperature sensorscreen.use_lm75b=FalseThe Text APIfrompapirusimportPapirusTexttext=PapirusText([rotation=rot])# Write text to the screen# text.write(text)text.write("hello world")# Write text to the screen specifying all optionstext.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)frompapirusimportPapirusTextPos# 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 awaytext.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 awaytext.AddText("Another line",Id="Top")# Update the first line# "hello world" will disappear and "New Text" will be displayed straight awaytext.UpdateText("Start","New Text")# Remove The second line of text# "Another line" will be removed from the screen straight awaytext.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)frompapirusimportPapirusTextPos# Calling PapirusTextPos this way will mean nothing is written to the screen by defaulttext=PapirusTextPos(False[,rotation=rot])# Write text to the screen at selected point, with an Id# Nothing will show on the screentext.AddText("hello world",10,10,Id="Start")# Add another line of text, at the default location# Nothing will show on the screentext.AddText("Another line",Id="Top")# Now display BOTH lines on the screentext.WriteAll()# Update the first line# No change will happen on the screentext.UpdateText("Start","New Text")# Remove the second line of text# The text won't be removed from the screen yettext.RemoveText("Top")# Now update the screen to show the changestext.WriteAll()The Positional Text API (example 3)frompapirusimportPapirusTextPos# 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 backgroundtext.AddText("hello world",10,10,Id="Start",invert=True)NotesPapirusTextPos 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 parametermaxLinesin theAddText()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, callingWriteAll(True)will do the same thing on a one off basis.Unicode Support in the Text APIfrompapirusimportPapirusTexttext=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")NoteThe default font, FreeMono, haslimited unicode support, so you may want to specify an alternate font to use a fuller range characters.The Image APIfrompapirusimportPapirusImageimage=PapirusImage([rotation=rot])# easy write image to screen# image.write(path)image.write('/path/to/image')The composite API (Text and image)frompapirusimportPapirusComposite# Calling PapirusComposite this way will mean nothing is written to the screen until WriteAll is calledtextNImg=PapirusComposite(False[,rotation=rot])# Write text to the screen at selected point, with an Id# Nothing will show on the screentextNImg.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 screentextNImg.AddImg("/path/to/image",Id="Top")# Now display all elements on the screentextNImg.WriteAll()# Update the first line# No change will happen on the screentextNImg.UpdateText("Start","New Text")# Update the BigImg# No change will happen on the screentextNImg.UpdateImg("BigImg","/path/to/new/images")# Remove top image# The images won't be removed from the screen yettextNImg.RemoveImg("Top")# Now update the screen to show the changestextNImg.WriteAll()Code versioningFor 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 theinit.py.Font familyPaPiRusText and PaPiRusTextPos are using the fontFreeMono.ttfby default. It is possible to specify the argumentfont_pathinPapirusText.write,PapirusTextPos.AddText,PapirusTextPos.UpdateTextandPapirusTextPos.addToImageTextto change thefont family. The argument must be a string containing the path to the.ttffile.# Change font family
from papirus import PapirusText
text = PapirusText()
text.write("Hello World", fontPath='/path/to/ttf')Command Line# Set the screen size you are usingpapirus-set[1.44|1.9|2.0|2.6|2.7]# Write data to the screenpapirus-write"Some text to write"[-x][-y][-fsize][-rot][-inv]# Draw image on the screenpapirus-draw/path/to/image-t[resize|crop]-r[0|90|180|270][-i]# Clear the screenpapirus-clearNote:The line break '\n' is not converted by the shell (bash). In order to do this you need to use the method describedhere. For example:papirus-write $'hello\nWorld'. Bear in mind that you need to use single quotes after the '$', double quotes do not work.DemosAll demos can be seen by running the following commands. Code can be found in the repo for the python bin directory.# Board and screen diagnosticpapirus-test# Show clockpapirus-clock[rotation]# Run game of lifepapirus-gol# Show system informationpapirus-system# Push framebuffer to screenpapirus-framepush(comingsoon)# Demo of using the buttonspapirus-buttons[rotation]# Demo of getting temperature from LM75papirus-temp[rotation]# Demo showing effect of fast updatepapirus-radar# Display text filling the width of the displaypapirus-textfill'Some text'[rotation]# Snake gamepapirus-snake# Display Twitter feedspapirus-twitter# Composite text and graphicspapirus-composite-write# Copy framebuffer (text console or desktop) to PaPiRus using the buttons to zoom and pan# Only for 2.7" and 2.0" displayspapirus-fbcopy# Display image sequences or slideshow# For an animation, the directory containing the images must have numbered images in the form 0.gif, 1.gif, 2.gif, etc.# Otherwise the images will be displayed in filename order.papirus-animation[--delayDELAY][--rotationROTATION][--fullupdate][--loop]directory# Take a picture with the RPi camera using the PaPiRus screen as viewfinder# Only for 2.7" and 2.0" displayspapirus-camDemos for using the Real Time Clock of the PaPiRus HATThe PaPiRus HAT has a battery backed-up Real Time Clock. For more information about the RTC and demos see theRTC-Hat-Examplesdirectory and README files.Tips for using imagesThe PaPiRus can only display Bitmap images (.BMP) in black and white (1 bit colour). If you pass an image to PaPiRus
that is not a 1 Bit Bitmap, it will automatically be converted to this by the software. However, for best results
and higher image quality we would recommend that you convert the image to a 1 Bit Bitmap before pushing to the
PaPiRus screen using GIMP or Photoshop or similar photo editing tools likethe rePaper companionto resize images and convert them to XBM format
orWIF (the WyoLum Image Format).Screen ResolutionsThe screens have the following screen resolutions:1.44"     128 x 96
1.9"      144 x 128
2.0"      200 x 96
2.6"      232 x 128
2.7"      264 x 176Refresh rates and screen lifespanA typical ePaper refresh rate for a full-screen update is around 1 to 2 Hz (1 to 2 updates per second). The refresh rate of the ePaper displays is dependent on a number of factors including temperature. At lower temperatures you have to drive the display more slowly otherwise you can get "ghosting" and also can damage the display.Lastly, a good way to increase the refresh rate of information on the screen is to not use full screen updates but use partial updates as described below.Full and Partial UpdatesAlso try using the method partial_update() instead of the update() one if you want to refresh the screen faster and maybe want to create some simple animations. Remember though that the partial method cannot be used indefinitely.
You should refresh the screen using a Full Update every few minutes and it is also recommended to completely power down the screen every few hours.Fast UpdateFast Update works the same as Partial Update, except the refresh rate is not dependent on temperature but can be set by the user. The refresh duration for this mode is set in milliseconds by writing to/dev/epd/pu_stagetime. See the papirus-radar demo code for details.
Using this mode is only advised if you know what you are doing as it will severely reduce the life of the display and may cause other bizarre side-effects.
As with the Partial Update mode you should refresh the screen using a Full Update every few minutes and it is also recommended to completely power down the screen every few hours.Hardware tipsIn case you have problems assembling the board pleasecheck this article on our websiteon which you can find:Connect the screen to the PaPiRus boardConnect the GPIO adapterInstall the pogo pin connectorInstall the push buttonsPlease note: Not all the sections apply to both the PaPiRus HAT and the PaPiRus Zero.Datasheets, connectivity, pinout, jumpers and further informationFor additional information follow the links below:PaPiRus HATPaPiRus ZeroPinout.xyz resourcesThird party software librariesIt is safe to say we have an awesome and growing community of people using epaper with PaPiRus and beyond and we get a huge amount of contributions of code, some of which we can easily integrate here and others which we can't (we are only a small team). However we want to make sure that any contributions are easy to find, for anyone looking. So here is a list of other software libraries that might be useful to you (if you have one of your own, please visit the"Issues"tab above and let us know!):Go software library for driving PaPiRusRISC OS software library for driving PaPiRusPaPiRus HAT working with resin.ioRaspberry Pi Internal Watchdog Setup and InformationBaseball Pi - get the live box score, plays, and batter stats of your favorite MLB team right on your desktopPaPiRus Netapp (find Raspberry Pi’s on your network, run a speed test of your internet connection, show a graph of your past speed test results) -blog hereandGitHub Repo herePaPiRus Ruby gem for the Raspberry Pi PaPiRus eInk screenPaPiRuby - Ruby wrapper for the Raspberry Pi PaPiRus eInk screenPower outage monitor (using PiJuice and PaPiRus) by Frederick Vandenbosch.You can find pictures and code here