Linux ST7735 Driver

A Linux kernel SPI character driver for a 128x128 ST7735 LCD on Raspberry Pi 5. The driver owns the SPI transport, DC and RESET GPIOs, controller initialization, display window selection, and RGB565 frame transfer.

Project status: Beta. The complete display path has been verified on Raspberry Pi 5, including module loading, Device Tree binding, color-test ioctls, and full-frame writes through /dev/st7735. The ABI and deployment process may still change before a stable release.

Features

• Linux spi_driver bound through Device Tree
• SPI mode 0 at up to 8 MHz
• GPIO descriptor control for DC and active-low RESET
• ST7735 initialization sequence
• 128x128 RGB565 full-frame output
• 4096-byte chunked SPI transfers
• Character device interface at /dev/st7735
• Mutex-protected control and frame operations
• Test ioctls for reset, initialization, and solid colors

Architecture

flowchart LR
    App["Userspace application"] -->|"write(): 32768-byte RGB565 frame"| Dev["/dev/st7735"]
    App -->|"ioctl(): reset / init / color test"| Dev
    Dev --> Driver["ST7735 kernel driver"]
    Driver -->|"SPI0 MOSI / SCLK / CE0"| LCD["ST7735 LCD"]
    Driver -->|"GPIO24 DC / GPIO25 RESET"| LCD

Loading

The paired userspace application is maintained separately: walker3354/rpi-ip-display.

Hardware

• Raspberry Pi 5 Model B
• Raspberry Pi OS 64-bit
• Linux 6.12.87+rpt-rpi-2712 used for Beta verification
• ST7735 or ST7735S 128x128 SPI LCD

Wiring

LCD pin	Raspberry Pi 5	BCM GPIO	Function
GND	Pin 6	-	Ground
VCC	Pin 1	-	3.3 V
SCL	Pin 23	GPIO11	SPI0 SCLK
SDA	Pin 19	GPIO10	SPI0 MOSI
RES	Pin 22	GPIO25	Reset
DC	Pin 18	GPIO24	Data/command select
CS	Pin 24	GPIO8	SPI0 CE0
BL	Pin 17	-	3.3 V backlight

Use 3.3 V logic. This LCD is an SPI device; labels such as SCL and SDA refer to SPI clock and MOSI on this module.

Build

Install matching kernel headers, then run:

make

The build produces:

ST7735_driver.ko
st7735-walker-overlay.dtbo
test/fill_red

For VS Code kernel symbol indexing:

make compile_commands

Load For Testing

The following commands apply the overlay only for the current boot:

sudo insmod ./ST7735_driver.ko
sudo dtoverlay -d "$PWD" st7735-walker-overlay

Verify the binding:

readlink -f /sys/bus/spi/devices/spi0.0/driver
ls -l /dev/st7735

Expected driver path:

/sys/bus/spi/drivers/st7735

Unload:

sudo dtoverlay -r st7735-walker-overlay
sudo rmmod ST7735_driver

Userspace ABI

The display accepts exactly one complete RGB565 frame per write():

128 x 128 x 2 = 32768 bytes

Short or oversized writes return EINVAL.

Available ioctls:

ioctl	Purpose
ST7735_IOCTL_RESET	Hardware reset
ST7735_IOCTL_INIT	Controller initialization
ST7735_IOCTL_FILL_RED	RGB565 red test
ST7735_IOCTL_FILL_BLUE	RGB565 blue test
ST7735_IOCTL_FILL_GREEN	RGB565 green test

Controller command/data switching remains internal to the driver. Userspace provides complete RGB565 frames rather than raw ST7735 commands.

Verification

The Beta version has passed:

• make W=1
• Device Tree overlay compilation
• module unload and reload
• spi0.0 binding to the custom driver
• /dev/st7735 creation
• reset and initialization ioctls
• red, green, and blue fill ioctls
• 32768-byte userspace frame write
• invalid one-byte write rejection

Beta Limitations

• Only one 128x128 display instance is currently supported.
• Frame dimensions, pixel format, orientation, and offsets are fixed.
• Only complete-frame writes are accepted.
• The overlay is loaded manually during development.
• No stable ABI guarantee is provided yet.

Repository Layout

.
├── include/ST7735.h
├── src/ST7735.c
├── st7735-walker-overlay.dts
├── test/fill_red.c
├── example.c
├── Makefile
└── codex.md