Touch Display 2

Raspberry Pi Touch Display 2

Edit this on GitHub

Raspberry Pi Touch Display 2 is a touchscreen LCD that is available in 5-inch and 7-inch versions. It is intended for interactive use cases like tablets, entertainment systems, and information dashboards.

touch display 2 hero
The Raspberry Pi Touch Display 2.

Compatibility

Touch Display 2 is compatible with Raspberry Pi B+ and later.

It isn’t compatible with either Raspberry Pi Zero series or Raspberry Pi Keyboard computers, because these don’t have DSI connectors.

Raspberry Pi Model 5 and Raspberry Pi Compute Modules natively support connecting up to two Touch Display 2s.

You can mount an SBC form-factor Raspberry Pi directly to the back of the Touch Display 2.

Autodetection

Raspberry Pi Model B+ and later devices auto-detect Touch Display 2.

Raspberry Pi Compute Modules don’t auto-detect DSI displays because they are intended for industrial applications where the integrator can use any and all GPIOs and interfaces for their own purposes.

Specifications

This section describes the characteristics and capabilities of Touch Display 2.

Features

Touch Display 2 has the following features:

  • 720 x 1280 pixel resolution. High-definition output.

  • 24-bit RGB display. Capable of showing over 16 million colours.

  • Multitouch. Supports up to five simultaneous touch points.

  • Mouse-equivalence. Supports full desktop control without a physical mouse, for example, selecting, dragging, scrolling, and long-pressing for menus.

  • On-screen keyboard. Supports an on-screen keyboard in place of a physical keyboard.

  • Integrated power. Powered directly by the host Raspberry Pi device, requiring no separate power supply.

Dimensions

Touch Display 2 has the following dimensions:

Depth

Outline dimensions

Viewing area

Active area

5-inch display

16 mm

143.5 x 91.5 mm

111.5 x 63 mm

110.5 x 62 mm

7-inch display

15 mm

189.5 x 120 mm

155.5 x 88 mm

154.5 x 87 mm

Hardware

The Touch Display 2 box contains the following:

  • A Touch Display 2

  • Eight M2.5 screws

  • A 15-way to 15-way flat flexible cable for connecting to Raspberry Pi 4 and earlier

  • A 22-way to 15-way flat flexible cable for connecting to Raspberry Pi 5

  • A GPIO power cable

Parts included in the Touch Display 2 box
Parts included in the Touch Display 2 box.

Connections

Touch Display 2 connects to a Raspberry Pi device using:

  • A DSI connector. You attach the appropriate flat flexible cable (FFC) to this to carry video and touch data.

    • Raspberry Pi 5 uses the supplied 22-way to 15-way FFC.

    • Raspberry Pi 4 and earlier use the supplied 15-way to 15-way FFC.

    • Raspberry Pi Compute Module IO Boards use a Raspberry Pi Standard-Mini FFC. This is sold separately.

  • The GPIO header. The supplied GPIO power cable carries power from the GPIO header on the Raspberry Pi to the display.

Connect to a Raspberry Pi device

Follow the appropriate procedures for your device.

You don’t need any special tools to connect your device to the display, but you must have the correct FFC cable ready. You also need your device, its boot media, and its power supply.

If you want to attach your device to the display, you need a Phillips/cross-head screwdriver that fits the M2.5 screws that are included with the display. If you don’t want to attach your device to the display, you might need a longer FFC cable.

  • Raspberry Pi B+ and later

  • Raspberry Pi Compute Module

Raspberry Pi B+ and later

Warning
 Disconnect your Raspberry Pi from power before starting Step 1.

Step 1. Connect the FFC to the Touch Display 2

Before you start, check that you have selected the correct flat flexible cable for your Raspberry Pi model:

  • For Raspberry Pi 5, use the 22-way to 15-way FFC.

  • For all other Raspberry Pi models, use the 15-way to 15-way FFC.

