tiny-paper-display

Show pictures on a device running the tiny-paper display firmware, over its USB cable. MIT. Python 3.9+; one dependency, pyserial. pip install tiny-paper-display works after the first release. Until then, use pip install ./python from the repository root, or pip install "git+https://github.com/tiny-paper/tiny-paper-display#subdirectory=python". The guide with every step: docs/use.md (the site's "Use it" page).

Bluetooth: pip install "tiny-paper-display[bluetooth]" (adds bleak and cryptography). Make a key with the cable (setup --key: Bluetooth on, about three times the battery use, an unmeasured estimate); the key is saved in ~/.config/tiny-paper-display/keys/<name>.json (mode 0600), no system pairing. Then use the device name (tp-display-XXXX) or address; tpd.open(bluetooth=NAME, key_file=PATH) takes a key file from elsewhere (a container). Every frame is sealed (AES-CCM); a device without that key answers AUTH (bt_key.NoKey). On battery the device is found within about 22 s. Radio behaviour on real hardware is unproven until a person has tried it.

import tiny_paper_display as tpd
with tpd.open() as d:                                        # the first device found; closed at the end
    d.configure(full_every=30)                               # a setting on the device (None: default)
    d.show("photo.png", fit="fit", dither="floyd")           # path, bytes or tpd.Canvas

Picture options (fit, border, dither, depth, threshold, rotate) are per call, never sent to the device, and give the pixels of the site's Picture page (docs/spec/vectors/picture-prepare.json). JPEG and other formats need Pillow: pip install tiny-paper-display[images].

Pictures and videos from the command line: tiny-paper-display show|clear|movie|setup.

After any failure the Device stays usable and the next show sends the whole picture. group.show(...) returns, per device, the answer or the exception; the other devices go on.

show results carry prepare_ms and transfer_ms (the host's time) next to the device's ms. Measured on this machine for 1872x1404 (pytest -s python/tests/test_speed.py): fit + 4 bit without dither 0.5 s, Floyd-Steinberg 2.6 s, Canvas to PNG under 0.05 s, PNG decode 0.03 s (filter none) to 3 s (Paeth rows; install Pillow for any PNG or JPEG).

Tests, no hardware: pip install -e "./python[test]", then pytest python/tests. They replay docs/spec/vectors/usb-display.json, the same bytes the firmware's own test replays.