gc9b72

Python driver for GC9B72 round SPI TFT panels on Raspberry Pi and other Linux single-board computers. Developed against a 2.1" 360x360 module.

If your GC9B72 panel stays black or white, you are probably sending a GC9A01 init sequence. The two controllers both drive round panels and are otherwise unrelated, and the GC9B72 is in none of the usual libraries — not TFT_eSPI, not Adafruit GFX. The sequence this driver sends is documented in INIT_SEQUENCE.md.

Installing

The C and imaging libraries come from apt rather than pip:

sudo apt install -y python3-lgpio python3-spidev python3-numpy python3-pil

Raspberry Pi OS will not let pip write to the system Python (PEP 668, the externally-managed-environment error). Install into a virtual environment that can still see those apt packages:

python3 -m venv --system-site-packages ~/.venvs/display
~/.venvs/display/bin/pip install gc9b72

Run your scripts with ~/.venvs/display/bin/python. If you would rather keep one system-wide Python, pip install --break-system-packages gc9b72 also works, at the usual risk of pip and apt disagreeing later.

SPI must be enabled (sudo raspi-config nonint do_spi 0, then reboot). A full frame is 253 KB and the default SPI buffer is 4 KB, so for a usable frame rate append spidev.bufsiz=65536 to the line in /boot/firmware/cmdline.txt.

If opening the device raises PermissionError, add yourself to the right groups with sudo usermod -aG spi,gpio $USER and log back in.

Wiring

4-wire SPI at 3.3V logic, so it connects straight to the header with no level shifter. GPIO numbers are BCM.

BCM is the number you pass to the driver; the header pin is where the wire physically goes. They are not the same numbering and mixing them up is how VCC ends up on 5V.

SDO and TE are unused — leave them unconnected. SDA is MOSI and SCL is the clock: this is SPI, not I²C, despite the pin names, which is the usual way to lose an evening with these modules. VCC wants 3.3V, not 5V, unless the module carries its own regulator.

Using

from gc9b72 import GC9B72
from PIL import Image, ImageDraw

with GC9B72(dc=25, rst=24, bl=18, speed_hz=40_000_000) as d:
    img = Image.new("RGB", (d.width, d.height), (0, 0, 0))
    ImageDraw.Draw(img).ellipse([20, 20, 340, 340], fill=(255, 100, 0))
    d.show_image(img)

Pin numbers are BCM. dc, rst and bl are the only GPIOs the driver drives; everything else goes to the SPI bus (/dev/spidev0.0 by default).

Options

Methods

show_image(image) draws a PIL image, blit(array) an (h, w, 3) uint8 numpy array, and fill(colour) a solid colour from rgb565(r, g, b). backlight(on) switches the backlight and backlight_pwm(percent) dims it.

Examples

The examples are not part of the installed package — clone the repository to get them:

git clone https://github.com/guillermozuur-design/gc9b72

examples/demo.py draws test patterns — solid colours, colour bars, alignment markers, a clock, and an fps benchmark:

python3 examples/demo.py           # all of them
python3 examples/demo.py bars      # left should be red, right blue
python3 examples/demo.py corners   # circle should meet the edge of the glass
python3 examples/demo.py bench

bars and corners are the quickest way to settle bgr, rotation and the offsets for your particular module.

Panels

Sold as 2.1" round TFT modules, silkscreened Driver IC: GC9B72. 480x480 variants exist — change WIDTH/HEIGHT at the top of gc9b72/__init__.py; the init sequence is the same.

Credits

The register init sequence is derived from fb-gc9b72.c in xboot. For the ESP32 there is Arduino_GC9B72, and for LVGL there is GC9B72-LVGL-Driver.

MIT licensed — see LICENSE.