Raspberry Pi Documentation

Display

Raspberry Pi Touch Display

The Raspberry Pi Touch Display is an LCD display which connects to the Raspberry Pi through the DSI connector. In some situations, it allows for the use of both the HDMI and LCD displays at the same time (this requires software support).

Board Support

The DSI display is designed to work with all models of Raspberry Pi, however early models that do not have mounting holes (the Raspberry Pi 1 model A and B) will require additional mounting hardware to fit the HAT-dimensioned stand-offs on the display PCB.

Physical Installation

The following image shows how to attach the Raspberry Pi to the back of the Touch Display (if required), and how to connect both the data (ribbon cable) and power (red/black wires) from the Raspberry Pi to the display. If you are not attaching the Raspberry Pi to the back of the display, take extra care when attaching the ribbon cable to ensure it is the correct way round. The black and red power wires should be attached to the GND and 5v pins respectively.

DSI Display Connections

Screen Orientation

LCD displays have an optimum viewing angle, and depending on how the screen is mounted it may be necessary to change the orientation of the display to give the best results. By default, the Raspberry Pi Touch Display and Raspberry Pi are set up to work best when viewed from slightly above, for example on a desktop. If viewing from below, you can physically rotate the display, and then tell the system software to compensate by running the screen upside down.

KMS and FKMS Mode

KMS and FKMS modes are used by default on the Raspberry Pi 4B. KMS and FKMS use the DRM/MESA libraries to provide graphics and 3D acceleration.

To set screen orientation when running the graphical desktop, select the Screen Configuration option from the Preferences menu. Right click on the DSI display rectangle in the layout editor, select Orientation then the required option.

To set screen orientation when in console mode, you will need to edit the kernel command line to pass the required orientation to the system.

sudo nano /boot/cmdline.txt

To rotate by 90 degrees clockwise, add the following to the cmdline, making sure everything is on the same line, do not add any carriage returns. Possible rotation values are 0, 90, 180 and 270.

video=DSI-1:800x480@60,rotate=90
Note
In console mode it is not possible to rotate the DSI display separately to the HDMI display, so if you have both attached they must both be set to the same value.

Legacy Graphics Mode

Legacy graphics mode is used by default on all Raspberry Pi models prior to the Raspberry Pi 4B, and can also be used on the Raspberry Pi 4B if required, by disabling KMS and FKMS modes by commenting out the KMS or FKMS line in config.txt.

Note
Legacy mode on the Raspberry Pi 4B has no 3D acceleration so it should only be used if you have a specific reason for needing it.

To flip the display, add the following line to the file /boot/config.txt:

lcd_rotate=2

This will vertically flip the LCD and the touch screen, compensating for the physical orientation of the display.

You can also rotate the display by adding the following to the config.txt file.

  • display_lcd_rotate=x, where x can be one of the following:

display_lcd_rotate result

0

no rotation

1

rotate 90 degrees clockwise

2

rotate 180 degrees clockwise

3

rotate 270 degrees clockwise

0x10000

horizontal flip

0x20000

vertical flip

Note
The 90 and 270 degree rotation options require additional memory on the GPU, so these will not work with the 16MB GPU split.

Touchscreen Orientation

Additionally, you have the option to change the rotation of the touchscreen independently of the display itself by adding a dtoverlay instruction in config.txt, for example:

dtoverlay=rpi-ft5406,touchscreen-swapped-x-y=1,touchscreen-inverted-x=1

The options for the touchscreen are:

DT parameter Action

touchscreen-size-x

Sets X resolution (default 800)

touchscreen-size-y

Sets Y resolution (default 600)

touchscreen-inverted-x

Invert X coordinates

touchscreen-inverted-y

Invert Y coordinates

touchscreen-swapped-x-y

Swap X and Y cordinates

Troubleshooting

Read our troubleshooting steps, tips, and tricks here: Raspberry Pi Touch Display troubleshooting.

Specifications

  • 800×480 RGB LCD display

  • 24-bit colour

  • Industrial quality: 140-degree viewing angle horizontal, 130-degree viewing angle vertical

  • 10-point multi-touch touchscreen

  • PWM backlight control and power control over I2C interface

  • Metal-framed back with mounting points for Raspberry Pi display conversion board and Raspberry Pi

  • Backlight lifetime: 20000 hours

  • Operating temperature: -20 to +70 degrees centigrade

  • Storage temperature: -30 to +80 degrees centigrade

  • Contrast ratio: 500

  • Average brightness: 250 cd/m2

  • Viewing angle (degrees):

    • Top - 50

    • Bottom - 70

    • Left - 70

    • Right - 70

  • Power requirements: 200mA at 5V typical, at maximum brightness.

Mechanical Specification

Legacy Support

Note
These instructions are for the original Model A and B boards.

The DSI connector on the Model A/B boards does not have the I2C connections required to talk to the touchscreen controller and DSI controller. You can work around this by using the additional set of jumper cables provided with the display kit to wire up the I2C bus on the GPIO pins to the display controller board.

Using the jumper cables, connect SCL/SDA on the GPIO header to the horizontal pins marked SCL/SDA on the display board. We also recommend that you power the Model A/B via the GPIO pins using the jumper cables.

