Merge pull request #3170 from raspberrypi/develop

Push to production

documentation/asciidoc/accessories/sense-hat/software.adoc

@@ -35,7 +35,7 @@ You can find more information on how to use the Sense HAT in the Raspberry Pi Pr
 
 `sense-hat` is the officially supported library for the Sense HAT; it provides access to all of the on-board sensors and the LED matrix.
 
-Complete documentation for the library can be found at https://pythonhosted.org/sense-hat/[pythonhosted.org/sense-hat].
+Complete documentation for the library can be found at https://sense-hat.readthedocs.io/en/latest/[sense-hat.readthedocs.io].
 
 === Using the Sense HAT with {cpp}
 

documentation/asciidoc/computers/configuration/boot_folder.adoc

@@ -41,10 +41,6 @@ Some text-based housekeeping information containing the date and git commit ID o
 
 When this file is present, SSH will be enabled on boot. The contents don't matter, it can be empty. SSH is otherwise disabled by default.
 
-==== wpa_supplicant.conf
-
-This is the file to configure wireless network settings (if the hardware is capable of it). Edit the country code and the network part to fit your case. More information on how to use this file can be found in xref:configuration.adoc#setting-up-a-headless-raspberry-pi[the `wireless/headless` section].
-
 ==== Device Tree files
 
 There are various Device Tree blob files, which have the extension `.dtb`. These contain the hardware definitions of the various models of Raspberry Pi, and are used on boot to set up the kernel xref:configuration.adoc#part3.1[according to which Raspberry Pi model is detected].

documentation/asciidoc/computers/configuration/display-rotation.adoc

@@ -60,7 +60,7 @@ xrandr --output HDMI-1 --reflect x
 
 === Rotating the text console
 
-This is acheived by editing the KMS settings - see <<the-kernel-command-line,configuring the kernel command line>> for more details.
+This is achieved by editing the KMS settings - see <<the-kernel-command-line,configuring the kernel command line>> for more details.
 
 NOTE: If you have multiple screens connected, they must all be set to the same rotation value in console mode, or no rotation will be applied.
 

documentation/asciidoc/computers/configuration/headless.adoc

@@ -1,77 +1,46 @@
-== Setting up a Headless Raspberry Pi
+[[setting-up-a-headless-raspberry-pi]]
+== Set up a headless Raspberry Pi
 
-To use your Raspberry Pi without a monitor or keyboard (known as headless), you need to enable wireless networking and SSH.
+A **headless** Raspberry Pi runs without a monitor, keyboard, or mouse. To run a Raspberry Pi headless, you need a way to access it from another computer. To access your Raspberry Pi remotely, you'll need to connect your Raspberry Pi to a network, and a way to access the Raspberry Pi over that network.
 
-If you haven't already imaged your Raspberry Pi, you can set up wireless networking and SSH during the xref:getting-started.adoc#installing-the-operating-system[imaging process].
+To connect your Raspberry Pi to a network, you can either plug your device into a wired connection via Ethernet or configure wireless networking.
 
-If you already have an image on the micro SD card, you can access the xref:configuration.adoc#the-boot-folder[boot folder] by inserting the card into a card reader on a Linux or Windows machine. Adding certain files to this folder will activate certain setup features on the first boot of the Raspberry Pi.
+To access your Raspberry Pi over that network, use SSH. Once you've connected over SSH, you can use `raspi-config` to xref:remote-access.adoc#vnc[enable VNC] if you'd prefer a graphical desktop environment.
 
-If you plan on using VNC to access the desktop environment of your headless Raspberry Pi, use the `raspi-config` tool to set a xref:configuration.adoc#resolution[default display resolution].
+If you're setting up your Raspberry Pi from scratch, set up wireless networking and SSH during the xref:getting-started.adoc#installing-the-operating-system[imaging process]. If you've already got a Raspberry Pi set up, you can configure SSH using `raspi-config`.
 
