[mikeysklar]

What

GIFs can now play as 1-bit video on monochrome e-paper, through displayio.

Why

A stock e-paper update takes about 6 seconds, too slow for animation.

Part 3 of 3, stacked on #11739, which is stacked on #11738.

import displayio, videocore, videogif
import ssd1683_lag
display = ssd1683_lag.make_display()  # fast=True, lag_frames=4
gif = videogif.GifDecoder("/teapot_1bit_hq.gif")
video = videocore.VideoBuffer(bytearray(50 * 300), bits_per_pixel=1)
root = displayio.Group()
root.append(video)
display.root_group = root
video.play(gif)
while True:
    if not display.busy:
        display.refresh()

lag3_nf1_hq_autoclean_wipes.mp4

Feather RP2040 ThinkInk with the 4.2" panel, filmed on an earlier build of this stack. The script also ran a wipe every 4 s and a clean every 15 s.

Change	Behavior
VideoBuffer(bits_per_pixel=1)	Rows padded to a byte, white when bright. Plain buffers only
Per-board GIF width limit	Default stays 320. Width 800 costs 480 B per open GIF
1-bit buffers on monochrome displays	New draw path. Rotated displays raise ValueError
Feather RP2040 ThinkInk	Video on, GIF width 800

Tested on Feather RP2040 ThinkInk, 4.2" SSD1683, lag 4	Result
Panel updates per second, 60 s	17.4, stock 0.16
7 ways code can end, 3 each	21/21 back to REPL, 3.6 to 6.9 s
Frame decode	16.3 ms median, 113 ms max
Flash free, all three PRs	180 KB

Test files

Test GIF: teapot_1bit_hq.gif (400x300, 120 frames at 20 ms)

Test driver: ssd1683_lag.py (needs a fast build, see #11739)

# ssd1683_lag: stand-in for a driver library. Constructs EPaperDisplay with lag drive on the
# Feather RP2040 ThinkInk + 4.2" SSD1683, 1-frame 125 Hz balanced LUT. Needs firmware built with
# CIRCUITPY_EPAPERDISPLAY_FAST. The display cleans itself: before its first refresh and when it is
# released or the code stops.
import board, busio, displayio, epaperdisplay, fourwire

NO_PINGPONG = bytes([0x00, 0xFF, 0xFF, 0xFF, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00])
VSS, VSH1, VSL = 0x00, 0x40, 0x80


def seq(c, data=b"", delay=None):
    n = len(data)
    hi = (n >> 8) | (0x80 if delay is not None else 0)
    return bytes([c, hi, n & 0xFF]) + data + (bytes([delay]) if delay is not None else b"")


def make_lut(frames, fr):
    def one(vs):
        g = bytearray(42)
        g[0:7] = bytes([1, vs | frames, 0, 0, 0, 1, 0])
        return g

    lut = bytearray(227)
    lut[0:42] = one(VSS)  # LUTC
    lut[42:84] = one(VSS)  # WW
    lut[84:126] = one(VSH1)  # BW
    lut[126:168] = one(VSL)  # WB
    lut[168:210] = one(VSS)  # BB
    lut[224] = fr
    return lut


START = (
    seq(0x12, delay=0x32) + seq(0x18, b"\x80") + seq(0x11, b"\x03") + seq(0x01, b"\x2b\x01\x00")
    + seq(0x32, make_lut(1, 0x05))  # 1 frame, frame rate byte 0x05 = 125 Hz
    + seq(0x3F, b"\x07") + seq(0x03, b"\x17") + seq(0x04, b"\x41\xa8\x32") + seq(0x2C, b"\x30")
    + seq(0x21, b"\x00\x00") + seq(0x3C, b"\x80") + seq(0x37, NO_PINGPONG)
    + seq(0x22, b"\xc0") + seq(0x20)
)
# Full refresh with the waveform stored in the panel. Runs with both RAM planes white.
CLEAN = (
    seq(0x12, delay=0x32) + seq(0x3C, b"\x05") + seq(0x18, b"\x80") + seq(0x11, b"\x03")
    + seq(0x44, b"\x00\x31") + seq(0x45, b"\x00\x00\x2b\x01") + seq(0x01, b"\x2b\x01\x00")
    + seq(0x1A, b"\x5a\x00") + seq(0x22, b"\x91") + seq(0x20) + seq(0x22, b"\xc7") + seq(0x20)
)
STOP = seq(0x10, b"\x01", delay=0x64)  # deep sleep, HV off
# Full RAM window before the update.
REFRESH = seq(0x44, b"\x00\x31") + seq(0x45, b"\x00\x00\x2b\x01") + seq(0x22, b"\x0c") + seq(0x20)


_spi = None


def release():
    # Finishes any owed drive, cleans, sleeps and frees the ring. The SPI would otherwise keep
    # the pins.
    global _spi
    displayio.release_displays()
    if _spi is not None:
        _spi.deinit()
        _spi = None


def make_display(lag=4):
    global _spi
    release()
    spi = _spi = busio.SPI(board.EPD_SCK, board.EPD_MOSI)
    bus = fourwire.FourWire(spi, command=board.EPD_DC, chip_select=board.EPD_CS,
                            reset=board.EPD_RESET, baudrate=20_000_000)
    return epaperdisplay.EPaperDisplay(
        bus, START, STOP, clean_sequence=CLEAN, width=400, height=300, ram_width=50, ram_height=300,
        busy_pin=board.EPD_BUSY, busy_state=True, seconds_per_frame=0,
        refresh_display_command=REFRESH, write_black_ram_command=0x24,
        write_previous_ram_command=0x26, fast=True, lag_frames=lag,
        set_column_window_command=0x44, set_row_window_command=0x45,
        set_current_column_command=0x4E, set_current_row_command=0x4F,
        address_little_endian=True, two_byte_sequence_length=True)

Display	Result
Monochrome e-paper	Draws (board)
Sharp, tricolor, 16-bit, rotated	From source only, see docs

Video uses the fast updates from #11739, so its panel warning applies here.

AI assistance

Written with Claude Code.

🤖 Generated with Claude Code

[mikeysklar]

Merged main and resolved the conflict with #11829.

The 1-bit copy now follows display rotation too, using the same mapping as the 16-bit path.

Tested on a Feather RP2040 ThinkInk,.

Rotation	Video matches TileGrid
0	Yes
90	Yes
180	Yes
270	Yes

Also turned off gifio on the following due to lack of flash:

• makerdiary nRF52840 dongle