README.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from IPython.display import display, Markdown\n",
    "from pathlib import Path"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# PaperPi\n",
    "|     |     |\n",
    "|:---:|:---:|\n",
    "|<img src=./paperpi/plugins/splash_screen/splash_screen.layout-sample.png alt=\"Splash Screen\" width=400/> Splash Screen| <img src=./documentation/images/PaperPi_Demo_frame.gif alt=\"PaperPi\" width=400 /> PaperPi Weather Plugin|\n",
    "\n",
    "PaperPi is an e-Paper display with multiple rotating display plugins that contain dynamic content.\n",
    "\n",
    "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. \n",
    "\n",
    "\n",
    "PaperPi is written to work with almost all of the [WaveShare](https://www.waveshare.com/product/displays/e-paper.htm) 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](#supportedScreens)\n",
    "\n",
    "\n",
    "For information on building a frame, case and custom cable, see [these instructions](./documentation/Frame_Cable_Case.md).\n",
    "\n",
    "To get started, jump to the **[Setup Instructions](#setup)**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "## Plugins\n",
    "PaperPi supports many different plugins and layouts for each plugin.\n",
    "\n",
    " \n",
    "### [Complete Plugins List](./documentation/Plugins.md)\n",
    "\n",
    "| | | |\n",
    "|:-------------------------:|:-------------------------:|:-------------------------:|\n",
    "|<img src=./paperpi/plugins/librespot_client/librespot_client.layout-sample.png alt=\"librespot plugin\" width=300 />[LibreSpot (spotify) Plugin](./paperpi/plugins/librespot_client/README.md)|<img src=./paperpi/plugins/word_clock/word_clock.layout-sample.png alt=\"word clock plugin\" width=300 />[Word Clock](./paperpi/plugins/word_clock/README.md)|<img src=./paperpi/plugins/lms_client/lms_client.layout-sample.png alt=\"lms client plugin\" width=300 />[Logitech Media Server Plugin](./paperpi/plugins/lms_client/README.md)|\n",
    "|<img src=./paperpi/plugins/moon_phase/moon_phase.layout-sample.png alt=\"decimal binary clock\" width=300 />[Moon Phase](./paperpi/plugins/moon_phase/README.md)|<img src=./paperpi/plugins/met_no/met_no.layout-sample.png alt=\"met_no plugin\" width=300 />[Met.no Weather](./paperpi/plugins/met_no/README.md)|<img src=./paperpi/plugins/crypto/crypto.layout-sample.png alt=\"Crypto Currency Ticker\" width=300 />[Crypto Currency](./paperpi/plugins/crypto/README.md)|\n",
    "|<img src=./paperpi/plugins/reddit_quote/reddit_quote.layout-sample.png alt=\"reddit/r/quotes\" width=300 />[Reddit Quotes](./paperpi/plugins/reddit_quote/README.md)|<img src=./paperpi/plugins/xkcd_comic/xkcd_comic.layout-sample.png alt=\"XKCD Comic\" width=300 />[XKCD Comic](./paperpi/plugins/xkcd_comic/README.md)|<img src=./paperpi/plugins/basic_clock/basic_clock.layout-sample.png alt=\"Basic Clock\" width=300 />[Basic Clock](./paperpi/plugins/basic_clock/README.md)| |\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Changes\n",
    "See the [Change Log](./documentation/Change_Log.md) for a complete list of updates"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a name=\"requirements\"></a>\n",
    "## Requirements\n",
    "\n",
    "### Required Hardware\n",
    "* Raspberry Pi 4B, Pi3\n",
    "    - A Pi Zero is likely sufficient, but is untested at this time (Nov 2020)\n",
    "* Raspberry Pi OS Buster or later\n",
    "* [WaveShare EPD SPI-only Screen](https://www.waveshare.com/product/displays/e-paper.htm) with PiHat\n",
    "    - see the full list of currently [supported screens](#supportedScreens)\n",
    "    - UART, SPI/USB/I80 screens are **not supported** as there is no python library for diving these boards\n",
    "    \n",
    "     \n",
    "### Optional Hardware\n",
    "* [HiFiBerry hat](https://www.hifiberry.com/shop/#boards) (*optional*) \n",
    "    * 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\n",
    "    * GPIO 2x20 headers **must be added** to the HiFiBerry HAT to provide an interface for the WaveShare HAT.\n",
    "    * HiFiBerry's [DAC+ Bundle](https://www.hifiberry.com/shop/bundles/hifiberry-dac-bundle-4/) with the following configuraiton is a good choice:\n",
    "        * DAC+ Pro \n",
    "        * Acrylic Case for (RCA) AND DIGI+\n",
    "        * Raspberry Pi 4B 2GB (1GB should be sufficient as well)\n",
    "        * 16GB SD Card\n",
    "        * PowerSupply (USB C 5.1V/3A)\n",
    "        * 2x20 Pin Male Header (required for WaveShare HAT)\n",
    "\n",
    "### Optional Software\n",
    "PaperPi plugins work with a variety of other software such as Logitech Media Server and Spotify. Check the [Plugin documentation](./documentation/Plugins.md) for further instructions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a name=\"setup\"> </a>\n",
    "## Setup\n",
    "PaperPi requires only small amount of setup. \n",
    "\n",
    "### Hardware/OS Setup\n",
    "**All Waveshare Screens**\n",
    "\n",
    "The WaveShare displays require the SPI interface. SPI can be enabled through the `raspi-config` command.\n",
    "1. Enable SPI (see images below)\n",
    "    - `$ sudo raspi-config` > Interface Options > SPI > Yes\n",
    "2. Reboot\n",
    "    - `$ sudo shutdown -r now`\n",
    "    \n",
    "| |\n",
    "|:-------------------------:|\n",
    "|<img src=./documentation/images/raspi_config_00_iface_opts.png alt=\"librespot plugin\" width=500 />|\n",
    "|<img src=./documentation/images/raspi_config_01_spi.png alt=\"librespot plugin\" width=500 />|\n",
    "|<img src=./documentation/images/raspi_config_02_spi_enabled.png alt=\"librespot plugin\" width=500 />|\n",
    "\n",
    "\n",
    "### Userland Setup\n",
    "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.\n",
    "1. [Download the tarball](https://github.com/txoof/epd_display/raw/master/paperpi_latest.tgz)\n",
    "    - `$ wget https://github.com/txoof/epd_display/raw/master/paperpi_latest.tgz`\n",
    "2. Decompress the archive: `tar xvzf paperpi.tgz`\n",
    "3. Launch PaperPi: `$ ./paperpi/dist/paperpi`\n",
    "    - On the first run PaperPi will create a configuration file in `~/.config/com.txoof.paperpi/paperpi.ini` and then exit\n",
    "4. Edit the configuration file to match your needs. The default configuration will provide a reasonable starting point\n",
    "    - `$ nano ~/.config/com.txoof.paperpi/paperpi.ini`\n",
    "        - At minimum you must specify the `display_type`\n",
    "        - If you are using an HD IT8951 display, you must also set the `vcom` value which can be found on the ribon cable.\n",
    "        ```\n",
    "        # choose the display type that matches your e-paper pannel \n",
    "        display_type = epd2in7\n",
    "        # vcom value for HDIT8951 displays\n",
    "        vcom = 0.0\n",
    "        ```\n",
    "        - See the list of [supported screens](#supportedScreens) for more information\n",
    "5. Launch PaperPi again -- you should immediately see a splash screen followed shortly by the first active plugin.\n",
    "6. Press `ctrl+c` to shutdown paperpi cleanly\n",
    "    - Waveshare recommends clearing pannels to a blank state prior to long-term storage\n",
    "\n",
    "### Daemon Setup\n",
    "PaperPi is designed to run as an unattended daemon process that starts at system boot.\n",
    "\n",
    "1. [Download the tarball](https://github.com/txoof/epd_display/raw/master/paperpi_latest.tgz)\n",
    "    - `$ wget https://github.com/txoof/epd_display/raw/master/paperpi_latest.tgz`\n",
    "2. Decompress the archive: `tar xvzf paperpi.tgz`\n",
    "3. Install PaperPi as a service, run the install script: `$ sudo ./install.sh` \n",
    "    - This will:\n",
    "        * add the necessary service users and groups\n",
    "        * add a configuration file to `/etc/defaults/paperpi.ini`\n",
    "        * install PaperPi as a systemd service\n",
    "4. Edit `/etc/defaults/paperpi.ini` to configure a `display_type` and enable any plugins\n",
    "    - `$ sudo nano /etc/defaults/paperpi.ini`\n",
    "    - At minimum you must specify the `display_type`\n",
    "    - See the list of [supported screens](#supportedScreens) for more information\n",
    "5. Start PaperPi: `$ sudo systemctl restart paperpi` \n",
    "    - PaperPi will now start and restart at boot as a systemd service\n",
    "    - PaperPi may fail to clear the screen when the daemon is stopped. This a known [issue](https://github.com/txoof/epd_display/issues/19)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "## Developing PaperPi\n",
    "If you would like to develop [plugins](./documentation/Plugins.md) for PaperPi, you will likely need a working build environment. \n",
    "\n",
    "### Requirements:\n",
    "* python 3.7+\n",
    "* pipenv\n",
    "\n",
    "**Create a Build Environment**\n",
    "\n",
    "1. Clone the repo: `https://github.com/txoof/epd_display.git`\n",
    "2. Run `$ create_devel_venv.sh` to create a build environment\n",
    "    - This will check for all necessary libraries and python modules\n",
    "3. The build script will then attempt to build a binary of PaperPi using pyintsaller \n",
    "    - executables are stored in `./dist/`\n",
    "    \n",
    "**Build Paperpi**\n",
    "\n",
    "1. Create a build environment (see above)\n",
    "2. Run `$ build.sh` to create a pyinstaller one-file distributable\n",
    "3. If you've updated documentation in any plugins, be sure to rebuild the documentation with `$ pipenv run python3 create_docs.py`\n",
    "4. Submit a PR if you'd like your changes included in the official distribution"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Contributing\n",
    "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.\n",
    "\n",
    "Plugins can be pure python, but should follow the [guide provided](./documentation/Plugins.md).\n",
    "\n",
    "See [this gist](https://gist.github.com/txoof/ed4319db317f813b9e500ff190ca4a87) for a quick guide for setting up a jupyter environment on a Raspberry Pi."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a name=\"supportedScreens\"> </a>\n",
    "## Supported Screens\n",
    "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.\n",
    "\n",
    "All IT8951 Screens now support 8 bit grayscale output.\n",
    "\n",
    "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.\n",
    "\n",
    "**WaveShare Screen**\n",
    "\n",
    "NN. Board        Supported:\n",
    "--  -----        ----------\n",
    "00. epd1in02     supported: False\n",
    " * AttributeError: module does not support `EPD.display()`\n",
    "01. epd1in54     supported: True\n",
    "02. epd1in54_V2  supported: True\n",
    "03. epd1in54b    supported: True\n",
    "04. epd1in54b_V2 supported: True\n",
    "05. epd1in54c    supported: True\n",
    "06. epd2in13     supported: True\n",
    "07. epd2in13_V2  supported: True\n",
    "08. epd2in13b_V3 supported: True\n",
    "09. epd2in13bc   supported: True\n",
    "10. epd2in13d    supported: True\n",
    "11. epd2in66     supported: True\n",
    "12. epd2in66b    supported: True\n",
    "13. epd2in7      supported: True\n",
    "14. epd2in7b     supported: True\n",
    "15. epd2in7b_V2  supported: True\n",
    "16. epd2in9      supported: True\n",
    "17. epd2in9_V2   supported: True\n",
    "18. epd2in9b_V3  supported: True\n",
    "19. epd2in9bc    supported: True\n",
    "20. epd2in9d     supported: True\n",
    "21. epd3in7      supported: False\n",
    " * unsupported `EPD.Clear()` function\n",
    " * AttributeError: module does not support `EPD.display()`\n",
    "22. epd4in01f    supported: True\n",
    "23. epd4in2      supported: True\n",
    "24. epd4in2b_V2  supported: True\n",
    "25. epd4in2bc    supported: True\n",
    "26. epd5in65f    supported: True\n",
    "27. epd5in83     supported: True\n",
    "28. epd5in83_V2  supported: True\n",
    "29. epd5in83b_V2 supported: True\n",
    "30. epd5in83bc   supported: True\n",
    "31. epd7in5      supported: True\n",
    "32. epd7in5_HD   supported: True\n",
    "33. epd7in5_V2   supported: True\n",
    "34. epd7in5b_HD  supported: True\n",
    "35. epd7in5b_V2  supported: True\n",
    "36. epd7in5bc    supported: True\n",
    "37. All IT8951 Based Panels"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a name=\"knownIssues\"> </a>\n",
    "## Isuses\n",
    "**Hardware Issues**\n",
    "See the [troubleshooting guide](./documentation/Troubleshooting.md)\n",
    "\n",
    "**Software Bugs**\n",
    "Please [open tickets at GitHub](https://github.com/txoof/epd_display/issues)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# prepare table of EPD modules\n",
    "from epdlib.Screen import *\n",
    "list_compatible_modules()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[NbConvertApp] Converting notebook README.ipynb to markdown\n",
      "[NbConvertApp] Writing 11466 bytes to README.md\n"
     ]
    }
   ],
   "source": [
    "!jupyter-nbconvert --to markdown --template md_nocode README.ipynb"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "celltoolbar": "Edit Metadata",
  "kernelspec": {
   "display_name": "epd_display-ApAYs8Kw",
   "language": "python",
   "name": "epd_display-apays8kw"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}