-IMPORTANT: If you are installing Raspberry Pi OS, and intend to run it headless, you will need to create a new user account. Since you will not be able to create the user account xref:getting-started.adoc#configuration-on-first-boot[using the first-boot wizard] as it requires both a monitor and a keyboard, you *MUST* add a `userconf.txt` file to the boot folder to create a user on first boot or configure the OS with a user account using the xref:getting-started.adoc#advanced-options[Advanced Menu] in the Raspberry Pi Imager.
+WARNING: Depending on the model and SD card, your Raspberry Pi may require up to 5 minutes to boot and connect to your wireless network the first time it boots.
 
-=== Configuring Networking
+=== Connect to a wired network
 
-You will need to define a `wpa_supplicant.conf` file for your particular wireless network. Put this file onto the boot folder of the SD card. When the Raspberry Pi boots for the first time, it will copy that file into the correct location in the Linux root file system and use those settings to start up wireless networking.
+To connect to a wired network at first boot, plug your headless Raspberry Pi in via Ethernet, or an Ethernet adapter if your Raspberry Pi model does not include an Ethernet port. Your Raspberry Pi will automatically connect to the network.
 
-The Raspberry Pi's IP address will not be visible immediately after power on, so this step is crucial to connect to it headlessly. Depending on the OS and editor you are creating this on, the file could have incorrect newlines or the wrong file extension so make sure you use an editor that accounts for this. Linux expects the line feed (LF) newline character. 
+=== Connect to a wireless network
 
-WARNING: After your Raspberry Pi is connected to power, make sure to wait a few (up to 5) minutes for it to boot up and register on the network.
+To configure wireless network access at first boot in a headless Raspberry Pi, use the advanced settings menu in Raspberry Pi Imager. Enter the SSID and password of your preferred wireless network. Your Raspberry Pi will use these credentials to connect to the network on first boot. Some wireless adapters and some Raspberry Pi boards do not support 5Ghz networks; check the documentation for your wireless module to ensure compatibility with your preferred network.
 
-A xref:configuration.adoc#wireless-networking-command-line[`wpa_supplicant.conf`] file example:
+NOTE: Previous versions of Raspberry Pi OS made use of a `wpa_supplicant.conf` file which could be placed into the boot folder to configure wireless network settings. This is no longer possible from Raspberry Pi OS Bookworm onwards.
 
-----
-ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
-country=<Insert 2 letter ISO 3166-1 country code here>
-update_config=1
-
-network={
- ssid="<Name of your wireless LAN>"
- psk="<Password for your wireless LAN>"
-}
-----
-
-Where the country code should be set the two letter ISO/IEC alpha2 code for the country in which you are using, e.g.
-
-* GB (United Kingdom)
-* FR (France)
-* DE (Germany)
-* US (United States)
-* SE (Sweden)
+=== Remote access
 