To connect the FFC:

  1. Slide the retaining clip outwards from both sides of the FFC connector on the Touch Display 2.

  2. Insert the FFC into the Touch Display 2 FFC connector, then slide the retaining clip back into place to secure the cable.

    The metal contacts must face upwards, away from the Touch Display 2.

    If you’re connecting to a Raspberry Pi 5, and therefore using the 22-way to 15-way FFC, the 22-way end is the smaller end of the cable. Insert the larger end of the cable into the Touch Display 2 FFC connector.

Image showing the flat flexible cable and GPIO connections correctly attached to the Touch Display 2
The flat flexible cable and GPIO power cable (see Step 3) correctly attached to the Touch Display 2.

Step 2. Connect the FFC to the Raspberry Pi

Caution
 Take care not to pinch the FFC in this step.

  1. Slide the retaining clip upwards from both sides of the FFC connector on the Raspberry Pi. This is labelled DISPLAY on Raspberry Pi 4B and earlier.

  2. Connect the other end of the FFC to the port on the Raspberry Pi, then slide the retaining clip back into place to secure the cable.

    The metal contacts must face towards the Ethernet and USB-A ports.

    The FFC connector attached to a Raspberry Pi device
    The FFC connector attached to a Raspberry Pi device.

Step 3. Connect the GPIO power cable between the device and the display

Warning
 Connecting the power cable incorrectly can damage the display.

  1. Plug the smaller end of the GPIO power cable into the J1 port on the Touch Display 2.

  2. Connect the three-pin end of the GPIO power cable to your Raspberry Pi’s GPIO.

    With the USB and Ethernet ports facing down, the power cable must be attached vertically to the top-right of the GPIO header. This means the red 5 V power cable is at the top-right of the pin block.

    This results in the red cable connecting to pin 2 (top-right), and the black cable (ground) connecting to pin 6.

    The GPIO cable connected in the correct location and orientation, with the red 5 V cable at the top-right of the header
    The GPIO cable from the Touch Display 2 attaches to the top-right of the GPIO header on the Raspberry Pi device.

  3. (optional) To physically attach the Raspberry Pi to the Touch Display 2, align the device with the four corner stand-offs on the Touch Display 2, then insert the four M2.5 screws (included) into the stand-offs, and tighten until your Raspberry Pi is secure.

Step 4. Power on the Raspberry Pi

Now you’ve connected the Raspberry Pi to the Touch Display 2, power it on.

  1. Connect your boot media to the Raspberry Pi.

  2. Connect the Raspberry Pi to your power supply.

    The Touch Display 2 turns on when the device boots, but it can take up to one minute for Raspberry Pi OS to start displaying output on the screen.

Raspberry Pi Compute Module

This section assumes that you’re familiar with your Compute Module. For more information, see Raspberry Pi Compute Module.

You can connect a Touch Display 2 to a Raspberry Pi Compute Module that is attached to an IO Board. You need a Raspberry Pi Standard-Mini FFC (sold separately) to do this.

Step 1. Specify the display in config.txt

Raspberry Pi Compute Modules don’t automatically detect Touch Display 2s.

You must configure the Compute Module for the devices it is connecting to by adding an overlay entry in config.txt. The default connection is the port labelled 1, but you can use the port labelled 0.

Note
 If you’re using a Raspberry Pi Compute Module that has eMMC memory, make sure you edit the configuration file that is used to boot the device: either the one stored on the eMMC or one on external boot media if you’ve reconfigured the boot order. See rpiboot.

To enable Touch Display 2:

  1. Boot your Raspberry Pi Compute Module, then open /boot/firmware/config.txt.

    If you’re running a headless setup, either open the boot media on another computer or remotely connect to the device using Raspberry Pi Connect or SSH.

  2. Edit the config.txt file to add one of the following:

    • For the 5-inch display, enter dtoverlay=vc4-kms-dsi-ili9881-5inch

    • For the 7-inch display, enter dtoverlay=vc4-kms-dsi-ili9881-7inch

      To use the CAM/DISP 0 or DISP0 port, append ,dsi0 to the overlay name:

    • For the 5-inch display, enter dtoverlay=vc4-kms-dsi-ili9881-5inch,dsi0

    • For the 7-inch display, enter dtoverlay=vc4-kms-dsi-ili9881-7inch,dsi0

  3. Power down your device, then disconnect the power supply.

