PaperTTY

Overview

PaperTTY is a simple Python module for using affordable SPI e-ink displays as a computer monitor, with a Raspberry Pi being the typical computer interfacing with the display. Most of the tested displays are Waveshare branded, but also others - particularly ones using the IT8951 controller - might work.

Things it can display on the e-ink: | Subcommand | Description | | ---------- | --------------------------------------- | | fb | Framebuffer (/dev/fbX) | | terminal | Linux virtual console (/dev/vcs[au]X) | | vnc | VNC desktop | | image | Image files | | stdin | Standard input |

To use any feature, you need to select an appropriate driver for your e-ink display as a top-level option (papertty --driver X ...). To see the list of drivers, use papertty list.

To see help for individual subcommands, use --help with them, ie. papertty --driver X --terminal --help.

Usage

PaperTTY is currently packaged using Poetry, however it can be installed via pip too. The instructions here are for Raspberry Pi (please open an issue if you need support for another platform).

You need to enable SPI first:

• sudo raspi-config
  • Interfacing Options -> SPI -> Yes
• May want to reboot just in case

Then, you also need some system dependencies:

• sudo apt install python3-venv python3-pip libopenjp2-7 libtiff5-dev libjpeg-dev libfreetype-dev

Install with pip to virtualenv

If you just want it installed as packaged in PyPi (if you need to modify something use the Poetry way instead - also note that it is possible for the package in PyPi to not match the latest source):

python3 -m venv papertty_venv
source papertty_venv/bin/activate
pip install papertty
papertty_venv/bin/papertty --help

Install with Poetry

The "correct" way to set up PaperTTY is using Poetry. This gives you the most flexibility and handles the virtualenv creation automatically. Sometimes with VNC issues one may need to downgrade vncdotool to 0.13.0, too, which is not as easy with the pip method.

First you need to install Poetry, refer to their instructions.

Then:

git clone https://github.com/joukos/PaperTTY.git
cd PaperTTY
poetry install  # if you change something with the deps, do a `poetry update`
poetry run papertty --help

To get a direct path for the script (which will be run in the virtual environment with all the dependencies), run in the directory: echo $(poetry env info -p)/bin/papertty. Append any options you need and this is what you want to start in a SystemD unit or so, possibly with sudo depending on the OS configuration and the feature you wish to use.

The rest of this page has not been updated but is left as reference until a more holistic documentation update is actually done. If you have any issues, please search the existing issues and create a new one if necessary. joukos/2022-01-17

Warning - old stuff ahead!

---

PyPi!

This is still WIP.

You can now install PaperTTY via PyPi. The updated (simplified) documentation is still a bit unfinished and things moved around somewhat, so the rest of this page is not quite up to date yet on all details.

TL;DR:

sudo apt install python3-venv python3-pip libopenjp2-7 libtiff5 libjpeg-dev
# # optionally configure a virtualenv before running pip:
# python3 -m venv papertty_venv
# source papertty_venv/bin/activate
pip3 install papertty

---

Image display command

@colin-nolan has contributed a subcommand to display image files on the screen, allowing to test the displays or easily make a photo slideshow or similar. Try image --help to check it out.

Partial refresh support for 4.2" (2020-03-01)

Thanks to @gdkrmr, the 4.2" module now has a new driver that supports partial refresh. Note that now the default behavior is to do partial updates and you'll need to add --nopartial to driver settings if you want to use the full refresh instead.

Interactive Update (2020-02-18)

Starting terminal with the --interactive option adds a menu to the Ctrl-C handler that allows you to change the font, font size and spacing on the fly. This should be helpful when trying out fonts.

Cursor Update (2020-01-25)

The terminal mode now supports different cursors. --nocursor had been deprecated in favor of --cursor=none. The usual underscore-like cursor is set via --cursor=default, which, as the name suggests, is also the default mode. There is also a --cursor=block option, which inverts the colors at the cursor's location. Finally, there is also an option to provide a numerical value, e.g. --cursor=5, which draws an underscore cursor shifted 5 pixels towards the top; --cursor=default and --cursor=0 are thus equivalent.

Unicode Update (2020-01-22)

