Merge pull request #3901 from raspberrypi/touch-display-2

Roll out TD2

Author: nathan-contino

documentation/asciidoc/accessories/display/display_intro.adoc

@@ -1,15 +1,15 @@
 == Raspberry Pi Touch Display
 
-The https://www.raspberrypi.com/products/raspberry-pi-touch-display/[Raspberry Pi Touch Display] is an LCD display that connects to the Raspberry Pi using the DSI connector. You can use both the Touch Display and an HDMI display output at the same time.
+The https://www.raspberrypi.com/products/raspberry-pi-touch-display/[Raspberry Pi Touch Display] is an LCD display that connects to the Raspberry Pi using a DSI connector and GPIO connector.
 
 .The Raspberry Pi 7-inch Touch Display
 image::images/display.png[The Raspberry Pi 7-inch Touch Display, width="70%"]
 
-The Touch Display is compatible with all models of Raspberry Pi except the Raspberry Pi Zero and Zero 2 W, which lack a DSI connector. The earliest Raspberry Pi models lack appropriate mounting holes, requiring additional mounting hardware to fit the stand-offs on the display PCB.
+The Touch Display is compatible with all models of Raspberry Pi from Raspberry Pi 1B+ onwards, except Raspberry Pi Zero and Zero 2 W, which lack a DSI connector. The earliest Raspberry Pi models lack appropriate mounting holes, requiring additional mounting hardware to fit the stand-offs on the display PCB.
 
 The display has the following key features: 
 
-* 800×480 RGB LCD display
+* 800×480px RGB LCD display
 * 24-bit colour
 * Industrial quality: 140 degree viewing angle horizontal, 120 degree viewing angle vertical
 * 10-point multi-touch touchscreen
@@ -85,7 +85,7 @@ TIP: In Raspberry Pi OS releases prior to _Bookworm_, use `matchbox-keyboard` in
 
 === Change screen orientation
 
-If you want to physically rotate the display, or mount it in a specific position, select **Screen Configuration** from the **Preferences** menu. Right-click on the DSI-1 display rectangle in the layout editor, select **Orientation**, then pick the best option to fit your needs. You can also ensure that the touch overlay is assigned to the correct display with the **Touchscreen** option.
+If you want to physically rotate the display, or mount it in a specific position, select **Screen Configuration** from the **Preferences** menu. Right-click on the touch display rectangle (likely DSI-1) in the layout editor, select **Orientation**, then pick the best option to fit your needs.
 
 image::images/display-rotation.png[Screenshot of orientation options in screen configuration, width="80%"]
 
@@ -153,7 +153,7 @@ The `vc4-kms-dsi-7inch` overlay supports the following options:
 | Disables the touch overlay totally
 |===
 
-To specify these options, add them, separated by commas, to your `dtoverlay` line in `/boot/firmware/config.txt`. Boolean values default to true when present, but you can set them to false with the suffix "=0". Integer values require a value, e.g. `sizey=240`. For instance, to set the X resolution to 400 pixels and invert both X and Y coordinates, use the following line:
+To specify these options, add them, separated by commas, to your `dtoverlay` line in `/boot/firmware/config.txt`. Boolean values default to true when present, but you can set them to false using the suffix "=0". Integer values require a value, e.g. `sizey=240`. For instance, to set the X resolution to 400 pixels and invert both X and Y coordinates, use the following line:
 
 [source,ini]
 ----

documentation/asciidoc/accessories/touch-display-2.adoc

@@ -0,0 +1 @@
+include::touch-display-2/about.adoc[]

documentation/asciidoc/accessories/touch-display-2/about.adoc