Step 2. Connect the FFC to the Touch Display 2

Important
 If you haven’t already done so, disconnect your Raspberry Pi Compute Module from power before continuing.

To connect the FFC to the display:

  1. Slide the retaining clip outwards from both sides of the FFC connector on the Touch Display 2.

  2. Insert the widest end of the FFC into the Touch Display 2 FFC connector, then slide the retaining clip back into place to secure the cable.

    The metal contacts must face upwards, away from the Touch Display 2.

  3. Add two jumpers to J6, as required:

    • If connecting to CAM/DISP 1 on Raspberry Pi Compute Module 5 IO Board.

    • If connecting to the DSIO interface on Raspberry Pi Compute Module 4 IO Board.

Image showing the flat flexible cable correctly attached to the Touch Display 2
The FFC attached to the Touch Display 2.

Step 3. Connect the FFC to the Raspberry Pi Compute Module IO Board

  1. Open the retaining clip on the FFC connector on the Raspberry Pi Compute Module IO Board. Make sure you select the connector you set (CAM/DISP 1 or CAM/DISP 0) in the configuration file in Step 1.

  2. Insert the other end of the FFC into the connector port, then close the retaining clip to secure the cable.

    The metal contacts must face downwards.

The FFC connector attached to a Raspberry Pi device
The FFC connector attached to a Raspberry Pi device. Note that the DSI port is oriented horizontally on some devices and vertically on others.

Step 4. Connect the GPIO power cable between the device and the display

Warning
 Connecting the power cable incorrectly can damage the display.

To connect the GPIO power cable (supplied with the display) to Raspberry Pi Compute Module 4 IO Board and later:

  1. Plug the smaller end of the GPIO power cable into the J1 port on the Touch Display 2.

  2. Position the Compute Module IO Board with the USB and HDMI ports facing left.

  3. Connect the three-pin end of the GPIO power cable to the top right of the GPIO header (labelled Rasperry Pi HAT on the silkscreen).

Image showing the correct installation of a GPIO power cable on a Raspberry Pi Compute Module IO Board.
The GPIO power cable attached to the GPIO header on a Raspberry Pi Compute Module Board.

Step 5. Power on your Compute Module

Image showing a Raspberry Pi Compute Module IO Board attached to a Touch Display 2.
A Raspberry Pi Compute Module IO Board connected to a Touch Display 2.

Now you have connected the Raspberry Pi Compute Module to the Touch Display 2, power the Compute Module on.

  1. Connect your boot media to the Raspberry Pi device – skip this if you’re booting from eMMC.

  2. Connect the Raspberry Pi device to your power supply.

  3. If your IO board has one, press and release the Power Button.

    The Touch Display 2 turns on when the device boots, but it can take up to one minute for Raspberry Pi OS to start displaying output on the screen.

Troubleshooting

Your display is now ready to use, but if it’s not turning on or not displaying anything, check the following:

  • DSI connections. Check the FFC cable is seated properly at both ends, that the metal strips point towards the connections correctly, and that it is connected to the correct DSI connector.

  • GPIO connections. The display is powered by the GPIO cable from your device, so make sure both ends of the cable are seated properly and that the three-pin end of the cable is attached to the correct pins of the GPIO header.

  • Power. Check your device is powered on and has boot media attached (if required). If you’re using a Compute Module with a power switch, check that it has been pressed.

  • config.txt. If you’re using a Compute Module, check the syntax of the overlay you added to config.txt in Step 1. Check also that you’ve specified the correct screen size in the overlay.

  • EEPROM boot order. If you’re using a Compute Module with onboard boot media, or you have multiple drives attached to your Compute Module, make sure the config.txt file you edited in Step 1 is on the boot media you’re booting from.

If none of these things help, visit the Raspberry Pi forums to get further assistance.

On-screen keyboard

