This version is compatible with Raspberry Pi OS Bullseye and does not work properly with Buster.

PaperPi is a lovely, quiet, slow internet e-Paper radio. 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.

To get started, jump to the Setup Instructions.

• Works with almost all of the WaveShare SPI displays out of the box with minimal setup or configuration
• Supports RGB screens
• Scales plugin output to match your display size from tiny 2" 1 bit displays all the way to 10" HD 8 bit displays
• Supports an open and hackable plugin architecture
• Easy install and configuration
• Quiet, low distraction display with just the content you want
• Looks great on your desk or in your living room

For information on building a frame, case and custom cable, see these instructions.

PaperPi supports many different plugins and multiple layouts for each plugin that can provide different data.

LMS Client: two_column_three_row	LMS Client: two_rows_text_only

Some plugins, marked with RGB, also support 7-Color Screens.

Plugin Samples

LibreSpot (spotify) Plugin RGB	Word Clock RGB	Slideshow RGB
Moon Phase	Met.no Weather RGB	Crypto Currency
Reddit Quotes RGB	XKCD Comic	Basic Clock

See the Developing Plugins guide for more information on creating your own plugins.

See the Change Log for a complete list of updates

V 0.5

• PaperPi migrated to EPD Lib V0.6
• 7 Color, RGB screens now supported. NB! 2/3 Color screens are only supported in 1 bit black/white mode
• Stalled plugins now timeout after a configurable time

V 0.4.1

• PaperPi is no longer distributed as a PyInstaller frozen blob and now installs into /usr/local/paperpi and 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/plugins without rebuilding
• Add support for mirroring output
• Add additional plugins
• Add mirror option

PaperPi is compatible Raspberry Pi OS Bookworm.

• Raspberry Pi (Pi 4, Pi 3, and Pi Zero)
• Raspberry Pi OS Bookworm
• WaveShare EPD Screen with PiHat
  • see the full list of currently supported screens
  • Note: HDMI screens are not supported

• 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)

PaperPi plugins work with a variety of other software such as Logitech Media Server and Spotify. Check the Plugin documentation for further instructions

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.

Check here if you'd like a step-by-step guide.

To get started, copy and paste the following command into a terminal window on your Raspberry Pi to download the latest stable version of PaperPi and automatically start the install and setup process.

Stable

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/txoof/PaperPi/main/install/remote_install.sh)"

Development

curl -fsSL https://raw.githubusercontent.com/txoof/PaperPi/main/install/remote_install.sh | /bin/bash -s -- -b development

Self Install

If you would rather install PaperPi yourself without running a remote script, clone this repo and run ./install/install.sh from within the repo root.

Other Branches

If you would like to remote install from a different remote branch, use:

curl -fsSL https://raw.githubusercontent.com/txoof/PaperPi/main/install/remote_install.sh | bash -s -- -b REPLACE_WITH_BRANCH_NAME

Daemon Mode

The installer should prompt you to edit /etc/default/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

The configuration file is kept in /etc/default/paperpi.ini for the daemon and ~/.config/com.txoof.paperpi/paperpi.ini when run as a user.

The configuration file is written as a ini style file. Each section is defined by square brackets [Section Name]. White space and comments are ignored. Variables are formatted one-per-line: variable_name = value. Strings should not be quoted.

The configuration file has sample values for each plugin that should work for most installations. Plugins such as the LMS and Spotify plugins require configuration.

Configuration Structure

[main]: The global configuration variables

• display_type (string): Name of display
• vcom (float): negative floating point value printed on the ribbon cable of HD screens (e.g. -1.93)
• max_refresh (integer): maximum number of screen refreshes before a total (flashing) wipe (only applies to HD screens)
• splash (boolean): True to display the splash screen on boot; False to launch directly into the display loop
• rotation (integer): rotate the screen 0, 90, 180, 270 degrees. Most screens are oriented with the ribbon cable at the bottom.
• mirror (boolean): True to flip the content. This is useful if everything appears backwards on your screen

[Plugin: Human Readable Plugin Name]: Per-plugin configuration

Plugins configurations are always in square brackets and must start with the string Plugin: . Plugins that have leading characters are ignored and treated as disabled.

The same plugin can be configured multiple times in the same instance. For example, you may want to track multiple LMS players, or display weather for multiple locations.

Each plugin has the following required values and may have values specific to the configuration of the plugin. For example your location. Check the Plugin Documentation for more information.

• plugin (string): plugin_name - this is the exact name of the plugin and can be found on the plugin documentation page
• layout (string): name of layout to use. See the plugin page for an example of every supported layout for each plugin. Every plugin should have a default layout called layout.
• refresh_rate (integer): time in seconds before refreshing the data for this plugin. Some plugins connect to external APIs that discourage high rates of requests. A value of around 30-120 seconds is probably good for most plugins.
• min_display_time (integer): time in seconds that represents the minimum amount of time the plugin should be displayed before cycling to another plugin. Setting this to a value lower than the screen-clear time for your screen is a mistake.
• max_priority (integer): lower value plugins take priority over higher values. This should be left alone unless you're sure you know what you are doing.

Most plugins should have a maximum priority of 2. This is the default level for plugins that passively cycle. Some plugins such as the Spotify and LMS plugin set their priority to something like 3 when there is no relevant information to display. The value of 3 excludes them from the display loop. When music starts playing, the priority moves to a value of 0 to ensure that the rest of the plugins are displayed. Check the LMS plugin documentation for a full explanation.

To uninstall PaperPi, run /usr/bin/local/paperpi/install.sh with either -u to uninstall or -p to uninstall and remove all configuration files.

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

If you would like to develop for PaperPi or create plugins for PaperPi, you will likely need a working build environment. You can also hack on fonts and layouts directly on an existing install.

• python 3.11+

Create a Build Environment

1. Clone the repo: https://github.com/txoof/PaperPi
2. Run $ ./utilities/init_devel_environment.sh to create a build environment
   • This will check for all necessary libraries and python modules and create a local venv for development

PRs are always welcome! Plugins can be pure python, but should follow the guide provided.

Virtually all WaveShare E-Paper screens are now supported!

• WaveShare 7-Color displays are now fully supported
• HD IT8951 Screens support partial refresh, fast update and 8 bit gray scale
• 2 and 3 Color screens (b/c variants) are only supported in Black/White mode

Most of the WaveShare screens that support 2/3 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.

Hardware Issues See the troubleshooting guide

Software Bugs Please open tickets at GitHub.

If you're interested in helping out, check out the issues and jump in. Collaborators are always welcome

• @blbal - typos
• @aaronr8684 - writing installer, catching hundreds of errors and generally be a great person
• @veebch - inspiration for Reddit and Crypto plugins
• @PaperCloud10 - testing of new versions and debugging slideshow plugin
• @VaporwareII, @harperreed - diagnosing remote installation failures