@@ -0,0 +1,129 @@
+== About
+
+The https://www.raspberrypi.com/products/raspberry-pi-touch-display-2/[Raspberry Pi Touch Display 2] is a portrait orientation touchscreen LCD display designed for interactive projects like tablets, entertainment systems, and information dashboards.
+
+.The Raspberry Pi Touch Display 2
+image::images/touch-display-2-hero.jpg[width="80%"]
+
+The Touch Display 2 connects to a Raspberry Pi using a DSI connector and GPIO connector. Raspberry Pi OS provides touchscreen drivers with support for five-finger multitouch and an on-screen keyboard, providing full functionality without the need to connect a keyboard or mouse.
+
+== Specifications
+
+* 1280×720px resolution, 24-bit RGB display
+* 155×88mm active area
+* 7" diagonal
+* powered directly by the host Raspberry Pi, requiring no separate power supply
+* supports up to five points of simultaneous multi-touch
+
+The Touch Display 2 is compatible with all models of Raspberry Pi from Raspberry Pi 1B+ onwards, except Raspberry Pi Zero and Zero 2 W, which lack a DSI connector.
+
+The Touch Display 2 box contains the following parts (in left to right, top to bottom order in the image below):
+
+* Touch Display 2
+* eight M2.5 screws
+* 15-way to 15-way FFC
+* 22-way to 15-way FFC for Raspberry Pi 5
+* GPIO connector cable
+
+.Parts included in the Touch Display 2 box
+image::images/touch-display-2-whats-in-the-booooox.jpg["Parts included in the Touch Display 2 box", width="80%"]
+
+== Install
+
+.A Raspberry Pi 5 connected and mounted to the Touch Display 2
+image::images/touch-display-2-installation-diagram.png["A Raspberry Pi 5 connected and mounted to the Touch Display 2", width="80%"]
+
+To connect a Touch Display 2 to a Raspberry Pi, use a Flat Flexible Cable (FFC) and a GPIO connector. The FFC you'll use depends upon your Raspberry Pi model:
+
+* for Raspberry Pi 5, use the included 22-way to 15-way FFC
+* for any other Raspberry Pi model, use the included 15-way to 15-way FFC
+
+Once you have determined the correct FFC for your Raspberry Pi model, complete the following steps to connect your Touch Display 2 to your Raspberry Pi:
+
+. Disconnect your Raspberry Pi from power.
+. Lift the retaining clips on either side of the FFC connector on the Touch Display 2.
+. Insert one 15-way end of your FFC into the Touch Display 2 FFC connector, with the copper contacts facing upwards, away from the Touch Display 2.
++
+TIP: If you use 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.
+. While holding the FFC firmly in place, simultaneously push both retaining clips down on the FFC connector of the Touch Display 2.
+. Lift the retaining clips on either side of the DSI connector of your Raspberry Pi. This port should be marked with some variation of the term `DISPLAY` or `DISP`. If your Raspberry Pi has multiple DSI connectors, prefer the port labelled `1`.
+. Insert the other end of your FFC into the Raspberry Pi DSI connector, with the copper contacts facing towards the Ethernet and USB-A ports.
+. While holding the FFC firmly in place, simultaneously push both retaining clips down on the DSI connector of the Raspberry Pi.
+. Plug the GPIO connector cable into the port marked `J1` on the Touch Display 2.
+. Connect the other (three-pin) end of the GPIO connector cable to pins 2, 4, and 6 of the xref:../computers/raspberry-pi.adoc#gpio[Raspberry Pi's GPIO]. Connect the red cable (5V power) to pin 2, and the black cable (ground) to pin 6. Viewed from above, with the Ethernet and USB-A ports facing down, these pins are located at the top right of the board, with pin 2 in the top right-most position.
++
+.The GPIO connection to the Touch Display 2
+image::images/touch-display-2-gpio-connection.png[The GPIO connection to the Touch Display 2, width="40%"]
++
+TIP: If pin 6 isn't available, you can use any other open `GND` pin to connect the black wire. If pin 2 isn't available, you can use any other 5V pin to connect the red wire, such as pin 4.
+. Optionally, use the included M2.5 screws to mount your Raspberry Pi to the back of the Touch Display 2.
+.. Align the four corner stand-offs of your Raspberry Pi with the four mount points that surround the FFC connector and `J1` port on the back of the Touch Display 2, taking special care not to pinch the FFC.
+.. Insert the screws into the four corner stand-offs and tighten until your Raspberry Pi is secure.
+. Reconnect your Raspberry Pi to power. It may take up to one minute to initialise the Touch Display 2 connection and begin displaying to the screen.
+
+=== Use an on-screen keyboard
+
+Raspberry Pi OS _Bookworm_ and later include the Squeekboard on-screen keyboard by default. When a touch display is attached, the on-screen keyboard should automatically show when it is possible to enter text and automatically hide when it is not possible to enter text.
+
+For applications which do not support text entry detection, use the keyboard icon at the right end of the taskbar to manually show and hide the keyboard.
+
+You can also permanently show or hide the on-screen keyboard in the Display tab of Raspberry Pi Configuration or the `Display` section of `raspi-config`.
+
+TIP: In Raspberry Pi OS releases prior to _Bookworm_, use `matchbox-keyboard` instead. If you use the wayfire desktop compositor, use `wvkbd` instead.
+
+=== Change screen orientation
+
+If you want to physically rotate the display, or mount it in a specific position, select **Screen Configuration** from the **Preferences** menu. Right-click on the touch display rectangle (likely DSI-1) in the layout editor, select **Orientation**, then pick the best option to fit your needs.
+
+==== Rotate screen without a desktop
+
+To set the screen orientation on a device that lacks a desktop environment, edit the `/boot/firmware/cmdline.txt` configuration file to pass an orientation to the system. Add the following line to `cmdline.txt`:
+
+[source,ini]
+----
+video=DSI-1:1280x720@60,rotate=<rotation-value>
+----
+
+Replace the `<rotation-value>` placeholder with one of the following values, which correspond to the degree of rotation relative to the default on your display:
+
+* `0`
+* `90`
+* `180`
+* `270`
+
+For example, a rotation value of `90` rotates the display 90 degrees to the right. `180` rotates the display 180 degrees, or upside-down.
+
+NOTE: It is not possible to rotate the DSI display separately from the HDMI display with `cmdline.txt`. When you use DSI and HDMI simultaneously, they share the same rotation value.
+
+==== Touch Display 2 device tree option reference
+
+The `vc4-kms-dsi-ili9881-7inch` overlay supports the following options:
+
+|===
+| DT parameter | Action
+
+| `sizex`
+| Sets X resolution (default 1280)
+
+| `sizey`
+| Sets Y resolution (default 720)
+
+| `invx`
+| Invert X coordinates
+
+| `invy`
+| Invert Y coordinates
+
+| `swapxy`
+| Swap X and Y coordinates
+
+| `disable_touch`
+| Disables the touch overlay totally
+|===
+
+To specify these options, add them, separated by commas, to your `dtoverlay` line in `/boot/firmware/config.txt`. Boolean values default to true when present, but you can set them to false using the suffix "=0". Integer values require a value, e.g. `sizey=240`. For instance, to set the X resolution to 400 pixels and invert both X and Y coordinates, use the following line:
+
+[source,ini]
+----
+dtoverlay=vc4-kms-dsi-ili9881-7inch,sizex=400,invx,invy
+----