On systems with /dev/vcsu* (e.g. Raspbian Stretch or Buster, with kernel 4.19+) and when using a TrueType font, the terminal mode now has full support for Unicode output. This is automatic, with a fallback to 8-bit if either of these requirements isn't met. We've also changed the standard encoding for 8-bit to ISO-8859-1, which should be a little closer to what the vcs device provides.

IT8951 Optimization II (2020-01-15)

The previous optimization was improved further to speed up VNC output too. If you try it, please leave a comment at https://github.com/joukos/PaperTTY/issues/32 (and create a new issue if there's problems).

IT8951 Optimization (2020-01-11)

An optimization by @chi-lambda for the IT8951 driver was merged and may speed up the bit-packing in TTY mode even by up to 10x for these displays, so the refresh rates should be significantly better now. Please create an issue if there are problems (the unoptimized version can be checked out with the tag v0.03_unoptimized).

IT8951 Update (2019-11-03)

Support for IT8951 based displays kindly provided by @fimad has been merged. This means that Waveshare 6", 7.8", 9.7" and 10.3" may work since they use this controller. At least the 6" and 9.7" displays have been verified to work. A big thanks to everyone involved with the discussion and code contributions (https://github.com/joukos/PaperTTY/issues/25)!

If you have one of these displays and want to test it, add your experiences to https://github.com/joukos/PaperTTY/issues/32.

Here is a picture of the 9.7" in action (by @math85360):

YouTube video

VNC Update (2019-07-07)

So, it's been almost a year since last update and I've been very very busy.

Since I'm going to be even busier for the next two years or so, and probably won't have much time to spend on this project, I wanted to see if I could kludge this one last thing that I think is needed (and was referenced in https://github.com/joukos/PaperTTY/issues/23#issuecomment-435578128): a VNC client to PaperTTY.

I'm happy to announce that it works! It's not the most elegant or beautiful thing, but now you can run a graphical desktop and any programs you wish on these epaper screens. It also solves many problems and complexities with text-only terminals, namely encoding/font issues and other quirks. I've tested it with the 4.2" and the 2.13" displays.

The performance is pretty much the same as before, maybe a tad more image processing though, but the bottleneck is the display refresh anyway. All the complex stuff is done by vncdotool by Marc Sibson, since it was the most mature-seeming VNC library I could find that would work with Python 3 without extra work. It's also overkill for the job - all that's needed is to read the screen content periodically.

The way this works is pretty simple: PaperTTY will connect to the VNC server, then just reads the screen content in a loop. If the image changes, the region containing the changes will be updated on the display. This is not actually very efficient and originally I planned to have it update the native VNC "dirty rectangles", but it was simpler to kludge it like this for a start, and it seems to work fine, so it's perhaps easier to make better now.

Some benefits and features

• Run all CLI and GUI programs
• Dithers colors so you can throw anything at it and hopefully it's legible on the display
• About as fast as just using the terminal mode, but much less hassle (sort of)
• Has options for rotating and inverting the colors
• Rescales the VNC screen to fit the display (panning not implemented)
• Simplistic, surely buggy and doesn't fix the other problems PaperTTY might have

Quick start

• Install PaperTTY from PyPi:
  • pip install papertty
• Start a VNC server somewhere (on the RPi for example)
  • ie. vncserver -geometry 250x128 :1
• Run PaperTTY as usual, but use the vnc subcommand (see --help for options)
  • ie. sudo papertty --driver epd2in13 vnc --display 1 --password supAPass --sleep 0.1 --rotate 90
  • This would (by default) connect to localhost, display 1 (= port 5901), using the 2.13" driver, specifies the password, sleeps 0.1 seconds after each update, and rotates the screen by 90 degrees
• If image looks wonky, make sure you have the right orientation for the VNC server (ie. -geometry 300x400 vs. -geometry 400x300) and the correct --rotate value.

Standalone RPi with mouse and keyboard

So, you have your nice display and a RPi that you want to combine into a cool e-ink laptop, using peripherals plugged into the RPi. There's currently no automation or service files for this purpose, but what you can try is this (for the 2.13"):

• Install or enable a desktop environment / window manager, unless it already exists (ie. if you plug in the HDMI port, you should get a graphical session)
• Install