In this tutorial, I’ll walk you through the process of installing an LCD touchscreen on the Raspberry Pi, step by step. Many LCD touchscreens for the Raspberry Pi include an image file that you can write to your SD card and get up and running pretty quickly. But what if you want to run a clean version of Raspbian, without all the bloatware included on the manufacturer’s image? Also, what if you want to install a different OS such as Rasbmc or XBMC? In these cases, you should follow this tutorial and go through the steps to configure it on your own. This works on the Raspberry Pi 2 Model B as well as older versions of the Raspberry Pi. Don’t worry, it’s not that hard!

I am using the Waveshare 3.2″ TFT (thin-film transistor) LCD. Many other LCD screens are supported by this process, but check here to see if your screen is supported by the FBTFT driver to make sure. Scroll down the file and look for an abbreviated name of the screen you are using:

FBTFT Supported Screens

What we need to do to get the LCD working is install and configure the FBTFT drivers created by notro. There are two types of drivers we need to be concerned with here. One set of drivers is for the actual LCD display screen, and the other set of drivers is for the touchscreen sensors. Here is a good article explaining Linux kernel modules, devices, and drivers, which you may want to read for some background information. The standard version of Raspbian does not include the drivers for LCD touchscreens, so we will need to install and configure them manually. So just follow the steps below to get your LCD touch screen working on the Raspberry Pi.

Watch the video tutorial for a quick overview of the steps:

Touchscreen Setup and Configuration

1. First we need to configure the fbturbo video driver to output the display of the Raspberry Pi to the SPI bus instead of the HDMI bus. At the command prompt, enter: sudo nano /usr/share/X11/xorg.conf.d/99-fbturbo.conf.

In this file, find the line that says: Option “fbdev” “/dev/fb0” and change the fb0 to fb1:

LCD 99-fbturbo step 1

The fb0 option tells the video driver to output to HDMI, and the fb1 option tells it to output to the LCD screen. The file should now look like this:

lcd 99-fbturbo step 2

Press Ctrl-X then Y to exit nano and save the changes.

2. The touchscreen uses SPI (serial peripheral interface) to communicate to the main processor. By default, SPI communication is disabled. If you are using the Raspberry Pi 2 Model B, or a version of Raspbian released after 1-31-2015, this can be done in the raspi-config menu. Enter sudo raspi-config at the command prompt to enter the configuration menu, then find the “Advanced Options” line:

Raspi-config advanced settings

Click enter here to see the Advanced Options, then find the line that says “SPI ENABLE/DISABLE AUTOMATIC LOADING“:

Raspi-config enable spi

Click enter here:

Enable SPI

Then enter again for “yes”. Now exit the configuration menu and enter sudo reboot at the command prompt. You can skip to step 3 now.

If you are using a version of Raspbian that was released before 1-31-2015, we need to enable SPI it by removing the entry from the blacklist file. Enter sudo nano /etc/modprobe.d/raspi-blacklist.conf at the command prompt to edit the file:

lcd spi blacklist before #

We need to remove the spi-bcm2708 driver from the blacklist by “commenting out” the line that says: blacklist spi-bcm2708. Placing a “#” in front of the line tells the computer to ignore it:

lcd spi blacklist after #

Press Ctrl-X then Y to exit nano and save the changes.

3. Now we can download and install the drivers for the LCD. At the command prompt, enter sudo REPO_URI= rpi-update. This will download and install the drivers and kernel modules that are needed to run the LCD touchscreen. The download is about 47.2 MB:

lcd drivers install

After the drivers have downloaded and installed, a reboot is necessary, so enter sudo reboot or sudo poweroff:

lcd drivers install then reboot

4. After booting up and logging back in to the Raspberry Pi, we will need to configure the kernel modules for the LCD and the touchscreen. To configure these kernel modules, we need to edit the /etc/modules file. At the command prompt, enter sudo nano /etc/modules:

lcd etc.modules before edit

The first term of each line in this file is the name of a kernel module that will be loaded automatically at boot time. The terms after the name of the kernel module on each line are called parameters, and parameters can be changed to adjust the properties of each kernel module.

Currently, the only module that is set to load automatically is snd-bcm2835, which is the module for the Raspberry Pi’s Broadcom processor.

Add this code below the snd-bcm2835 line to support the fbtft_device and ads7846_device modules:


fbtft_device name=waveshare32b gpios=dc:22,reset:27 speed=48000000

waveshare32b width=320 height=240 buswidth=8 init=-1,0xCB,0x39,0x2C,0x00,0x34,0x02,-1,0xCF,0x00,0XC1,0X30,-1,0xE8,0x85,0x00,0x78,-1,0xEA,0x00,0x00,-1,0xED,0x64,0x03,0X12,0X81,-1,0xF7,0x20,-1,0xC0,0x23,-1,0xC1,0x10,-1,0xC5,0x3e,0x28,-1,0xC7,0x86,-1,0x36,0x28,-1,0x3A,0x55,-1,0xB1,0x00,0x18,-1,0xB6,0x08,0x82,0x27,-1,0xF2,0x00,-1,0x26,0x01,-1,0xE0,0x0F,0x31,0x2B,0x0C,0x0E,0x08,0x4E,0xF1,0x37,0x07,0x10,0x03,0x0E,0x09,0x00,-1,0XE1,0x00,0x0E,0x14,0x03,0x11,0x07,0x31,0xC1,0x48,0x08,0x0F,0x0C,0x31,0x36,0x0F,-1,0x11,-2,120,-1,0x29,-1,0x2c,-3

