Touch display changes

documentation/asciidoc/accessories/display.adoc

@@ -1,6 +1,3 @@
 include::display/display_intro.adoc[]
 
 include::display/legacy.adoc[]
-
-include::display/troubleshooting.adoc[]
-

documentation/asciidoc/accessories/display/display_intro.adoc

@@ -1,47 +1,71 @@
 == Raspberry Pi Touch Display
 
-The https://www.raspberrypi.com/products/raspberry-pi-touch-display/[Raspberry Pi Touch Display] is an LCD display which connects to the Raspberry Pi through the DSI connector. In recent versions of Raspberry Pi OS, both the HDMI and LCD display outputs can be used at the same time.
+The https://www.raspberrypi.com/products/raspberry-pi-touch-display/[Raspberry Pi Touch Display] is an LCD display which connects to the Raspberry Pi using the DSI connector. While the panel is connected, you can use both it, and the the normal HDMI display output at the same time.
 
-=== Board Support
+The Touch Display will function with all models of Raspberry Pi. Although the earliest Raspberry Pi models, which lack appropriate mounting holes, require additional mounting hardware to fit the stand-offs on the display PCB.
 
-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.
+You can mount a Raspberry Pi to the back of the Touch Display using its stand-offs and then connect the appropriate cables between each device, depending on your use case. You can also mount the Touch Display in a separate chassis if you have one available. The connections remain the same, though you may need longer cables depending on the chassis you use.
 
-=== Physical Installation
+.A Raspberry Pi connected to the Touch Display
+image::images/GPIO_power-500x333.jpg[Image of Raspberry Pi connected to the Touch Display, width="70%"]
 
-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.
+Connect one end of the Flat Flexible Cable (FFC) to the `RPI-DISPLAY` port on the Touch Display PCB. The silver or gold contacts should face away from the display. Then connect the other end of the FFC to the `DISPLAY` port on the Raspberry Pi. The contacts on this end should face inward, towards the Raspberry Pi.
 
-image::images/GPIO_power-500x333.jpg[DSI Display Connections]
+If the FFC isn't fully inserted, or it's not positioned correctly, you will experience issues with the display. You should always double-check this connection when troubleshooting, especially if you don't see anything on your display, or the display is showing a single colour.
 
-The other three pins should be left disconnected, unless connecting the display to an original Raspberry Pi 1 Model A or B. See the section on xref:display.adoc#legacy-support[legacy support] for more information on connecting the display to an original Raspberry Pi.
+=== Powering the Touch Display
 
-NOTE: An original Raspberry Pi can be easily identified from other models, it is the only model with a 26-pin rather than 40-pin GPIO header connector.
+We recommend using the Raspberry Pi's GPIO to provide power to the Touch Display. However, if you want to power the display directly, you can use a separate micro USB power supply to provide power. 
 
-=== Screen Orientation
+==== Provide power through the Raspberry Pi
 
-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.
+To power the Touch Display using a Raspberry Pi, you need to connect two jumper wires between the 5V and GND pins on xref:../computers/raspberry-pi.adoc#gpio-and-the-40-pin-header[Raspberry Pi's GPIO] and the 5V and GND pins on the display, as shown in the following illustration.
 
-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.
+.The location of the display's 5V and GND pins
+image::images/touch-GPIO.png[Illustration of display pins, width="30%"]
 
-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.
+Before you begin, make sure the Raspberry Pi is powered off and not connected to any power source. Connect one end of the black jumper wire to pin six (GND) on the Raspberry Pi and one end of the red jumper wire to pin four (5V). If pin six isn't available, you can use any other open GND pin to connect the black wire. 
 
-[,bash]
-----
-sudo nano /boot/firmware/cmdline.txt
-----
+Next, connect the other end of the black wire to the GND pin on the display and the other end of the red wire to the 5V pin on the display. Once all the connections are made, you should see the Touch Display turn on the next time you turn on your Raspberry Pi.
+
+The other three pins on the Touch Display are used to connect the display to an original Raspberry Pi 1 Model A or B. Refer to our documentation on xref:display.adoc#legacy-support[legacy support] for more information.
+
+NOTE: An original Raspberry Pi is easily identified compared to other models; it is the only model with a 26-pin rather than 40-pin GPIO header connector.
+
+==== Provide power through a micro USB power supply
+
+If you don't want to use a Raspberry Pi to provide power to the Touch Display, you can use a micro USB power supply instead. We recommend using the https://www.raspberrypi.com/products/micro-usb-power-supply/[Raspberry Pi 12.5W power supply] to make sure the display runs as intended.
+
+Do not connect the GPIO pins on your Raspberry Pi to the display if you choose to use micro USB for power. The only connection between the two boards should be the Flat Flexible Cable.
+
+WARNING: If you use a micro USB cable to power the display it must be mounted inside a chassis that blocks access to the display's PCB while it's in use.
+
+=== Screen orientation
 
