PaperPi V3
NOTE
This version of PaperPi is under heavy development and is not ready for the average user. We are working on adding more screen compatibility, possibly adding color screen support for inkyPHAT and WaveShare 3 color screens. There are also plans to make plugins easier to install and update.
See our Milestones here. PRs, bug reports, contributions, and testers are welcome.
This version is compatible with Raspberry Pi OS Bullseye and does not work properly with Buster.
The stable version of PaperPi can be found here.
 Splash Screen |
 PaperPi Weather Plugin |
About PaperPi
PaperPi is an e-Paper display with multiple rotating display plugins that contain dynamic content.
PaperPi is a quiet and clean portal to the internet. No loud colors, no busy animations, just a lovely selection of the information you want without buzz and distraction. PaperPi rotates through your choice of plugin screens at the pace you choose.
PaperPi is written to work with almost all of the WaveShare SPI displays out of the box. PaperPi will work with the tiny 2" displays all the way up to the 10" HD displays with minimal configuration. Check the complete list of supported screens below.
For information on building a frame, case and custom cable, see these instructions.
To get started, jump to the Setup Instructions
Plugins
PaperPi supports many different plugins and layouts for each plugin.
Complete Plugins List
 LibreSpot (spotify) Plugin |
 Word Clock |
 Logitech Media Server Plugin |
 Moon Phase |
 Met.no Weather |
 Crypto Currency |
 Reddit Quotes |
 XKCD Comic |
 Basic Clock |
