Tutorial: Get a SPI Display working (Waveshare 320x240 using fbcp-ili9341)

You are wondering on how to get a SPI display to work? Yeah me too so I hope this quick guide will help you.
I did this using a Waveshare 320x240 LCD IPS screen. This is the pinout I used which is provided by Waveshare themselves.

I’m sorry if an issue isn’t the right place but I figured most people with this question would see it here first. If it fits into the README (as a shortened version) I would gladly open a pull request.

If I’m missing something or got something wrong please comment down below.

Stuff on your computer: First of all open config.txt which is located in the boot partition while having the SD card mounted on your computer.
I didn’t need to follow these few steps which tell you to remove any dtoverlay or dtparam=spi=on parameter as I didn’t have them in my config.

As described here, add these lines to your config.txt (or uncomment and modify the existing ones but hdmi_cvt didn’t exist for me yet):

hdmi_group=2
hdmi_mode=87
hdmi_cvt=320 240 60 1 0 0 0
hdmi_force_hotplug=1

Note: You will need to change the first two hdmi_cvt values based on the resolution of your screen. As I mentioned already, I used a 320x240 screen in this example.

Stuff on the pi: You can now eject your SD card and boot the pi.
When you are in a terminal (for example using ssh), follow these steps as documented here:

sudo apt install cmake git
cd ~
git clone https://github.com/juj/fbcp-ili9341.git
cd fbcp-ili9341

Open st7735r.h using a text editor:
nano st7735r.h

Go to line 18 which defines the values for the controller the display in this example uses: ST7789
Change DISPLAY_NATIVE_HEIGHT from 240 to 320 as described here.
Then save (CTRL+S) and exit (CTRL+X).

Yes, in my experience you need to change height and not width even though the width should be 320. Idk, this is a bit weird but maybe I just don’t understand it correctly.

Now we need to compile the driver.
Create a build folder:
mkdir build
and open it:
cd build

If you have used the same pinout as in the image in the beginning then these values should be right.
If not then you need to change TFT_DATA_CONTROL and TFT_RESET_PIN. Remember that these numbers are the GPIO pin names and not counted. Image to see which GPIO Pin has which number

Note: The BUS_CLOCK_DIVISOR is not a pin but a value that defines the speed of the clock together with the value 60 we set in the config.txt. I don’t really understand this value myself but I read that most people recommend using 30 here first before changing it and it worked for me just fine.

cmake -DST7789=ON -DGPIO_TFT_DATA_CONTROL=25 -DGPIO_TFT_RESET_PIN=27 -DSPI_BUS_CLOCK_DIVISOR=30 -DSTATISTICS=0 -DUSE_DMA_TRANSFERS=OFF ..

Since I had to mount my display with the ribbon cable on the right side, so basically upside down from the original orientation the manufacturer intended, I had to flip the image by including this option before the two dots at the end: -DDISPLAY_ROTATE_180_DEGREES=ON

Now wait for that to finish and then type:
make -j

When that is done we are almost done. You can test the driver now by running sudo ./fbcp-ili9341 but since the driver should start automatically on boot we have to do one last change.
Open /etc/rc.local with a text editor with sudo privileges:
sudo nano /etc/rc.local

Add these lines before exit:

# Start display driver
/home/pi/fbcp-ili9341/build/fbcp-ili9341 &

Thats it!

I hope this helped you to figure out on how to get your display running. I had many questions for a few days but these were all the steps I had to take to get my display up and running. I credited every source where I got my information from in this post.
(I hope I didn’t forget anything, wasn’t the only one having this problem and that it works for you.)

[nboumalham]

@HerrEurobeat,

You just saved me hours of tinkering to get this working.

I just followed your perfect summary and in 15 min…boom…working from the first run.

I did noticed though that the ratio of the python app is a bit off on the screen (narrower on the sides and taller). Did you notice the same thing?

Vielen Dank!

[rsappia]

The BL pin is not driving the backlight directly, it drives a transistor base so it can be connected to a PWM signal to be able to dimmer the backlight. In other words, it is ok to connect it directly to a gpio (dont forget to activate it!!), this will not damage the RPI ports 😉. If you dont wire the backlight, all what you get is… a black screen. TFT displays need a backlight activated to display its content.