-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.
+LCD displays have an ideal viewing angle, and it may be necessary to change the orientation of the display to find the perfect angle. If you need to physically rotate the display, or mount it in a specific position, you can use software to adjust the orientation of the screen to better match your setup.
 
+To set the screen orientation from the desktop environment, select **Screen Configuration** from the **Preferences** menu. Right-click on the DSI display rectangle 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%"]
+
+To set screen orientation from the command line, you need to edit the kernel's `/boot/firmware/cmdline.txt` file to pass the required orientation to the system.
+
+[source ,bash]
 ----
-video=DSI-1:800x480@60,rotate=90
+sudo nano /boot/firmware/cmdline.txt
 ----
 
-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 rotation value.
+To rotate the screen, add `video=DSI-1:800x480@60,rotate=90` to the `cmdline.txt` configuration file. Make sure everything is on the same line; do not add any carriage returns. Possible rotation values are 0, 90, 180 and 270.
 
-=== Touchscreen Orientation
+NOTE: In console mode it is not possible to rotate the DSI display separately from the HDMI display. If you have both attached they need to be set to the same rotation value.
 
-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:
+=== Touchscreen orientation
 
-`dtoverlay=rpi-ft5406,touchscreen-swapped-x-y=1,touchscreen-inverted-x=1`
+You also have the option to change the rotation of the active touchscreen area independently of the display itself by adding a `dtoverlay` instruction in the xref:../computers/config_txt.adoc[`/boot/firmware/config.txt`] file, as in the following example:
+
+----
+dtoverlay=rpi-ft5406,touchscreen-swapped-x-y=1,touchscreen-inverted-x=1
+----
 
 The options for the touchscreen are:
 
@@ -64,10 +88,6 @@ The options for the touchscreen are:
 | Swap X and Y coordinates
 |===
 
-=== Troubleshooting
-
-Read our troubleshooting steps, tips, and tricks here: xref:display.adoc#troubleshooting-the-display[Raspberry Pi Touch Display troubleshooting].
-
 === Specifications
 
 * 800×480 RGB LCD display
@@ -88,7 +108,7 @@ Read our troubleshooting steps, tips, and tricks here: xref:display.adoc#trouble
  ** Right - 70
 * Power requirements: 200mA at 5V typical, at maximum brightness.
 
-==== Mechanical Specification
+==== Mechanical specification
 
 * Outer dimensions: 192.96 × 110.76mm
 * Viewable area: 154.08 × 85.92mm

documentation/asciidoc/accessories/display/legacy.adoc

@@ -1,6 +1,26 @@
 == Legacy Support
 
-NOTE: These instructions are for the original Raspberry Pi 1 Model A and B boards only. You can identify an original board as it is the only model with a 26-pin GPIO header, all other models have the now-standard 40-pin connector.
+[NOTE]
+====
+These options are only available through X11 with pre-Raspberry Pi 4 hardware and pre-Bookworm releases of Raspberry Pi OS. 
+
+Run `sudo apt install matchbox-keyboard` in a terminal to install an on-screen keyboard.
+
+Add this code to `/etc/X11/xorg.conf` to enable right-click emulation:
+----
+Section "InputClass"
+   Identifier "calibration"
+   Driver "evdev"
+   MatchProduct "FT5406 memory based driver"
+
+   Option "EmulateThirdButton" "1"
+   Option "EmulateThirdButtonTimeout" "750"
+   Option "EmulateThirdButtonMoveThreshold" "30"
+EndSection
+----
+====
+
+These instructions are for the original Raspberry Pi 1 Model A and B boards only. You can identify an original board as it is the only model with a 26-pin GPIO header, all other models have the now-standard 40-pin connector.
 
 The DSI connector on the Raspberry Pi 1 Model A and 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.