Raspberry Pi OS Bookworm and later include the Squeekboard on-screen keyboard.

With Touch Display 2, this keyboard automatically appears when you can enter text. It automatically disappears when you can’t.

For applications that don’t support text entry detection, you can manually show or hide the keyboard by selecting the keyboard icon at the top-right of the taskbar.

To always show, or to always disable, the on-screen keyboard using the Raspberry Pi graphical interface:

  1. From the Raspberry Pi menu, go to Preferences > Control Centre > Display.

  2. Select Enabled always or Disabled, as required.

To permanently show, or to disable, the on-screen keyboard using the command line:

  1. Open a terminal, and enter sudo raspi-config.

  2. Navigate to the Display section of raspi-config, then choose your keyboard setting.

Change display orientation

If you’re using Raspberry Pi OS with a desktop environment, you can change the orientation of Touch Display 2 with the Raspberry Pi Control Centre application. This allows you to independently change the orientation of multiple connected displays.

If you’re using Raspberry Pi OS Lite (which has no desktop environment), you can change the orientation of Touch Display 2 by editing /boot/firmware/cmdline.txt. However, if you have multiple displays connected, this method changes the orientation of them all.

There are four orientations to choose from:

  • Normal (default). Portrait format.

  • Left. Display rotated 90 degrees clockwise.

  • Inverted. Display rotated 180 degrees.

  • Right. Display rotated 270 degrees clockwise.

With the desktop

To rotate the display using the Raspberry Pi desktop:

  1. Go to Preferences > Control Centre > Screens.

  2. Right-click the rectangle in the layout editor that represents your Touch Display 2 (likely labelled DSI-1).

  3. Select Orientation.

  4. Choose between Normal, Left, Inverted, or Right, to rotate the display.

  5. Select Apply, then select OK to keep your change or Cancel to discard it.

With the kernel command line

To rotate the display in console mode by editing the kernel command line:

  1. Open the /boot/firmware/cmdline.txt file, which contains parameters that Raspberry Pi OS reads when it boots.

  2. Add the following to the end of the file, replacing <rotation-value> with the number of degrees clockwise to rotate by (0, 90, 180, or 270):

    video=DSI-1:720x1280@60,rotate=<rotation-value>

    The rotate= setting only rotates the text-mode console. For applications that write directly to DRM, such as cvlc or the libcamera apps, use the rotation options that come with them (if available).

Change display brightness

  1. Go to Preferences > Control Centre > Screens.

  2. Right-click the rectangle in the layout editor that represents your Touch Display 2 (likely labelled DSI-1).

  3. Select Brightness.

  4. Choose a brightness level.

    The brightness level changes immediately.

Customise touchscreen settings

Note
 These settings are only required when rotating the display and using touch inputs in a non-desktop environment.

Use the Device Tree overlay to tell Raspberry Pi OS how to configure the Touch Display 2 at boot.

  • For the 5-inch display, the overlay is called vc4-kms-dsi-ili9881-5inch.

  • For the 7-inch display, the overlay is called vc4-kms-dsi-ili9881-7inch.

To modify the Device Tree overlay in the boot configuration:

  1. Open /boot/firmware/config.txt.

  2. Add the required Device Tree parameters to a dtoverlay line, separated by commas. See the Device Tree options table below for details.

Device Tree options

Parameter Action

sizex

Sets the touch horizontal resolution (default 720)

sizey

Sets the touch vertical resolution (default 1280)

invx

Inverts the touch X-axis (left/right)

invy

Inverts the touch Y-axis (up/down)

swapxy

Swaps the touch X and Y axes (rotate 90° logically)

disable_touch

Disables the touchscreen functionality

  • Booleans (invx, invy, swapxy, and disable_touch) default to true if present, but you can set them to false using the suffix =0.

  • Integers (sizex and sizey) require a number, for example, sizey=240.

Example

In the following example for a 7-inch Touch Display 2, invx inverts the X axis, and invy inverts the Y axis:

dtoverlay=vc4-kms-dsi-ili9881-7inch,invx,invy