Merge pull request #3130 from raspberrypi/bookworm

Merge Bookworm down to develop

documentation/asciidoc/accessories/audio/configuration.adoc

@@ -6,13 +6,13 @@ image::images/gui.png[]
 
 There are a number of third-party audio software applications available for Raspberry Pi that will support the plug-and-play feature of our audio boards. Often these are used headless. They can be controlled via a PC or Mac application, or by a web server installed on Raspberry Pi, with interaction through a webpage.
 
-If you need to configure Raspberry Pi OS yourself, perhaps if you're running a headless system of your own and don't have the option of control via the GUI, you will need to make your Raspberry Pi audio board the primary audio device in Raspberry Pi OS, disabling the Raspberry Pi’s on-board audio device. This is done by editing the `/boot/config.txt` file. Using a Terminal session connected to your Raspberry Pi via SSH, run the following command to edit the file:
+If you need to configure Raspberry Pi OS yourself, perhaps if you're running a headless system of your own and don't have the option of control via the GUI, you will need to make your Raspberry Pi audio board the primary audio device in Raspberry Pi OS, disabling the Raspberry Pi’s on-board audio device. This is done by editing the xref:../computers/config_txt.adoc#what-is-config-txt[`/boot/firmware/config.txt`] file. Using a Terminal session connected to your Raspberry Pi via SSH, run the following command to edit the file:
 
 ----
-$ sudo nano /boot/config.txt
+$ sudo nano /boot/firmware/config.txt
 ----
 
-Find the `dtparam=audio=on` line in the file and comment it out by placing a # symbol at the start of the line. Anything written after the # symbol in any given line will be disregarded by the program. Your ``/boot/config.txt`` file should now have the following entry:
+Find the `dtparam=audio=on` line in the file and comment it out by placing a # symbol at the start of the line. Anything written after the # symbol in any given line will be disregarded by the program. Your `/boot/firmware/config.txt` file should now contain the following entry:
 
 ----
 #dtparam=audio=on
@@ -24,7 +24,7 @@ Press CTRL+X, then Y and Enter to save, followed by a reboot of your Raspberry P
 $ sudo reboot
 ----
 
-Alternatively, the `/boot/config.txt` file can be edited directly onto the Raspberry Pi's microSD card, inserted into your usual computer. Using the default file manager, open the `boot` volume on the card and edit the `config.txt` file using an appropriate text editor, then save the file, eject the microSD card and reinsert it back into your Raspberry Pi.
+Alternatively, the `/boot/firmware/config.txt` file can be edited directly onto the Raspberry Pi's microSD card, inserted into your usual computer. Using the default file manager, open the `/boot/firmware/` volume on the card and edit the `config.txt` file using an appropriate text editor, then save the file, eject the microSD card and reinsert it back into your Raspberry Pi.
 
 === Attaching the HAT
 

documentation/asciidoc/accessories/audio/getting_started.adoc

@@ -18,7 +18,9 @@ Use a small flat-head screwdriver to attach your speaker to the screw terminals.
 
 === Setting up your Raspberry Pi
 
-In this example, we are using Raspberry Pi OS Lite. Our guides on https://www.raspberrypi.com/documentation/computers/getting-started.html#installing-the-operating-system[Getting started] cover this topic in great detail. Make sure that you update your operating system before proceeding and follow the instructions provided for Codec Zero configuration, including the commands to enable the on-board microphone and speaker output.
+In this example, we are using Raspberry Pi OS Lite. Refer to our guide on xref:../computers/getting-started.adoc#installing-the-operating-system[installing Raspberry Pi OS] for more details.
+
+Make sure that you update your operating system before proceeding and follow the instructions provided for Codec Zero configuration, including the commands to enable the on-board microphone and speaker output.
 
 === Programming your Raspberry Pi
 

documentation/asciidoc/accessories/audio/hardware-info.adoc

@@ -70,16 +70,6 @@ To restore a saved file:
 $ sudo alsactl restore -f /home/pi/usecase.state
 ----
 
