[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(3)  # lag_frames=3, seconds_per_frame=0
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, lag on

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

Test files

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

Test driver: ssd1683_lag.py (needs a lag 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_LAG. 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=6):
    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, keep_awake=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

[tannewt]

Just glanced at this. I think we will want to push back the display format info back to the gif decoder so it can do the color conversion early. I'm not sure that'll always work though because LVGL doesn't support all color modes that displayio does. In that case we'd need to color convert late.

[mikeysklar]

VideoBuffer now tells the GIF decoder the pixel format at play time.

The decoder converts to 1 bit itself.

A format the decoder can't produce raises for now. Late conversion could cover those.