In this tutorial, I’ll walk you step by step through the process of installing an LCD touchscreen on the Raspberry Pi. Most LCD touchscreens for the Raspberry Pi ship with an OS 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, updated version of Raspbian, without any bloatware included with the manufacturer’s image? Also, you might want to install a different OS such as Rasbmc or XBMC. In these cases, you should configure the touchscreen from scratch, as I’ll show you how to do in this tutorial. This process has been tested and 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!

PCBWay Ad

Note: Be sure to make a backup of any important data on your SD card before starting this!

I’m using the Waveshare 3.2″ TFT LCD touchscreen with fresh install of Raspbian Jessie Full. Raspbian Jessie Lite won’t work with the touchscreen because it doesn’t have X-Server and the fbturbo video driver installed. A lot of LCD touchscreens can be set up by this process, but check here to see if your LCD 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 touchscreen working on the Raspberry Pi.

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

Enable SPI

The Pi communicates with the touchscreen through SPI (serial peripheral interface). By default, SPI communication is disabled, so you need to enable it. If you’re using a version of Raspbian released after 1-31-2015, this can be done in the raspi-config menu.

If you’re using a version of Raspbian that was released before 1-31-2015, you’ll need to enable SPI by removing the entry from the blacklist file. Enter this at the command prompt to edit the file:

sudo nano /etc/modprobe.d/raspi-blacklist.conf

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.

Configure the fbturbo Driver

Now you need to configure the fbturbo video driver to output the Raspberry Pi’s display to the SPI bus instead of the HDMI bus. Enter this at the command prompt:

sudo nano /usr/share/X11/xorg.conf.d/99-fbturbo.conf

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 the display 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.

Install the fbtft Drivers

Note: As of the 1-31-15 release of Raspbian, the fbturbo drivers are now included and enabled by default. So skip this step if your Raspbian OS was released 1-31-15 or later.

Now you need to download and install the drivers and kernel modules that are needed to run the LCD touchscreen. Enter this at the command prompt:

sudo REPO_URI=https://github.com/notro/rpi-firmware rpi-update

The download is about 47.2 MB:

lcd drivers install

After the drivers have downloaded and installed, reboot the Pi by entering sudo reboot.

Configure the Kernel Modules

After the Pi is booted up and you’ve logging back in, the next step is to configure the kernel modules for the LCD display and touchscreen sensors. To do that we need to edit the /etc/modules file. So enter this at the command prompt:

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:

spi-bcm2708

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

Edit the /boot/cmdline.txt File

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.name=waveshare32b 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 fbtft_device.name=waveshare32b in the code above with fbtft_device.name=YOUR DEVICE NAME.

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

Configure startx to Load Automatically

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:

IMG_7660

If your screen looks like this:

IMG_7656

It is probably due to your Pi being overclocked at turbo speed or Pi 2 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=https://github.com/notro/rpi-firmware 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, and subsribe to get more tutorial like this in your inbox!