-Here is a more elaborate example that should work for most typical wpa2 personal networks. This template below works for 2.4ghz/5ghz hidden or not networks. The utilization of quotes around the ssid - psk can help avoid any oddities if your network ssid or password has special chars (! @ # $ etc)
-
-----
-ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
-update_config=1
-country=<Insert 2 letter ISO 3166-1 country code here>
-
-network={
-        scan_ssid=1
-        ssid="<Name of your wireless LAN>"
-        psk="<Password for your wireless LAN>"
-        proto=RSN
-        key_mgmt=WPA-PSK
-        pairwise=CCMP
-        auth_alg=OPEN
-}
-----
+With no keyboard or monitor, you need a way to xref:remote-access.adoc[remotely control] your headless Raspberry Pi. On first boot, the only option is SSH. To enable SSH on a fresh installation of Raspberry Pi OS, choose one of the following methods:
 
-NOTE: Some older Raspberry Pi boards and some USB wireless dongles do not support 5GHz networks.
+* enable SSH in the Advanced Menu of Raspberry Pi Imager, then enter a username and password
+* create a file named `ssh` at the root of the SD card, then configure a user manually with `userconf.txt` following the instructions in the section below
 
-NOTE: With no keyboard or monitor, you will need some way of xref:remote-access.adoc[remotely accessing] your headless Raspberry Pi. For headless setup, SSH can be enabled by placing a file named `ssh`, without any extension, onto the boot folder of the SD Card. For more information see the section on xref:remote-access.adoc#ssh[setting up an SSH server].
+For more information, see xref:remote-access.adoc#ssh[set up an SSH server]. Once you've connected over SSH, you can use `raspi-config` to xref:remote-access.adoc#vnc[enable VNC] if you'd prefer a graphical desktop environment.
 
 [[configuring-a-user]]
-=== Configuring a User
+==== Configure a user manually
 
-You will need to add a `userconf.txt` in the boot partition of the SD card; this is the part of the SD card which can be seen when it is mounted in a Windows or MacOS computer.
+At the root of your SD card, create a file named `userconf.txt`.
 
-This file should contain a single line of text, consisting of `username:password` – so your desired username, followed immediately by a colon, followed immediately by an *encrypted* representation of the password you want to use.
+This file should contain a single line of text, consisting of `<username>:<password>`: your desired username, followed immediately by a colon, followed immediately by an *encrypted* representation of the password you want to use.
 
-To generate the encrypted password, the easiest way is to use OpenSSL on a Raspberry Pi that is already running – open a terminal window and enter:
+To generate the encrypted password, use https://www.openssl.org[OpenSSL] on another computer. Open a terminal and enter the following:
 
 ----
 openssl passwd -6
 ----
 
-This will prompt you to enter your password, and verify it. It will then produce what looks like a string of random characters, which is actually an encrypted version of the supplied password.
+When prompted, enter your password and verify it. This command will then output an encrypted version of the supplied password.

documentation/asciidoc/computers/configuration/kernel-command-line-config.adoc

@@ -43,7 +43,7 @@ In addition, it is possible to add rotation and reflect parameters as documented
 video=HDMI-A-1:1920x1080M@60,rotate=90,reflect_x`
 ----
 
-NOTE: It is not possible to specify the rotation and reflection parameters without also explictly specifying the resolution.
+NOTE: It is not possible to specify the rotation and reflection parameters without also explicitly specifying the resolution.
 
 Possible options for the display type, the first part of the `video=` entry,  are as follows:
 

documentation/asciidoc/computers/os/using-python.adoc

@@ -1,10 +1,10 @@
 == Python on Raspberry Pi
 
-Python 3 is installed by default on Raspberry Pi OS and is used for many important functions. Interfering with the system Python installation can therefore cause problems for your operating system, so it's important that if you install third-party Python libaries you use the correct package management tools.
+Python 3 is installed by default on Raspberry Pi OS and is used for many important functions. Interfering with the system Python installation can therefore cause problems for your operating system, so it's important that if you install third-party Python libraries you use the correct package management tools.
 
-There are two routes to installing libraries into the default `python` distribution. Firstly you can use `apt` and install pre-configured system packages, or alternatively you can use `pip` to install packages that are not distributed as part of Raspberry Pi OS.
+There are two routes to installing libraries into the default `python` distribution. Firstly you can use `apt` and install pre-configured system packages, or alternatively, you can use `pip` to install packages that are not distributed as part of Raspberry Pi OS.
 
-IMPORTANT: From _Bookworm_ onwards packages installed via `pip` must be installed into a Python Virtal Environment using `venv`. This has been introduced by the Python community not Raspberry Pi, see https://peps.python.org/pep-0668/[PEP 668] for more details
+IMPORTANT: From _Bookworm_ onwards packages installed via `pip` must be installed into a Python Virtual Environment using `venv`. This has been introduced by the Python community, not Raspberry Pi, see https://peps.python.org/pep-0668/[PEP 668] for more details
 
 === Installing Python packages using apt
 
@@ -23,9 +23,9 @@ to install the pre-built library.
 
 Using `apt` makes installing larger packages, like `numpy` which has many native dependencies including a Fortran compiler, much simpler than installing individual packages using Python's own package management system.
 
-If you want to install a Python library called "foobar" you can use `apt search foobar` to search for the exact package name. In most cases you'll find that the required package is going to be called `python-foobar` or `python3-foobar`.
+If you want to install a Python library called "foobar" you can use `apt search foobar` to search for the exact package name. In most cases, you'll find that the required package is going to be called `python-foobar` or `python3-foobar`.
 
-=== About Python virtual enivronments
+=== About Python virtual environments
 
 In previous versions of the operating system you used to be able to directly install libraries system wide using the package installer for Python, commonly known as `pip`. You'll find the following sort of command in many tutorials online.
 
@@ -34,7 +34,7 @@ In previous versions of the operating system you used to be able to directly ins
 $ pip install buildhat
 ----
 
-However, in newer versions of Raspberry Pi OS, and other operating systems, this is disallowed. If you try and install a Python package system wide you'll recieve an error similar to this,
+However, in newer versions of Raspberry Pi OS, and other operating systems, this is disallowed. If you try and install a Python package system-wide you'll receive an error similar to this,
 
 [source,bash]
 ----
@@ -59,7 +59,7 @@ hint: See PEP 668 for the detailed specification.
 
 This error is generated because you're trying to install a third-party package into the system Python. A long-standing practical problem for Python users has been conflicts between OS package managers like `apt` and Python-specific package management tools like `pip`. These conflicts include both Python-level API incompatibilities and conflicts over file ownership.
 
-Therefore from _Bookworm_ onwards packages installed via `pip` must be installed into a Python Virtal Environment using `venv`. A virtual environment is a container where you can safely install third-party modules so they won't interfere with, or break, your system Python.
+Therefore from _Bookworm_ onwards packages installed via `pip` must be installed into a Python Virtual Environment using `venv`. A virtual environment is a container where you can safely install third-party modules so they won't interfere with, or break, your system Python.
 
 === Using pip with virtual environments
 
@@ -90,15 +90,15 @@ $
 
 NOTE: If you want to inherit the currently installed packages from the system Python you should create your virtual environment using `python -m venv --system-site-packages env`.
 
-Inside this directory is full Python distribution. To activate your virtual environment and make that version of Python the one you're currently using you should type,
+Inside this directory is a full Python distribution. To activate your virtual environment and make that version of Python the one you're currently using you should type,
 
 [source,bash]
 ----
 $ source env/bin/activate
 (env) $
 ----
 
-and you'll see that your prompt is now prepended with `(env)` to indicate that you're no longer using the system Python. Instead you're using the version of Python contained inside your virtual environment. Any changes you make here, or modules you install into your environment, won't cause problems for your system Python.
+and you'll see that your prompt is now prepended with `(env)` to indicate that you're no longer using the system Python. Instead, you're using the version of Python contained inside your virtual environment. Any changes you make here, or modules you install into your environment, won't cause problems for your system Python.
 
 [source,bash]
 ----

documentation/asciidoc/computers/raspberry-pi/boot-net.adoc

@@ -18,7 +18,7 @@ To network boot, the boot ROM does the following:
 * TFTP RRQ 'bootsig.bin'
  ** This will normally result in an error `file not found`. This is to be expected, and TFTP boot servers should be able to handle it.
 
-From this point the `bootcode.bin` code continues to load the system. The first file it will try to access is [`serial_number`]/start.elf. If this does not result in an error then any other files to be read will be pre-pended with the `serial_number`. This is useful because it enables you to create separate directories with separate start.elf / kernels for your Raspberry Pis.
+From this point the `bootcode.bin` code continues to load the system. The first file it will try to access is [`serial_number`]/start.elf. If this does not result in an error then any other files to be read will be prepended with the `serial_number`. This is useful because it enables you to create separate directories with separate start.elf / kernels for your Raspberry Pis.
 To get the serial number for the device you can either try this boot mode and see what file is accessed using tcpdump / wireshark, or you can run a standard Raspberry Pi OS SD card and `cat /proc/cpuinfo`.
 
 If you put all your files into the root of your tftp directory then all following files will be accessed from there.