ads7846_device model=7846 cs=1 gpio_pendown=17 speed=1000000 keep_vref_on=1 swap_xy=0 pressure_max=255 x_plate_ohms=60 x_min=200 x_max=3900 y_min=200 y_max=3900

Note: Line 6 is long so make sure you get everything, and use cut/paste to avoid typos. The file should look something like this now:

lcd etc.modules after edit

The kernel module for the LCD screen is called fbtft_device and the kernel module for the touchscreen is called ads7846_device. ads7846 is the name of the touchscreen controller chip used in the Waveshare 3.2″ LCD and many other touchscreen displays.

If you are not using the Waveshare 3.2″ Touchscreen LCD, first find the fbtft_device name of your device by checking here. Next, on the line that begins with fbtft_device, change the term name=waveshare32b to name=YOUR DEVICE NAME. Now, on the next line that begins with waveshare32b, change the waveshare32b term to your own device name, for example adafruit28, or sainsmart32_spi

Press Ctrl-X then Y to exit nano and save the changes.

5. Now we need to edit the /boot/cmdline.txt file which contains all of the settings used to configure the system when it boots up. This file is read by the GPU (graphics processing unit), before it is read by the CPU (central processing unit) and the Linux OS. It is equivalent to BIOS in other systems, and contains lots of useful options for configuring your system at boot time. To edit this file, enter sudo nano /boot/cmdline.txt at the command prompt.

lcd boot.cmdline.txt before and after edit

Replace the code in this file with this code, entered in one single line:

dwc_otg.lpm_enable=0 console=ttyAMA0,115200 console=tty1 root=/dev/mmcblk0p2 rootfstype=ext4 elevator=deadline rootwait fbtft_device.custom fbtft_device.gpios=dc:22,reset:27 fbtft_device.bgr=1 fbtft_device.speed=48000000 fbcon=map:10 fbcon=font:ProFont6x11 logo.nologo dma.dmachans=0x7f35 console=tty1 consoleblank=0 fbtft_device.fps=50 fbtft_device.rotate=0

Note: This line is really long, so make sure you get everything, and copy/paste to avoid typos.

Similarly to what was done in step 4 above, if you are not using the Waveshare 3.2″ Touchscreen LCD, first find the fbtft_device name of your device by checking here. Then replace in the code above with DEVICE NAME. 

Press Ctrl-X then Y to exit nano and save the changes.

6. The final step is to setup the Pi to load startx automatically and boot to the GUI. If you would rather boot to the command prompt, just skip this step. Enter sudo nano /etc/rc.local at the command prompt:

lcd .etc.rc.local before edit

Now add su -l pi -c startx above the line that says exit 0:

lcd .etc.rc.local after edit

Press Ctrl-X then Y to exit nano and save the changes.

If you are using the Raspberry Pi 2 Model B, the next step is to set the system to boot to the desktop GUI in the raspi-config menu. If you are using versions of Raspbian earlier than 1-31-15 on the Model B+, you can skip this part.

At the command prompt, enter sudo raspi-config.

raspi-config boot to desktop

Select the line that says Enable Boot to Desktop/Scratch, and press enter.

raspi-config boot to desktop 2

Select the line that says Desktop Log in as user “pi” at the graphical desktop, and press enter. Now exit the raspi-config menu.

At the command prompt, enter sudo reboot, and after the Pi boots up the GUI should appear on the LCD screen:


If your screen looks like this:


It is probably due to your Pi being overclocked at turbo speed or Pi2 speed. Try the high setting or lower to fix this.

There have been some issues with the FBTFT drivers when using sudo update and sudo upgrade. Some people have reported that after updating and upgrading, the LCD touchscreen stops working. This seems to be caused by the Raspberry Pi bootloader package overwriting the FBTFT kernel and modules during the update/upgrade install. To prevent this from happening, update and upgrade by:

1. Updating all packages except for the Raspberry Pi bootloader by entering this at the command prompt:

sudo apt-mark hold raspberrypi-bootloader
sudo apt-get update
sudo apt-get upgrade

2. Then, updating the Raspberry Pi bootloader independently by entering this at the command prompt:

sudo apt-get install rpi-update
sudo SKIP_KERNEL=1 rpi-update

If your drivers have been accidentally overwritten, they can be restored without having to go through the entire installation process again. Just enter this at the command prompt:

sudo REPO_URI= BRANCH=builtin rpi-update
sudo reboot

More information about this issue can be found here.

Continue on to the next article Raspberry Pi Touchscreen Calibration and Screen Rotation to find out how to change the screen orientation of your Raspberry Pi and calibrate the touchscreen for the best accuracy.

If you have any problems setting up your Raspberry Pi LCD touchscreen, please leave a comment below and I will try to help you solve it…

Please share this if you found it useful!

Need an easy-to-use way to design circuits and layout PCBs?

Try EasyEDA, a free circuit design software that also offers low cost, high quality PCB manufacturing.