The gc9a01-overlay.dts was commited on the official Raspberry Pi Linux kernel. Development on this repository has ceased and any issue or new feature should be handled there.

This is an overlay for the fb_ili9340 graphics driver from NoTro FBTFT, to use with LCD displays that has the Galaxycore's GC9A01 single chip driver. It allows to easily setup (in just 3 super easy steps!) said displays to be used on newer Raspberry Pi OS releases that already includes fbtft on it's kernel.

The display should be connected to the Raspberry Pi on the first SPI channel (spi0) pins, as follows:

1. Locate your sdcard boot partition. If you are on 'Windows', that should be the partition where the sdcard was mounted (e.g. E:/). On 'Raspberry Pi OS' that should be /boot;

2. Check the overlays directory in boot partition (e.g. E:/overlays on 'Windows' or /boot/overlays on 'Raspberry Pi OS') and look for the gc9a01.dtbo overlay file. If you're missing the file, you can download it from here (official Raspberry Pi Firmware repository) and save it to the said directory;

3. Edit the config.txt file on the boot partition and append the following line to the end of the file:

dtoverlay=gc9a01

The line above will attach GC9A01 LCD driver to /dev/fb1 framebuffer over spi0 spi pins and initialize the LCD.

That's it. Put the sdcard on the Raspberry Pi and boot (if you did the above steps right inside from 'Raspberry Pi OS', just reboot with sudo reboot).

After power up, open a terminal and verify that the device was properly mounted:

ls /dev/fb*

• this should list both fb0 and fb1.

Since this overlay is just an extension of the device driver, it only attaches and initiates the LCD device on the fb1 framebuffer (it's like turning on the TV without any cable or antenna input). In order to actually see something on the display, you need something sending image to it. What users tipically do is just mirror the HDMI output (displayed on fb0) on the LCD (displayed on fb1). For this task there are many tools available and we'll help you to setup one of them bellow. If you are a developer, another way to show stuff on the display would be your application directly write on fb1 framebuffer, but that won't be covered here.

Raspberry Pi Framebuffer Copy is a tool that copies the primary framebuffer (fb0) to a secondary one (fb1).

Run the following commands to download, build and install:

cd ~
git clone https://github.com/tasanakorn/rpi-fbcp
cd rpi-fbcp/
mkdir build
cd build/
cmake ..
make
sudo install fbcp /usr/local/bin/fbcp

To make it run on boot, edit the following file:

sudo vi /etc/rc.local

Add fbcp& on the line right before exit 0. The & will make it run on background, without hanging the boot process:

fbcp&
exit 0

Reboot the Raspberry Pi and you'll start seeing the image from HDMI mirrored on the LCD.

The overlay support some optional parameters that allow changes in the default behavior and affects only the LCD display. They are key=value pairs, comma separated in no predefined order, as follow:

dtoverlay=gc9a01,speed=40000000,rotate=0,width=240,height=240,fps=50,debug=0

• speed: max spi frequency to be used
• rotate: image rotation (in degrees: 0, 90, 180, 270)
• width: width of the display
• height: height of the display
• fps: max fps to be used
• debug: debug level to be logged on boot process

Since fbcp is making a plain copy from HDMI to LCD, screen resolution may affect the final result. Additional settings can be added on the config.txt in order to adjust the resulting image to your needs. The full set of options can be checked at /boot/overlays/README.

Note that the following settings will be applied both to the HDMI and the LCD.

dtoverlay=gc9a01
hdmi_force_hotplug=1
hdmi_cvt=240 240 60 1 0 0 0
hdmi_group=2
hdmi_mode=87
hdmi_drive=2
display_rotate=2

• hdmi_force_hotplug: force HDMI output rather than DVI
• hdmi_cvt: adjusts de resolution, framerate and more. Format: <width> <height> <framerate> <aspect> <margins> <interlace>
• hdmi_group: set DMT group (Display Monitor Timings: the standard typically used by monitors)
• hdmi_mode: set DMT mode
• hdmi_drive: force a HDMI mode rather than DVI
• display_rotate: rotate screen 180 degrees

The display_rotate setting allows to rotate or flip the screen orientation to fit your needs. The default value is 0, possible values are:

• 0 no rotation
• 1 rotate 90 degrees clockwise
• 2 rotate 180 degrees clockwise
• 3 rotate 270 degrees clockwise
• 0x10000 horizontal flip
• 0x20000 vertical flip

This setting is a bitmask. So you can both flip and rotate the display at the same time. Example:

• 0x10001 both do a horizontal flip and rotate 90 degrees clockwise (0x10000 + 1).
• 0x20003 both do a vertical flip and rotate 270 degrees clockwise (0x20000 + 3).

Clone the repository:

cd ~
git clone https://github.com/juliannojungle/gc9a01-overlay
cd gc9a01-overlay

Build overlay:

dtc -W no-unit_address_vs_reg -@ -I dts -O dtb -o gc9a01.dtbo gc9a01-overlay.dts

Load overlay:

sudo dtoverlay -v -d . gc9a01.dtbo

Test loaded overlay:

ls /dev/fb*

• should list both fb0 and fb1

Unload overlay:

sudo dtoverlay -r gc9a01

Check for info on boot process:

dmesg | grep graphics

• should list the loaded driver info

^{@juliannojungle, 2022}