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/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

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

1. Clone the repo: https://github.com/txoof/PaperPi
2. Run $ ./utilities/create_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

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

0. inky.auto
1. inky.impression
2. inky.phat1608_black
3. inky.phat1608_red
4. inky.phat1608_yellow
5. inky.phat_black
6. inky.phat_red
7. inky.phat_yellow
8. inky.what_black
9. inky.what_red
10. inky.what_yellow
11. omni_epd.mock
12. waveshare_epd.epd1in02
13. waveshare_epd.epd1in54
14. waveshare_epd.epd1in54_V2
15. waveshare_epd.epd1in54b
16. waveshare_epd.epd1in54b_V2
17. waveshare_epd.epd1in54c
18. waveshare_epd.epd2in13
19. waveshare_epd.epd2in13_V2
20. waveshare_epd.epd2in13b
21. waveshare_epd.epd2in13b_V3
22. waveshare_epd.epd2in13c
23. waveshare_epd.epd2in13d
24. waveshare_epd.epd2in66
25. waveshare_epd.epd2in66b
26. waveshare_epd.epd2in7
27. waveshare_epd.epd2in7b
28. waveshare_epd.epd2in7b_V2
29. waveshare_epd.epd2in9
30. waveshare_epd.epd2in9_V2
31. waveshare_epd.epd2in9b
32. waveshare_epd.epd2in9b_V3
33. waveshare_epd.epd2in9c
34. waveshare_epd.epd2in9d
35. waveshare_epd.epd3in7
36. waveshare_epd.epd4in01f
37. waveshare_epd.epd4in2
38. waveshare_epd.epd4in2b
39. waveshare_epd.epd4in2b_V2
40. waveshare_epd.epd4in2c
41. waveshare_epd.epd5in65f
42. waveshare_epd.epd5in83
43. waveshare_epd.epd5in83_V2
44. waveshare_epd.epd5in83b
45. waveshare_epd.epd5in83b_V2
46. waveshare_epd.epd5in83c
47. waveshare_epd.epd7in5
48. waveshare_epd.epd7in5_HD
49. waveshare_epd.epd7in5_V2
50. waveshare_epd.epd7in5b
51. waveshare_epd.epd7in5b_HD
52. waveshare_epd.epd7in5b_V2
53. waveshare_epd.epd7in5c
54. 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