documentation/asciidoc/accessories/touch-display-2/images/touch-display-2-gpio-connection.png

@@ -108,6 +108,12 @@
                     "image": "full-sized/m2-hat-plus.png",
                     "subpath": "m2-hat-plus.adoc"
                 },
+                {
+                    "title": "Touch Display 2",
+                    "description": "The Raspberry Pi Touch Display 2",
+                    "image": "full-sized/Touch-Display-2.png",
+                    "subpath": "touch-display-2.adoc"
+                },
                 {
                     "title": "Camera",
                     "description": "Raspberry Pi camera boards",
@@ -120,12 +126,6 @@
                     "image": "full-sized/ai-cam.png",
                     "subpath": "ai-camera.adoc"
                 },
-                {
-                    "title": "Display",
-                    "description": "The Raspberry Pi Touch Display",
-                    "image": "full-sized/Display.png",
-                    "subpath": "display.adoc"
-                },
                 {
                     "title": "Keyboard and mouse",
                     "description": "Official Raspberry Pi keyboard and mouse",
@@ -168,6 +168,12 @@
                     "image": "full-sized/Designing-a-HAT.png",
                     "url": "https://datasheets.raspberrypi.com/hat/hat-plus-specification.pdf"
                 },
+                {
+                    "title": "Touch Display",
+                    "description": "The Raspberry Pi Touch Display",
+                    "image": "full-sized/Display.png",
+                    "subpath": "display.adoc"
+                },
                 {
                     "title": "TV HAT",
                     "description": "Watch TV on your Raspberry Pi",