diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 55cc13bb9..beb7f0705 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,9 +16,11 @@ Unless you are opening a pull request which will only make small corrections, fo Before starting writing your contribution to the documentation, you should take a look at the [style guide](https://github.com/raspberrypi/style-guide/blob/master/style-guide.md). +**IMPORTANT**: Because the documentation makes use of the Asciidoc `include` statement, the `xref:` statements inside the documentation do not link back to the correct pages on Github, as Github does not support Asciidoc include functionality (see [#2005](https://github.com/raspberrypi/documentation/issues/2005)). However, these links work correctly when the HTML documentation is built and deployed. Please do not submit Pull Requests fixing link destinations unless you're sure that the link is broken [on the documentation site](https://www.raspberrypi.com/documentation/) itself. + ## Type of Content -We welcome contributions from the community, ranging from correcting small typos all the way through to adding entire new sections to the documentation. However, going forward we're going to be fairly targetted about what sort of content we add to the documentation. We are looking to keep the repository, and the documentation, focussed on Raspberry Pi-specific things, rather than having generic Linux or computing content. +We welcome contributions from the community, ranging from correcting small typos all the way through to adding entire new sections to the documentation. However, going forward we're going to be fairly targeted about what sort of content we add to the documentation. We are looking to keep the repository, and the documentation, focused on Raspberry Pi-specific things, rather than having generic Linux or computing content. We are therefore deprecating the more generic documentation around using the Linux operating system, ahead of removing these sections entirely at some point in the future as part of a larger update to the documentation site. This move is happening as we feel these sort of more general topics are, ten years on from when the documentation was initially written, now much better covered elsewhere on the web. diff --git a/documentation/asciidoc/accessories/build-hat/net-brick.adoc b/documentation/asciidoc/accessories/build-hat/net-brick.adoc index 54cc2a8f8..f65318a92 100644 --- a/documentation/asciidoc/accessories/build-hat/net-brick.adoc +++ b/documentation/asciidoc/accessories/build-hat/net-brick.adoc @@ -1,6 +1,6 @@ === Using the Build HAT from .NET -The Raspberry Pi Built HAT is refered to "Brick" in LEGO® parlance and you can talk directly to it from .NET using the https://datasheets.raspberrypi.com/build-hat/build-hat-serial-protocol.pdf[Build HAT Serial Protocol]. +The Raspberry Pi Built HAT is referred to "Brick" in LEGO® parlance and you can talk directly to it from .NET using the https://datasheets.raspberrypi.com/build-hat/build-hat-serial-protocol.pdf[Build HAT Serial Protocol]. You can create a `brick` object as below, diff --git a/documentation/asciidoc/accessories/build-hat/net-sensors.adoc b/documentation/asciidoc/accessories/build-hat/net-sensors.adoc index 1ecf0c954..c8d6d72e8 100644 --- a/documentation/asciidoc/accessories/build-hat/net-sensors.adoc +++ b/documentation/asciidoc/accessories/build-hat/net-sensors.adoc @@ -179,8 +179,8 @@ while (!Console.KeyAvailable) { var colorRead = colorSensor.GetColor(); Console.WriteLine($"Color: {colorRead}"); - var relected = colorSensor.GetReflectedLight(); - Console.WriteLine($"Reflected: {relected}"); + var reflected = colorSensor.GetReflectedLight(); + Console.WriteLine($"Reflected: {reflected}"); var ambiant = colorSensor.GetAmbiantLight(); Console.WriteLine($"Ambiant: {ambiant}"); var distance = colorSensor.GetDistance(); @@ -210,4 +210,4 @@ while(!console.KeyAvailable) console.WriteLine($"Distance: {distance.Distance} mm"); Thread.Sleep(200); } ----- \ No newline at end of file +---- diff --git a/documentation/asciidoc/accessories/camera/libcamera_3rd_party_tuning.adoc b/documentation/asciidoc/accessories/camera/libcamera_3rd_party_tuning.adoc index 0a4af9ec0..a20bd82bd 100644 --- a/documentation/asciidoc/accessories/camera/libcamera_3rd_party_tuning.adoc +++ b/documentation/asciidoc/accessories/camera/libcamera_3rd_party_tuning.adoc @@ -2,7 +2,7 @@ ==== The Camera Tuning File -Most of the image procesing applied to frames from the sensor is done by the hardware ISP (Image Signal Procesor). This processing is governed by a set of _control algorithms_ and these in turn must have a wide range of parameters supplied to them. These parameters are tuned specifically for each sensor and are collected together in a JSON file known as the _camera tuning file_. +Most of the image processing applied to frames from the sensor is done by the hardware ISP (Image Signal Processor). This processing is governed by a set of _control algorithms_ and these in turn must have a wide range of parameters supplied to them. These parameters are tuned specifically for each sensor and are collected together in a JSON file known as the _camera tuning file_. This _tuning file_ can be inspected and edited by users. Using the `--tuning-file` command line option, users can point the system at completely custom camera tuning files. diff --git a/documentation/asciidoc/accessories/camera/libcamera_apps_intro.adoc b/documentation/asciidoc/accessories/camera/libcamera_apps_intro.adoc index 5f0ad4130..2321035d0 100644 --- a/documentation/asciidoc/accessories/camera/libcamera_apps_intro.adoc +++ b/documentation/asciidoc/accessories/camera/libcamera_apps_intro.adoc @@ -4,7 +4,7 @@ `libcamera` is a new software library aimed at supporting complex camera systems directly from the Linux operating system. In the case of the Raspberry Pi it enables us to drive the camera system directly from open source code running on ARM processors. The proprietary code running on the Broadcom GPU, and to which users have no access at all, is almost completely by-passed. -`libcamera` presents a C++ API to applications and works at the level of configuring the camera and then allowing an application to request image frames. These image buffers reside in system memory and can be passed directly to still image encoders (such as JPEG) or to video encoders (such as h.264), though such ancilliary functions as encoding images or displaying them are strictly beyond the purview of `libcamera` itself. +`libcamera` presents a C++ API to applications and works at the level of configuring the camera and then allowing an application to request image frames. These image buffers reside in system memory and can be passed directly to still image encoders (such as JPEG) or to video encoders (such as h.264), though such ancillary functions as encoding images or displaying them are strictly beyond the purview of `libcamera` itself. For this reason Raspberry Pi supplies a small set of example `libcamera-apps`. These are simple applications, built on top of `libcamera`, and are designed largely to emulate the function of the legacy stack built on Broadcom's propretary GPU code (some users will recognise these legacy applications as `raspstill` and `raspivid`). The applications we provide are: diff --git a/documentation/asciidoc/accessories/camera/libcamera_options_vid.adoc b/documentation/asciidoc/accessories/camera/libcamera_options_vid.adoc index 9a12d0303..b4925a566 100644 --- a/documentation/asciidoc/accessories/camera/libcamera_options_vid.adoc +++ b/documentation/asciidoc/accessories/camera/libcamera_options_vid.adoc @@ -90,7 +90,7 @@ Example: `libcamera-vid -t 0 -o test.h264 -k --initial pause` --split Split multiple recordings into separate files ---- -This option should be used in conjunction with `--keypress` or `--signal` and causes each recording session (inbetween the pauses) to be written to a separate file. +This option should be used in conjunction with `--keypress` or `--signal` and causes each recording session (in between the pauses) to be written to a separate file. Example: `libcamera-vid -t 0 --keypress --split --initial pause -o test%04d.h264` @@ -98,7 +98,7 @@ Example: `libcamera-vid -t 0 --keypress --split --initial pause -o test%04d.h264 --segment Write the video recording into multiple segments ---- -This option causes the video recording to be split accross multiple files where the parameter gives the approximate duration of each file in milliseconds. +This option causes the video recording to be split across multiple files where the parameter gives the approximate duration of each file in milliseconds. One convenient little trick is to pass a very small duration parameter (namely, `--segment 1`) which will result in each frame being written to a separate output file. This makes it easy to do "burst" JPEG capture (using the MJPEG codec), or "burst" raw frame capture (using `libcamera-raw`). diff --git a/documentation/asciidoc/accessories/camera/libcamera_vid.adoc b/documentation/asciidoc/accessories/camera/libcamera_vid.adoc index 637a8d9f4..1418cc29f 100644 --- a/documentation/asciidoc/accessories/camera/libcamera_vid.adoc +++ b/documentation/asciidoc/accessories/camera/libcamera_vid.adoc @@ -11,7 +11,7 @@ The resulting file can be played with `vlc` (among other applications) ---- vlc test.h264 ---- -Note that this is an unpackaged video bistream, it is not wrapped in any kind of container format (such as an mp4 file). The `--save-pts` option can be used to output frame timestamps so that the bitstream can subsequently be converted into an appropriate format using a tool like `mkvmerge`. +Note that this is an unpackaged video bitstream, it is not wrapped in any kind of container format (such as an mp4 file). The `--save-pts` option can be used to output frame timestamps so that the bitstream can subsequently be converted into an appropriate format using a tool like `mkvmerge`. `libcamera-vid -o test.h264 --save-pts timestamps.txt` diff --git a/documentation/asciidoc/accessories/display/display_intro.adoc b/documentation/asciidoc/accessories/display/display_intro.adoc index 98c3197db..7d186335c 100644 --- a/documentation/asciidoc/accessories/display/display_intro.adoc +++ b/documentation/asciidoc/accessories/display/display_intro.adoc @@ -103,7 +103,7 @@ The options for the touchscreen are: | Invert Y coordinates | touchscreen-swapped-x-y -| Swap X and Y cordinates +| Swap X and Y coordinates |=== === Troubleshooting diff --git a/documentation/asciidoc/computers/config_txt/boot.adoc b/documentation/asciidoc/computers/config_txt/boot.adoc index e183f1e9e..ebba73dbf 100644 --- a/documentation/asciidoc/computers/config_txt/boot.adoc +++ b/documentation/asciidoc/computers/config_txt/boot.adoc @@ -41,9 +41,11 @@ Set the `disable_commandline_tags` command to `1` to stop `start.elf` from filli === `arm_64bit` -If set to non-zero, forces the kernel loading system to assume a 64-bit kernel, starts the processors up in 64-bit mode, and sets `kernel8.img` to be the kernel image loaded, unless there is an explicit `kernel` option defined in which case that is used instead. Defaults to 0 on all platforms. *NOTE*: 64-bit kernels may be uncompressed image files or a gzip archive of an image (which can still be called kernel8.img; the bootloader will recognize the archive from the signature bytes at the beginning). +If set to non-zero, forces the kernel loading system to assume a 64-bit kernel, starts the processors up in 64-bit mode, and sets `kernel8.img` to be the kernel image loaded, unless there is an explicit `kernel` option defined in which case that is used instead. Defaults to 0 on all platforms. -Note that the 64-bit kernel will only work on the Pi4, Pi3, and Pi2B rev1.2 boards with latest firmware. +NOTE: 64-bit kernels may be uncompressed image files or a gzip archive of an image (which can still be called kernel8.img; the bootloader will recognize the archive from the signature bytes at the beginning). + +NOTE: The 64-bit kernel will only work on the Raspberry Pi 4, 3, and 2B rev 1.2 boards with latest firmware. === `arm_control` diff --git a/documentation/asciidoc/computers/config_txt/overclocking.adoc b/documentation/asciidoc/computers/config_txt/overclocking.adoc index cb0bf91fb..9aa7b822a 100644 --- a/documentation/asciidoc/computers/config_txt/overclocking.adoc +++ b/documentation/asciidoc/computers/config_txt/overclocking.adoc @@ -275,30 +275,6 @@ This table gives defaults for options that are the same across all models. The firmware uses Adaptive Voltage Scaling (AVS) to determine the optimum CPU/GPU core voltage in the range defined by `over_voltage` and `over_voltage_min`. -|=== -| Model | Default | Resulting voltage - -| Pi 1 -| 0 -| 1.2V - -| Pi 2 -| 0 -| 1.2-1.3125V - -| Pi 3 -| 0 -| 1.2-1.3125V - -| Pi 4, Pi400, CM4 -| 0 -| 0.88V - -| Pi Zero -| 6 -| 1.35V -|=== - [discrete] ===== Specific to Raspberry Pi 4, Raspberry Pi 400 and CM4 diff --git a/documentation/asciidoc/computers/config_txt/video.adoc b/documentation/asciidoc/computers/config_txt/video.adoc index c39979c45..fe877fd70 100644 --- a/documentation/asciidoc/computers/config_txt/video.adoc +++ b/documentation/asciidoc/computers/config_txt/video.adoc @@ -1405,7 +1405,7 @@ hdmi_timings= ---- = horizontal pixels (width) = invert hsync polarity - = horizontal forward padding from DE acitve edge + = horizontal forward padding from DE active edge = hsync pulse width in pixel clocks = vertical back padding from DE active edge = vertical pixels height (lines) @@ -1568,7 +1568,7 @@ dpi_timings= < ---- = horizontal pixels (width) = invert hsync polarity - = horizontal forward padding from DE acitve edge + = horizontal forward padding from DE active edge = hsync pulse width in pixel clocks = vertical back padding from DE active edge = vertical pixels height (lines) diff --git a/documentation/asciidoc/computers/configuration/access-point-routed.adoc b/documentation/asciidoc/computers/configuration/access-point-routed.adoc index ea9148aa5..473613766 100644 --- a/documentation/asciidoc/computers/configuration/access-point-routed.adoc +++ b/documentation/asciidoc/computers/configuration/access-point-routed.adoc @@ -58,7 +58,7 @@ In order to provide network management services (DNS, DHCP) to wireless clients, sudo apt install dnsmasq ---- -Finally, install `netfilter-persistent` and its plugin `iptables-persistent`. This utilty helps by saving firewall rules and restoring them when the Raspberry Pi boots: +Finally, install `netfilter-persistent` and its plugin `iptables-persistent`. This utility helps by saving firewall rules and restoring them when the Raspberry Pi boots: ---- sudo DEBIAN_FRONTEND=noninteractive apt install -y netfilter-persistent iptables-persistent diff --git a/documentation/asciidoc/computers/configuration/device-tree.adoc b/documentation/asciidoc/computers/configuration/device-tree.adoc index 1a6dd5752..17a013ca3 100644 --- a/documentation/asciidoc/computers/configuration/device-tree.adoc +++ b/documentation/asciidoc/computers/configuration/device-tree.adoc @@ -723,7 +723,7 @@ The HAT overlay is automatically loaded by the firmware after the base DTB, so i [[part3.5]] ==== Dynamic Device Tree -As of Linux 4.4, the RPi kernels support the dynamic loading of overlays and parameters. Compatible kernels manage a stack of overlays that are applied on top of the base DTB. Changes are immediately reflected in `/proc/device-tree` and can cause modules to be loaded and platform devices to be created and destroyed. +As of Linux 4.4, Raspberry Pi kernels support the dynamic loading of overlays and parameters. Compatible kernels manage a stack of overlays that are applied on top of the base DTB. Changes are immediately reflected in `/proc/device-tree` and can cause modules to be loaded and platform devices to be created and destroyed. The use of the word "stack" above is important - overlays can only be added and removed at the top of the stack; changing something further down the stack requires that anything on top of it must first be removed. diff --git a/documentation/asciidoc/computers/configuration/uart.adoc b/documentation/asciidoc/computers/configuration/uart.adoc index c97e593e4..7eba843a5 100644 --- a/documentation/asciidoc/computers/configuration/uart.adoc +++ b/documentation/asciidoc/computers/configuration/uart.adoc @@ -89,6 +89,10 @@ The following table summarises the assignment of the first two UARTs: | secondary (Bluetooth) | primary +| Compute Module 3 & 3+ +| primary +| secondary + | Raspberry Pi 4 | secondary (Bluetooth) | primary diff --git a/documentation/asciidoc/computers/getting-started/network-installation.adoc b/documentation/asciidoc/computers/getting-started/network-installation.adoc index a77ca8859..57809a849 100644 --- a/documentation/asciidoc/computers/getting-started/network-installation.adoc +++ b/documentation/asciidoc/computers/getting-started/network-installation.adoc @@ -8,7 +8,7 @@ But how do you get the operating system onto your SD card if you don’t have an If you do not have another computer to run Raspberry Pi Imager you can start the application directly on a Raspberry Pi 4 or Raspberry Pi 400 by connecting it to the Internet with an Ethernet cable. This will allow you to install the operating system onto a **blank** SD Card directly from the network without using another computer. -IMPORTANT: Network installation is only supported on Raspberry Pi 4 and Raspberry Pi 400. Additionally, to avoid slowing down “normal boot,” the network instllation feature is only enabled if there’s no bootable media present, and you have xref:raspberry-pi.adoc#usb-mass-storage-boot[USB mass storage boot] in your xref:raspberry-pi.adoc#BOOT_ORDER[boot order]. +IMPORTANT: Network installation is only supported on Raspberry Pi 4 and Raspberry Pi 400. Additionally, to avoid slowing down “normal boot,” the network installation feature is only enabled if there’s no bootable media present, and you have xref:raspberry-pi.adoc#usb-mass-storage-boot[USB mass storage boot] in your xref:raspberry-pi.adoc#BOOT_ORDER[boot order]. === Updating to the BETA bootloader @@ -20,7 +20,7 @@ WARNING: Installation of the beta bootloader should be fairly safe, but you shou The easiest way to update the bootloader on your Raspberry Pi 4 or 400 is by using the Raspberry Pi Imager, either running on your Raspberry Pi or another computer, to copy the required software onto an SD card. You’ll need a spare blank SD Card and, if you’re using a Raspberry Pi or another computer that doesn’t have an SD Card slot, a USB to SD Card dongle. -You should be aware that the SD Card you’re using to update your Raspberry Pi’s bootloader will be wiped of any existing data, so you shouldn’t use the SD Card you are currently using with your Raspberry Pi. +You should be aware that the SD Card you’re using to update your Raspberry Pi computer's bootloader will be wiped of any existing data, so you shouldn’t use the SD Card you are currently using with your Raspberry Pi. In the Imager application, click on the “Choose OS” button and scroll down the “Operating System” list in the pop-up window and select “Misc utility images”, then select “Beta Test Bootloader.” @@ -51,11 +51,11 @@ You will need a keyboard to make use of the network installation feature. While video::b1SYVpM9lto[youtube] -You should also insert a **blank** SD Card into the Raspberry Pi's SD Card slot. +You should also insert a **blank** SD Card into the SD card slot of your Raspberry Pi. NOTE: You should make sure there isn't a bootable SD Card, or USB drive, attached to your Raspberry Pi. -Power on your Raspberry Pi. As always it will first look for an SD Card, and then a USB drive, to find bootable media. However if you have a keyboard attached the Raspberry Pi will now show the network installation screen. +Power on your Raspberry Pi. As always it will first look for an SD Card, and then a USB drive, to find bootable media. However if you have a keyboard attached, the Raspberry Pi will now show the network installation screen. image::images/network-install-1.png[width="80%"] @@ -73,4 +73,4 @@ image::images/network-install-4.png[width="80%"] NOTE: More information can about using the Raspberry Pi Imager can be found in the section on xref:getting-started.adoc#installing-the-operating-system[installing your operating system]. -After installing the operating system onto your blank SD Card you will not longer see the network installation screen on boot. If you do want to run it, you just need to remove any bootable disks. You can re-insert them later when the Raspberry PI Imager is running. But take care not to overwrite any working disks that you want to keep! \ No newline at end of file +After installing the operating system onto your blank SD Card you will no longer see the network installation screen on boot. If you do want to run it, you just need to remove any bootable disks. You can re-insert them later when Raspberry Pi Imager is running. But take care not to overwrite any working disks that you want to keep! diff --git a/documentation/asciidoc/computers/getting-started/setting-up.adoc b/documentation/asciidoc/computers/getting-started/setting-up.adoc index 2bd5c7437..9422e7799 100644 --- a/documentation/asciidoc/computers/getting-started/setting-up.adoc +++ b/documentation/asciidoc/computers/getting-started/setting-up.adoc @@ -2,7 +2,7 @@ To get started with your Raspberry Pi computer you'll need the following accessories: -A computer monitor, or television. Most should work as a display for the Raspberry Pi, but for best results, you should use a display with HDMI input. You'll also need a appropriate xref:getting-started.adoc#connecting-a-display[display] cable, to connect your monitor to your Raspberry Pi. +A computer monitor, or television. Most should work as a display for the Raspberry Pi, but for best results, you should use a display with HDMI input. You'll also need an appropriate xref:getting-started.adoc#connecting-a-display[display] cable, to connect your monitor to your Raspberry Pi. NOTE: If your display uses an HDMI connection and has built-in speakers, you can use it to output sound. diff --git a/documentation/asciidoc/computers/linux_kernel/building.adoc b/documentation/asciidoc/computers/linux_kernel/building.adoc index f02c51caf..25deb2525 100644 --- a/documentation/asciidoc/computers/linux_kernel/building.adoc +++ b/documentation/asciidoc/computers/linux_kernel/building.adoc @@ -6,13 +6,13 @@ The default compilers and linkers that come with an OS are configured to build e Cross-compilation of the Raspberry Pi kernel is useful for two reasons: * it allows a 64-bit kernel to be built using a 32-bit OS, and vice versa, and -* even a modest laptop can cross-compile a Pi kernel significantly faster than the Pi itself. +* even a modest laptop can cross-compile a Raspberry Pi kernel significantly faster than the Raspberry Pi itself. The instructions below are divided into native builds and cross-compilation; choose the section appropriate for your situation - although there are many common steps between the two, there are also some important differences. === Building the Kernel Locally -On a Raspberry Pi, first install the latest version of https://www.raspberrypi.com/software/operating-systems/#raspberry-pi-os-32-bit[Raspberry Pi OS]. Then boot your Pi, plug in Ethernet to give you access to the sources, and log in. +On a Raspberry Pi, first install the latest version of https://www.raspberrypi.com/software/operating-systems/#raspberry-pi-os-32-bit[Raspberry Pi OS]. Then boot your Raspberry Pi, log in, and ensure you're connected to the internet to give you access to the sources. First install Git and the build dependencies: @@ -51,9 +51,9 @@ Configure the kernel; as well as the default configuration, you may wish to xref [[default_configuration]] ===== Apply the Default Configuration -First, prepare the default configuration by running the following commands, depending on your Raspberry Pi version: +First, prepare the default configuration by running the following commands, depending on your Raspberry Pi model: -For Raspberry Pi 1, Pi Zero, Pi Zero W, and Compute Module default build configuration +For Raspberry Pi 1, Zero and Zero W, and Raspberry Pi Compute Module 1 default (32-bit only) build configuration [,bash] ---- @@ -62,7 +62,7 @@ KERNEL=kernel make bcmrpi_defconfig ---- -For Raspberry Pi Zero 2 W, Pi 2, Pi 3, Pi 3+, and Compute Module 3 default build configuration +For Raspberry Pi 2, 3, 3+ and Zero 2 W, and Raspberry Pi Compute Modules 3 and 3+ default 32-bit build configuration [,bash] ---- @@ -71,7 +71,7 @@ KERNEL=kernel7 make bcm2709_defconfig ---- -For Raspberry Pi 4 default build configuration (32 bit) +For Raspberry Pi 4 and 400, and Raspberry Pi Compute Module 4 default 32-bit build configuration [,bash] ---- @@ -80,7 +80,7 @@ KERNEL=kernel7l make bcm2711_defconfig ---- -For Pi Zero 2 W, Pi 3, Pi 3+, Pi 4, Pi 400, and Compute Modules 3, 3+ and 4 default build configuration (64 bit) +For Raspberry Pi 3, 3+, 4, 400 and Zero 2 W, and Raspberry Pi Compute Modules 3, 3+ and 4 default 64-bit build configuration [,bash] ---- cd linux @@ -102,7 +102,7 @@ You can also change that setting graphically as shown in xref:linux_kernel.adoc# ==== Building the Kernel -Build and install the kernel, modules, and Device Tree blobs; this step can take a *long* time depending on the Pi model in use. For the 32-bit kernel: +Build and install the kernel, modules, and Device Tree blobs; this step can take a *long* time depending on the Raspberry Pi model in use. For the 32-bit kernel: [,bash] ---- @@ -128,10 +128,11 @@ sudo cp arch/arm64/boot/Image /boot/$KERNEL.img NOTE: On a Raspberry Pi 2/3/4, the `-j4` flag splits the work between all four cores, speeding up compilation significantly. +If you now reboot, your Raspberry Pi should be running your freshly-compiled kernel! + === Cross-Compiling the Kernel -First, you will need a suitable Linux cross-compilation host. We tend to use Ubuntu; since Raspberry Pi OS is -also a Debian distribution, it means many aspects are similar, such as the command lines. +First, you will need a suitable Linux cross-compilation host. We tend to use Ubuntu; since Raspberry Pi OS is also a Debian distribution, it means many aspects are similar, such as the command lines. You can either do this using VirtualBox (or VMWare) on Windows, or install it directly onto your computer. For reference, you can follow instructions online http://www.wikihow.com/Install-Ubuntu-on-VirtualBox[at Wikihow]. @@ -177,7 +178,7 @@ Enter the following commands to build the sources and Device Tree files: ===== 32-bit Configs -For Pi 1, Pi Zero, Pi Zero W, or Compute Module: +For Raspberry Pi 1, Zero and Zero W, and Raspberry Pi Compute Module 1: [,bash] ---- @@ -186,7 +187,7 @@ KERNEL=kernel make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- bcmrpi_defconfig ---- -For Pi Zero 2 W, Pi 2, Pi 3, Pi 3+, or Compute Module 3: +For Raspberry Pi 2, 3, 3+ and Zero 2 W, and Raspberry Pi Compute Modules 3 and 3+: [,bash] ---- @@ -195,7 +196,7 @@ KERNEL=kernel7 make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- bcm2709_defconfig ---- -For Raspberry Pi 4: +For Raspberry Pi 4 and 400, and Raspberry Pi Compute Module 4: [,bash] ---- @@ -206,7 +207,7 @@ make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- bcm2711_defconfig ===== 64-bit Configs -For Pi Zero 2 W, Pi 3, Pi 3+, Pi 4, Pi 400, and Compute Modules 3, 3+ and 4: +For Raspberry Pi 3, 3+, 4, 400 and Zero 2 W, and Raspberry Pi Compute Modules 3, 3+ and 4: [,bash] ---- @@ -247,7 +248,7 @@ sdb sdb2 ---- -with `sdb1` being the FAT (boot) partition, and `sdb2` being the `ext4` filesystem (root) partition. +with `sdb1` being the `FAT` filesystem (boot) partition, and `sdb2` being the `ext4` filesystem (root) partition. Mount these first, adjusting the partition letter as necessary: @@ -306,12 +307,12 @@ sudo umount mnt/fat32 sudo umount mnt/ext4 ---- -Another option is to copy the kernel into the same place, but with a different filename - for instance, kernel-myconfig.img - rather than overwriting the kernel.img file. You can then edit the config.txt file to select the kernel that the Pi will boot into: +Another option is to copy the kernel into the same place, but with a different filename - for instance, `kernel-myconfig.img` - rather than overwriting the `kernel.img` file. You can then edit the `config.txt` file to select the kernel that the Raspberry Pi will boot: ---- kernel=kernel-myconfig.img ---- -This has the advantage of keeping your kernel separate from the kernel image managed by the system and any automatic update tools, and allowing you to easily revert to a stock kernel in the event that your kernel cannot boot. +This has the advantage of keeping your custom kernel separate from the stock kernel image managed by the system and any automatic update tools, and allowing you to easily revert to a stock kernel in the event that your kernel cannot boot. -Finally, plug the card into the Pi and boot it! +Finally, plug the card into the Raspberry Pi and boot it! diff --git a/documentation/asciidoc/computers/os/updating.adoc b/documentation/asciidoc/computers/os/updating.adoc index 0e77f81b6..64096650b 100644 --- a/documentation/asciidoc/computers/os/updating.adoc +++ b/documentation/asciidoc/computers/os/updating.adoc @@ -6,7 +6,7 @@ The second reason, related to the first, is that the software you are running on === Using APT -The easiest way to manage installing, upgrading, and removing software is using APT (Advanced Packaging Tool) from Debian. To update software in Raspberry Pi OS, you can use the `apt` tool from a Terminal window. +The easiest way to manage installing, upgrading, and removing software is using APT (Advanced Packaging Tool) from Debian. To update software in Raspberry Pi OS, you can use the `apt` tool from a Terminal window. ==== Keeping your Operating System up to Date @@ -120,13 +120,13 @@ sudo apt purge tree WARNING: Pre-release versions of software are not guaranteed to work. You should not use `rpi-update` on any system unless recommended to do so by a Raspberry Pi engineer. It may leave your system unreliable or even completely broken. It should not be used as part of any regular update process. -The `rpi-update` script is supplied by a third party, "Hexxeh", and also supported by Raspberry Pi engineers. The script source can be found on GitHub at https://github.com/Hexxeh/rpi-update +The `rpi-update` script was originally written by https://github.com/Hexxeh[Hexxeh], but is now supported by Raspberry Pi engineers. The script source is in the https://github.com/raspberrypi/rpi-update[rpi-update repository]. ==== What it does `rpi-update` will download the latest pre-release version of the linux kernel, its matching modules, device tree files, along with the latest versions of the VideoCore firmware. It will then install these files to relevant locations on the SD card, overwriting any previous versions. -All the source data used by `rpi-update` comes from the GitHub repo https://github.com/Hexxeh/rpi-firmware. This repository simply contains a subset of the data from the https://github.com/raspberrypi/firmware[official firmware repository], as not all the data from that repo is required. +All the source data used by `rpi-update` comes from the https://github.com/raspberrypi/rpi-firmware[rpi-firmware repository]. This repository simply contains a subset of the data from the https://github.com/raspberrypi/firmware[official firmware repository], as not all the data from that repo is required. ==== Running `rpi-update` @@ -139,7 +139,7 @@ sudo rpi-update sudo reboot ---- -It has a number of options, which are documented at the Hexxeh GitHub repository at https://github.com/Hexxeh/rpi-update +It has a number of options documented in the https://github.com/raspberrypi/rpi-update[rpi-update repository]. ==== How to get back to safety diff --git a/documentation/asciidoc/computers/raspberry-pi/bcm2711-bootloader.adoc b/documentation/asciidoc/computers/raspberry-pi/bcm2711-bootloader.adoc index 0ff2a593a..e1e117858 100644 --- a/documentation/asciidoc/computers/raspberry-pi/bcm2711-bootloader.adoc +++ b/documentation/asciidoc/computers/raspberry-pi/bcm2711-bootloader.adoc @@ -2,7 +2,7 @@ === Editing the Configuration -Before editing the bootloader configuration, xref:os.adoc#updating-and-upgrading-raspberry-pi-os[update your system] to get the latest version of the `rpi-eeprom` package. Releases prior to the 2020-09-03 default/critical release will not support all features listed here. +Before editing the bootloader configuration, xref:os.adoc#updating-and-upgrading-raspberry-pi-os[update your system] to get the latest version of the `rpi-eeprom` package. To view the current EEPROM configuration: + `rpi-eeprom-config` @@ -28,7 +28,7 @@ Default: `0` If `1` then `sudo halt` will run in a lower power mode until either GPIO3 or GLOBAL_EN are shorted to ground. -Default: `1` (`0` in original version of bootloader 2019-05-10) +Default: `1` [[POWER_OFF_ON_HALT]] ==== POWER_OFF_ON_HALT @@ -44,7 +44,6 @@ Default: `0` The `BOOT_ORDER` setting allows flexible configuration for the priority of different boot modes. It is represented as 32bit unsigned integer where each nibble represents a boot mode. The boot modes are attempted in lowest significant nibble to highest significant nibble order. -The minimum supported bootloader version for custom boot modes is 2020-09-03. [discrete] ====== `BOOT_ORDER` fields @@ -76,7 +75,7 @@ The BOOT_ORDER property defines the sequence for the different boot modes. It is | 0x5 | BCM-USB-MSD -| USB 2.0 boot from USB Type C socket (CM4: USB type A socket on CM IO board, using bootloader EEPROM from 2020-12-14 onwards). +| USB 2.0 boot from USB Type C socket (CM4: USB type A socket on CM IO board). | 0x6 | NVME @@ -267,10 +266,10 @@ If self update is enabled then the bootloader will look for the update files (.s Notes:- * Self-update is not enabled in SD boot; the ROM can already load recovery.bin from the SD card. -* Before self-update can be used the bootloader must have already been updated to a version which supports self update. The recommended approach would be to use the Raspberry Pi Imager and a spare SD card to update to pieeprom-2020-09-03 then use self-update for subsequent updates. +* Bootloader releases prior to 2021 do not support `self-update`. * For network boot make sure that the TFTP `boot` directory can be mounted via NFS and that `rpi-eeprom-update` can write to it. -Default: `1` (`0` in versions prior to 2020-09-03) +Default: `1` [[FREEZE_VERSION]] ==== FREEZE_VERSION @@ -334,6 +333,7 @@ Default: "" If no USB mass storage devices are found within this timeout then USB-MSD is stopped and the next boot mode is selected +Minimum: `5000` (5 seconds) + Default: `20000` (20 seconds) + [[USB_MSD_LUN_TIMEOUT]] @@ -341,6 +341,7 @@ Default: `20000` (20 seconds) + How long to wait in milliseconds before advancing to the next LUN e.g. a multi-slot SD-CARD reader. This is still being tweaked but may help speed up boot if old/slow devices are connected as well as a fast USB-MSD device containing the OS. +Minimum: `100` + Default: `2000` (2 seconds) [[USB_MSD_PWR_OFF_TIME]] diff --git a/documentation/asciidoc/computers/raspberry-pi/boot-gpio.adoc b/documentation/asciidoc/computers/raspberry-pi/boot-gpio.adoc index b13befd2e..740a75cca 100644 --- a/documentation/asciidoc/computers/raspberry-pi/boot-gpio.adoc +++ b/documentation/asciidoc/computers/raspberry-pi/boot-gpio.adoc @@ -43,7 +43,7 @@ Once GPIO boot mode is enabled, the Raspberry Pi will no longer boot. You must p | USB |=== -USB in the table above selects both USB device boot mode and USB host boot mode. In order to use a USB boot mode, it must by enabled in the OTP memory. For more information, see xref:raspberry-pi.adoc#usb-device-boot-mode[USB device boot] and xref:raspberry-pi.adoc#usb-host-boot-mode[USB host boot]. +USB in the table above selects both USB device boot mode and USB host boot mode. In order to use a USB boot mode, it must be enabled in the OTP memory. For more information, see xref:raspberry-pi.adoc#usb-device-boot-mode[USB device boot] and xref:raspberry-pi.adoc#usb-host-boot-mode[USB host boot]. ==== Raspberry Pi 3A+, 3B+ and Compute Module 3+ diff --git a/documentation/asciidoc/computers/raspberry-pi/bootflow-2711.adoc b/documentation/asciidoc/computers/raspberry-pi/bootflow-2711.adoc index a8ffebc83..0677f74a3 100644 --- a/documentation/asciidoc/computers/raspberry-pi/bootflow-2711.adoc +++ b/documentation/asciidoc/computers/raspberry-pi/bootflow-2711.adoc @@ -76,7 +76,7 @@ The bootloader may also be updated before the firmware is started if a `pieeprom === Fail-safe OS updates (TRYBOOT) -The bootloader/firmware provide a one-shot flag which, if set, is cleared but causes `tryboot.txt` to be loaded instead of `config.txt`. This alternate config would specify the pending OS update firmware, cmdline, kernel and os_prefix parameters. Since the flag is cleared before starting the firwmare a crash or reset will cause the original `config.txt` file to be loaded on the next reboot. +The bootloader/firmware provide a one-shot flag which, if set, is cleared but causes `tryboot.txt` to be loaded instead of `config.txt`. This alternate config would specify the pending OS update firmware, cmdline, kernel and os_prefix parameters. Since the flag is cleared before starting the firmware, a crash or reset will cause the original `config.txt` file to be loaded on the next reboot. To set the `tryboot` flag add `tryboot` after the partition number in the `reboot` command. Normally, the partition number defaults to zero but it must be specified if extra arguments are added. ---- diff --git a/documentation/asciidoc/computers/raspberry-pi/display-parallel-interface.adoc b/documentation/asciidoc/computers/raspberry-pi/display-parallel-interface.adoc index fdd8b6573..bf2377545 100644 --- a/documentation/asciidoc/computers/raspberry-pi/display-parallel-interface.adoc +++ b/documentation/asciidoc/computers/raspberry-pi/display-parallel-interface.adoc @@ -102,7 +102,7 @@ dpi_timings= < = horizontal pixels (width) = invert hsync polarity - = horizontal forward padding from DE acitve edge + = horizontal forward padding from DE active edge = hsync pulse width in pixel clocks = vertical back padding from DE active edge = vertical pixels height (lines) diff --git a/documentation/asciidoc/computers/raspberry-pi/power-supplies.adoc b/documentation/asciidoc/computers/raspberry-pi/power-supplies.adoc index 26aa4abe6..3ea1f5601 100644 --- a/documentation/asciidoc/computers/raspberry-pi/power-supplies.adoc +++ b/documentation/asciidoc/computers/raspberry-pi/power-supplies.adoc @@ -1,6 +1,6 @@ == Power Supply -The power supply requirements differ by Raspberry Pi model. All models require a 5.1V supply, but the current required generally increases according to model. All models up to the Raspberry Pi 3 require a micro USB power connector, whilst the Raspberry Pi 4 uses a USB-C connector. +The power supply requirements differ by Raspberry Pi model. All models require a 5.1V supply, but the current required generally increases according to model. All models up to the Raspberry Pi 3 require a micro USB power connector, whilst the Raspberry Pi 4 and Raspberry Pi 400 use a USB-C connector. Exactly how much current (mA) the Raspberry Pi requires is dependent on what you connect to it. The following table gives various current requirements. @@ -52,6 +52,11 @@ Exactly how much current (mA) the Raspberry Pi requires is dependent on what you | 1.2A | 600mA +| Raspberry Pi 400 +| 3.0A +| 1.2A +| 800mA + | Raspberry Pi Zero | 1.2A | Limited by PSU, board, and connector ratings only @@ -70,7 +75,7 @@ Exactly how much current (mA) the Raspberry Pi requires is dependent on what you Raspberry Pi have developed their own power supplies for use with all models. These are reliable, use heavy gauge wires and are reasonably priced. -For Raspberry Pi 0-3, we recommend our https://www.raspberrypi.com/products/micro-usb-power-supply/[2.5A micro USB Supply]. For Raspberry Pi 4, we recommend our https://www.raspberrypi.com/products/type-c-power-supply/[3A USB-C Supply] +For Raspberry Pi 0-3, we recommend our https://www.raspberrypi.com/products/micro-usb-power-supply/[2.5A micro USB Supply]. For Raspberry Pi 4 and Raspberry Pi 400, we recommend our https://www.raspberrypi.com/products/type-c-power-supply/[3A USB-C Supply]. If you need to connect a USB device that will take the power requirements above the values specified in the table above, then you must connect it using an externally-powered USB hub. @@ -91,8 +96,9 @@ The specific power requirements of each model are shown below. | Raspberry Pi 3 Model B+ | 2.5A | 1.2A | 500mA | Raspberry Pi 4 Model B | 3.0A | 1.2A | 600mA | Raspberry Pi 400 | 3.0A | 1.2A | 800mA -| Raspberry Pi Zero W/WH | 1.2A | Limited by PSU, board, and connector ratings only.| 150mA | Raspberry Pi Zero | 1.2A | Limited by PSU, board, and connector ratings only | 100mA +| Raspberry Pi Zero W/WH | 1.2A | Limited by PSU, board, and connector ratings only.| 150mA +| Raspberry Pi Zero 2 W | 2A | Limited by PSU, board, and connector ratings only | 350mA |=== From the Raspberry Pi B+ onwards, 1.2A is supplied to downstream USB peripherals. This allows the vast majority of USB devices to be connected directly to these models, assuming the upstream power supply has sufficient available current. diff --git a/documentation/asciidoc/computers/raspberry-pi/raspberry-pi-industrial.adoc b/documentation/asciidoc/computers/raspberry-pi/raspberry-pi-industrial.adoc index e2c876406..ac40786af 100644 --- a/documentation/asciidoc/computers/raspberry-pi/raspberry-pi-industrial.adoc +++ b/documentation/asciidoc/computers/raspberry-pi/raspberry-pi-industrial.adoc @@ -21,7 +21,7 @@ Also, from 36 to 43 (inclusive), there are eight rows of 32 bits available for t To program these bits, you will need to use the vcmailbox. This is a Linux driver interface to the firmware which will handle the programming of the rows. To do this, please refer to the https://github.com/raspberrypi/firmware/wiki/Mailbox-property-interface[documentation], and the vcmailbox https://github.com/raspberrypi/userland/blob/master/host_applications/linux/apps/vcmailbox/vcmailbox.c[example application]. -The vcmailbox application can be used directly from the command line on a Raspberry Pi Raspberry Pi OS build. An example usage would be: +The vcmailbox application can be used directly from the command line on Raspberry Pi OS. An example usage would be: [,bash] ---- diff --git a/documentation/asciidoc/computers/raspberry-pi/usb-bus-on-raspberry-pi.adoc b/documentation/asciidoc/computers/raspberry-pi/usb-bus-on-raspberry-pi.adoc index 6ccad69fe..70058bdfc 100644 --- a/documentation/asciidoc/computers/raspberry-pi/usb-bus-on-raspberry-pi.adoc +++ b/documentation/asciidoc/computers/raspberry-pi/usb-bus-on-raspberry-pi.adoc @@ -1,10 +1,10 @@ -== Universial Serial Bus (USB) +== Universal Serial Bus (USB) In general, every device supported by Linux can be used with a Raspberry Pi, although there are some limitations for models prior to Pi 4. === Maximum Power Output -As with all computers, the USB ports on the Raspberry Pi supply a limited amount of power. Often problems with USB devices are caused by power issues. To rule out power as the cause of an problem, connect your USB devices to the Raspberry Pi using a powered hub. +As with all computers, the USB ports on the Raspberry Pi supply a limited amount of power. Often problems with USB devices are caused by power issues. To rule out insufficient power as the cause of the problem, connect your USB devices to the Raspberry Pi using a powered hub. |=== | Model | Max power output of USB ports diff --git a/documentation/asciidoc/microcontrollers/microcontroller_docs.adoc b/documentation/asciidoc/microcontrollers/microcontroller_docs.adoc index 4d97ae19d..846455243 100644 --- a/documentation/asciidoc/microcontrollers/microcontroller_docs.adoc +++ b/documentation/asciidoc/microcontrollers/microcontroller_docs.adoc @@ -28,5 +28,5 @@ The API level Doxygen documentation for the Raspberry Pi Pico C/{cpp} SDK is als [NOTE] ==== -If you are building applications with the C/C++ SDK and targetting boards other than the Raspberry Pi Pico, you will need to pass `-DPICO_BOARD=boardname` to CMake. Here `boardname` is the name of your board, e.g. for the Adafruit Feather RP2040 you should pass `-DPICO_BOARD=adafruit_feather_rp2040`. See the https://github.com/raspberrypi/pico-sdk/tree/master/src/boards[`boards/` directory] in the Pico SDK, and the https://forums.raspberrypi.com/viewtopic.php?f=147&t=304393[forums], for more information. +If you are building applications with the C/C++ SDK and targeting boards other than the Raspberry Pi Pico, you will need to pass `-DPICO_BOARD=boardname` to CMake. Here `boardname` is the name of your board, e.g. for the Adafruit Feather RP2040 you should pass `-DPICO_BOARD=adafruit_feather_rp2040`. See the https://github.com/raspberrypi/pico-sdk/tree/master/src/boards[`boards/` directory] in the Pico SDK, and the https://forums.raspberrypi.com/viewtopic.php?f=147&t=304393[forums], for more information. ====