See the Developing Plugins guide for more information on creating your own plugins.
Changes
See the Change Log for a complete list of updates
V 0.3.0
- PaperPi is no longer distributed as a PyInstaller frozen blob and now installs into
/usr/local/paperpiand places an executable entry script in/usr/local/bin/. - Plugins can now be edited easily in
/usr/local/paperpi/plugins/ - Additional plugins can be placed in
/usr/local/paperpi/pluginswithout rebuilding - Add support for mirroring output
PaperPi Requirements
PaperPi is compatible with Raspberry Pi OS Bullseye. Some python dependencies such as numpy will not build properly under Buster.
Required Hardware
- Raspberry Pi (Pi 4, Pi 3, and Pi Zero)
- Raspberry Pi OS Buster or later (64-bit supported)
- WaveShare EPD Screen with PiHat
- see the full list of currently supported screens
- Note: HDMI screens are not supported
Optional Hardware
- HiFiBerry hat (optional)
- The HiFiBerry DAC+ PRO and similar boards add high-quality audio output to the Pi so it can act as a display and also work as a LMS client player using squeezelite
- GPIO 2x20 headers must be added to the HiFiBerry HAT to provide an interface for the WaveShare HAT.
- HiFiBerry's DAC+ Bundle with the following configuration is a good choice:
- DAC+ Pro
- Acrylic Case for (RCA) AND DIGI+
- Raspberry Pi 4B 2GB (1GB should be sufficient as well)
- 16GB SD Card
- PowerSupply (USB C 5.1V/3A)
- 2x20 Pin Male Header (required for WaveShare HAT)
Optional Software
PaperPi plugins work with a variety of other software such as Logitech Media Server and Spotify. Check the Plugin documentation for further instructions
Install & Setup
PaperPi requires only small amount of setup and is packaged with amateurs in mind. By default PaperPi will install as a daemon service that will start at boot.
Install
To get started, copy and paste the following command into a terminal window to download the latest stable version of PaperPi and automatically start the install and setup process.
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/txoof/PaperPi/main/install/remote_install.sh)"
If you would rather install PaperPi yourself, clone this repo and run ./install/install.sh
Setup
Daemon Mode
The installer should prompt you to edit /etc/defaults/paperpi.ini. At minimum you must add your EPD Screen and enable several plugins. A complete list of supported EPD Screens are listed below.
Any changes to the PaperPi configuration require a restart of the service:
sudo systemctl restart paperpi-daemon.service
To disable the service from starting on boot, run the command:
sudo systemctl disable paperpi-daemon.service
On Demand
If you would rather run PaperPi on-demand rather than a daemon service you can run it as regular user (e.g. pi) by running /usr/local/bin/paperpi. A new configuration file will be created in your user's directory. Make sure to edit this file and add, at minimum, your EPD Screen.
PaperPi can be run on demand in daemon mode using paperpi -d
Uninstall
To uninstall PaperPi, run ./install/install.sh with either -u to uninstall or -p to uninstall and remove all configuration files.
Command Reference
usage: paperpi.py [-h] [--add_config plugin user|daemon] [-c CONFIG_FILE.ini]
[-l LOG_LEVEL] [-d] [--list_plugins]
[--plugin_info [plugin|plugin.function]]
[--run_plugin_func plugin.function [optional_arg1 arg2 argN ...]]
[-V]
optional arguments:
-h, --help show this help message and exit
--add_config plugin user|daemon
copy sample config to the user or daemon configuration
file
-c CONFIG_FILE.ini, --config CONFIG_FILE.ini
use the specified configuration file
-l LOG_LEVEL, --log_level LOG_LEVEL
change the log output level
-d, --daemon run in daemon mode (ignore user configuration if
found)
--list_plugins list all available plugins
--plugin_info [plugin|plugin.function]
get information for plugins and user-facing functions
provided by a plugin
--run_plugin_func plugin.function [optional_arg1 arg2 argN ...]
run a user-facing function for a plugin
-V, --version display version and exit
--add_config plugin user|daemon: add a configuration file for plugin to the user configuration or daemon configuration files
-c/--config CONFIG_FILE.ini: Use the specified CONFIG_FILE instead of the default
-l/--log_level DEBUG|INFO|WARNING|ERROR: Specify the logging level from the command line
--list_plugins: List all plugins that have been found.
--plugin_info plugin|plugin.function: Print help information for a plugin and all of it's helper functions or a specific plugin.function
--run_plugin_func plugin.function Some plugins provide helper functions such as determining the LAT/LON of a location (met_no, moon_phases) or finding local Logitech Media Servers (lms_client). --run_plugin_func runs a plugin helper function. Use --plugin_info to learn more.
-V/--version: Display version information and exit
Developing PaperPi
If you would like to develop plugins for PaperPi, you will likely need a working build environment.
Requirements
- python 3.7+
- pipenv
Create a Build Environment
- Clone the repo:
https://github.com/txoof/PaperPi - Run
$ ./utilities/create_devel_environment.shto create a build environment- This will check for all necessary libraries and python modules and create a local venv for development
Contributing
Plugins can be pure python, but should follow the guide provided.
Supported Screens
Most NON-IT8951 screens are only supported in 1 bit (black and white) mode. Color output is not supported at this time. Some waveshare drivers do not provide 'standard' display and Clear methods; these displays are not supported at this time.
All IT8951 Screens now support 8 bit grayscale output.
Some WaveShare screens that support color output will also work with with the non-colored driver. Using the 1 bit driver can yield significantly better update speeds. For example: the waveshare_epd.epd2in7b screen takes around 15 seconds to update even when refreshing a 1 bit image, but can be run using the waveshare_epd.epd2in7 module in 1-bit mode which takes less than 2 seconds to update.
WaveShare Screen
NN. mfg.name
- inky.auto
- inky.impression
- inky.phat1608_black
- inky.phat1608_red
- inky.phat1608_yellow
- inky.phat_black
- inky.phat_red
- inky.phat_yellow
- inky.what_black
- inky.what_red
- inky.what_yellow
- omni_epd.mock
- waveshare_epd.epd1in02
- waveshare_epd.epd1in54
- waveshare_epd.epd1in54_V2
- waveshare_epd.epd1in54b
- waveshare_epd.epd1in54b_V2
- waveshare_epd.epd1in54c
- waveshare_epd.epd2in13
- waveshare_epd.epd2in13_V2
- waveshare_epd.epd2in13b
- waveshare_epd.epd2in13b_V3
- waveshare_epd.epd2in13c
- waveshare_epd.epd2in13d
- waveshare_epd.epd2in66
- waveshare_epd.epd2in66b
- waveshare_epd.epd2in7
- waveshare_epd.epd2in7b
- waveshare_epd.epd2in7b_V2
- waveshare_epd.epd2in9
- waveshare_epd.epd2in9_V2
- waveshare_epd.epd2in9b
- waveshare_epd.epd2in9b_V3
- waveshare_epd.epd2in9c
- waveshare_epd.epd2in9d
- waveshare_epd.epd3in7
- waveshare_epd.epd4in01f
- waveshare_epd.epd4in2
- waveshare_epd.epd4in2b
- waveshare_epd.epd4in2b_V2
- waveshare_epd.epd4in2c
- waveshare_epd.epd5in65f
- waveshare_epd.epd5in83
- waveshare_epd.epd5in83_V2
- waveshare_epd.epd5in83b
- waveshare_epd.epd5in83b_V2
- waveshare_epd.epd5in83c
- waveshare_epd.epd7in5
- waveshare_epd.epd7in5_HD
- waveshare_epd.epd7in5_V2
- waveshare_epd.epd7in5b
- waveshare_epd.epd7in5b_HD
- waveshare_epd.epd7in5b_V2
- waveshare_epd.epd7in5c
- waveshare_epd.it8951
Issues
Hardware Issues See the troubleshooting guide
Software Bugs Please open tickets at GitHub.
Document updated 2022.05.01
PaperPi (Development)
This is a development version of PaperPi that's not fit for prime-time yet.
The official version can be found here.
Helping Out
If you're interested in helping out, check out the issues and jump in. Collaborators are always welcome
24 Dec 17, 2022
1 Jan 22, 2022
16 Dec 7, 2022
53 Sep 25, 2022
17 Dec 10, 2022
3 Dec 25, 2021
80 Jan 7, 2023
12 Nov 2, 2022
18 Dec 26, 2022
8 Nov 28, 2022
11 Oct 28, 2022
1 Dec 20, 2021
8 Dec 6, 2022
2 Aug 6, 2022
1 Jun 15, 2022
7 Jul 15, 2022
192 Dec 28, 2022
16 Jun 19, 2022
1 Dec 18, 2021