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

[3urobeat]

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.)

[nsier]

thanks for this @HerrEurobeat

Just to be clear, if we are using the pinouts mapped for the click well, we def have to change a few pins for this display.

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

accounts for this correct?

[3urobeat]

@nsier
Yes, if you use the clickwheel pins like in the schematics of this project you would need to use a different pin. I used the pinout by Waveshare and just changed a pin of the clickwheel in the code. Just use the command I provided in my post and change that one pin in the command. Don't leave out anything else.

[nsier]

@nsier
Yes, if you use the clickwheel pins like in the schematics of this project you would need to use a different pin. I used the pinout by Waveshare and just changed a pin of the clickwheel in the code. Just use the command I provided in my post and change that one pin in the command. Don't leave out anything else.

Thanks!

Last question, do we need to wire up the Backlight? I bought the Adafruit version of this display and the wiring guide they show doesn't seem to require it

https://learn.adafruit.com/2-2-tft-display/python-wiring-and-setup

thanks
Nick

[3urobeat]

Thanks!

Last question, do we need to wire up the Backlight? I bought the Adafruit version of this display and the wiring guide they show doesn't seem to require it

https://learn.adafruit.com/2-2-tft-display/python-wiring-and-setup

thanks

Nick

No problem :)
Take a look at the wiring diagram from Waveshare which I linked at the very top. I think they wired the BL up to a GPIO pin as the Display gets Power from it (at least thats what I think, maybe it is also just a control pin) which you can then pull to high or low to enable/disable the BL.

The script supports a display turnoff after 60sec but it wasn't working for me, probably because of the different display. But you could change it in the code to pull the GPIO pin to get it working.
So to answer your question - I'm not 100% you need to wire it up but I would do it as it can't hurt. The Waveshare diagram shows a pin to wire it up to.

[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.

[nsier]

I don't seem to have a build folder within my fbcp-ili9341 directory.

is it Ok just to compile in fbcp-ili9341 ?

[rsappia]

@nsier here you can get some additional details about the installation:

http://rsflightronics.com/spotifypod

and here (Option 2)

https://krystof.io/mirroring-raspberry-pi-hdmi-video-to-a-st7789-1-3-inch-lcd-display/

[3urobeat]

@nsier If I recall correctly you have to create the folder and I seem to have missed including it in the explanation. Just do a mkdir build, then cd into the folder and continue with building the driver.

Edit: I edited my post and included the folder creation step. Thanks for pointing out that it was missing!

[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!

[3urobeat]

@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!

Kein Problem! :D
Yes I did notice the same thing.
If I recall correctly I even found something that had to do with scaling in the code but I think I didn't mess around with it.
Tbh this project still needs a lot of work and I decided to wait for @dupontgu to work on it again before I tinker more with it.

[X3NON4]

I keep getting the message that it failed and to make sure I have hdmi_force_hotplug=1 in the /boot/config.txt whenever I run sudo ./fbcp-ili9341, and in the config file I have hdmi_force_hotplug=1 so what could be the problem?

[XEROxMEXICANO]

Hello when I run the make file I get an error telling me to add hdmi_force_hotplug=1 to the config file, and when I check it's there uncommented. Do any of you know a possible solution or at least whats wrong?

[3urobeat]

Hey
Sorry, it has been 1.5 years since I looked at this project, I don't know why that might happen

[acburk]

Hello when I run the make file I get an error telling me to add hdmi_force_hotplug=1 to the config file, and when I check it's there uncommented. Do any of you know a possible solution or at least whats wrong?

check that you have dtoverlay=vc4-kms-v3d commented out, might be a new default thing in the config.txt