For the GPIO header pinout, see this diagram.

DSI display autodetection is disabled by default on these boards. To enable detection, add the following line to /boot/config.txt:

ignore_lcd=0

Power the setup via the PWR IN micro-USB connector on the display board. Do not power the setup via the Pi’s micro-USB port: the input polyfuse’s maximum current rating will be exceeded as the display consumes approximately 400mA.

Note
With the display connected to the GPIO I2C pins, the GPU will assume control of the respective I2C bus. The host operating system should not access this I2C bus, as simultaneous use of the bus by both the GPU and Linux will result in sporadic crashes.

Troubleshooting the Display

Have you got a good power supply?

Having intermittent problems, or seeing a little rainbow square in the top right corner? It is likely that you need a better power supply.

We recommend our official 2.5A adapter because we know it works, but any good 2.5A supply should work.

Have you updated Raspberry Pi OS?

If not, many problems will be solved by making sure your software is up-to date.

You can undo any previous use of rpi-update and get your Pi back to the latest stable software by connecting to a network and running:

sudo apt update
sudo apt install --reinstall libraspberrypi0 libraspberrypi-{bin,dev,doc} raspberrypi-bootloader
sudo reboot

My touchscreen doesn’t work, or works intermittently

  • Make sure you’ve updated Raspberry Pi OS (see above for steps)

  • Check the smaller ribbon cable is seated properly

If you want to make sure your Pi has detected your touchscreen, try running:

dmesg | grep -i ft5406

You should see a couple of lines that look like this:

[ 5.224267] rpi-ft5406 rpi_ft5406: Probing device
[ 5.225960] input: FT5406 memory based driver as /devices/virtual/input/input3

A detected touchscreen will also cause the fbheight and fbwidth parameters in /proc/cmdline to equal 480 and 800 respectively (the resolution of the screen). You can verify this by running:

cat /proc/cmdline | grep bcm2708_fb

My screen is upside-down!

Depending on your display stand, you might find that the LCD display defaults to being upside-down. You can fix this by rotating it with /boot/config.txt.

sudo nano /boot/config.txt

Then add:

lcd_rotate=2

Hit CTRL+X and y to save. And finally:

sudo reboot

My display fades out to weird patterns when I shutdown/reboot my Pi

Don’t panic! This is perfectly normal.

My display is black

  • Make sure you’ve updated Raspberry Pi OS (see above for steps)

  • Check the ribbon cable between your Pi and the LCD is properly seated

  • Make sure you have a SD card properly inserted into your Pi

My display is white

  • Check the larger ribbon cable between the display and driver board is properly seated

Raspberry Pi OS says my screen is 752x448. Surely that’s wrong?

Yes, the screen should be 800x480. This is a result of overscan being enabled.

Disable it by running raspi-config:

sudo raspi-config

And then navigating to Advanced Options > Overscan and picking Disable.

My touchscreen isn’t aligned correctly: my taps are slightly out

This is probably also a side-effect of overscan being enabled, try the solution above.

Some windows are cut off at the bottom of the screen so I can’t use them

If some windows in X are cut off at the side/bottom of the screen, this is unfortunately a side-effect of developers assuming a minimum screen resolution of 1024x768 pixels.

You can usually reveal hidden buttons and fields by;

  • right clicking on the edge or top of the window,

  • picking "move"

  • using the up arrow key to nudge the window up off the top of the screen

If you don’t have a mouse, see the right click fix below.

Tips and Tricks

How do I use multiple monitors?

At the moment you can’t use HDMI and the LCD together in the X desktop, but you can send the output of certain applications to one screen or the other.

Omxplayer is one example. It has been modified to enable secondary display output.

To start displaying a video onto the LCD display (assuming it is the default display) just type:

omxplayer video.mkv

To start a second video onto the HDMI type:

omxplayer --display=5 video.mkv

Please note: you may need to increase the amount of memory allocated to the GPU to 128MB if the videos are 1080P. Adjust the gpu_mem value in config.txt for this. The Raspberry Pi headline figures are 1080P30 decode, so if you are using two 1080P clips it may not play correctly depending on the complexity of the videos.

Display numbers are:

  • LCD: 4

  • TV/HDMI: 5

  • Auto select non-default display: 6

How do I enable right click?

You can emulate a right click with a setting change. Just:

sudo nano /etc/X11/xorg.conf

Paste in:

Section "InputClass"
   Identifier "calibration"
   Driver "evdev"
   MatchProduct "FT5406 memory based driver"

   Option "EmulateThirdButton" "1"
   Option "EmulateThirdButtonTimeout" "750"
   Option "EmulateThirdButtonMoveThreshold" "30"
EndSection

Hit CTRL+X and y to save. Then:

sudo reboot

Once enabled, right click works by pressing and holding the touchscreen and will be activated after a short delay.

How do I get an on-screen keyboard?

Florence Virtual Keyboard

Install with:

sudo apt install florence
Matchbox Virtual Keyboard

Install like so:

sudo apt install matchbox-keyboard

And then find in Accessories > Keyboard.