-=== Using external USB devices
-
-If you want to enable 1.2 amp USB support (to allow USB hard disks to power up when
-accessory boards are in use), you may also want to add the following line to your `/boot/config.txt`
-file:
-
-----
-max_usb_current=1
-----
-
 === MPD-based audio with volume control
 
 To allow Music Player Daemon (MPD)-based audio software to control the audio board’s built in volume, the file

documentation/asciidoc/accessories/build-hat/py-installing-software.adoc

@@ -6,7 +6,7 @@ Install the Build HAT Python library. Open a Terminal window and type,
 
 [source]
 ----
-$ pip3 install buildhat 
+$ sudo apt install python3-buildhat 
 ----
 
 For more information about the Build HAT Python Library see https://buildhat.readthedocs.io/[ReadTheDocs].

documentation/asciidoc/accessories/camera/camera_hardware.adoc

@@ -190,7 +190,7 @@ Then, please follow the relevant setup instructions for the xref:../computers/ca
 | Depends on lens
 
 | Maximum exposure times (seconds)
-| 6 (legacy) / 0.97 (libcamera)
+| 0.97
 | 11.76
 | 112
 | 112

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,96 +1,71 @@
 == 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).
+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.
 
-[.whitepaper, title="Implementing a DSI Driver on the Raspberry Pi", subtitle="", link=https://pip.raspberrypi.com/categories/685-whitepapers-app-notes/documents/RP-003472-WP/Using-a-DSI-display.pdf]
-****
-This whitepaper is an introduction to writing a Display Serial Interface (DSI) driver for liquid crystal display (LCD) panels running under the Kernel Mode Setting (KMS) graphics system.
-****
+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.
 
-=== Board Support
+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.
 
-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.
+.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%"]
 
-=== Physical Installation
+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.
 
-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.
+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.
 
-image::images/GPIO_power-500x333.jpg[DSI Display Connections]
+=== Powering the Touch Display
 
-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.
+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. 
 
-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.
+==== Provide power through the Raspberry Pi
 
-=== Screen Orientation
+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.
 
-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.
+.The location of the display's 5V and GND pins
+image::images/touch-GPIO.png[Illustration of display pins, width="30%"]
 
-==== KMS and FKMS Mode
+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. 
 
-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.
+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.
 
-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 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.
 
-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.
+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.
 
-[,bash]
-----
-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.
+==== Provide power through a micro USB power supply
 
-To flip the display, add the following line to the file `/boot/config.txt`:
+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.
 
-`lcd_rotate=2`
+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.
 
-This will vertically flip the LCD and the touch screen, compensating for the physical orientation of the display.
+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.
 
-You can also rotate the display by adding the following to the `config.txt` file.
+=== Screen orientation
 
-* `display_lcd_rotate=x`, where `x` can be one of the following:
+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.
 
-|===
-| display_lcd_rotate | result
-
-| 0
-| no rotation
-
-| 1
-| rotate 90 degrees clockwise
+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.
 
-| 2
-| rotate 180 degrees clockwise
+image::images/display-rotation.png[Screenshot of orientation options in screen configuration, width="80%"]
 
-| 3
-| rotate 270 degrees clockwise
+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.
 
-| 0x10000
-| horizontal flip
+[source ,bash]
+----
+sudo nano /boot/firmware/cmdline.txt
+----
 
-| 0x20000
-| vertical flip
-|===
+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.
 
-NOTE: The 90 and 270 degree rotation options require additional memory on the GPU, so these will not work with the 16MB GPU split.
+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.
 
-=== Touchscreen Orientation
+=== 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:
+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`
+----
+dtoverlay=rpi-ft5406,touchscreen-swapped-x-y=1,touchscreen-inverted-x=1
+----
 
 The options for the touchscreen are:
 
@@ -113,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
@@ -137,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,17 +1,36 @@
 == 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.
 
 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 http://pinout.xyz/[this diagram].
 
-DSI display autodetection is disabled by default on these boards. To enable detection, add the following line to `/boot/config.txt`:
+DSI display autodetection is disabled by default on these boards. To enable detection, add the following line to the xref:../computers/config_txt.adoc#what-is-config-txt[`/boot/firmware/config.txt`] file:
 
 `ignore_lcd=0`
 
 Power the setup via the `PWR IN` micro-USB connector on the display board. Do not power the setup via the Raspberry 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.