epd_display/PaperPi

NOTE: Project Archived

This project has been migrated to PaperPi and is no longer maintained. PaperPi offers all of the same functionality, but a cleaner install process, a more open and flexible plugin structure and removes the need for a frozen binary.

This repository is maintained only for hitorical purposes. Check the new version for updates!

Splash Screen	PaperPi Weather Plugin

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

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

Changes

See the Change Log for a complete list of updates

Requirements

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

Setup

PaperPi requires only small amount of setup.

Hardware/OS Setup

All Waveshare Screens

The WaveShare displays require the SPI interface. SPI can be enabled through the raspi-config command.

1. Enable SPI (see images below)
   • $ sudo raspi-config > Interface Options > SPI > Yes
2. Reboot
   • $ sudo shutdown -r now

Userland Setup

PaperPi can be run directly on-demand from a user account such as the default "pi" user. Any other user will work as well, but the user must be a member of the spi group.

1. Download the tarball
   • $ wget https://github.com/txoof/epd_display/raw/master/paperpi_latest.tgz
2. Decompress the archive: tar xvzf paperpi.tgz
3. Launch PaperPi: $ ./paperpi/dist/paperpi
   • On the first run PaperPi will create a configuration file in ~/.config/com.txoof.paperpi/paperpi.ini and then exit
4. Edit the configuration file to match your needs. The default configuration will provide a reasonable starting point
   • $ nano ~/.config/com.txoof.paperpi/paperpi.ini
     • At minimum you must specify the display_type
     • If you are using an HD IT8951 display, you must also set the vcom value which can be found on the ribon cable.

     # choose the display type that matches your e-paper pannel 
     display_type = epd2in7
     # vcom value for HDIT8951 displays
     vcom = 0.0
     

     • See the list of supported screens for more information
5. Launch PaperPi again -- you should immediately see a splash screen followed shortly by the first active plugin.
6. Press ctrl+c to shutdown paperpi cleanly
   • Waveshare recommends clearing pannels to a blank state prior to long-term storage

Daemon Setup

PaperPi is designed to run as an unattended daemon process that starts at system boot.

1. Download the tarball
   • $ wget https://github.com/txoof/epd_display/raw/master/paperpi_latest.tgz
2. Decompress the archive: tar xvzf paperpi.tgz
3. Install PaperPi as a service, run the install script: $ sudo ./install.sh
   • This will:
     • add the necessary service users and groups
     • add a configuration file to /etc/defaults/paperpi.ini
     • install PaperPi as a systemd service
4. Edit /etc/defaults/paperpi.ini to configure a display_type and enable any plugins
   • $ sudo nano /etc/defaults/paperpi.ini
   • At minimum you must specify the display_type
   • See the list of supported screens for more information
5. Start PaperPi: $ sudo systemctl restart paperpi
   • PaperPi will now start and restart at boot as a systemd service
   • PaperPi may fail to clear the screen when the daemon is stopped. This a known issue.

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/epd_display.git
2. Run $ create_devel_venv.sh to create a build environment
   • This will check for all necessary libraries and python modules
3. The build script will then attempt to build a binary of PaperPi using pyintsaller
   • executables are stored in ./dist/

Build Paperpi

1. Create a build environment (see above)
2. Run $ build.sh to create a pyinstaller one-file distributable
3. If you've updated documentation in any plugins, be sure to rebuild the documentation with $ pipenv run python3 create_docs.py
4. Submit a PR if you'd like your changes included in the official distribution

Contributing

PaperPi's core is written and maintained in Jupyter Notebook. If you'd like to contribute, please make pull requests in the Jupyter notebooks. Making PRs to the .py files means manually moving the changes into the Jupyter Notebook and adds considerable work to the build/test process.

Plugins can be pure python, but should follow the guide provided.

See this gist for a quick guide for setting up a jupyter environment on a Raspberry Pi.

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 epd2in7b screen takes around 15 seconds to update even when refreshing a 1 bit image, but can be run using the epd2in7 module in 1-bit mode which takes less than 2 seconds to update.

WaveShare Screen

NN. Board Supported:

---

0. epd1in02 supported: False

• AttributeError: module does not support EPD.display()

1. epd1in54 supported: True
2. epd1in54_V2 supported: True
3. epd1in54b supported: True
4. epd1in54b_V2 supported: True
5. epd1in54c supported: True
6. epd2in13 supported: True
7. epd2in13_V2 supported: True
8. epd2in13b_V3 supported: True
9. epd2in13bc supported: True
10. epd2in13d supported: True
11. epd2in66 supported: True
12. epd2in66b supported: True
13. epd2in7 supported: True
14. epd2in7b supported: True
15. epd2in7b_V2 supported: True
16. epd2in9 supported: True
17. epd2in9_V2 supported: True
18. epd2in9b_V3 supported: True
19. epd2in9bc supported: True
20. epd2in9d supported: True
21. epd3in7 supported: False

• unsupported EPD.Clear() function
• AttributeError: module does not support EPD.display()

22. epd4in01f supported: True
23. epd4in2 supported: True
24. epd4in2b_V2 supported: True
25. epd4in2bc supported: True
26. epd5in65f supported: True
27. epd5in83 supported: True
28. epd5in83_V2 supported: True
29. epd5in83b_V2 supported: True
30. epd5in83bc supported: True
31. epd7in5 supported: True
32. epd7in5_HD supported: True
33. epd7in5_V2 supported: True
34. epd7in5b_HD supported: True
35. epd7in5b_V2 supported: True
36. epd7in5bc supported: True
37. All IT8951 Based Panels

Isuses

Please open tickets at GitHub.