Simple test

Ensure your device works with this simple test. It plays examples/testpattern.rv565 on any board with a built-in display (board.DISPLAY).

examples/rv565_simpletest.py

# SPDX-FileCopyrightText: 2026 Ayushman Bhattacharya
# SPDX-License-Identifier: MIT
"""Play an RV565 clip on a board with a built-in display (board.DISPLAY).

Copy circuitpython_rv565.py (or .mpy) to CIRCUITPY/lib and
examples/testpattern.rv565 to the root of CIRCUITPY, then run this as code.py.
"""

import board

import circuitpython_rv565 as rv565

clip = rv565.open("/testpattern.rv565")
print("RV565 %dx%d, %d FPS, %d frames" % (clip.width, clip.height, clip.fps, len(clip)))

player = rv565.Player(clip, board.DISPLAY)
while True:
    stats = player.play()
    print(stats)  # achieved FPS, skipped frames, inflate and draw time per frame

Raspberry Pi Pico 2 and ST7789

A 2.0” 320x240 ST7789 on SPI0, drawn through displayio.

examples/rv565_pico2_st7789.py

# SPDX-FileCopyrightText: 2026 Ayushman Bhattacharya
# SPDX-License-Identifier: MIT
"""Raspberry Pi Pico 2 with a 2.0" 320x240 ST7789 on SPI0, through displayio.

Wiring (the same as the RV565 Pico 2 benchmark):
SCK GP18, MOSI GP19, CS GP17, DC GP20, RST GP21, BL GP22, plus 3V3 and GND.

CIRCUITPY needs:
  lib/circuitpython_rv565.py
  lib/adafruit_st7789.mpy   (from the Adafruit CircuitPython bundle)
  testpattern.rv565          (from examples/ in this repository)

Keep clips at 180x135 or smaller on the Pico 2: a 320x240 frame needs 150 KiB
for the inflated bytes and as much again for the bitmap.
"""

import board
import busio
import displayio
from adafruit_st7789 import ST7789

try:
    from fourwire import FourWire  # CircuitPython 9 and later
except ImportError:
    from displayio import FourWire  # CircuitPython 8

import circuitpython_rv565 as rv565

displayio.release_displays()
spi = busio.SPI(clock=board.GP18, MOSI=board.GP19)
bus = FourWire(
    spi,
    command=board.GP20,
    chip_select=board.GP17,
    reset=board.GP21,
    baudrate=40_000_000,
)
display = ST7789(bus, width=320, height=240, rotation=90, backlight_pin=board.GP22)

clip = rv565.open("/testpattern.rv565")
clip.build_index()  # validate the whole file before playing
player = rv565.Player(clip, display)
while True:
    print(player.play())

Raspberry Pi Pico 2, direct to the panel

The same wiring with DirectPlayer, which sends frames straight to the controller (about twice the frame rate).

examples/rv565_pico2_direct.py

# SPDX-FileCopyrightText: 2026 Ayushman Bhattacharya
# SPDX-License-Identifier: MIT
"""Experimental fast path: send frames straight to the ST7789 on a Pico 2.

RV565 frames are already in the panel's byte order, so DirectPlayer skips
displayio and sends each inflated frame with one bus.send(). Same wiring and
files as rv565_pico2_st7789.py. displayio is left without a root group while
this runs, so nothing else is drawn on the panel.
"""

import board
import busio
import displayio
from adafruit_st7789 import ST7789

try:
    from fourwire import FourWire  # CircuitPython 9 and later
except ImportError:
    from displayio import FourWire  # CircuitPython 8

import circuitpython_rv565 as rv565

displayio.release_displays()
spi = busio.SPI(clock=board.GP18, MOSI=board.GP19)
bus = FourWire(
    spi,
    command=board.GP20,
    chip_select=board.GP17,
    reset=board.GP21,
    baudrate=40_000_000,
)
# The driver sends the ST7789 init sequence (rotation, inversion, colour mode).
display = ST7789(bus, width=320, height=240, rotation=90, backlight_pin=board.GP22)

clip = rv565.open("/testpattern.rv565")
# displayio's rotation=90 is done in software, so DirectPlayer sets the
# controller's MADCTL to landscape (0x60, as the RV565 Pico 2 benchmark does)
# while playing and restores it afterwards. The benchmark's 320x240 module
# needs no offset that way; if the picture is shifted, upside down or
# mirrored on yours, pass x_offset/y_offset or madctl=0xA0.
player = rv565.DirectPlayer(clip, bus, 320, 240, display=display)
while True:
    print(player.play())

ESP32-S3 TFT Feather

examples/rv565_esp32s3_tft.py

# SPDX-FileCopyrightText: 2026 Ayushman Bhattacharya
# SPDX-License-Identifier: MIT
"""ESP32-S3 board with a built-in ST7789: the Adafruit ESP32-S3 TFT Feather.

Its 240x135 display is already set up as board.DISPLAY, so the 180x135 test
pattern fits at native size. Other ESP32-S3 boards with board.DISPLAY work
the same way; for a separate SPI panel, set it up as in
rv565_pico2_st7789.py with your board's pins.

The clip can live on CIRCUITPY or on an SD card mounted with sdcardio and
storage.mount (for example "/sd/clip.rv565"); frames are read from the file
one at a time, so the clip does not have to fit in RAM.
"""

import board

import circuitpython_rv565 as rv565

display = board.DISPLAY
clip = rv565.open("/testpattern.rv565")
print("RV565 %dx%d, %d FPS, %d frames" % (clip.width, clip.height, clip.fps, len(clip)))

player = rv565.Player(clip, display)
while True:
    stats = player.play(loops=3)
    print(stats)