diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 3c5b43746..b10d3588a 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -16,8 +16,8 @@ jobs: echo "Pull requests based on master can only come from the develop branch of this repository" echo "Please check your base branch as it should be develop by default" exit 1 - - uses: actions/checkout@v4 - - uses: actions/setup-python@v5 + - uses: actions/checkout@v5 + - uses: actions/setup-python@v6 with: python-version: 3.9 - name: Install Python dependencies @@ -28,11 +28,11 @@ jobs: with: ruby-version: 3.2 bundler-cache: true - - uses: seanmiddleditch/gha-setup-ninja@v5 + - uses: seanmiddleditch/gha-setup-ninja@v6 with: version: 1.10.2 - name: Install arm-none-eabi-gcc GNU Arm Embedded Toolchain - uses: carlosperate/arm-none-eabi-gcc-action@v1.10.0 + uses: carlosperate/arm-none-eabi-gcc-action@v1.11.0 - name: Install Doxygen run: | wget https://www.doxygen.nl/files/doxygen-1.10.0.linux.bin.tar.gz diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml index 9ffb99cfc..8614b20a0 100644 --- a/.github/workflows/stale.yml +++ b/.github/workflows/stale.yml @@ -13,7 +13,7 @@ jobs: pull-requests: write steps: - - uses: actions/stale@v9 + - uses: actions/stale@v10 with: repo-token: ${{ secrets.GITHUB_TOKEN }} stale-issue-message: 'This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.' diff --git a/.gitignore b/.gitignore index 1d7ee958d..3e3542a21 100644 --- a/.gitignore +++ b/.gitignore @@ -4,4 +4,7 @@ build build-pico-sdk-docs documentation/html documentation/asciidoc/pico-sdk +venv .venv +.env +.vscode diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 110258458..37fef6b8e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -88,6 +88,12 @@ Use the `gem` package manager to install the [Ruby bundler](https://bundler.io/) $ gem install bundler ``` +And then install the required Ruby gems: + +```console +$ bundle install +``` + Configure a Python virtual environment for this project: ```console @@ -101,12 +107,12 @@ $ source .env/bin/activate ``` > [!TIP] -> When you're using a virtual environment, you should see a `(.venv)` prefix at the start of your terminal prompt. At any time, run the `deactivate` command to exit the virtual environment. +> When you're using a virtual environment, you should see a `(.env)` prefix at the start of your terminal prompt. At any time, run the `deactivate` command to exit the virtual environment. -In the virtual environment, install the [YAML module for Python 3](https://formulae.brew.sh/formula/pyyaml#default): +In the virtual environment, install the required Python modules: ```console -$ pip3 install pyyaml +$ pip3 install -r requirements.txt ``` ### Build HTML diff --git a/Gemfile b/Gemfile index 797e2164e..bb73401e4 100644 --- a/Gemfile +++ b/Gemfile @@ -8,7 +8,7 @@ source "https://rubygems.org" # # This will help ensure the proper Jekyll version is running. # Happy Jekylling! -gem "jekyll", "~> 4.3.4" +gem "jekyll", "~> 4.4.1" # This is the default theme for new Jekyll sites. You may change this to anything you like. gem "minima", "~> 2.5" diff --git a/Gemfile.lock b/Gemfile.lock index 92d37db79..3bff0a608 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -3,35 +3,40 @@ GEM specs: addressable (2.8.7) public_suffix (>= 2.0.2, < 7.0) - asciidoctor (2.0.23) + asciidoctor (2.0.26) asciidoctor-tabs (1.0.0.beta.6) asciidoctor (>= 2.0.0, < 3.0.0) - bigdecimal (3.1.8) + base64 (0.2.0) + bigdecimal (3.1.9) colorator (1.1.0) concurrent-ruby (1.3.5) + csv (3.3.2) em-websocket (0.5.3) eventmachine (>= 0.12.9) http_parser.rb (~> 0) eventmachine (1.2.7) - ffi (1.17.0) + ffi (1.17.1) forwardable-extended (2.6.0) - google-protobuf (4.28.1) + google-protobuf (4.29.3) bigdecimal rake (>= 13) http_parser.rb (0.8.0) - i18n (1.14.6) + i18n (1.14.7) concurrent-ruby (~> 1.0) - jekyll (4.3.4) + jekyll (4.4.1) addressable (~> 2.4) + base64 (~> 0.2) colorator (~> 1.0) + csv (~> 3.0) em-websocket (~> 0.5) i18n (~> 1.0) jekyll-sass-converter (>= 2.0, < 4.0) jekyll-watch (~> 2.0) + json (~> 2.6) kramdown (~> 2.3, >= 2.3.1) kramdown-parser-gfm (~> 1.0) liquid (~> 4.0) - mercenary (>= 0.3.6, < 0.5) + mercenary (~> 0.3, >= 0.3.6) pathutil (~> 0.9) rouge (>= 3.0, < 5.0) safe_yaml (~> 1.0) @@ -42,14 +47,15 @@ GEM jekyll (>= 3.0.0) jekyll-feed (0.17.0) jekyll (>= 3.7, < 5.0) - jekyll-sass-converter (3.0.0) - sass-embedded (~> 1.54) + jekyll-sass-converter (3.1.0) + sass-embedded (~> 1.75) jekyll-seo-tag (2.8.0) jekyll (>= 3.8, < 5.0) jekyll-watch (2.2.1) listen (~> 3.0) - kramdown (2.4.0) - rexml + json (2.9.1) + kramdown (2.5.1) + rexml (>= 3.3.9) kramdown-parser-gfm (1.1.0) kramdown (~> 2.0) liquid (4.0.4) @@ -57,12 +63,12 @@ GEM rb-fsevent (~> 0.10, >= 0.10.3) rb-inotify (~> 0.9, >= 0.9.10) mercenary (0.4.0) - mini_portile2 (2.8.8) + mini_portile2 (2.8.9) minima (2.5.2) jekyll (>= 3.5, < 5.0) jekyll-feed (~> 0.9) jekyll-seo-tag (~> 2.1) - nokogiri (1.18.2) + nokogiri (1.18.10) mini_portile2 (~> 2.8.2) racc (~> 1.4) pathutil (0.16.2) @@ -73,11 +79,11 @@ GEM rb-fsevent (0.11.2) rb-inotify (0.11.1) ffi (~> 1.0) - rexml (3.3.7) - rouge (4.4.0) + rexml (3.4.0) + rouge (4.5.1) safe_yaml (1.0.5) - sass-embedded (1.78.0) - google-protobuf (~> 4.27) + sass-embedded (1.83.4) + google-protobuf (~> 4.29) rake (>= 13) slim (5.2.1) temple (~> 0.10.0) @@ -89,11 +95,11 @@ GEM tilt (2.3.0) tzinfo (2.0.6) concurrent-ruby (~> 1.0) - tzinfo-data (1.2025.1) + tzinfo-data (1.2025.2) tzinfo (>= 1.0.0) unicode-display_width (2.6.0) wdm (0.2.0) - webrick (1.8.1) + webrick (1.9.1) PLATFORMS ruby @@ -101,7 +107,7 @@ PLATFORMS DEPENDENCIES asciidoctor asciidoctor-tabs (>= 1.0.0.beta.6) - jekyll (~> 4.3.4) + jekyll (~> 4.4.1) jekyll-asciidoc jekyll-feed (~> 0.17) minima (~> 2.5) diff --git a/documentation/asciidoc/accessories/ai-camera/getting-started.adoc b/documentation/asciidoc/accessories/ai-camera/getting-started.adoc index 07d7812a5..b23720895 100644 --- a/documentation/asciidoc/accessories/ai-camera/getting-started.adoc +++ b/documentation/asciidoc/accessories/ai-camera/getting-started.adoc @@ -2,6 +2,10 @@ The instructions below describe how to run the pre-packaged MobileNet SSD and PoseNet neural network models on the Raspberry Pi AI Camera. +=== Hardware setup + +Attach the camera to your Raspberry Pi 5 board following the instructions at xref:../accessories/camera.adoc#install-a-raspberry-pi-camera[Install a Raspberry Pi Camera]. + === Prerequisites These instructions assume you are using the AI Camera attached to either a Raspberry Pi 4 Model B or Raspberry Pi 5 board. With minor changes, you can follow these instructions on other Raspberry Pi models with a camera connector, including the Raspberry Pi Zero 2 W and Raspberry Pi 3 Model B+. @@ -48,7 +52,7 @@ Once all the system packages are updated and firmware files installed, we can st The xref:../computers/camera_software.adoc#rpicam-apps[`rpicam-apps` camera applications] include IMX500 object detection and pose estimation stages that can be run in the post-processing pipeline. For more information about the post-processing pipeline, see xref:../computers/camera_software.adoc#post-process-file[the post-processing documentation]. -The examples on this page use post-processing JSON files located in `/usr/share/rpicam-assets/`. +The examples on this page use post-processing JSON files located in `/usr/share/rpi-camera-assets/`. ==== Object detection diff --git a/documentation/asciidoc/accessories/ai-camera/images/imx500-block-diagram.svg b/documentation/asciidoc/accessories/ai-camera/images/imx500-block-diagram.svg index 142854adb..146884217 100644 --- a/documentation/asciidoc/accessories/ai-camera/images/imx500-block-diagram.svg +++ b/documentation/asciidoc/accessories/ai-camera/images/imx500-block-diagram.svg @@ -1 +1,956 @@ - \ No newline at end of file + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/documentation/asciidoc/accessories/ai-camera/images/imx500-comparison.svg b/documentation/asciidoc/accessories/ai-camera/images/imx500-comparison.svg index 5355ecb23..23924b5f6 100644 --- a/documentation/asciidoc/accessories/ai-camera/images/imx500-comparison.svg +++ b/documentation/asciidoc/accessories/ai-camera/images/imx500-comparison.svg @@ -1 +1,656 @@ - \ No newline at end of file + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/documentation/asciidoc/accessories/ai-camera/model-conversion.adoc b/documentation/asciidoc/accessories/ai-camera/model-conversion.adoc index ce272ee5b..f449476c6 100644 --- a/documentation/asciidoc/accessories/ai-camera/model-conversion.adoc +++ b/documentation/asciidoc/accessories/ai-camera/model-conversion.adoc @@ -2,82 +2,84 @@ To deploy a new neural network model to the Raspberry Pi AI Camera, complete the following steps: -. Provide a neural network model. -. Quantise and compress the model so that it can run using the resources available on the IMX500 camera module. -. Convert the compressed model to IMX500 format. +. Provide a floating-point neural network model (PyTorch or TensorFlow). +. Run the model through Edge-MDT (Edge AI Model Development Toolkit). +.. *Quantise* and compress the model so that it can run using the resources available on the IMX500 camera module. +.. *Convert* the compressed model to IMX500 format. . Package the model into a firmware file that can be loaded at runtime onto the camera. -The first three steps will normally be performed on a more powerful computer such as a desktop or server. You must run the final packaging step on a Raspberry Pi. +The first two steps will normally be performed on a more powerful computer such as a desktop or server. You must run the final packaging step on a Raspberry Pi. === Model creation -The creation of neural network models is beyond the scope of this guide. Existing models can be re-used, or new ones created using popular frameworks like TensorFlow or PyTorch. +The creation of neural network models is beyond the scope of this guide. Existing models can be re-used, or new ones created using popular AI frameworks like TensorFlow or PyTorch. For more information, see the official https://developer.aitrios.sony-semicon.com/en/raspberrypi-ai-camera[AITRIOS developer website]. -=== Quantisation and compression +=== Model compression and conversion -Models are quantised and compressed using Sony's Model Compression Toolkit. To install the toolkit, run the following command: +==== Edge-MDT installation -[source,console] ----- -$ pip install model_compression_toolkit ----- - -For more information, see the https://github.com/sony/model_optimization[Sony model optimization GitHub repository]. - -The Model Compression Toolkit generates a quantised model in the following formats: - -* Keras (TensorFlow) -* ONNX (PyTorch) - -=== Conversion +The Edge-MDT (Model Development Toolkit) software package installs all the tools required to quantise, compress, and convert models to run on your IMX500 device. -To convert a model, first install the converter tools: +The Edge-MDT package takes a parameter to select between installing the PyTorch or TensorFlow version of the tools. [tabs] ====== -TensorFlow:: +PyTorch:: + [source,console] ---- -$ pip install imx500-converter[tf] +$ pip install edge-mdt[pt] ---- -+ -TIP: Always use the same version of TensorFlow you used to compress your model. -PyTorch:: +TensorFlow:: + [source,console] ---- -$ pip install imx500-converter[pt] +$ pip install edge-mdt[tf] ---- ++ +TIP: Always use the same version of TensorFlow you used to compress your model. ====== -If you need to install both packages, use two separate Python virtual environments. This prevents TensorFlow and PyTorch from causing conflicts with one another. +If you need to install both packages, use two separate Python virtual environments. This prevents TensorFlow and PyTorch from causing conflicts with each other. + +==== Model Optimization -Next, convert the model: +Models are quantised and compressed using Sony's Model Compression Toolkit (MCT). This tool is automatically installed as part of the Edge-MDT installation step. For more information, see the https://github.com/sony/model_optimization[Sony model optimization GitHub repository]. + +The Model Compression Toolkit generates a quantised model in the following formats: + +* Keras (TensorFlow) +* ONNX (PyTorch) + +=== Conversion + +The converter is a command line application that compiles the quantised model (in .onnx or .keras formats) into a binary file that can be packaged and loaded onto the AI Camera. This tool is automatically installed as part of the Edge-MDT installation step. + +To convert a model model: [tabs] ====== -TensorFlow:: +PyTorch:: + [source,console] ---- -$ imxconv-tf -i -o +$ imxconv-pt -i -o ---- -PyTorch:: +TensorFlow:: + [source,console] ---- -$ imxconv-pt -i -o +$ imxconv-tf -i -o ---- ====== -Both commands create an output folder that contains a memory usage report and a `packerOut.zip` file. +IMPORTANT: For optimal use of the memory available to the accelerator on the IMX500 sensor, add `--no-input-persistency` to the above commands. However, this will disable input tensor generation that may be used for debugging purposes. -For optimal use of the memory available to the accelerator on the IMX500 sensor, add `--no-input-persistency` to the above commands. However, this will disable input tensor generation and return to the application for debugging purposes. +Both commands create an output folder that contains a memory usage report and a `packerOut.zip` file. For more information on the model conversion process, see the official https://developer.aitrios.sony-semicon.com/en/raspberrypi-ai-camera/documentation/imx500-converter[Sony IMX500 Converter documentation]. diff --git a/documentation/asciidoc/accessories/ai-hat-plus/about.adoc b/documentation/asciidoc/accessories/ai-hat-plus/about.adoc index 98f1923bf..1185d338e 100644 --- a/documentation/asciidoc/accessories/ai-hat-plus/about.adoc +++ b/documentation/asciidoc/accessories/ai-hat-plus/about.adoc @@ -9,7 +9,9 @@ Raspberry Pi 5. The NPU in the AI HAT+ can be used for applications including pr The AI HAT+ is available in 13 and 26 tera-operations per second (TOPS) variants, built around the Hailo-8L and Hailo-8 neural network inference accelerators. The 13 TOPS variant works best with moderate workloads, with performance similar to the xref:ai-kit.adoc[AI Kit]. The 26 TOPS variant can run larger networks, can run networks faster, and can more effectively run multiple networks simultaneously. -The AI HAT+ communicates using Raspberry Pi 5’s PCIe interface. The host Raspberry Pi 5 automatically detects the on-board Hailo accelerator and uses the NPU for supported AI computing tasks. Raspberry Pi OS's built-in `rpicam-apps` camera applications automatically use the NPU to run compatible post-processing tasks. +The AI HAT+ communicates using Raspberry Pi 5's PCIe interface. The host Raspberry Pi 5 automatically detects the on-board Hailo accelerator and uses the NPU for supported AI computing tasks. Raspberry Pi OS's built-in `rpicam-apps` camera applications automatically use the NPU to run compatible post-processing tasks. + +WARNING: The Raspberry Pi AI HAT+ is not yet supported by Raspberry Pi OS Trixie. To use AI HAT+, install or stay on Raspberry Pi OS Bookworm for now. [[ai-hat-plus-installation]] == Install diff --git a/documentation/asciidoc/accessories/ai-kit/about.adoc b/documentation/asciidoc/accessories/ai-kit/about.adoc index bc93a483f..2a635dcc4 100644 --- a/documentation/asciidoc/accessories/ai-kit/about.adoc +++ b/documentation/asciidoc/accessories/ai-kit/about.adoc @@ -12,6 +12,8 @@ The Raspberry Pi AI Kit bundles the xref:m2-hat-plus.adoc#m2-hat-plus[Raspberry * mounting hardware kit * 16mm stacking GPIO header +WARNING: The Raspberry Pi AI Kit is not yet supported by Raspberry Pi OS Trixie. To use the AI Kit, install or stay on Raspberry Pi OS Bookworm for now. + == AI module features * 13 tera-operations per second (TOPS) neural network inference accelerator built around the Hailo-8L chip. diff --git a/documentation/asciidoc/accessories/audio/hardware-info.adoc b/documentation/asciidoc/accessories/audio/hardware-info.adoc index c7d445d64..240c9fd0f 100644 --- a/documentation/asciidoc/accessories/audio/hardware-info.adoc +++ b/documentation/asciidoc/accessories/audio/hardware-info.adoc @@ -39,7 +39,7 @@ If appropriate then the following are also used: === DAC PRO, DAC{plus}, DigiAMP{plus}, Codec Zero -image::images/pin_table_new.jpg[width="80%"] +image::images/all_audio_boards_gpio_pinouts.png[width="80%"] The DAC PRO, DAC{plus} and DigiAMP{plus} re-expose the Raspberry Pi signals, allowing additional sensors and peripherals to be added easily. Please note that some signals are for exclusive use (I2S and EEPROM) by some diff --git a/documentation/asciidoc/accessories/audio/images/all_audio_boards_gpio_pinouts.png b/documentation/asciidoc/accessories/audio/images/all_audio_boards_gpio_pinouts.png new file mode 100644 index 000000000..35dfadbf6 Binary files /dev/null and b/documentation/asciidoc/accessories/audio/images/all_audio_boards_gpio_pinouts.png differ diff --git a/documentation/asciidoc/accessories/audio/images/pin_table_new.jpg b/documentation/asciidoc/accessories/audio/images/pin_table_new.jpg deleted file mode 100644 index b9ca1a8bc..000000000 Binary files a/documentation/asciidoc/accessories/audio/images/pin_table_new.jpg and /dev/null differ diff --git a/documentation/asciidoc/accessories/build-hat/images/setting-up.png b/documentation/asciidoc/accessories/build-hat/images/setting-up.png old mode 100755 new mode 100644 index 8964b0e44..e69d97a3c Binary files a/documentation/asciidoc/accessories/build-hat/images/setting-up.png and b/documentation/asciidoc/accessories/build-hat/images/setting-up.png differ diff --git a/documentation/asciidoc/accessories/build-hat/introduction.adoc b/documentation/asciidoc/accessories/build-hat/introduction.adoc index 3ee1e7fd8..297dd957b 100644 --- a/documentation/asciidoc/accessories/build-hat/introduction.adoc +++ b/documentation/asciidoc/accessories/build-hat/introduction.adoc @@ -1,7 +1,9 @@ [[about-build-hat]] == About -The https://raspberrypi.com/products/build-hat[Raspberry Pi Build HAT] is an add-on board that connects to the 40-pin GPIO header of your Raspberry Pi, which was designed in collaboration with LEGO® Education to make it easy to control LEGO® Technic™ motors and sensors with Raspberry Pi computers. +The https://raspberrypi.com/products/build-hat[Raspberry Pi Build HAT] is an add-on board that connects to the 40-pin GPIO header of your Raspberry Pi, which was designed in collaboration with LEGO® Education to make it easy to control LEGO® Technic™ motors and sensors with Raspberry Pi computers. + +WARNING: The Raspberry Pi Build HAT is not yet supported by Raspberry Pi OS Trixie. To use the Build HAT, install or stay on Raspberry Pi OS Bookworm for now. image::images/build-hat.jpg[width="80%"] diff --git a/documentation/asciidoc/accessories/build-hat/preparing-build-hat.adoc b/documentation/asciidoc/accessories/build-hat/preparing-build-hat.adoc index 0e19d8bda..824d67d74 100644 --- a/documentation/asciidoc/accessories/build-hat/preparing-build-hat.adoc +++ b/documentation/asciidoc/accessories/build-hat/preparing-build-hat.adoc @@ -2,7 +2,7 @@ NOTE: Before starting to work with your Raspberry Pi Build HAT you should xref:../computers/getting-started.adoc#setting-up-your-raspberry-pi[set up] your Raspberry Pi, xref:../computers/getting-started.adoc#installing-the-operating-system[install] the latest version of the operating system using https://www.raspberrypi.com/downloads/[Raspberry Pi Imager]. -Attach 9mm spacers to the bottom of the board. Seat the Raspberry Pi Build HAT onto your Raspberry Pi. Make sure you put it on the right way up. Unlike other HATs, all the components are on the bottom, leaving room for a breadboard or LEGO® elements on top. +Attach 9mm spacers to the bottom of the board. Seat the Raspberry Pi Build HAT onto your Raspberry Pi. Make sure you put it on the right way up. Unlike other HATs, all the components are on the bottom, leaving room for a breadboard or LEGO® elements on top. video::images/fitting-build-hat.webm[width="80%"] @@ -18,10 +18,10 @@ The following pins are used by the Build HAT itself and you should not connect a [cols="^1,^1,^1", width="75%", options="header"] |=== | GPIO| Use | Status -| GPIO0/1 | ID prom | -| GPIO4| Reset | -| GPIO14| Tx | -| GPIO15| Rx | +| GPIO0/1 | ID prom | +| GPIO4| Reset | +| GPIO14| Tx | +| GPIO15| Rx | | GPIO16 | RTS | unused | GPIO17 | CTS | unused |=== @@ -29,11 +29,11 @@ The following pins are used by the Build HAT itself and you should not connect a === Set up your Raspberry Pi -Once the Raspberry Pi has booted, open the Raspberry Pi Configuration tool by clicking on the Raspberry Menu button and then selecting "Preferences" and then "Raspberry Pi Configuration". +Once the Raspberry Pi has booted, open the Control Centre tool by selecting the Raspberry Menu button and then selecting **Preferences > Control Centre**. -Click on the "interfaces" tab and adjust the Serial settings as shown below: +Select the **Interfaces** tab and adjust the serial settings as shown in the following image: -image::images/setting-up.png[width="50%"] +image::images/setting-up.png["The Interfaces tab. SSH, VNC, and Serial Port are enabled. The rest of the options are not enabled.", width="50%"] ==== Use your Raspberry Pi headless diff --git a/documentation/asciidoc/accessories/camera/camera_hardware.adoc b/documentation/asciidoc/accessories/camera/camera_hardware.adoc index 2c62ce3d6..12ef1c3a1 100644 --- a/documentation/asciidoc/accessories/camera/camera_hardware.adoc +++ b/documentation/asciidoc/accessories/camera/camera_hardware.adoc @@ -43,13 +43,17 @@ WARNING: Cameras are sensitive to static. Earth yourself prior to handling the P === Connect the Camera -The flex cable inserts into the connector labelled CAMERA on the Raspberry Pi, which is located between the Ethernet and HDMI ports. The cable must be inserted with the silver contacts facing the HDMI port. To open the connector, pull the tabs on the top of the connector upwards, then towards the Ethernet port. The flex cable should be inserted firmly into the connector, with care taken not to bend the flex at too acute an angle. To close the connector, push the top part of the connector towards the HDMI port and down, while holding the flex cable in place. +Before connecting any Camera, shut down your Raspberry Pi and disconnect it from power. -We have created a video to illustrate the process of connecting the camera. The following video shows how to connect the original camera on the original Raspberry Pi 1. The principle is the same for all Raspberry Pi boards with a camera connector, though the Raspberry Pi 5 and all Raspberry Pi Zero models require a https://www.raspberrypi.com/products/camera-cable/[different camera cable]. +The flex cable inserts into the connector labelled CAMERA on the Raspberry Pi, which is located between the Ethernet and HDMI ports. The cable must be inserted with the silver contacts facing the HDMI port. To open the connector, pull the tabs on the top of the connector upwards, then towards the Ethernet port. The flex cable should be inserted firmly into the connector, with care taken not to bend the flex at too acute an angle. To close the connector, push the top part of the connector down and away from the Ethernet port while holding the flex cable in place. + +The following video shows how to connect the original camera on the original Raspberry Pi 1: video::GImeVqHQzsE[youtube,width=80%,height=400px] -Depending on the model, the camera may come with a small piece of translucent blue plastic film covering the lens. This is only present to protect the lens while it is being mailed to you, and needs to be removed by gently peeling it off. +All Raspberry Pi boards with a camera connector use the same installation method, though the Raspberry Pi 5 and all Raspberry Pi Zero models require a https://www.raspberrypi.com/products/camera-cable/[different camera cable]. + +Some cameras may come with a small piece of translucent blue plastic film covering the lens. This is only present to protect the lens during shipping. To remove it, gently peel it off. NOTE: There is additional documentation available around fitting the recommended https://datasheets.raspberrypi.com/hq-camera/cs-mount-lens-guide.pdf[6mm] and https://datasheets.raspberrypi.com/hq-camera/c-mount-lens-guide.pdf[16mm] lens to the HQ Camera. @@ -265,3 +269,73 @@ Other available schematics; * Camera Module v3 https://datasheets.raspberrypi.com/camera/camera-module-3-schematics.pdf[PDF] * HQ Camera Module https://datasheets.raspberrypi.com/hq-camera/hq-camera-schematics.pdf[PDF] +==== Camera Connector Pinout (15-Pin) + +This is the pinout of the 15-pin Camera Serial Interface (CSI) connector used on flagship Raspberry Pi models prior to Raspberry Pi 5. +The connector is compatible with Amphenol SFW15R-2STE1LF. + +Signal direction is specified from the perspective of the Raspberry Pi. +The I2C lines (SCL and SDA) are pulled up to 3.3 V on the Raspberry Pi board. + +The function and direction of the GPIO lines depend on the specific Camera Module in use. Typically, `CAM_IO0` is used as an active-high power enable. Some products don't include `CAM_IO1`. + +NOTE: Which end is pin 1 on an FPC connector depends on your source and destination hardware, and whether your cable has metallic contacts on the top, the bottom, or both the top and bottom. Pin 15 of the flat flexible connector (FFC) is nearest the edge of the board. + +|=== +| Pin | Name | Description | Direction / Type + +| 1 | GND | - | Ground +| 2 | CAM_DN0 | D-PHY lane 0 (negative) | Input, D-PHY +| 3 | CAM_DP0 | D-PHY lane 0 (positive) | Input, D-PHY +| 4 | GND | - | Ground +| 5 | CAM_DN1 | D-PHY lane 1 (negative) | Input, D-PHY +| 6 | CAM_DP1 | D-PHY lane 1 (positive) | Input, D-PHY +| 7 | GND | - | Ground +| 8 | CAM_CN | D-PHY Clock (negative) | Input, D-PHY +| 9 | CAM_CP | D-PHY Clock (positive) | Input, D-PHY +|10 | GND | - | Ground +|11 | CAM_IO0 | GPIO (for example, Power-Enable) | Bidirectional, 3.3 V +|12 | CAM_IO1 | GPIO (for example, Clock, LED) | Bidirectional, 3.3 V +|13 | SCL | I2C Clock | Bidirectional, 3.3 V +|14 | SDA | I2C Data | Bidirectional, 3.3 V +|15 | 3V3 | 3.3 V Supply | Output +|=== + +==== Camera Connector Pinout (22-Pin) + +This is the pinout of the 22-pin Camera Serial Interface (CSI) connector used on the Raspberry Pi Zero series, the Compute Module IO boards, and flagship models since Raspberry Pi 5. +The connector is compatible with Amphenol F32Q-1A7H1-11022. + +Signal direction is specified from the perspective of the Raspberry Pi. +The I2C lines (SCL and SDA) are pulled up to 3.3 V on the Raspberry Pi board. + +The function and direction of the GPIO lines depend on the specific Camera Module in use. Typically, `CAM_IO0` is used as an active-high power enable. Some products don't include `CAM_IO1`. + +NOTE: Which end is pin 1 on an FPC connector depends on your source and destination hardware, and whether your cable has metallic contacts on the top, the bottom, or both the top and bottom. + +|=== +| Pin | Name | Description | Direction / Type + +| 1 | GND | - | Ground +| 2 | CAM_DN0 | D-PHY lane 0 (negative) | Input, D-PHY +| 3 | CAM_DP0 | D-PHY lane 0 (positive) | Input, D-PHY +| 4 | GND | - | Ground +| 5 | CAM_DN1 | D-PHY lane 1 (negative) | Input, D-PHY +| 6 | CAM_DP1 | D-PHY lane 1 (positive) | Input, D-PHY +| 7 | GND | - | Ground +| 8 | CAM_CN | D-PHY Clock (negative) | Input, D-PHY +| 9 | CAM_CP | D-PHY Clock (positive) | Input, D-PHY +|10 | GND | - | Ground +|11 | CAM_DN2 | D-PHY lane 2 (negative) | Input, D-PHY +|12 | CAM_DP2 | D-PHY lane 2 (positive) | Input, D-PHY +|13 | GND | - | Ground +|14 | CAM_DN3 | D-PHY lane 3 (negative) | Input, D-PHY +|15 | CAM_DP3 | D-PHY lane 3 (positive) | Input, D-PHY +|16 | GND | - | Ground +|17 | CAM_IO0 | GPIO (for example, Power-Enable) | Bidirectional, 3.3 V +|18 | CAM_IO1 | GPIO (for example, Clock, LED) | Bidirectional, 3.3 V +|19 | GND | - | Ground +|20 | SCL | I2C Clock | Bidirectional, 3.3 V +|21 | SDA | I2C Data | Bidirectional, 3.3 V +|22 | 3V3 | 3.3 V Supply | Output +|=== \ No newline at end of file diff --git a/documentation/asciidoc/accessories/camera/external_trigger.adoc b/documentation/asciidoc/accessories/camera/external_trigger.adoc index b30140ca4..642412d54 100644 --- a/documentation/asciidoc/accessories/camera/external_trigger.adoc +++ b/documentation/asciidoc/accessories/camera/external_trigger.adoc @@ -21,17 +21,6 @@ We can use a Raspberry Pi Pico to provide the trigger. Connect any Pico GPIO pin image::images/pico_wiring.jpg[alt="Image showing Raspberry Pi Pico wiring",width="50%"] -==== Boot up the Raspberry Pi with the camera connected. - -Enable external triggering through superuser mode: - -[source,console] ----- -$ sudo su -$ echo 1 > /sys/module/imx296/parameters/trigger_mode -$ exit ----- - ==== Raspberry Pi Pico MicroPython Code [source,python] @@ -55,15 +44,37 @@ The low pulse width is equal to the shutter time, and the frequency of the PWM e NOTE: In this example, Pin 28 connects to the XTR touchpoint on the GS camera board. -=== Operation +=== Camera driver configuration + +This step is only necessary if you have more than one camera with XTR wired in parallel. + +Edit `/boot/firmware/config.txt`. Change `camera_auto_detect=1` to `camera_auto_detect=0`. + +Append this line: +[source] +---- +dtoverlay=imx296,always-on +---- +When using the CAM0 port on a Raspberry Pi 5, CM4 or CM5, append `,cam0` to that line without a space. If both cameras are on the same Raspberry Pi you will need two dtoverlay lines, only one of them ending with `,cam0`. + +If the external trigger will not be started right away, you also need to increase the libcamera timeout xref:camera.adoc#libcamera-configuration[as above]. + +=== Starting the camera + +Enable external triggering: + +[source,console] +---- +$ echo 1 | sudo tee /sys/module/imx296/parameters/trigger_mode +---- -Run the code on the Pico, and set the camera running: +Run the code on the Pico, then set the camera running: [source,console] ---- $ rpicam-hello -t 0 --qt-preview --shutter 3000 ---- -Every time that the Pico pulses the pin, it should generate a frame. To control the framerate, vary the duration between pulses. +Every time the Pico pulses the pin, it should capture a frame. However, if `--gain` and `--awbgains` are not set, some frames will be dropped to allow AGC and AWB algorithms to settle. -NOTE: When running `rpicam-apps`, always specify a fixed shutter duration to ensure the AGC does not adjust the camera's shutter speed. The duration does not matter, since it is actually controlled by the external trigger pulse. +NOTE: When running `rpicam-apps`, always specify a fixed shutter duration, to ensure the AGC does not try to adjust the camera's shutter speed. The value is not important, since it is actually controlled by the external trigger pulse. diff --git a/documentation/asciidoc/accessories/camera/synchronous_cameras.adoc b/documentation/asciidoc/accessories/camera/synchronous_cameras.adoc index 58734110c..9561864ff 100644 --- a/documentation/asciidoc/accessories/camera/synchronous_cameras.adoc +++ b/documentation/asciidoc/accessories/camera/synchronous_cameras.adoc @@ -1,102 +1,108 @@ == Synchronous Captures -Both the HQ Camera and the Global Shutter Camera, have support for synchronous captures. -Making use of the XVS pin (Vertical Sync) allows one camera to pulse when a frame capture is initiated. -The other camera can then listen for this sync pulse, and capture a frame at the same time as the other camera. +The High Quality (HQ) Camera supports synchronous captures. +One camera (the "source") can be configured to generate a pulse on its XVS (Vertical Sync) pin when a frame capture is initiated. +Other ("sink") cameras can listen for this pulse, and capture a frame at the same time as the source camera. -=== Using the HQ Camera +This method is largely superseded by xref:../computers/camera_software.adoc#software-camera-synchronisation[software camera synchronisation] which can operate over long distances without additional wires and has sub-millisecond accuracy. But when cameras are physically close, wired synchronisation may be used. -For correct operation, both cameras require a 1.65V pull up voltage on the XVS line, which is created by a potential divider through the 3.3V and GND pins on the Raspberry Pi. +NOTE: Global Shutter (GS) Cameras can also be operated in a synchronous mode. However, the source camera will record one extra frame. Instead, for GS Cameras we recommend using an xref:camera.adoc#external-trigger-on-the-gs-camera[external trigger source]. You cannot synchronise a GS Camera and an HQ Camera. -image::images/synchronous_camera_wiring.jpg[alt="Image showing potential divider setup",width="50%"] +=== Connecting the cameras -Create a potential divider from two 10kΩ resistors to 3.3V and ground (to make 1.65V with an effective source impedance of 5kΩ). This can be connected to either Raspberry Pi. +Solder a wire to the XVS test point of each camera, and connect them together. -Solder the GND and XVS test points of each HQ Camera board to each other. +Solder a wire to the GND test point of each camera, and connect them together. -Connect the XVS wires to the 1.65V potential divider pull-up. +*For GS Cameras only,* you will also need to connect the XHS (Horizontal Sync) test point of each camera together. On any GS Camera that you wish to act as a sink, bridge the two halves of the MAS pad with solder. -==== Boot up both Raspberry Pis +NOTE: An earlier version of this document recommended an external pull-up for XVS. This is no longer recommended. Instead, ensure you have the latest version of Raspberry Pi OS and set the `always-on` property for all connected cameras. -The file `/sys/module/imx477/parameters/trigger_mode` determines which board outputs pulses, or waits to receive pulses (source and sink). -This parameter can only be altered in superuser mode. +=== Driver configuration -Run the following commands to configure the sink: +You will need to configure the camera drivers to keep their 1.8V power supplies on when not streaming, and optionally to select the source and sink roles. -[source,console] +==== For the HQ Camera + +Edit `/boot/firmware/config.txt`. Change `camera_auto_detect=1` to `camera_auto_detect=0`. + +Append this line for a source camera: +[source] ---- -$ sudo su -$ echo 2 > /sys/module/imx477/parameters/trigger_mode -$ exit +dtoverlay=imx477,always-on,sync-source ---- -Run the following commands to configure the source: - -[source,console] +Or for a sink: +[source] ---- -$ sudo su -$ echo 1 > /sys/module/imx477/parameters/trigger_mode -$ exit +dtoverlay=imx477,always-on,sync-sink ---- -Run the following command to start the sink: +When using the CAM0 port on a Raspberry Pi 5, CM4 or CM5, append `,cam0` to that line without a space. If two cameras are on the same Raspberry Pi you will need two dtoverlay lines, only one of them ending with `,cam0`. + +Alternatively, if you wish to swap the cameras' roles at runtime (and they are not both connected to the same Raspberry Pi), omit `,sync-source` or `,sync-sink` above. Instead you can set a module parameter before starting each camera: +For the Raspbery Pi with the source camera: [source,console] ---- -$ rpicam-vid --frames 300 --qt-preview -o sink.h264 +$ echo 1 | sudo tee /sys/module/imx477/parameters/trigger_mode ---- -Run the following command to start the source: - +For the Raspberry Pi with the sink camera: [source,console] ---- -$ rpicam-vid --frames 300 --qt-preview -o source.h264 +$ echo 2 | sudo tee /sys/module/imx477/parameters/trigger_mode ---- +You will need to do this every time the system is booted. -Frames should be synchronous. Use `--frames` to ensure the same number of frames are captured, and that the recordings are exactly the same length. -Running the sink first ensures that no frames are missed. - -NOTE: The potential divider is needed to pull up the XVS pin to high whilst the source is in an idle state. This ensures that no frames are created or lost upon startup. The source whilst initialising goes from LOW to HIGH which can trigger a false frame. - -=== Use the GS Camera +==== For the GS Camera -NOTE: The Global Shutter (GS) camera can also be operated in a synchronous mode. However, the source camera will record one extra frame. A much better alternative method to ensure that both cameras capture the same amount of frames is to use the xref:camera.adoc#external-trigger-on-the-gs-camera[external trigger method]. +Edit `/boot/firmware/config.txt`. Change `camera_auto_detect=1` to `camera_auto_detect=0`. -To operate as source and sink together, the Global Shutter Cameras also require connection of the XHS (horizontal sync) pins together. However, these do not need connection to a pullup resistor. - -The wiring setup is identical to the xref:camera.adoc#using-the-hq-camera[HQ Camera method], except that you will also need to connect the XHS pins together. - -Create a potential divider from two 10kΩ resistors to 3.3V and ground (to make 1.65V with an effective source impedance of 5kΩ). This can be connected to either Raspberry Pi. - -Solder 2 wires to the XVS test points on each board and connect both of these wires together to the 1.65V potential divider. +For either a source or a sink, append this line: +[source] +---- +dtoverlay=imx296,always-on +---- +When using the CAM0 port on a Raspberry Pi 5, CM4 or CM5, append `,cam0` to that line without a space. If two cameras are on the same Raspberry Pi you will need two dtoverlay lines, only one of them ending with `,cam0`. -Solder the GND of each Camera board to each other. Also solder 2 wires to the XHS test points on each board and connect these. No pullup is needed for XHS pin. +On the GS Camera, the sink role is enabled by the MAS pin and cannot be configured by software ("trigger_mode" and "sync-sink" relate to the xref:camera.adoc#external-trigger-on-the-gs-camera[external trigger method], and should _not_ be set for this method). -On the boards that you wish to act as sinks, solder the two halves of the MAS pad together. This tells the sensor to act as a sink, and will wait for a signal to capture a frame. +=== Libcamera configuration -==== Boot up source and sink +If the cameras are not all started within 1 second, the `rpicam` applications can time out. To prevent this, you must edit a configuration file on any Raspberry Pi(s) with sink cameras. -Run the following command to start the sink: +On Raspberry Pi 5 or CM5: +[source,console] +---- +$ cp /usr/share/libcamera/pipeline/rpi/pisp/example.yaml timeout.yaml +---- +On other Raspberry Pi models: [source,console] ---- -$ rpicam-vid --frames 300 -o sync.h264 +$ cp /usr/share/libcamera/pipeline/rpi/vc4/rpi_apps.yaml timeout.yaml ---- -Due to the limitations of the IMX296 sensor, the sink cannot record exactly the same number of frames as the source. **The source records one extra frame before the sink starts recording**. Because of this, you need to specify that the sink records one less frame with the `--frames` option. +Now edit the copy. In both cases, delete the `#` (comment) from the `"camera_timeout_value_ms":` line, and change the number to `60000` (60 seconds). -Wait at least two seconds before you start the source. +=== Starting the cameras -After waiting two seconds, run the following command to start the source: +Run the following commands to start the sink: [source,console] ---- -$ rpicam-vid --frames 299 -o sync.h264 +$ export LIBCAMERA_RPI_CONFIG_FILE=timeout.yaml +$ rpicam-vid --frames 300 --qt-preview -o sink.h264 ---- -Because the sink and source record a different number of frames, use `ffmpeg` to resync the videos. By dropping the first frame from the source, we then get two recordings with the same starting point and frame length: +Wait a few seconds, then run the following command to start the source: [source,console] ---- -$ ffmpeg -i source.h264 -vf select="gte(n\, 1)" source.h264 +$ rpicam-vid --frames 300 --qt-preview -o source.h264 ---- +Frames should be synchronised. Use `--frames` to ensure the same number of frames are captured, and that the recordings are exactly the same length. +Running the sink first ensures that no frames are missed. + +NOTE: When using the GS camera in synchronous mode, the sink will not record exactly the same number of frames as the source. **The source records one extra frame before the sink starts recording**. Because of this, you need to specify that the sink records one less frame with the `--frames` option. diff --git a/documentation/asciidoc/accessories/display/display_intro.adoc b/documentation/asciidoc/accessories/display/display_intro.adoc index 424540ab6..b7f5204ec 100644 --- a/documentation/asciidoc/accessories/display/display_intro.adoc +++ b/documentation/asciidoc/accessories/display/display_intro.adoc @@ -7,7 +7,7 @@ image::images/display.png[The Raspberry Pi 7-inch Touch Display, width="70%"] The Touch Display is compatible with all models of Raspberry Pi, except the Zero series and Keyboard series, which lack a DSI connector. The earliest Raspberry Pi models lack appropriate mounting holes, requiring additional mounting hardware to fit the stand-offs on the display PCB. -The display has the following key features: +The display has the following key features: * 800×480px RGB LCD display * 24-bit colour @@ -79,7 +79,7 @@ Raspberry Pi OS _Bookworm_ and later include the Squeekboard on-screen keyboard For applications which do not support text entry detection, use the keyboard icon at the right end of the taskbar to manually show and hide the keyboard. -You can also permanently show or hide the on-screen keyboard in the Display tab of Raspberry Pi Configuration or the `Display` section of `raspi-config`. +You can also permanently show or hide the on-screen keyboard in the **Display** tab of Control Centre or the `Display` section of `raspi-config`. TIP: In Raspberry Pi OS releases prior to _Bookworm_, use `matchbox-keyboard` instead. If you use the wayfire desktop compositor, use `wvkbd` instead. @@ -159,3 +159,7 @@ To specify these options, add them, separated by commas, to your `dtoverlay` lin ---- dtoverlay=vc4-kms-dsi-7inch,sizex=400,invx,invy ---- + +=== Installation on Compute Module based devices. + +All Raspberry Pi SBCs auto-detect the official Touch Displays as the circuitry connected to the DSI connector on the Raspberry Pi board is fixed; this autodetection ensures the correct Device Tree entries are passed to the kernel. However, Compute Modules are intended for industrial applications where the integrator can use any and all GPIOs and interfaces for whatever purposes they require. Autodetection is therefore not feasible, and hence is disabled on Compute Module devices. This means that the Device Tree fragments required to set up the display need to be loaded via some other mechanism, which can be either with a dtoverlay entry in config.txt as described above, via a custom base DT file, or if present, a HAT EEPROM. \ No newline at end of file diff --git a/documentation/asciidoc/accessories/m2-hat-plus/about.adoc b/documentation/asciidoc/accessories/m2-hat-plus/about.adoc index a3b033a28..a3194fb13 100644 --- a/documentation/asciidoc/accessories/m2-hat-plus/about.adoc +++ b/documentation/asciidoc/accessories/m2-hat-plus/about.adoc @@ -1,51 +1,67 @@ [[m2-hat-plus]] == About +[.clearfix] +-- +[.left] .The Raspberry Pi M.2 HAT+ -image::images/m2-hat-plus.jpg[width="80%"] +image::images/m2-hat-plus.jpg[width="100%"] +[.left] +.The Raspberry Pi M.2 HAT+ Compact in the Raspberry Pi Case +image::images/m2-hat-plus-compact-with-case.jpg[width="100%"] +-- -The Raspberry Pi M.2 HAT+ M Key enables you to connect M.2 peripherals such as NVMe drives and other PCIe accessories to Raspberry Pi 5's PCIe interface. +The Raspberry Pi M.2 HAT+ M Key and M.2 HAT+ Compact M Key enable you to connect M.2 peripherals such as NVMe drives and other PCIe accessories to Raspberry Pi 5's PCIe interface. -The M.2 HAT+ adapter board converts between the PCIe connector on Raspberry Pi 5 and a single M.2 M key edge connector. You can connect any device that uses the 2230 or 2242 form factors. The M.2 HAT+ can supply up to 3A of power. +The M.2 HAT+ and M.2 HAT+ Compact adapter boards convert between the PCIe connector on Raspberry Pi 5 and a single M.2 M key edge connector. The M.2 HAT+ supports any device that uses the 2230 or 2242 form factor; the M.2 HAT+ Compact supports any device that uses the 2230 form factor. -The M.2 HAT+ uses Raspberry Pi's https://datasheets.raspberrypi.com/hat/hat-plus-specification.pdf[HAT+ specification], which allows Raspberry Pi OS to automatically detect the HAT+ and any connected devices. +We provide the M.2 HAT+ in a standard and a compact format to serve different use cases: -The included threaded spacers provide ample room to fit the Raspberry Pi Active Cooler beneath an M.2 HAT+. +* The M.2 HAT+ includes threaded spacers that provide ample room to fit the Raspberry Pi Active Cooler beneath it. However, the M.2 HAT+ is _only_ compatible with the https://www.raspberrypi.com/products/raspberry-pi-5-case/[Raspberry Pi Case for Raspberry Pi 5] _if you remove the lid and the included fan_. -The M.2 HAT+ is _only_ compatible with the https://www.raspberrypi.com/products/raspberry-pi-5-case/[Raspberry Pi Case for Raspberry Pi 5] _if you remove the lid and the included fan_. +* The M.2 HAT+ Compact is designed to fit around the included fan in the https://www.raspberrypi.com/products/raspberry-pi-5-case/[Raspberry Pi Case for Raspberry Pi 5]. However, you can't fit the Active Cooler beneath it. + +Both the M.2 HAT+ and M.2 HAT+ Compact conform to the https://datasheets.raspberrypi.com/hat/hat-plus-specification.pdf[Raspberry Pi HAT+ specification], which allows Raspberry Pi OS to automatically detect the HAT+ and any connected devices. == Features +The M.2 HAT+ and M.2 HAT+ Compact both have the following features: + * Single-lane PCIe 2.0 interface (500 MB/s peak transfer rate) -* Supports devices that use the M.2 M key edge connector -* Supports devices with the 2230 or 2242 form factor -* Supplies up to 3A to connected M.2 devices +* Support for devices that use the M.2 M key edge connector +* Up to 3 A supply to connected M.2 devices * Power and activity LEDs -* Conforms to the https://datasheets.raspberrypi.com/hat/hat-plus-specification.pdf[Raspberry Pi HAT+ specification] -* Includes: -** ribbon cable -** 16mm GPIO stacking header -** 4 threaded spacers -** 8 screws -** 1 knurled double-flanged drive attachment screw to secure and support the M.2 peripheral -[[m2-hat-plus-installation]] -== Install +The M.2 HAT+ and M.2 HAT+ Compact differ in the following ways: + +* M.2 HAT+ supports devices with the 2230 or 2242 form factor; M.2 HAT+ Compact only supports the 2230 form factor. + +=== Hardware + +The Raspberry Pi M.2 HAT+ or M.2 HAT+ Compact box contains the following parts: -To use the Raspberry Pi M.2 HAT+, you will need: +* Ribbon cable +* Threaded spacers +* Screws +* 1 knurled double-flanged drive attachment screw to secure and support the M.2 peripheral -* a Raspberry Pi 5 +The M.2 HAT+ also includes a 16 mm GPIO stacking header; M.2 HAT+ Compact doesn't include this component. -Each M.2 HAT+ comes with a ribbon cable, GPIO stacking header, and mounting hardware. Complete the following instructions to install your M.2 HAT+: +To use the M.2 HAT+ or M.2 HAT+ Compact, you also need: -. First, ensure that your Raspberry Pi runs the latest software. Run the following command to update: +* A Raspberry Pi 5 + +[[m2-hat-plus-installation]] +== Prepare your Raspberry Pi + +. Ensure that your Raspberry Pi runs the latest software. Run the following command to update: + [source,console] ---- $ sudo apt update && sudo apt full-upgrade ---- -. Next, xref:../computers/raspberry-pi.adoc#update-the-bootloader-configuration[ensure that your Raspberry Pi firmware is up-to-date]. Run the following command to see what firmware you're running: +. xref:../computers/raspberry-pi.adoc#update-the-bootloader-configuration[Ensure that your Raspberry Pi firmware is up-to-date]. Run the following command to see what firmware you're running: + [source,console] ---- @@ -72,54 +88,136 @@ Then, reboot with `sudo reboot`. . Disconnect the Raspberry Pi from power before beginning installation. +[[standard-installation]] +== Install the M.2 HAT+ + +Follow these steps to install the M.2 HAT+. To install the M.2 HAT+ Compact go to <> instead. + +=== (Optional) Install the Active Cooler . The M.2 HAT+ is compatible with the Raspberry Pi 5 Active Cooler. If you have an Active Cooler, install it before installing the M.2 HAT+. + -- image::images/m2-hat-plus-installation-01.png[width="60%"] -- -. Install the spacers using four of the provided screws. Firmly press the GPIO stacking header on top of the Raspberry Pi GPIO pins; orientation does not matter as long as all pins fit into place. Disconnect the ribbon cable from the M.2 HAT+, and insert the other end into the PCIe port of your Raspberry Pi. Lift the ribbon cable holder from both sides, then insert the cable with the copper contact points facing inward, towards the USB ports. With the ribbon cable fully and evenly inserted into the PCIe port, push the cable holder down from both sides to secure the ribbon cable firmly in place. -+ + +=== Install the mounting hardware + +. Install the spacers using the provided screws. + +. Firmly press the GPIO stacking header on top of the Raspberry Pi GPIO pins; orientation doesn't matter as long as all pins fit into place. + +. Disconnect the ribbon cable from the M.2 HAT+. Insert the other end into the PCIe port of your Raspberry Pi. Lift the ribbon cable holder from both sides, then insert the cable with the copper contact points facing inward, towards the USB ports. With the ribbon cable fully and evenly inserted into the PCIe port, push the cable holder down from both sides to secure the ribbon cable firmly in place. + -- image::images/m2-hat-plus-installation-02.png[width="60%"] -- -. Set the M.2 HAT+ on top of the spacers, and use the four remaining screws to secure it in place. + +=== Install the board + +. Set the M.2 HAT+ on top of the spacers and use the remaining screws to secure it in place. + -- image::images/m2-hat-plus-installation-03.png[width="60%"] -- -. Insert the ribbon cable into the slot on the M.2 HAT+. Lift the ribbon cable holder from both sides, then insert the cable with the copper contact points facing up. With the ribbon cable fully and evenly inserted into the port, push the cable holder down from both sides to secure the ribbon cable firmly in place. + +. Insert the ribbon cable into the slot on the M.2 HAT+. ++ +Lift the ribbon cable holder from both sides, then insert the cable with the copper contact points facing up. With the ribbon cable fully and evenly inserted into the port, push the cable holder down from both sides to secure the ribbon cable firmly in place. + -- image::images/m2-hat-plus-installation-04.png[width="60%"] -- + +=== Install your M.2 drive + . Remove the drive attachment screw by turning the screw counter-clockwise. Insert your M.2 SSD into the M.2 key edge connector, sliding the drive into the slot at a slight upward angle. Do not force the drive into the slot: it should slide in gently. + -- image::images/m2-hat-plus-installation-05.png[width="60%"] -- + . Push the notch on the drive attachment screw into the slot at the end of your M.2 drive. Push the drive flat against the M.2 HAT+, and insert the SSD attachment screw by turning the screw clockwise until the SSD feels secure. Do not over-tighten the screw. + -- image::images/m2-hat-plus-installation-06.png[width="60%"] -- -. Congratulations, you have successfully installed the M.2 HAT+. Connect your Raspberry Pi to power; Raspberry Pi OS will automatically detect the M.2 HAT+. If you use Raspberry Pi Desktop, you should see an icon representing the drive on your desktop. If you don't use a desktop, you can find the drive at `/dev/nvme0n1`. To make your drive automatically available for file access, consider xref:../computers/configuration.adoc#automatically-mount-a-storage-device[configuring automatic mounting]. + +Congratulations, you have successfully installed the M.2 HAT+. + +.Installed M.2 HAT+ +image::images/m2-hat-plus-installation-07.png[width="80%"] + + +[[compact-installation]] +== Install the M.2 HAT+ Compact + +Follow these steps to install the M.2 HAT+ Compact. To install the M.2 HAT+ go to <> instead. + +=== Install the mounting hardware + +. Install the spacers using the provided screws. ++ +-- +image::images/m2-hat-plus-compact-installation-02.png[width="60%"] +-- + +=== Install the board + +. Set the M.2 HAT+ Compact on top of the spacers and use the remaining screws to secure it in place. + -- -image::images/m2-hat-plus-installation-07.png[width="60%"] +image::images/m2-hat-plus-compact-installation-03.png[width="60%"] -- +. Insert the ribbon cable into the PCIe port of your Raspberry Pi. ++ +Lift the ribbon cable holder from both sides, then insert the cable with the copper contact points facing inward, towards the USB ports. With the ribbon cable fully and evenly inserted into the PCIe port, push the cable holder down from both sides to secure the ribbon cable firmly in place. ++ +-- +image::images/m2-hat-plus-compact-installation-04.png[width="60%"] +-- + +=== Install your M.2 drive + +. Remove the drive attachment screw by turning the screw counter-clockwise. Insert your M.2 SSD into the M.2 key edge connector, sliding the drive into the slot at a slight upward angle. Do not force the drive into the slot: it should slide in gently. ++ +-- +image::images/m2-hat-plus-compact-installation-05.png[width="60%"] +-- + +. Push the notch on the drive attachment screw into the slot at the end of your M.2 drive. Push the drive flat against the M.2 HAT+ Compact, and insert the SSD attachment screw by turning the screw clockwise until the SSD feels secure. Do not over-tighten the screw. ++ +-- +image::images/m2-hat-plus-compact-installation-06.png[width="60%"] +-- + +Congratulations, you have successfully installed the M.2 HAT+ Compact. + +.Installed M.2 HAT+ Compact +image::images/m2-hat-plus-compact-installation-07.png[width="80%"] + +== Start your Raspberry Pi + +. Connect your Raspberry Pi to power; Raspberry Pi OS automatically detects the M.2 HAT+ or M.2 HAT+ Compact. If you use Raspberry Pi Desktop, you see an icon representing the drive on your desktop. If you don't use a desktop, you can find the drive at `/dev/nvme0n1`. + +. To make your drive automatically available for file access, consider xref:../computers/configuration.adoc#automatically-mount-a-storage-device[configuring automatic mounting]. + WARNING: Always disconnect your Raspberry Pi from power before connecting or disconnecting a device from the M.2 slot. == Boot from NVMe -To boot from an NVMe drive attached to the M.2 HAT+, complete the following steps: +To boot from an NVMe drive attached to the M.2 HAT+ or M.2 HAT+ Compact, complete the following steps: -. xref:../computers/getting-started.adoc#raspberry-pi-imager[Format your NVMe drive using Raspberry Pi Imager]. You can do this from your Raspberry Pi if you already have an SD card with a Raspberry Pi OS image. -. Boot your Raspberry Pi into Raspberry Pi OS using an SD card or USB drive to alter the boot order in the persistent on-board EEPROM configuration. -. In a terminal on your Raspberry Pi, run `sudo raspi-config` to open the Raspberry Pi Configuration CLI. -. Under `Advanced Options` > `Boot Order`, choose `NVMe/USB boot`. Then, exit `raspi-config` with `Finish` or the *Escape* key. -. Reboot your Raspberry Pi with `sudo reboot`. +. xref:../computers/getting-started.adoc#raspberry-pi-imager[Install an operating system to your NVMe drive by using Raspberry Pi Imager]. You can do this from your Raspberry Pi if you already have an SD card with a Raspberry Pi OS image. +. Reboot your Raspberry Pi. +* If you don't have an SD card inserted in your Raspberry Pi 5, it boots automatically from your NVMe drive. +* If you do have an SD card inserted in your Raspberry Pi 5, it attempts to boot from the SD card first. You can change the boot order on your Raspberry Pi by completing the following steps: +.. Boot your Raspberry Pi into Raspberry Pi OS using an SD card. +.. In a terminal on your Raspberry Pi, run `sudo raspi-config` to open the Raspberry Pi Configuration CLI. +.. Under `Advanced Options` > `Boot Order`, choose `NVMe/USB boot`. +.. Exit `raspi-config` with `Finish` or the *Escape* key. +.. Reboot your Raspberry Pi with `sudo reboot`. For more information, see xref:../computers/raspberry-pi.adoc#nvme-ssd-boot[NVMe boot]. @@ -131,11 +229,8 @@ To enable PCIe Gen 3 speeds, follow the instructions at xref:../computers/raspbe == Schematics -.Schematics for the Raspberry Pi M.2 HAT+ -image::images/m2-hat-plus-schematics.png[width="80%"] - -Schematics are also available as a https://datasheets.raspberrypi.com/m2-hat-plus/raspberry-pi-m2-hat-plus-schematics.pdf[PDF]. +The schematics for the M.2 HAT+ are available as a https://datasheets.raspberrypi.com/m2-hat-plus/raspberry-pi-m2-hat-plus-schematics.pdf[PDF] == Product brief -For more information about the M.2 HAT+, including mechanical specifications and operating environment limitations, see the https://datasheets.raspberrypi.com/m2-hat-plus/raspberry-pi-m2-hat-plus-product-brief.pdf[product brief]. +For more information about the M.2 HAT+ and M.2 HAT+ Compact, including mechanical specifications and operating environment limitations, see the https://datasheets.raspberrypi.com/m2-hat-plus/raspberry-pi-m2-hat-plus-product-brief.pdf[product brief]. diff --git a/documentation/asciidoc/accessories/m2-hat-plus/images/m2-hat-plus-compact-installation-02.png b/documentation/asciidoc/accessories/m2-hat-plus/images/m2-hat-plus-compact-installation-02.png new file mode 100644 index 000000000..7733a5e5c Binary files /dev/null and b/documentation/asciidoc/accessories/m2-hat-plus/images/m2-hat-plus-compact-installation-02.png differ diff --git a/documentation/asciidoc/accessories/m2-hat-plus/images/m2-hat-plus-compact-installation-03.png b/documentation/asciidoc/accessories/m2-hat-plus/images/m2-hat-plus-compact-installation-03.png new file mode 100644 index 000000000..c7b34e880 Binary files /dev/null and b/documentation/asciidoc/accessories/m2-hat-plus/images/m2-hat-plus-compact-installation-03.png differ diff --git a/documentation/asciidoc/accessories/m2-hat-plus/images/m2-hat-plus-compact-installation-04.png b/documentation/asciidoc/accessories/m2-hat-plus/images/m2-hat-plus-compact-installation-04.png new file mode 100644 index 000000000..6b6eace10 Binary files /dev/null and b/documentation/asciidoc/accessories/m2-hat-plus/images/m2-hat-plus-compact-installation-04.png differ diff --git a/documentation/asciidoc/accessories/m2-hat-plus/images/m2-hat-plus-compact-installation-05.png b/documentation/asciidoc/accessories/m2-hat-plus/images/m2-hat-plus-compact-installation-05.png new file mode 100644 index 000000000..104b024fc Binary files /dev/null and b/documentation/asciidoc/accessories/m2-hat-plus/images/m2-hat-plus-compact-installation-05.png differ diff --git a/documentation/asciidoc/accessories/m2-hat-plus/images/m2-hat-plus-compact-installation-06.png b/documentation/asciidoc/accessories/m2-hat-plus/images/m2-hat-plus-compact-installation-06.png new file mode 100644 index 000000000..3ca9c2d1f Binary files /dev/null and b/documentation/asciidoc/accessories/m2-hat-plus/images/m2-hat-plus-compact-installation-06.png differ diff --git a/documentation/asciidoc/accessories/m2-hat-plus/images/m2-hat-plus-compact-installation-07.png b/documentation/asciidoc/accessories/m2-hat-plus/images/m2-hat-plus-compact-installation-07.png new file mode 100644 index 000000000..45ddcdd41 Binary files /dev/null and b/documentation/asciidoc/accessories/m2-hat-plus/images/m2-hat-plus-compact-installation-07.png differ diff --git a/documentation/asciidoc/accessories/m2-hat-plus/images/m2-hat-plus-compact-with-case.jpg b/documentation/asciidoc/accessories/m2-hat-plus/images/m2-hat-plus-compact-with-case.jpg new file mode 100644 index 000000000..84d26b5b7 Binary files /dev/null and b/documentation/asciidoc/accessories/m2-hat-plus/images/m2-hat-plus-compact-with-case.jpg differ diff --git a/documentation/asciidoc/accessories/monitor/images/monitor-hero.png b/documentation/asciidoc/accessories/monitor/images/monitor-hero.png index dbaa5f56d..b8c91e40f 100644 Binary files a/documentation/asciidoc/accessories/monitor/images/monitor-hero.png and b/documentation/asciidoc/accessories/monitor/images/monitor-hero.png differ diff --git a/documentation/asciidoc/accessories/monitor/monitor_intro.adoc b/documentation/asciidoc/accessories/monitor/monitor_intro.adoc index ae747671a..b6d3d2233 100644 --- a/documentation/asciidoc/accessories/monitor/monitor_intro.adoc +++ b/documentation/asciidoc/accessories/monitor/monitor_intro.adoc @@ -65,7 +65,7 @@ To switch from Power Saving mode to Full Power mode, press and hold the *increas [TIP] ==== -If the Monitor flashes on and off, your USB power supply is not capable of providing sufficient current to power the monitor. This can happen if you power the Monitor from a Raspberry Pi 5 or Pi 500 which is itself powered by a 5V/3A power supply. Try the following fixes to stop the Monitor from flashing on and off: +If the Monitor flashes on and off, your USB power supply is not capable of providing sufficient current to power the monitor. This can happen if you power the Monitor from a Raspberry Pi 5, 500, or 500+ which is itself powered by a 5V/3A power supply. Try the following fixes to stop the Monitor from flashing on and off: * reduce the display brightness and volume (you may have to connect your monitor to another power supply to access the settings) * switch to a different power source or cable diff --git a/documentation/asciidoc/accessories/ssds/about.adoc b/documentation/asciidoc/accessories/ssds/about.adoc index abccf00e9..662ad3f37 100644 --- a/documentation/asciidoc/accessories/ssds/about.adoc +++ b/documentation/asciidoc/accessories/ssds/about.adoc @@ -11,7 +11,7 @@ Raspberry Pi SSDs are available in the following sizes: * 256GB * 512GB -To use an SSD with your Raspberry Pi, you need a Raspberry Pi 5-compatible M.2 adapter, such as the xref:../accessories/m2-hat-plus.adoc[Raspberry Pi M.2 HAT+]. +To use an SSD with your Raspberry Pi, you need a Raspberry Pi 5-compatible M.2 adapter, such as the xref:../accessories/m2-hat-plus.adoc[Raspberry Pi M.2 HAT+ or M.2 HAT+ Compact]. == Specifications diff --git a/documentation/asciidoc/accessories/touch-display-2/about.adoc b/documentation/asciidoc/accessories/touch-display-2/about.adoc index 35763f58e..341cb8c75 100644 --- a/documentation/asciidoc/accessories/touch-display-2/about.adoc +++ b/documentation/asciidoc/accessories/touch-display-2/about.adoc @@ -1,129 +1,223 @@ -== About - -The https://www.raspberrypi.com/products/touch-display-2/[Raspberry Pi Touch Display 2] is a portrait orientation touchscreen LCD display designed for interactive projects like tablets, entertainment systems, and information dashboards. +The https://www.raspberrypi.com/products/touch-display-2/[Raspberry Pi Touch Display 2] is a portrait orientation touchscreen LCD (with rotation options) designed for interactive projects like tablets, entertainment systems, and information dashboards. .The Raspberry Pi Touch Display 2 image::images/touch-display-2-hero.jpg[width="80%"] -The Touch Display 2 connects to a Raspberry Pi using a DSI connector and GPIO connector. Raspberry Pi OS provides touchscreen drivers with support for five-finger multitouch and an on-screen keyboard, providing full functionality without the need to connect a keyboard or mouse. - == Specifications -* 1280×720px resolution, 24-bit RGB display -* 155×88mm active area -* 7" diagonal -* powered directly by the host Raspberry Pi, requiring no separate power supply -* supports up to five points of simultaneous multi-touch +This section describes the physical characteristics and capabilities of Touch Display 2, including dimensions, features, and hardware. -The Touch Display 2 is compatible with all models of Raspberry Pi from Raspberry Pi 1B+ onwards, except the Zero series and Keyboard series, which lack a DSI connector. +=== Dimensions + +The Touch Display 2 is available in two sizes: 5-inch and 7-inch (measured diagonally). Aside from the physical size, these two displays have identical features and functionality. The following table summarises the dimensions of these two displays: + +[cols="1,1,1,1,1"] +|=== +| +|*Depth* +|*Outline dimensions* +|*Viewing area* +|*Active area* + +|*5-inch display* +|16 mm +|143.5 x 91.5 mm +|111.5 x 63 mm +|110.5 x 62 mm + +|*7-inch display* +|15 mm +|189.5 x 120 mm +|155.5 x 88 mm +|154.5 x 87 mm +|=== + +=== Features +Touch Display 2 (both 5-inch and 7-inch) includes the following features: + +* **720 x 1280 pixel resolution.** High-definition output. +* **24-bit RGB display.** Capable of showing over 16 million colours. +* **Multitouch.** Supports up to five simultaneous touch points. +* **Mouse-equivalence.** Supports full desktop control without a physical mouse, for example, selecting, dragging, scrolling, and long-pressing for menus. +* **On-screen keyboard.** Supports a visual keyboard in place of a physical keyboard. +* **Integrated power.** Powered directly by the host Raspberry Pi, requiring no separate power supply. -The Touch Display 2 box contains the following parts (in left to right, top to bottom order in the image below): +=== Hardware -* Touch Display 2 -* eight M2.5 screws -* 15-way to 15-way FFC -* 22-way to 15-way FFC for Raspberry Pi 5 -* GPIO connector cable +The Touch Display 2 box contains the following parts: + +- A Touch Display 2 +- Eight M2.5 screws +- A 15-way to 15-way FFC +- A 22-way to 15-way FFC for Raspberry Pi 5 +- A GPIO power cable + +The following image shows these items from top to bottom, left to right. .Parts included in the Touch Display 2 box image::images/touch-display-2-whats-in-the-booooox.jpg["Parts included in the Touch Display 2 box", width="80%"] -== Install +=== Connectors + +The Touch Display 2 connects to a Raspberry Pi using: + +- A **DSI connector** for video and touch data. +- The **GPIO header** for power. + +To make the DSI connection, use a **Flat Flexible Cable (FFC)** included with your display. The type of FFC you need depends on your Raspberry Pi model: + +- For **Raspberry Pi 5**, use the **22-way to 15-way FFC**. +- For all other Raspberry Pi models, use the **15-way to 15-way FFC**. + +The Touch Display 2 is compatible with all models of Raspberry Pi from Raspberry Pi 1B+ onwards, except the Zero series and Keyboard series, which lack a DSI connector. + +== Connect to Raspberry Pi + +After determining the correct FFC for your Raspberry Pi model, you can connect your Touch Display 2 to your Raspberry Pi. After completing the following steps, you can reconnect your Raspberry Pi to power. It can take up to one minute for Raspberry Pi OS to start displaying output to the Touch Display 2 screen. .A Raspberry Pi 5 connected and mounted to the Touch Display 2 image::images/touch-display-2-installation-diagram.png["A Raspberry Pi 5 connected and mounted to the Touch Display 2", width="80%"] -To connect a Touch Display 2 to a Raspberry Pi, use a Flat Flexible Cable (FFC) and a GPIO connector. The FFC you'll use depends upon your Raspberry Pi model: - -* for Raspberry Pi 5, use the included 22-way to 15-way FFC -* for any other Raspberry Pi model, use the included 15-way to 15-way FFC +IMPORTANT: Disconnect your Raspberry Pi from power before completing the following steps. -Once you have determined the correct FFC for your Raspberry Pi model, complete the following steps to connect your Touch Display 2 to your Raspberry Pi: +=== Step 1. Connect FFC to Touch Display 2 -. Disconnect your Raspberry Pi from power. -. Lift the retaining clips on either side of the FFC connector on the Touch Display 2. +. Slide the retaining clip outwards from both sides of the FFC connector on the Touch Display 2. . Insert one 15-way end of your FFC into the Touch Display 2 FFC connector, with the metal contacts facing upwards, away from the Touch Display 2. -+ -TIP: If you use the 22-way to 15-way FFC, the 22-way end is the _smaller_ end of the cable. Insert the _larger_ end of the cable into the Touch Display 2. -. While holding the FFC firmly in place, simultaneously push both retaining clips down on the FFC connector of the Touch Display 2. -. Lift the retaining clips on either side of the DSI connector of your Raspberry Pi. This port should be marked with some variation of the term `DISPLAY` or `DISP`. If your Raspberry Pi has multiple DSI connectors, prefer the port labelled `1`. -. Insert the other end of your FFC into the Raspberry Pi DSI connector, with the metal contacts facing towards the Ethernet and USB-A ports. -. While holding the FFC firmly in place, simultaneously push both retaining clips down on the DSI connector of the Raspberry Pi. -. Plug the GPIO connector cable into the port marked `J1` on the Touch Display 2. -. Connect the other (three-pin) end of the GPIO connector cable to pins 2, 4, and 6 of the xref:../computers/raspberry-pi.adoc#gpio[Raspberry Pi's GPIO]. Connect the red cable (5V power) to pin 2, and the black cable (ground) to pin 6. Viewed from above, with the Ethernet and USB-A ports facing down, these pins are located at the top right of the board, with pin 2 in the top right-most position. -+ + - If you're connecting to a Raspberry Pi 5, and therefore using the **22-way to 15-way FFC**, the 22-way end is the smaller end of the cable. Insert the larger end of the cable into the Touch Display 2 FFC connector. + - If you're using the **15-way to 15-way FFC**, insert either end of the cable into the Touch Display 2 FFC connector. +. Hold the FFC firmly in place and simultaneously push the retaining clip back in to the Touch Display 2 FFC connector from both sides. + +=== Step 2. Connect FFC to Raspberry Pi + +. Slide the retaining clip upwards from both sides of the DSI connector of your Raspberry Pi. + - This port should be marked with some variation of the term **DISPLAY**, **CAM/DISP**, or **DISP**. + - If your Raspberry Pi has multiple DSI connectors, we recommend using the port labelled **1**. +. Insert the other end of your FFC into the Raspberry Pi DSI connector, with the metal contacts facing the Ethernet and USB-A ports. +. Hold the FFC firmly in place and simultaneously push the retaining clip back down on the FFC connector of the Raspberry Pi to secure the cable. + +=== Step 3. Connect the GPIO power cable + +. Plug the smaller end of the GPIO power cable into the **J1** port on the Touch Display 2. +. Connect the three-pin end of the GPIO power cable to your xref:../computers/raspberry-pi.adoc#gpio[Raspberry Pi's GPIO]. + +This connects the red cable (5 V power) to pin 2 and the black cable (ground) to pin 6. Viewed from above, with the Ethernet and USB-A ports facing down, these pins are located in the top-right corner of the board, with pin 2 in the top right-most position. + .The GPIO connection to the Touch Display 2 image::images/touch-display-2-gpio-connection.png[The GPIO connection to the Touch Display 2, width="40%"] -+ -TIP: If pin 6 isn't available, you can use any other open `GND` pin to connect the black wire. If pin 2 isn't available, you can use any other 5V pin to connect the red wire, such as pin 4. -. Optionally, use the included M2.5 screws to mount your Raspberry Pi to the back of the Touch Display 2. -.. Align the four corner stand-offs of your Raspberry Pi with the four mount points that surround the FFC connector and `J1` port on the back of the Touch Display 2, taking special care not to pinch the FFC. -.. Insert the screws into the four corner stand-offs and tighten until your Raspberry Pi is secure. -. Reconnect your Raspberry Pi to power. It may take up to one minute to initialise the Touch Display 2 connection and begin displaying to the screen. -=== Use an on-screen keyboard +WARNING: Connecting the power cable incorrectly might cause damage to the display. + +=== Step 4. Mount your Raspberry Pi to the Touch Display 2 (optional) + +Optionally, use the included M2.5 screws to mount your Raspberry Pi to the back of your Touch Display 2. + +. Align the four corner stand-offs of your Raspberry Pi with the four mounting points that surround the FFC connector and J1 port on the back of the Touch Display 2. +. Insert the M2.5 screws (included) into the four corner stand-offs and tighten until your Raspberry Pi is secure. + +Take care not to pinch the FFC. -Raspberry Pi OS _Bookworm_ and later include the Squeekboard on-screen keyboard by default. When a touch display is attached, the on-screen keyboard should automatically show when it is possible to enter text and automatically hide when it is not possible to enter text. +== Use an on-screen keyboard -For applications which do not support text entry detection, use the keyboard icon at the right end of the taskbar to manually show and hide the keyboard. +Raspberry Pi OS **Bookworm** and later already includes the **Squeekboard on-screen keyboard**. With a Touch Display 2 attached, the keyboard automatically appears when you can enter text, and automatically disappears when you can't. -You can also permanently show or hide the on-screen keyboard in the Display tab of Raspberry Pi Configuration or the `Display` section of `raspi-config`. +For applications that don't support text entry detection, you can manually show or hide the keyboard using the keyboard icon at the right side of the taskbar. You can also permanently show or hide the on-screen keyboard using the Raspberry Pi graphical interface or the command line. -TIP: In Raspberry Pi OS releases prior to _Bookworm_, use `matchbox-keyboard` instead. If you use the wayfire desktop compositor, use `wvkbd` instead. +- **Raspberry Pi desktop interface:** From the Raspberry Pi menu, go to **Preferences > Control Centre > Display** and choose your on-screen keyboard setting. +- **Command line:** Open a terminal and enter `sudo raspi-config`. Navigate to the **Display** section of `raspi-config` and then choose your keyboard setting. -=== Change screen orientation +== Change screen orientation -If you want to physically rotate the display, or mount it in a specific position, select **Screen Configuration** from the **Preferences** menu. Right-click on the touch display rectangle (likely DSI-1) in the layout editor, select **Orientation**, then pick the best option to fit your needs. +You can change the orientation behaviour of the Touch Display 2, both with a desktop and without a desktop. This is useful if you want to physically rotate the screen or mount it in a landscape position. -==== Rotate screen without a desktop +You have four rotation options: -To set the screen orientation on a device that lacks a desktop environment, edit the `/boot/firmware/cmdline.txt` configuration file to pass an orientation to the system. Add the following entry to the end of `cmdline.txt`: +- **0** maintains the default display position, which is a portrait orientation. +- **90** rotates the display 90 degrees to the right (clockwise), making it a landscape orientation. +- **180** rotates the display 180 degrees to the right (clockwise), which flips the display upside down. +- **270** rotates the display 270 degrees to the right (clockwise), which is the same as rotating the display 90 degrees to the left (counterclockwise), making it a landscape orientation. + +=== With a desktop +If you have the Raspberry Pi OS desktop running, you can rotate the display through the **Screen Configuration** tool: + +. Go to **Preferences > Screen Configuration**. This opens the layout editor where you can see your connected displays. +. Right-click the rectangle in the layout editor that represents your Touch Display 2 (likely labelled `DSI-1`). +. Select **Orientation**. +. Choose a rotation: *0°*, *90°*, *180°*, or *270°*. This rotates the display by the specified number of degrees to the right. + +=== Without a desktop + +To rotate the display without a desktop, edit the `/boot/firmware/cmdline.txt` file, which contains parameters that Raspberry Pi OS reads when it boots. Add the following to the end of `cmdline.txt`, replacing `` with the number of degrees to rotate by (`0`, `90`, `180`, or `270`): [source,ini] ---- video=DSI-1:720x1280@60,rotate= ---- -Replace the `` placeholder with one of the following values, which correspond to the degree of rotation relative to the default on your display: +This `rotate=` setting only rotates the text-mode console; any applications that write directly to DRM (such as `cvlc` or the libcamera apps) won't be rotated, and will instead need to use their own rotation options (if available). + +NOTE: You can't rotate the DSI display separately from the HDMI display with `cmdline.txt`. When you use DSI and HDMI simultaneously, they share the same rotation value. + +== Customise touchscreen settings -* `0` -* `90` -* `180` -* `270` +You can use the Device Tree overlay to tell Raspberry Pi OS how to configure the Touch Display 2 at boot. -For example, a rotation value of `90` rotates the display 90 degrees to the right. `180` rotates the display 180 degrees, or upside-down. +- For the 5-inch display, the overlay is called `vc4-kms-dsi-ili9881-5inch`. +- For the 7-inch display, the overlay is called `vc4-kms-dsi-ili9881-7inch`. -NOTE: It is not possible to rotate the DSI display separately from the HDMI display with `cmdline.txt`. When you use DSI and HDMI simultaneously, they share the same rotation value. +You can modify the Device Tree overlay in the boot configuration file (`/boot/firmware/config.txt`). -==== Touch Display 2 device tree option reference +Open `/boot/firmware/config.txt` and then add the required Device Tree parameters to the `dtoverlay` line, separated by commas. -The `vc4-kms-dsi-ili9881-7inch` overlay supports the following options: +- Booleans (`invx`, `invy`, `swapxy`, and `disable_touch`) default to true if present, but you can set them to false using the suffix `=0`. +- Integers (`sizex` and `sizey`) require a number, for example, `sizey=240`. + +See the table below for details. + +=== Device Tree options |=== -| DT parameter | Action +| Parameter | Action | `sizex` -| Sets X resolution (default 720) +| Sets the touch horizontal resolution (default 720) | `sizey` -| Sets Y resolution (default 1280) +| Sets the touch vertical resolution (default 1280) | `invx` -| Invert X coordinates +| Inverts the touch X-axis (left/right) | `invy` -| Invert Y coordinates +| Inverts the touch Y-axis (up/down) | `swapxy` -| Swap X and Y coordinates +| Swaps the touch X and Y axes (rotate 90° logically) | `disable_touch` -| Disables the touch overlay totally +| Disables the touchscreen functionality |=== -To specify these options, add them, separated by commas, to your `dtoverlay` line in `/boot/firmware/config.txt`. Boolean values default to true when present, but you can set them to false using the suffix "=0". Integer values require a value, e.g. `sizey=240`. For instance, to set the X resolution to 400 pixels and invert both X and Y coordinates, use the following line: +=== Example + +In the following example, `invx` flips the X axis and `invy` flips the Y axis for a 7-inch Touch Display 2: [source,ini] ---- -dtoverlay=vc4-kms-dsi-ili9881-7inch,sizex=400,invx,invy +dtoverlay=vc4-kms-dsi-ili9881-7inch,invx,invy ---- + + +== Connect to a Compute Module + +Unlike Raspberry Pi single board computers (SBC), which automatically detect the official Raspberry Pi Touch displays, Raspberry Pi Compute Modules don't automatically detect connected devices; you must tell it what display is attached. + +This is because the connections between the SoC and DSI connectors on a Raspberry Pi are fixed and the system knows what hardware is connected; auto-detection ensures that the correct Device Tree settings are passed to the Linux kernel, so the display works without additional configuration. + +Compute Modules, intended for industrial and custom applications, expose all GPIOs and interfaces. This provides greater flexibility for connecting hardware, but means that a Compute Module can't automatically detect devices like the Touch Display 2. This means that, for Compute Modules, the Device Tree fragments, which tell the kernel how to interact with the display, must be manually specified. You can do this in three ways: + +- By adding an overlay entry in `config.txt`. This is the simplest option. For configuration instructions, see the xref:../computers/compute-module.adoc#attaching-the-touch-display-2-lcd-panel[Compute Module hardware documentation]. +- Using a custom base device tree file. This is an advanced method not covered in this online documentation. +- Using a HAT EEPROM (if present). + + diff --git a/documentation/asciidoc/accessories/tv-hat/about-tv-hat.adoc b/documentation/asciidoc/accessories/tv-hat/about-tv-hat.adoc index e1cb7efa6..8099b68c6 100644 --- a/documentation/asciidoc/accessories/tv-hat/about-tv-hat.adoc +++ b/documentation/asciidoc/accessories/tv-hat/about-tv-hat.adoc @@ -45,7 +45,7 @@ During the `tvheadend` installation, you will be asked to choose an administrato On another computer on your network, open up a web browser and type the following into the address bar: `http://raspberrypi.local:9981/extjs.html` -This should connect to `tvheadend` running on the Raspberry Pi. Once you have connected to `tvheadend` via the browser, you will be prompted to sign in using the account name and password you chose when you installed `tvheadend` on the Raspberry Pi. +This should connect to `tvheadend` running on the Raspberry Pi. Once you have connected to `tvheadend` via the browser, you will be prompted to sign in using the account name and password you chose when you installed `tvheadend` on the Raspberry Pi. A setup wizard should appear. @@ -63,7 +63,7 @@ Found muxes: 8 Found services: 172 ---- -In the next window, titled *Service mapping*, tick all three boxes: *Map all services*, *Create provider tags*, and *Create network tags*. You should see a list of TV channels you can watch, along with the programmes they're currently showing. +In the next window, titled *Service mapping*, tick all three boxes: *Map all services*, *Create provider tags*, and *Create network tags*. You should see a list of TV channels you can watch, along with the programmes they're currently showing. To watch a TV channel in the browser, click the little TV icon to the left of the channel listing, just to the right of the *i* icon. This brings up an in-browser media player. Depending on the decoding facilities built into your browser and the type of stream being played, you may find that playback can be jerky. In these cases, we recommend using a local media player as the playback application. diff --git a/documentation/asciidoc/computers/ai/getting-started.adoc b/documentation/asciidoc/computers/ai/getting-started.adoc index 59fda7c30..3a9b7263c 100644 --- a/documentation/asciidoc/computers/ai/getting-started.adoc +++ b/documentation/asciidoc/computers/ai/getting-started.adoc @@ -170,6 +170,19 @@ $ sudo apt-mark unhold hailo-tappas-core hailort hailo-dkms [tabs] ====== +v4.19:: +To install version 4.19 of Hailo's neural network tooling, run the following commands: ++ +[source,console] +---- +sudo apt install hailo-tappas-core=3.30.0-1 hailort=4.19.0-3 hailo-dkms=4.19.0-1 python3-hailort=4.19.0-2 +---- ++ +[source,console] +---- +$ sudo apt-mark hold hailo-tappas-core hailort hailo-dkms python3-hailort +---- + 4.18:: To install version 4.18 of Hailo's neural network tooling, run the following commands: + diff --git a/documentation/asciidoc/computers/camera/camera_usage.adoc b/documentation/asciidoc/computers/camera/camera_usage.adoc index 6c1382952..722f37c82 100644 --- a/documentation/asciidoc/computers/camera/camera_usage.adoc +++ b/documentation/asciidoc/computers/camera/camera_usage.adoc @@ -12,3 +12,8 @@ Raspberry Pi produces several official camera modules, including: For more information about camera hardware, see the xref:../accessories/camera.adoc#about-the-camera-modules[camera hardware documentation]. First, xref:../accessories/camera.adoc#install-a-raspberry-pi-camera[install your camera module]. Then, follow the guides in this section to put your camera module to use. + +[WARNING] +==== +This guide no longer covers the _legacy camera stack_ which was available in Bullseye and earlier Raspberry Pi OS releases. The legacy camera stack, using applications like `raspivid`, `raspistill` and the original `Picamera` (_not_ `Picamera2`) Python library, has been deprecated for many years, and is now unsupported. If you are using the legacy camera stack, it will only have support for the Camera Module 1, Camera Module 2 and the High Quality Camera, and will never support any newer camera modules. Nothing in this document is applicable to the legacy camera stack. +==== diff --git a/documentation/asciidoc/computers/camera/rpicam_apps_building.adoc b/documentation/asciidoc/computers/camera/rpicam_apps_building.adoc index 306e9cfb8..9fe1ea10a 100644 --- a/documentation/asciidoc/computers/camera/rpicam_apps_building.adoc +++ b/documentation/asciidoc/computers/camera/rpicam_apps_building.adoc @@ -27,7 +27,7 @@ To build `rpicam-apps` without first rebuilding `libcamera` and `libepoxy`, inst [source,console] ---- -$ sudo apt install -y libcamera-dev libepoxy-dev libjpeg-dev libtiff5-dev libpng-dev +$ sudo apt install -y libcamera-dev libepoxy-dev libjpeg-dev libtiff5-dev libpng-dev libopencv-dev ---- TIP: If you do not need support for the GLES/EGL preview window, omit `libepoxy-dev`. diff --git a/documentation/asciidoc/computers/camera/rpicam_apps_multicam.adoc b/documentation/asciidoc/computers/camera/rpicam_apps_multicam.adoc index 92c0891bf..fb387443a 100644 --- a/documentation/asciidoc/computers/camera/rpicam_apps_multicam.adoc +++ b/documentation/asciidoc/computers/camera/rpicam_apps_multicam.adoc @@ -8,4 +8,61 @@ To list all the cameras available on your platform, use the xref:camera_software.adoc#list-cameras[`list-cameras`] option. To choose which camera to use, pass the camera index to the xref:camera_software.adoc#camera[`camera`] option. -NOTE: `libcamera` does not yet provide stereoscopic camera support. When running two cameras simultaneously, they must be run in separate processes. This means there is no way to synchronise sensor framing or 3A operation between them. As a workaround, you could synchronise the cameras through an external sync signal for the HQ (IMX477) camera, and switch the 3A to manual mode if necessary. +NOTE: `libcamera` does not yet provide stereoscopic camera support. When running two cameras simultaneously, they must be run in separate processes, meaning there is no way to synchronise 3A operation between them. As a workaround, you could synchronise the cameras through an external sync signal for the HQ (IMX477) camera or use the software camera synchronisation support that is described below, switching the 3A to manual mode if necessary. + +==== Software Camera Synchronisation + +Raspberry Pi's _libcamera_ implementation has the ability to synchronise the frames of different cameras using only software. This will cause one camera to adjust it's frame timing so as to coincide as closely as possible with the frames of another camera. No soldering or hardware connections are required, and it will work with all of Raspberry Pi's camera modules, and even third party ones so long as their drivers implement frame duration control correctly. + +**How it works** + +The scheme works by designating one camera to be the _server_. The server will broadcast timing messages onto the network at regular intervals, such as once a second. Meanwhile other cameras, known as _clients_, can listen to these messages whereupon they may lengthen or shorten frame times slightly so as to pull them into sync with the server. This process is continual, though after the first adjustment, subsequent adjustments are normally small. + +The client cameras may be attached to the same Raspberry Pi device as the server, or they may be attached to different Raspberry Pis on the same network. The camera model on the clients may match the server, or they may be different. + +Clients and servers need to be set running at the same nominal framerate (such as 30fps). Note that there is no back-channel from the clients back to the server. It is solely the clients' responsibility to be up and running in time to match the server, and the server is completely unaware whether clients have synchronised successfully, or indeed whether there are any clients at all. + +In normal operation, running the same make of camera on the same Raspberry Pi, we would expect the frame start times of the camera images to match within "several tens of microseconds". When the camera models are different this could be significantly larger as the cameras will probably not be able to match framerates exactly and will therefore be continually drifting apart (and brought back together with every timing message). + +When cameras are on different devices, the system clocks should be synchronised using NTP (normally the case by default for Raspberry Pi OS), or if this is insufficiently precise, another protocol like PTP might be used. Any discrepancy between system clocks will feed directly into extra error in frame start times - even though the advertised timestamps on the frames will not tell you. + +**The Server** + +The server, as previously explained, broadcasts timing messages onto the network, by default every second. The server will run for a fixed number of frames, by default 100, after which it will inform the camera application on the device that the "synchronisation point" has been reached. At this moment, the application will start using the frames, so in the case of `rpicam-vid`, they will start being encoded and recorded. Recall that the behaviour and even existence of clients has no bearing on this. + +If required, there can be several servers on the same network so long as they are broadcasting timing messages to different network addresses. Clients, of course, will have to be configured to listen for the correct address. + +**Clients** + +Clients listen out for server timing messages and, when they receive one, will shorten or lengthen a camera frame duration by the required amount so that subsequent frames will start, as far as possible, at the same moment as the server's. + +The clients learn the correct "synchronisation point" from the server's messages, and just like the server, will signal the camera application at the same moment that it should start using the frames. So in the case of `rpicam-vid`, this is once again the moment at which frames will start being recorded. + +Normally it makes sense to start clients _before_ the server, as the clients will simply wait (the "synchronisation point" has not been reached) until a server is seen broadcasting onto the network. This obviously avoids timing problems where a server might reach its "synchronisation point" even before all the clients have been started! + +**Usage in `rpicam-vid`** + +We can use software camera synchronisation with `rpicam-vid` to record videos that are synchronised frame-by-frame. We're going to assume we have two cameras attached, and we're going to use camera 0 as the server, and camera 1 as the client. `rpicam-vid` defaults to a fixed 30 frames per second, which will be fine for us. + +First we should start the client: +[source,console] +---- +$ rpicam-vid -n -t 20s --camera 1 --codec libav -o client.mp4 --sync client +---- + +Note the `--sync client` parameter. This will record for 20 seconds but _only_ once the synchronisation point has been reached. If necessary, it will wait indefinitely for the first server message. + +To start the server: +[source,console] +---- +$ rpicam-vid -n -t 20s --camera 0 --codec libav -o server.mp4 --sync server +---- + +This too will run for 20 seconds counting from when the synchronisation point is reached and the recording starts. With the default synchronisation settings (100 frames at 30fps) this means there will be just over 3 seconds for clients to get synchronised. + +The server's broadcast address and port, the frequency of the timing messages and the number of frames to wait for clients to synchronise, can all be changed in the camera tuning file. Clients only pay attention to the broadcast address here which should match the server's; the other information will be ignored. Please refer to the https://datasheets.raspberrypi.com/camera/raspberry-pi-camera-guide.pdf[Raspberry Pi Camera tuning guide] for more information. + +In practical operation there are a few final points to be aware of: + +* The fixed framerate needs to be below the maximum framerate at which the camera can operate (in the camera mode that is being used). This is because the synchronisation algorithm may need to _shorten_ camera frames so that clients can catch up with the server, and this will fail if it is already running as fast as it can. +* Whilst camera frames should be correctly synchronised, at higher framerates or depending on system load, it is possible for frames, either on the clients or server, to be dropped. In these cases the frame timestamps will help an application to work out what has happened, though it's usually simpler to try and avoid frame drops - perhaps by lowering the framerate, increasing the number of buffers being allocated to the camera queues (see the xref:camera_software.adoc#buffer-count[`--buffer-count` option]), or reducing system load. \ No newline at end of file diff --git a/documentation/asciidoc/computers/camera/rpicam_apps_post_processing_tflite.adoc b/documentation/asciidoc/computers/camera/rpicam_apps_post_processing_tflite.adoc index 39d607f5e..2be746dcc 100644 --- a/documentation/asciidoc/computers/camera/rpicam_apps_post_processing_tflite.adoc +++ b/documentation/asciidoc/computers/camera/rpicam_apps_post_processing_tflite.adoc @@ -2,7 +2,12 @@ ==== Prerequisites -These stages require TensorFlow Lite (TFLite) libraries that export the {cpp} API. TFLite doesn't distribute libraries in this form, but you can download and install a version that exports the API from https://lindevs.com/install-precompiled-tensorflow-lite-on-raspberry-pi/[lindevs.com]. +These stages require TensorFlow Lite (TFLite) libraries that export the {cpp} API. From Trixie onwards, Raspberry Pi builds and distributes a TFLite package, which can be installed with the following command: + +[source,console] +---- +$ sudo apt install libtensorflow-lite-dev +---- After installing, you must xref:camera_software.adoc#build-libcamera-and-rpicam-apps[recompile `rpicam-apps` with TensorFlow Lite support]. diff --git a/documentation/asciidoc/computers/camera/rpicam_configuration.adoc b/documentation/asciidoc/computers/camera/rpicam_configuration.adoc index cd6d0f183..c36db3f69 100644 --- a/documentation/asciidoc/computers/camera/rpicam_configuration.adoc +++ b/documentation/asciidoc/computers/camera/rpicam_configuration.adoc @@ -38,6 +38,8 @@ Raspberry Pi OS recognises the following overlays in `/boot/firmware/config.txt` To use one of these overlays, you must disable automatic camera detection. To disable automatic detection, set `camera_auto_detect=0` in `/boot/firmware/config.txt`. If `config.txt` already contains a line assigning an `camera_auto_detect` value, change the value to `0`. Reboot your Raspberry Pi with `sudo reboot` to load your changes. +If your Raspberry Pi has two camera connectors (Raspberry Pi 5 or one of the Compute Modules, for example), then you can specify the use of camera connector 0 by adding `,cam0` to the `dtoverlay` that you used from the table above. If you do not add this, it will default to checking camera connector 1. Note that for official Raspberry Pi camera modules connected to SBCs (not Compute Modules), auto-detection will correctly identify all the cameras connected to your device. + [[tuning-files]] ==== Tweak camera behaviour with tuning files diff --git a/documentation/asciidoc/computers/camera/rpicam_options_common.adoc b/documentation/asciidoc/computers/camera/rpicam_options_common.adoc index 21f0974e1..90e535ff8 100644 --- a/documentation/asciidoc/computers/camera/rpicam_options_common.adoc +++ b/documentation/asciidoc/computers/camera/rpicam_options_common.adoc @@ -89,9 +89,19 @@ Alias: `-t` Default value: 5000 milliseconds (5 seconds) -Specify how long the application runs before closing. This applies to both video recording and preview windows. When capturing a still image, the application shows a preview window for `timeout` milliseconds before capturing the output image. +Specify how long the application runs before closing. This value is interpreted as a number of milliseconds unless an optional suffix is used to change the unit. The suffix may be one of: -To run the application indefinitely, specify a value of `0`. +* `min` - minutes +* `s` or `sec` - seconds +* `ms` - milliseconds (the default if no suffix used) +* `us` - microseconds +* `ns` - nanoseconds. + +This time applies to both video recording and preview windows. When capturing a still image, the application shows a preview window for the length of time specified by the `timeout` parameter before capturing the output image. + +To run the application indefinitely, specify a value of `0`. Floating point values are also permitted. + +Example: `rpicam-hello -t 0.5min` would run for 30 seconds. ==== `preview` @@ -553,3 +563,32 @@ Flushes output files to disk as soon as a frame finishes writing, instead of wai Specifies a JSON file that configures the post-processing applied by the imaging pipeline. This applies to camera images _before_ they reach the application. This works similarly to the legacy `raspicam` "image effects". Accepts a file name path as input. Post-processing is a large topic and admits the use of third-party software like OpenCV and TensorFlowLite to analyse and manipulate images. For more information, see xref:camera_software.adoc#post-processing-with-rpicam-apps[post-processing]. + +==== `buffer-count` + +The number of buffers to allocate for still image capture or for video recording. The default value of zero lets each application choose a reasonable number for its own use case (1 for still image capture, and 6 for video recording). Increasing the number can sometimes help to reduce the number of frame drops, particularly at higher framerates. + +==== `viewfinder-buffer-count` + +As the `buffer-count` option, but applies when running in preview mode (that is `rpicam-hello` or the preview, not capture, phase of `rpicam-still`). + +==== `metadata` + +Save captured image metadata to a file or `-` for stdout. The fields in the metadata output will depend on the camera model in use. + +See also `metadata-format`. + +==== `metadata-format` + +Format to save the metadata in. Accepts the following values: + +* `txt` for text format +* `json` for JSON format + +In text format, each line will have the form + + key=value + +In JSON format, the output is a JSON object. + +This option does nothing unless `--metadata` is also specified. diff --git a/documentation/asciidoc/computers/camera/rpicam_options_vid.adoc b/documentation/asciidoc/computers/camera/rpicam_options_vid.adoc index 7a5bb71e9..00ac1a258 100644 --- a/documentation/asciidoc/computers/camera/rpicam_options_vid.adoc +++ b/documentation/asciidoc/computers/camera/rpicam_options_vid.adoc @@ -132,3 +132,10 @@ Records exactly the specified number of frames. Any non-zero value overrides xre Records exactly the specified framerate. Accepts a nonzero integer. +==== `low-latency` + +On a Pi 5, the `--low-latency` option will reduce the encoding latency, which may be beneficial for real-time streaming applications, in return for (slightly) less good coding efficiency (for example, B frames and arithmetic coding will no longer be used). + +==== `sync` + +Run the camera in software synchronisation mode, where multiple cameras synchronise frames to the same moment in time. The `sync` mode can be set to either `client` or `server`. For more information, please refer to the detailed explanation of xref:camera_software.adoc#software-camera-synchronisation[how software synchronisation works]. \ No newline at end of file diff --git a/documentation/asciidoc/computers/camera/rpicam_vid.adoc b/documentation/asciidoc/computers/camera/rpicam_vid.adoc index f4ee22060..e88c5b762 100644 --- a/documentation/asciidoc/computers/camera/rpicam_vid.adoc +++ b/documentation/asciidoc/computers/camera/rpicam_vid.adoc @@ -11,13 +11,18 @@ For example, the following command writes a ten-second video to a file named `te $ rpicam-vid -t 10s -o test.h264 ---- -You can play the resulting file with VLC and other video players: +You can play the resulting file with ffplay and other video players: [source,console] ---- -$ vlc test.h264 +$ ffplay test.h264 ---- +[WARNING] +==== +Older versions of vlc were able to play H.264 files correctly, but recent versions do not - displaying only a few, or possibly garbled, frames. You should either use a different media player, or save your files in a more widely supported container format - such as MP4 (see below). +==== + On Raspberry Pi 5, you can output to the MP4 container format directly by specifying the `mp4` file extension for your output file: [source,console] @@ -25,6 +30,13 @@ On Raspberry Pi 5, you can output to the MP4 container format directly by specif $ rpicam-vid -t 10s -o test.mp4 ---- +On Raspberry Pi 4, or earlier devices, you can save MP4 files using: + +[source,console] +---- +$ rpicam-vid -t 10s --codec libav -o test.mp4 +---- + ==== Encoders `rpicam-vid` supports motion JPEG as well as both uncompressed and unformatted YUV420: @@ -76,3 +88,11 @@ To enable the `libav` backend, pass `libav` to the xref:camera_software.adoc#cod ---- $ rpicam-vid --codec libav --libav-format avi --libav-audio --output example.avi ---- + +==== Low latency video with the Pi 5 + +Pi 5 uses software video encoders. These generally output frames with a longer latency than the old hardware encoders, and this can sometimes be an issue for real-time streaming applications. + +In this case, please add the option `--low-latency` to the `rpicam-vid` command. This will alter certain encoder options to output the encoded frame more quickly. + +The downside is that coding efficiency is (slightly) less good, and that the processor's multiple cores may be used (slightly) less efficiently. The maximum framerate that can be encoded may be slightly reduced (though it will still easily achieve 1080p30). diff --git a/documentation/asciidoc/computers/camera/streaming.adoc b/documentation/asciidoc/computers/camera/streaming.adoc index 0d7e378a3..ffcf9a656 100644 --- a/documentation/asciidoc/computers/camera/streaming.adoc +++ b/documentation/asciidoc/computers/camera/streaming.adoc @@ -1,6 +1,6 @@ == Stream video over a network with `rpicam-apps` -This section describes native streaming from `rpicam-vid`. You can also use the xref:camera_software.adoc#libav-integration-with-rpicam-vid[`libav`] backend for network streaming. +This section describes how to stream video over a network using `rpicam-vid`. Whilst it's possible to stream very simple formats without using `libav`, for most applications we recommend using the xref:camera_software.adoc#libav-integration-with-rpicam-vid[`libav` backend]. === UDP @@ -8,67 +8,75 @@ To stream video over UDP using a Raspberry Pi as a server, use the following com [source,console] ---- -$ rpicam-vid -t 0 --inline -o udp://: +$ rpicam-vid -t 0 -n --inline -o udp://: ---- To view video streamed over UDP using a Raspberry Pi as a client, use the following command, replacing the `` placeholder with the port you would like to stream from: [source,console] ---- -$ vlc udp://@: :demux=h264 +$ ffplay udp://@: -fflags nobuffer -flags low_delay -framedrop ---- +As noted previously, `vlc` no longer handles unencapsulated H.264 streams. -Alternatively, use the following command on a client to stream using `ffplay`: +In fact, support for unencapsulated H.264 can generally be quite poor so it is often better to send an MPEG-2 Transport Stream instead. Making use of `libav`, this can be accomplished with: [source,console] ---- -$ ffplay udp://: -fflags nobuffer -flags low_delay -framedrop +$ rpicam-vid -t 0 -n --codec libav --libav-format mpegts -o udp://: ---- -=== TCP - -You can also stream video over TCP. To use a Raspberry Pi as a server: +In this case, we can also play the stream successfully with `vlc`: [source,console] ---- -$ rpicam-vid -t 0 --inline --listen -o tcp://0.0.0.0: +$ vlc udp://@: ---- -To view video streamed over TCP using a Raspberry Pi as a client, use the following command: +=== TCP + +You can also stream video over TCP. As before, we can send an unencapsulated H.264 stream over the network. To use a Raspberry Pi as a server: [source,console] ---- -$ vlc tcp/h264://: +$ rpicam-vid -t 0 -n --inline --listen -o tcp://0.0.0.0: ---- -Alternatively, use the following command on a client to stream using `ffplay` at 30 frames per second: +To view video streamed over TCP using a Raspberry Pi as a client, assuming the server is running at 30 frames per second, use the following command: [source,console] ---- $ ffplay tcp://: -vf "setpts=N/30" -fflags nobuffer -flags low_delay -framedrop ---- -=== RTSP +But as with the UDP examples, it is often preferable to send an MPEG-2 Transport Stream as this is generally better supported. To do this, use: -To use VLC to stream video over RTSP using a Raspberry Pi as a server, use the following command: +[source,console] +---- +$ rpicam-vid -t 0 -n --codec libav --libav-format mpegts -o tcp://0.0.0.0:?listen=1 +---- + +We can now play this back using a variety of media players, including `vlc`: [source,console] ---- -$ rpicam-vid -t 0 --inline -o - | cvlc stream:///dev/stdin --sout '#rtp{sdp=rtsp://:8554/stream1}' :demux=h264 +$ vlc tcp://: ---- -For the best performance on Raspberry Pi 5, use the following command instead, which adds libav to force the H264 format: +=== RTSP + +We can use VLC as an RTSP server, however, we must send it an MPEG-2 Transport Stream as it no longer understands unencapsulated H.264: [source,console] ---- -$ rpicam-vid -t 0 --inline --libav-format h264 -o - | cvlc stream:///dev/stdin --sout '#rtp{sdp=rtsp://:8554/stream1}' :demux=h264 +$ rpicam-vid -t 0 -n --codec libav --libav-format mpegts -o - | cvlc stream:///dev/stdin --sout '#rtp{sdp=rtsp://:8554/stream1}' ---- To view video streamed over RTSP using a Raspberry Pi as a client, use the following command: [source,console] ---- -$ ffplay rtsp://:8554/stream1 -vf "setpts=N/30" -fflags nobuffer -flags low_delay -framedrop +$ ffplay rtsp://:8554/stream1 -fflags nobuffer -flags low_delay -framedrop ---- Alternatively, use the following command on a client to stream using VLC: @@ -78,14 +86,13 @@ Alternatively, use the following command on a client to stream using VLC: $ vlc rtsp://:8554/stream1 ---- -To suppress the preview window on the server, use xref:camera_software.adoc#nopreview[`nopreview`]. +If you want to see a preview window on the server, just drop the `-n` option (see xref:camera_software.adoc#nopreview[`nopreview`]). -Use the xref:camera_software.adoc#inline[`inline`] flag to force stream header information into every intra frame, which helps clients understand the stream if they miss the beginning. +=== `libav` and Audio -=== `libav` +We have already been using `libav` as the backend for network streaming. `libav` allows us to add an audio stream, so long as we're using a format - like the MPEG-2 Transport Stream - that permits audio data. -You can use the `libav` backend as a network streaming source for audio/video. -To stream video over TCP using a Raspberry Pi as a server, use the following command, replacing the `` placeholder with the IP address of the client or multicast address and replacing the `` placeholder with the port you would like to use for streaming: +We can take one of our previous commands, like the one for streaming an MPEG-2 Transport Stream over TCP, and simply add the `--libav-audio` option: [source,console] ---- @@ -101,56 +108,99 @@ $ rpicam-vid -t 0 --codec libav --libav-format mpegts --libav-audio -o "udp://< === GStreamer -https://gstreamer.freedesktop.org/[GStreamer] is a Linux framework for reading, processing and playing multimedia files. This section shows how to use `rpicam-vid` to stream video over a network. +https://gstreamer.freedesktop.org/[GStreamer] is a Linux framework for reading, processing and playing multimedia files. We can also use it in conjunction with `rpicam-vid` for network streaming. + +This setup uses `rpicam-vid` to output an H.264 bitstream to stdout, though as we've done previously, we're going to encapsulate it in an MPEG-2 Transport Stream for better downstream compatibility. -This setup uses `rpicam-vid` to output an encoded h.264 bitstream to stdout. Then, we use the GStreamer `fdsrc` element to receive the bitstream, and extra GStreamer elements to send it over the network. On the server, run the following command to start the stream, replacing the `` placeholder with the IP address of the client or multicast address and replacing the `` placeholder with the port you would like to use for streaming: +Then, we use the GStreamer `fdsrc` element to receive the bitstream, and extra GStreamer elements to send it over the network. On the server, run the following command to start the stream, replacing the `` placeholder with the IP address of the client or multicast address and replacing the `` placeholder with the port you would like to use for streaming: [source,console] ---- -$ rpicam-vid -t 0 -n --inline -o - | gst-launch-1.0 fdsrc fd=0 ! udpsink host= port= +$ rpicam-vid -t 0 -n --codec libav --libav-format mpegts -o - | gst-launch-1.0 fdsrc fd=0 ! udpsink host= port= ---- -On the client, run the following command to receive the stream, replacing the `` placeholder with the IP address of the client or multicast address and replacing the `` placeholder with the port you would like to use for streaming: +We could of course use anything (such as vlc) as the client, and the best GStreamer clients for playback are beyond the scope of this document. However, we note that the following pipeline (with the obvious substitutions) would work on a Pi 4 or earlier device: [source,console] ---- -$ gst-launch-1.0 udpsrc address= port= ! h264parse ! v4l2h264dec ! autovideosink +$ gst-launch-1.0 udpsrc address= port= ! tsparse ! tsdemux ! h264parse ! queue ! v4l2h264dec ! autovideosink ---- +For a Pi 5, replace `v4l2h264dec` by `avdec_h264`. + TIP: To test this configuration, run the server and client commands in separate terminals on the same device, using `localhost` as the address. -==== RTP +==== `libcamerasrc` GStreamer element -To stream using RTP, run the following command on the server, replacing the `` placeholder with the IP address of the client or multicast address and replacing the `` placeholder with the port you would like to use for streaming: +`libcamera` provides a `libcamerasrc` GStreamer element which can be used directly instead of `rpicam-vid`. To use this element, run the following command on the server, replacing the `` placeholder with the IP address of the client or multicast address and replacing the `` placeholder with the port you would like to use for streaming. On a Pi 4 or earlier device, use: [source,console] ---- -$ rpicam-vid -t 0 -n --inline -o - | gst-launch-1.0 fdsrc fd=0 ! h264parse ! rtph264pay ! udpsink host= port= +$ gst-launch-1.0 libcamerasrc ! capsfilter caps=video/x-raw,width=640,height=360,format=NV12,interlace-mode=progressive ! v4l2h264enc extra-controls="controls,repeat_sequence_header=1" ! 'video/x-h264,level=(string)4' ! h264parse ! mpegtsmux ! udpsink host= port= ---- +On a Pi 5 you would have to replace `v4l2h264enc extra-controls="controls,repeat_sequence_header=1"` by `x264enc speed-preset=1 threads=1`. -To receive over RTP, run the following command on the client, replacing the `` placeholder with the IP address of the client or multicast address and replacing the `` placeholder with the port you would like to use for streaming: +On the client we could use the same playback pipeline as we did just above, or other streaming media players. -[source,console] +=== WebRTC + +Streaming over WebRTC (for example, to web browsers) is best accomplished using third party software. https://github.com/bluenviron/mediamtx[MediaMTX], for example, includes native Raspberry Pi camera support which makes it easy to use. + +To install it, download the latest version from the https://github.com/bluenviron/mediamtx/releases[releases] page. Raspberry Pi OS 64-bit users will want the "linux_arm64v8" compressed tar file (ending `.tar.gz`). Unpack it and you will get a `mediamtx` executable and a configuration file called `mediamtx.yml`. + +It's worth backing up the `mediamtx.yml` file because it documents many Raspberry Pi camera options that you may want to investigate later. + +To stream the camera, replace the contents of `mediamtx.yml` by: +---- +paths: + cam: + source: rpiCamera +---- +and start the `mediamtx` executable. On a browser, enter `http://:8889/cam` into the address bar. + +If you want MediaMTX to acquire the camera only when the stream is requested, add the following line to the previous `mediamtx.yml`: ---- -$ gst-launch-1.0 udpsrc address= port= caps=application/x-rtp ! rtph264depay ! h264parse ! v4l2h264dec ! autovideosink + sourceOnDemand: yes ---- +Consult the original `mediamtx.yml` for additional configuration parameters that let you select the image size, the camera mode, the bitrate and so on - just search for `rpi`. +==== Customised image streams with WebRTC -If the client is not a Raspberry Pi it may have different GStreamer elements available. On an x86 device running Linux, you might run the following command instead: +MediaMTX is great if you want to stream just the camera images. But what if we want to add some extra information or overlay, or do some extra processing on the images? + +Before starting, ensure that you've built a version of `rpicam-apps` that includes OpenCV support. Check it by running [source,console] ---- -$ gst-launch-1.0 udpsrc address= port= caps=application/x-rtp ! rtph264depay ! h264parse ! avdec_h264 ! autovideosink +$ rpicam-hello --post-process-file rpicam-apps/assets/annotate_cv.json ---- +and looking for the overlaid text information at the top of the image. -==== `libcamerasrc` GStreamer element +Next, paste the following into your `mediamtx.yml` file: +---- +paths: + cam: + source: udp://127.0.0.1:1234 +---- -`libcamera` provides a `libcamerasrc` GStreamer element which can be used directly instead of `rpicam-vid`. To use this element, run the following command on the server, replacing the `` placeholder with the IP address of the client or multicast address and replacing the `` placeholder with the port you would like to use for streaming: +Now, start `mediamtx` and then, if you're using a Pi 5, in a new terminal window, enter: [source,console] ---- -$ gst-launch-1.0 libcamerasrc ! capsfilter caps=video/x-raw,width=1280,height=720,format=NV12 ! v4l2convert ! v4l2h264enc extra-controls="controls,repeat_sequence_header=1" ! 'video/x-h264,level=(string)4.1' ! h264parse ! rtph264pay ! udpsink host= port= +$ rpicam-vid -t 0 -n --codec libav --libav-video-codec-opts "profile=baseline" --libav-format mpegts -o udp://127.0.0.1:1234?pkt_size=1316 --post-process-file rpicam-apps/assets/annotate_cv.json ---- +(On a Pi 4 or earlier device, leave out the `--libav-video-codec-opts "profile=baseline"` part of the command.) -and on the client we use the same playback pipeline as previously. +On another computer, you can now visit the same address as before, namely `http://:8889/cam`. +The reason for specifying "baseline" profile on a Pi 5 is that MediaMTX doesn't support B frames, so we need to stop the encoder from producing them. On earlier devices, with hardware encoders, B frames are never generated so there is no issue. On a Pi 5 you could alternatively remove this option and replace it with `--low-latency` which will also prevent B frames, and produce a (slightly less well compressed) stream with reduced latency. + +[NOTE] +==== +If you notice occasional pauses in the video stream, this may be because the UDP receive buffers on the Pi (passing data from `rpicam-vid` to MediaMTX) are too small. To increase them permantently, add +---- +net.core.rmem_default=1000000 +net.core.rmem_max=1000000 +---- +to your `/etc/sysctl.conf` file (and reboot or run `sudo sysctl -p`). +==== \ No newline at end of file diff --git a/documentation/asciidoc/computers/compute-module/cm-peri-sw-guide.adoc b/documentation/asciidoc/computers/compute-module/cm-peri-sw-guide.adoc index 04845e07f..cb1beac88 100644 --- a/documentation/asciidoc/computers/compute-module/cm-peri-sw-guide.adoc +++ b/documentation/asciidoc/computers/compute-module/cm-peri-sw-guide.adoc @@ -219,14 +219,7 @@ dtoverlay=enc28j60 Reboot with `sudo reboot`. -You should now see an `rtc0` entry in `/dev`. Run the following command to view the hardware clock time: - -[source,console] ----- -$ sudo hwclock ----- - -You should also have Ethernet connectivity. Run the following command to test your connectivity: +If you now run `ifconfig` you should see an aditional `eth` entry for the ENC28J60 NIC. You should also have Ethernet connectivity. Run the following command to test your connectivity: [source,console] ---- diff --git a/documentation/asciidoc/computers/compute-module/cmio-camera.adoc b/documentation/asciidoc/computers/compute-module/cmio-camera.adoc index e1ccbefc2..f65fb187f 100644 --- a/documentation/asciidoc/computers/compute-module/cmio-camera.adoc +++ b/documentation/asciidoc/computers/compute-module/cmio-camera.adoc @@ -21,6 +21,11 @@ To connect a single camera to a Compute Module, complete the following steps: + image::images/CMIO-Cam-Adapter.jpg[alt="Connecting the adapter board", width="60%"] +. _(CM5 only)_: Fit two jumpers on J6 per the board's written instructions. ++ +image::images/cm5io-j6-cam1.png[alt="Jumpers on J6 for CAM1", width="60%"] + + . _(CM1, CM3, CM3+, and CM4S only)_: Connect the following GPIO pins with jumper cables: * `0` to `CD1_SDA` * `1` to `CD1_SCL` @@ -65,19 +70,19 @@ dtparam=cam1_reg | directive | v1 camera -| `dtoverlay=ov5647,cam1` +| `dtoverlay=ov5647` | v2 camera -| `dtoverlay=imx219,cam1` +| `dtoverlay=imx219` | v3 camera -| `dtoverlay=imx708,cam1` +| `dtoverlay=imx708` | HQ camera -| `dtoverlay=imx477,cam1` +| `dtoverlay=imx477` | GS camera -| `dtoverlay=imx296,cam1` +| `dtoverlay=imx296` |=== . Reboot your Compute Module with `sudo reboot`. @@ -107,7 +112,7 @@ image::images/CMIO-Cam-Adapter.jpg[alt="Connect the adapter board", width="60%"] + image:images/CMIO-Cam-GPIO2.jpg[alt="GPIO connection with additional camera", width="60%"] -. _(CM4 and CM5)_: Connect the J6 GPIO pins with two vertical-orientation jumpers. +. _(CM4)_: Connect the J6 GPIO pins with two vertical-orientation jumpers. + image:images/j6_vertical.jpg[alt="Connect the J6 GPIO pins in vertical orientation", width="60%"] diff --git a/documentation/asciidoc/computers/compute-module/cmio-display.adoc b/documentation/asciidoc/computers/compute-module/cmio-display.adoc index c883a8648..c8f9b4c63 100644 --- a/documentation/asciidoc/computers/compute-module/cmio-display.adoc +++ b/documentation/asciidoc/computers/compute-module/cmio-display.adoc @@ -1,50 +1,41 @@ -== Attach the official 7-inch display +== Attaching the Touch Display LCD panel -Update your system software and firmware to the latest version before starting. -Compute Modules mostly use the same process, but sometimes physical differences force changes for a particular model. +Update your system software and firmware to the latest version before starting. Compute Modules mostly use the same process, but sometimes physical differences force changes for a particular model. -=== Connect a display to DISP1 +=== Connect a display to DISP1/DSI1 -NOTE: The Raspberry Pi Zero camera cable cannot be used as an alternative to the RPI-DISPLAY adapter. The two cables have distinct wiring. +NOTE: The Raspberry Pi Zero camera cable can't be used as an alternative to the RPI-DISPLAY adapter. The two cables have distinct wiring. -To connect a display to DISP1: +To connect a display to `DISP1/DSI1`: . Disconnect the Compute Module from power. -. Connect the display to the DISP1 port on the Compute Module IO board through the 22W to 15W display adapter. -. _(CM1, CM3, CM3+, and CM4S only)_: Connect the following GPIO pins with jumper cables: - * `0` to `CD1_SDA` - * `1` to `CD1_SCL` - +. Connect the display to the `DISP1/DSI1` port on the Compute Module IO board through the 22W to 15W display adapter. +. Complete the appropriate jumper connections: + - For *CM1*, *CM3*, *CM3+*, and *CM4S*, connect the following GPIO pins with jumper cables: + * `0` to `CD1_SDA` + * `1` to `CD1_SCL` + - For *CM5*, on the Compute Module 5 IO board, add the appropriate jumpers to J6, as indicated on the silkscreen. . Reconnect the Compute Module to power. -. Add the following line to xref:../computers/config_txt.adoc#what-is-config-txt[`/boot/firmware/config.txt`]: -+ -[source,ini] ----- -dtoverlay=vc4-kms-dsi-7inch ----- +. Add `dtoverlay=vc4-kms-dsi-7inch` to xref:../computers/config_txt.adoc#what-is-config-txt[`/boot/firmware/config.txt`]. . Reboot your Compute Module with `sudo reboot`. Your device should detect and begin displaying output to your display. -=== Connect a display to DISP0 +=== Connect a display to DISP0/DSI0 -To connect a display to DISP0: - -. Connect the display to the DISP0 port on the Compute Module IO board through the 22W to 15W display adapter. -. _(CM1, CM3, CM3+, and CM4S only)_: Connect the following GPIO pins with jumper cables: - * `28` to `CD0_SDA` - * `29` to `CD0_SCL` +To connect a display to `DISP0/DSI0` on CM1, CM3, and CM4 IO boards: +. Connect the display to the `DISP0/DSI0` port on the Compute Module IO board through the 22W to 15W display adapter. +. Complete the appropriate jumper connections: + - For *CM1*, *CM3*, *CM3+*, and *CM4S*, connect the following GPIO pins with jumper cables: + * `28` to `CD0_SDA` + * `29` to `CD0_SCL` + - For *CM4*, on the Compute Module 4 IO board, add the appropriate jumpers to J6, as indicated on the silkscreen. . Reconnect the Compute Module to power. -. Add the following line to `/boot/firmware/config.txt`: -+ -[source,ini] ----- -dtoverlay=vc4-kms-dsi-7inch ----- +. Add `dtoverlay=vc4-kms-dsi-7inch,dsi0` to `/boot/firmware/config.txt`. . Reboot your Compute Module with `sudo reboot`. Your device should detect and begin displaying output to your display. === Disable touchscreen -The touchscreen requires no additional configuration. Connect it to your Compute Module, and both the touchscreen element and display should work once successfully detected. +The touchscreen requires no additional configuration. Connect it to your Compute Module; both the touchscreen element and display work when successfully detected. To disable the touchscreen element, but still use the display, add the following line to `/boot/firmware/config.txt`: @@ -61,3 +52,20 @@ To entirely ignore the display when connected, add the following line to `/boot/ ---- ignore_lcd=1 ---- + +== Attaching the Touch Display 2 LCD panel + +Touch Display 2 is an LCD display designed for Raspberry Pi devices (see https://www.raspberrypi.com/products/touch-display-2/). It's available in two sizes: 5 inches or 7 inches (diagonally). For more information about these options, see *Specifications* in xref:../accessories/touch-display-2.adoc[Touch Display 2]. + +Regardless of the size that you use, Touch Display 2 connects in the same way as the original Touch Display, but the software setup on Compute Modules is slightly different because it uses a different display driver. For connection details, see *Connectors* in xref:../accessories/touch-display-2.adoc[Touch Display 2]. + +To enable Touch Display 2 on `DISP1/DSI1`, edit the `/boot/firmware/config.txt` file to add the following. You must also add jumpers to J6 as indicated on the silkscreen. + +- For the *5-inch* display: `dtoverlay=vc4-kms-dsi-ili9881-5inch` +- For the *7-inch* display: `dtoverlay=vc4-kms-dsi-ili9881-7inch` + +To use `DISP0/DSI0`, append `,dsi0` to the overlay name. + +- For the *5-inch* display: `dtoverlay=vc4-kms-dsi-ili9881-5inch,dsi0` +- For the *7-inch* display: `dtoverlay=vc4-kms-dsi-ili9881-7inch,dsi0` + diff --git a/documentation/asciidoc/computers/compute-module/datasheet.adoc b/documentation/asciidoc/computers/compute-module/datasheet.adoc index 11d52ccb8..3f7ffbd75 100644 --- a/documentation/asciidoc/computers/compute-module/datasheet.adoc +++ b/documentation/asciidoc/computers/compute-module/datasheet.adoc @@ -20,7 +20,7 @@ To learn more about Compute Module 4 (CM4) and its corresponding IO Board, see t * https://datasheets.raspberrypi.com/cm4/cm4-datasheet.pdf[CM4 datasheet] -[.whitepaper, title="Configure the Compute Module 4", subtitle="", link=https://pip.raspberrypi.com/categories/685-whitepapers-app-notes/documents/RP-003470-WP/Configuring-the-Compute-Module-4.pdf] +[.whitepaper, title="Configure the Compute Module 4", subtitle="", link=https://pip.raspberrypi.com/documents/RP-003470-WP-Configuring-the-Compute-Module-4.pdf] **** The Compute Module 4 is available in a number of different hardware configurations. Some use cases disable certain features that aren't required. @@ -57,7 +57,7 @@ Raspberry Pi Compute Module 1 (CM1) and Compute Module 3 (CM3) are supported pro * https://datasheets.raspberrypi.com/cm/cm1-schematics.pdf[Schematics for CM1] * https://datasheets.raspberrypi.com/cm/cm3-schematics.pdf[Schematics for CM3] -[.whitepaper, title="Transition from Compute Module 1 or Compute Module 3 to Compute Module 4", subtitle="", link=https://pip.raspberrypi.com/categories/685-whitepapers-app-notes/documents/RP-003469-WP/Transitioning-from-CM3-to-CM4.pdf] +[.whitepaper, title="Transition from Compute Module 1 or Compute Module 3 to Compute Module 4", subtitle="", link=https://pip.raspberrypi.com/documents/RP-003469-WP-Transitioning-from-CM3-to-CM4.pdf] **** This white paper helps developers migrate from Compute Module 1 or Compute Module 3 to Compute Module 4. **** diff --git a/documentation/asciidoc/computers/compute-module/images/cm4-cm5-antenna-physical.png b/documentation/asciidoc/computers/compute-module/images/cm4-cm5-antenna-physical.png index 7fcd0da44..269c015ec 100644 Binary files a/documentation/asciidoc/computers/compute-module/images/cm4-cm5-antenna-physical.png and b/documentation/asciidoc/computers/compute-module/images/cm4-cm5-antenna-physical.png differ diff --git a/documentation/asciidoc/computers/compute-module/images/cm5-case-physical.png b/documentation/asciidoc/computers/compute-module/images/cm5-case-physical.png index 05323596a..cedb3cbf8 100644 Binary files a/documentation/asciidoc/computers/compute-module/images/cm5-case-physical.png and b/documentation/asciidoc/computers/compute-module/images/cm5-case-physical.png differ diff --git a/documentation/asciidoc/computers/compute-module/images/cm5-cooler-physical.png b/documentation/asciidoc/computers/compute-module/images/cm5-cooler-physical.png index 521410178..d1e5ee150 100644 Binary files a/documentation/asciidoc/computers/compute-module/images/cm5-cooler-physical.png and b/documentation/asciidoc/computers/compute-module/images/cm5-cooler-physical.png differ diff --git a/documentation/asciidoc/computers/compute-module/images/cm5io-j6-cam1.png b/documentation/asciidoc/computers/compute-module/images/cm5io-j6-cam1.png new file mode 100644 index 000000000..82800d15d Binary files /dev/null and b/documentation/asciidoc/computers/compute-module/images/cm5io-j6-cam1.png differ diff --git a/documentation/asciidoc/computers/compute-module/introduction.adoc b/documentation/asciidoc/computers/compute-module/introduction.adoc index aa74d7bd5..70b3728a9 100644 --- a/documentation/asciidoc/computers/compute-module/introduction.adoc +++ b/documentation/asciidoc/computers/compute-module/introduction.adoc @@ -1,232 +1,388 @@ +A Raspberry Pi *Compute Module (CM)* is a compact version of a standard Raspberry Pi single-board computer (SBC) designed primarily for embedded and industrial applications. A Compute Module contains the core components of a Raspberry Pi but without the standard connectors like HDMI, USB, or Ethernet. + +A Raspberry Pi *Compute Module IO Board (CMIO)* provides the physical connectors, peripheral interfaces, and expansion options necessary for accessing and expanding a Compute Module's functionality. A Compute Module IO Board can be used as a standalone product, allowing for rapid prototyping and embedded systems development, or as a reference design for your own carrier (IO) board. In either case, you can selectively make use of only the connectors that your application requires. + +This page: + +* Summarises the available Raspberry Pi Compute Module and IO Board models, including information about their compatibility and key features. +* Describes the accessories available for Compute Module 5 (CM5) and its IO Board (CM5IO). +* Explains how to flash and boot Raspberry Pi Compute Modules. +* Explains how to configure the EEPROM bootloader of a Compute Module. +* Explains how to wire and enable peripherals like cameras and displays using Device Tree and overlays. +* Provides links to datasheets, schematics, and design resources. + == Compute Modules -Raspberry Pi Compute Modules are **system-on-module** variants of the flagship Raspberry Pi models. Compute Modules are especially popular for industrial and commercial applications, including digital signage, thin clients, and process automation. Some of these applications use the flagship Raspberry Pi design, but many users want a more compact design or on-board eMMC storage. +Raspberry Pi Compute Modules are *system-on-module (SoM)* variants of the flagship Raspberry Pi single-board computers (SBC). They're designed for industrial and commercial applications, such as digital signage, thin clients, and process automation. Many developers and system designers choose Compute Modules over flagship Raspberry Pi models for their compact design, flexibility, and support for on-board eMMC storage. + +=== Memory, storage, and wireless variants + +Raspberry Pi Compute Modules are available in several variants, differing in memory, embedded Multi-Media Card (eMMC) flash storage capacity (soldered onto the board), and wireless connectivity (Wi-Fi and Bluetooth). + +* *Memory.* Compute Modules 1, 3, and 3+ offer a fixed amount of RAM. Compute Modules 4, 4S, and 5 offer different amounts of RAM; for details about the available options, see the dedicated sections for each Compute Module model on this page. +* *Storage.* Compute Modules 3, 3+, 4, 4S, and 5 offer different storage options, with later models offering more options and larger sizes than earlier models. Compute Module 1 offers a fixed 4 GB of storage. Storage is provided by eMMC flash memory, which provides persistent storage with low power consumption and built-in features that improve reliability. Variants with no on-board storage are referred to with the suffix *Lite* or *L*, for example, "CM5Lite" or "CM3L". +* *Wireless.* Compute Modules 4 and 5 offer optional Wi-Fi and Bluetooth. + +=== Models -Compute Modules come in multiple variants, varying both in memory and soldered-on Multi-Media Card (eMMC) flash storage capacity. Like SD cards, eMMC provides persistent storage with minimal energy impact. Unlike SD cards, eMMC is specifically designed to be used as a disk and includes extra features to improve reliability. **Lite** models have no on-board storage, and are sometimes referred to with the shorthand suffix **L**, e.g. "CM3L". +The following table summarises Raspberry Pi Compute Modules in reverse chronological order, listing their SoC, GPU, CPU, and form factor for quick reference. For more information about each of these models, including memory and storage options, see the following dedicated sections on this page. -Compute Modules use the following Raspberry Pi SoCs: +[cols="1,1,1,1,1,1", options="header"] +|=== +|Model|Based on|SoC|GPU|CPU|Form factor + +| <> (2024) +| Raspberry Pi 5 +| Broadcom BCM2712 +|VideoCore VII +| 4 × Cortex-A76 at 2.4 GHz +|Dual 100-pin connectors + +| <> (2022) +| Raspberry Pi 4 Model B (in CM3 form factor) +| Broadcom BCM2711 +|VideoCore VI +| 4 × Cortex-A72 at 1.5 GHz +|DDR2 SODIMM + +| <> (2020) +| Raspberry Pi 4 Model B +| Broadcom BCM2711 +|VideoCore VI +| 4 × Cortex-A72 at 1.5 GHz +|Dual 100-pin connectors + +| <> (2019) +| Raspberry Pi 3 Model B+ +| Broadcom BCM2837B0 +|VideoCore IV +| 4 × Cortex-A53 at 1.2 GHz +|DDR2 SODIMM + +| <> (2017; discontinued October 2025) +| Raspberry Pi 3 Model B +| Broadcom BCM2837 +|VideoCore IV +| 4 × Cortex-A53 at 1.2 GHz +|DDR2 SODIMM + +| <> (2014) +| Raspberry Pi Model B +| Broadcom BCM2835 +|VideoCore IV +| 1 × ARM1176JZF-S at 700 MHz +|DDR2 SODIMM -* BCM2835 for CM1 -* BCM2837 for CM3, CM3+ -* BCM2711 for CM4, CM4S -* BCM2712 for CM5 +|=== +[[cm5]] === Compute Module 5 .Compute Module 5 image::images/cm5.png[alt="Compute Module 5", width="60%"] -The Compute Module 5 (CM5) combines the internals of a Raspberry Pi 5 (the BCM2712 processor and 2GB, 4GB, 8GB, or 16GB of RAM) with optional 0GB (Lite), 16GB, 32GB or 64GB of eMMC flash storage. +Compute Module 5 (*CM5*) combines the core components of Raspberry Pi 5 with optional flash storage. Key features include: -CM5 uses the same form factor as CM4, featuring two 100-pin high density connectors. +* *Processor.* Broadcom BCM2712. +* *Memory options.* 2 GB, 4 GB, 8 GB, or 16 GB of RAM. +* *Storage options.* 0 GB (*CM5Lite*), 16 GB, 32 GB, or 64 GB of eMMC flash memory. +* *Form factor.* Two 100-pin high-density connectors for connecting to the companion carrier board. -=== Compute Module 4 +CM5 uses the same form factor as *CM4* and provides input/output (I/O) interfaces beyond those available on standard Raspberry Pi boards, offering expanded options for more complex systems and designs. -.Compute Module 4 -image::images/cm4.jpg[alt="Compute Module 4", width="60%"] +[[cm4s]] +=== Compute Module 4S -The Compute Module 4 (CM4) combines the internals of a Raspberry Pi 4 (the BCM2711 processor and 1GB, 2GB, 4GB, or 8GB of RAM) with an optional 0GB (Lite), 8GB, 16GB or 32GB of eMMC flash storage. +.Compute Module 4S +image::images/cm4s.jpg[alt="Compute Module 4S", width="60%"] -Unlike CM1, CM3, and CM3+, CM4 does not use the DDR2 SO-DIMM form factor. Instead, CM4 uses two 100-pin high density connectors in a smaller physical footprint. This change helped add the following interfaces: +Compute Module 4S (*CM4S*) combines the core components of Raspberry Pi 4 with optional flash storage. Key features include: -* an additional second HDMI port -* PCIe -* Ethernet +* *Processor.* Broadcom BCM2711. +* *Memory options.* 1 GB, 2 GB, 4 GB, or 8 GB of RAM. +* *Storage options.* 0 GB (*CM4SLite*), 8 GB, 16 GB, or 32 GB of eMMC flash memory. +* *Form factor.* Standard DDR2 SODIMM module. -The previous form factor could not have supported these interfaces. +Unlike *CM4*, CM4S retains the DDR2 SODIMM form factor used in *CM1*, *CM3*, and *CM3+*. -=== Compute Module 4S +[[cm4]] +=== Compute Module 4 -.Compute Module 4S -image::images/cm4s.jpg[alt="Compute Module 4S", width="60%"] +.Compute Module 4 +image::images/cm4.jpg[alt="Compute Module 4", width="60%"] + +Compute Module 4 (*CM4*) combines the core components of Raspberry Pi 4 with optional flash storage. Key features include: + +* *Processor.* Broadcom BCM2711. +* *Memory options.* 1 GB, 2 GB, 4 GB, or 8 GB of RAM. +* *Storage options.* 0 GB (*CM4Lite*), 8 GB, 16 GB, or 32 GB of eMMC flash memory. +* *Form factor.* Two 100-pin high-density connectors for connecting to the companion carrier board. +* *Temperature range options.* Operating temperature of -20°C to +85°C for standard variants or -40°C to +85°C for wider applications. -The Compute Module 4S (CM4S) combines the internals of a Raspberry Pi 4 (the BCM2711 processor and 1GB, 2GB, 4GB, or 8GB of RAM) with an optional 0GB (Lite), 8GB, 16GB or 32GB of eMMC flash storage. Unlike CM4, CM4S comes in the same DDR2 SO-DIMM form factor as CM1, CM3, and CM3+. +Unlike earlier modules (*CM1*, *CM3*, *CM3+*), CM4 moved away from the DDR2 SODIMM form factor to a dual 100-pin high-density connector layout, which results in a smaller physical footprint. This redesign supports the following additional features: -[[compute-module-3-plus]] +* Dual HDMI connectors +* PCIe support +* Ethernet connector + +[[cm3plus]] === Compute Module 3+ .Compute Module 3+ image::images/cm3-plus.jpg[alt="Compute Module 3+", width="60%"] -The Compute Module 3+ (CM3+) combines the internals of a Raspberry Pi 3 Model B+ (the BCM2837 processor and 1GB of RAM) with an optional 0GB (Lite), 8GB, 16GB or 32GB of eMMC flash storage. CM3+ comes in the DDR2 SO-DIMM form factor. +Compute Module 3+ (*CM3+*) combines the core components of Raspberry Pi 3 Model B+ with optional flash storage. Key features include: + +* *Processor.* Broadcom BCM2837B0. +* *Memory*. 1 GB of RAM. +* *Storage options.* 0 GB (*CM3+Lite*) or 8 GB, 16 GB, or 32 GB of eMMC flash memory. +* *Form factor.* Standard DDR2 SODIMM module. +[[cm3]] === Compute Module 3 .Compute Module 3 image::images/cm3.jpg[alt="Compute Module 3", width="60%"] -The Compute Module 3 (CM3) combines the internals of a Raspberry Pi 3 (the BCM2837 processor and 1GB of RAM) with an optional 4GB of eMMC flash storage. CM3 comes in the DDR2 SO-DIMM form factor. +IMPORTANT: Raspberry Pi Compute Module 3 (CM3) and Compute Module 3 Lite (CM3Lite) have reached End-of-Life (EoL) due to the discontinuation of the core SoC used in these products. The official EoL date was 16 October 2025. The closest equivalent to CM3 is Raspberry Pi <>, which offers the same mechanical footprint, improved thermal design, and a BCM2837B0 processor, and so is recommended for existing designs. For new designs requiring the SODIMM form factor, we recommend <>. For all other new designs, we recommend <> or <>. For more information, see the official https://pip.raspberrypi.com/documents/RP-009286-PC?disposition=inline[Obsolescence Notice]. + +Compute Module 3 (*CM3*) combines the core components of Raspberry Pi 3 with an optional 4 GB of flash storage. Key features include: + +* *Processor.* Broadcom BCM2837. +* *Memory.* 1 GB of RAM. +* *Storage options.* 0 GB (*CM3Lite*) or 4 GB of eMMC flash memory. +* *Form factor.* Standard DDR2 SODIMM module. +[[cm1]] === Compute Module 1 .Compute Module 1 image::images/cm1.jpg[alt="Compute Module 1", width="60%"] -The Compute Module 1 (CM1) contains the internals of a Raspberry Pi (the BCM2835 processor and 512MB of RAM) as well as an optional 4GB of eMMC flash storage. CM1 comes in the DDR2 SO-DIMM form factor. - -== IO Boards - -Raspberry Pi IO Boards provide a way to connect a single Compute Module to a variety of I/O (input/output) interfaces. Compute Modules are small, lacking ports and connectors. IO Boards provide a way to connect Compute Modules to a variety of peripherals. +Compute Module 1 (*CM1*) combines the core components of Raspberry Pi Model B with 4 GB of flash storage. Key features include: -Raspberry Pi IO Boards provide the following functionality: +* *Processor.* Broadcom BCM2835. +* *Memory.* 512 MB of RAM. +* *Storage.* 4 GB of eMMC flash memory. +* *Form factor.* Standard DDR2 SODIMM module. -* power the module -* connects the GPIO to pin headers -* connects the camera and display interfaces to FFC connectors -* connects HDMI to HDMI ports -* connects USB to USB ports -* connects activity monitoring to LEDs -* eMMC programming over USB -* connects PCIe to connectors used to physically connect storage or peripherals - -IO Boards are breakout boards intended for development or personal use; in production, you should use a smaller, potentially custom board that provides only the ports and peripherals required for your use-case. +== IO Boards -=== Compute Module 5 IO Board +A Raspberry Pi Compute Module IO Board is the companion carrier board that provides the necessary connectors to interface with various input/output (I/O) peripherals on your Compute Module. Raspberry Pi Compute Module IO Boards provide the following functionality: -.Compute Module 5 IO Board -image::images/cm5io.png[alt="Compute Module 5 IO Board", width="60%"] +* Supply power to the Compute Module. +* Connect general-purpose input/output (GPIO) pins to standard pin headers so that you can attach sensors or electronics. +* Make camera and display interfaces available through flat flexible cable (FFC) connectors. +* Make HDMI signals available through HDMI connectors. +* Make USB interfaces available through standard USB connectors for peripheral devices. +* Provide LEDs that indicate power and activity status. +* Enable eMMC programming over USB for flashing the module's on-board storage. +* On CM4IO and CM5IO, expose PCIe through connectors so that you can attach storage or peripheral devices like SSDs or network adapters. -Compute Module 5 IO Board provides the following interfaces: - -* HAT footprint with 40-pin GPIO connector -* PoE header -* 2× HDMI ports -* 2× USB 3.0 ports -* Gigabit Ethernet RJ45 with PoE support -* M.2 M key PCIe socket compatible with the 2230, 2242, 2260, and 2280 form factors -* microSD card slot (only for use with Lite variants with no eMMC; other variants ignore the slot) -* 2× MIPI DSI/CSI-2 combined display/camera FPC connectors (22-pin 0.5 mm pitch cable) -* Real-time clock with battery socket -* four-pin JST-SH PWM fan connector -* USB-C power using the same standard as Raspberry Pi 5 (5V, 5A (25W) or 5V, 3A (15W) with a 600mA peripheral limit) -* Jumpers to disable features such as eMMC boot, EEPROM write, and the USB OTG connection +Raspberry Pi IO Boards are general-purpose boards designed for development, testing, and prototyping Compute Modules. For production use, you might design a smaller, custom carrier board that includes only the connectors you need for your use case. -=== Compute Module 4 IO Board +[[io-board-compatibility]] +=== IO Boards and compatibility -.Compute Module 4 IO Board -image::images/cm4io.jpg[alt="Compute Module 4 IO Board", width="60%"] +Not all IO Boards work with all Compute Module models. The following table summarises Raspberry Pi Compute Module IO Boards in reverse chronological order, listing their compatible Compute Modules (which include Lite versions), power input, and size. For more information about each of these boards, including available interfaces, see the following dedicated sections on this page. -Compute Module 4 IO Board provides the following interfaces: - -* HAT footprint with 40-pin GPIO connector and PoE header -* 2× HDMI ports -* 2× USB 2.0 ports -* Gigabit Ethernet RJ45 with PoE support -* microSD card slot (only for use with Lite variants with no eMMC; other variants ignore the slot) -* PCIe Gen 2 socket -* micro USB upstream port -* 2× MIPI DSI display FPC connectors (22-pin 0.5 mm pitch cable) -* 2× MIPI CSI-2 camera FPC connectors (22-pin 0.5 mm pitch cable) -* Real-time clock with battery socket -* 12V input via barrel jack (supports up to 26V if PCIe unused) - -=== Compute Module IO Board - -.Compute Module IO Board -image::images/cmio.jpg[alt="Compute Module IO Board", width="60%"] +[cols="1,1,1,1", options="header"] +|=== +|IO Board|Compatible CM|Power input|Size -Compute Module IO Board provides the following interfaces: +| <> (2024) +| <>; CM4 with reduced functionality +| 5 V through USB Type-C +|160 mm × 90 mm -* 120 GPIO pins -* HDMI port -* USB-A port -* 2× MIPI DSI display FPC connectors (22-pin 0.5 mm pitch cable) -* 2× MIPI CSI-2 camera FPC connectors (22-pin 0.5 mm pitch cable) +| <> (2020) +| <>; CM5 with reduced functionality +| 5 V through the GPIO header or 12 V through the DC barrel jack +|160 mm × 90 mm -The Compute Module IO Board comes in two variants: Version 1 and Version 3. Version 1 is only compatible with CM1. Version 3 is compatible with CM1, CM3, CM3+, and CM4S. Compute Module IO Board Version 3 is sometimes written as the shorthand CMIO3. +| <> (2017) +| <>, <>, <>, and <> +| 5 V through GPIO or a micro USB connector +| 85 mm × 105 mm -Compute Module IO Board Version 3 added a microSD card slot that did not exist in Compute Module IO Board Version 1. +| <> (2014) +| <> +| 5 V through GPIO or a micro USB connector. +| 85 mm × 105 mm -=== IO Board compatibility +|=== -Not all Compute Module IO Boards work with all Compute Module models. The following table shows which Compute Modules work with each IO Board: +[[cm5io]] +=== Compute Module 5 IO Board -[cols="1,1"] -|=== -| IO Board | Compatible Compute Modules - -| Compute Module IO Board Version 1 (CMIO)/(CMIO1) -a| -* CM1 -| Compute Module IO Board Version 3 (CMIO)/(CMIO3) -a| -* CM1 -* CM3 -* CM3+ -* CM4S -| Compute Module 4 IO Board (CM4IO) -a| -* CM4 -* CM5 (with reduced functionality) -| Compute Module 5 IO Board (CM5IO) -a| -* CM5 -* CM4 (with reduced functionality) -|=== +.Compute Module 5 IO Board +image::images/cm5io.png[alt="Compute Module 5 IO Board", width="60%"] -== CM5 Accessories +The Compute Module 5 IO Board (CM5IO) provides the following: + +* *Power and control connectors.* +** USB-C power using the same standard as Raspberry Pi 5: 5 V at 5 A (25 W) or 5 V at 3 A (15 W) with a 600 mA peripheral limit. +** A power button for CM5. +** Real-time clock (RTC) battery socket. +* *Video and display connectors.* +** Two HDMI connectors. +** Two MIPI DSI/CSI-2 combined display/camera FPC connectors (22-pin, 0.5 mm pitch cable). +* *Networking and connectivity connectors.* +** Two USB 3.0 (Type-A) connectors for keyboards, storage, or peripherals. +** A USB 2.0 (Type-C) connector for flashing CM5 or additional peripherals. +** A Gigabit Ethernet RJ45 with PoE support. +* *Expansion and storage options.* +** A M.2 M key PCIe socket compatible with the 2230, 2242, 2260, and 2280 form factors. +** A microSD card slot (only for use with *CM5Lite*, which has no eMMC; other variants ignore the slot). +** HAT footprint with 40-pin GPIO connector. +** PoE header. +* *Configuration options.* +** Jumpers to disable features such as eMMC boot, EEPROM write, and wireless connectivity. +** Selectable 1.8 V or 3.3 V GPIO voltage. +* *Fan connector.* A four-pin JST-SH PWM fan connector. + +[[cm4io]] +=== Compute Module 4 IO Board -=== IO Case +.Compute Module 4 IO Board +image::images/cm4io.jpg[alt="Compute Module 4 IO Board", width="60%"] -The world can be a dangerous place. The Compute Module 5 IO Board Case provides physical protection for a CM5IO Board. +The Compute Module 4 IO Board (CM4IO) provides the following: + +* *Power and control connectors.* +** 5 V through the GPIO header or 12 V input through barrel jack; supports up to 26 V if PCIe is unused. +** Real-time clock (RTC) battery socket. +* *Video and display connectors.* +** Two HDMI connectors. +** Two MIPI DSI display FPC connectors (22-pin, 0.5 mm pitch cable). +** Two MIPI CSI-2 camera FPC connectors (22-pin, 0.5 mm pitch cable). +* *Networking and connectivity connectors.* +** Two USB 2.0 connectors. +** A micro USB upstream port. +** A Gigabit Ethernet RJ45 with PoE support. +* *Expansion and storage options.* +** PCIe Gen 2 socket. +** A microSD card slot (only for use with *CM4Lite*, which has no eMMC; other variants ignore the slot). +** HAT footprint with 40-pin GPIO connector. +** PoE header. +* *Configuration options.* +** Jumpers to disable features such as eMMC boot, EEPROM write, and wireless connectivity. +** Selectable 1.8 V or 3.3 V GPIO voltage. +* *Fan connector.* Fan connector supporting standard 12 V fans with PWM drive. + +[[cmio]] +=== Compute Module IO Board (versions 1 and 3) + +.Compute Module IO Board (version 3) +image::images/cmio.jpg[alt="Compute Module IO Board (version 3)", width="60%"] + +There are two variants of the Compute Module IO Board: + +* Version 1 (CMIO), compatible only with <>. +* Version 3 (CMIO3), compatible with <>, <>, <>, and <>. This version adds a microSD card slot that doesn't exist on CMIO (version 1). + +The Compute Module IO Board (CMIO and CMIO3) provides the following: + +* *Power and control connectors.* 5 V input through GPIO or a micro USB connector. +* *Video and display connectors.* +** One Full size Type A HDMI. +** Two MIPI DSI display FPC connectors (22-pin, 0.5 mm pitch cable). +** Two MIPI CSI-2 camera FPC connectors (22-pin, 0.5 mm pitch cable). +* *Networking and connectivity connectors.* One USB 2.0 Type-A connector. +* *Expansion and storage options.* +** 46 GPIO pins. +** (CMIO3 only) A microSD card slot (only for use with *CM3Lite*, *CM3+Lite* and *CM4SLite*, which have no eMMC). + +== CM5 and CM5IO accessories + +Raspberry Pi offers the following accessories for CM5 and CM5IO: + +* <>, a two-piece metal enclosure for a CM5IO (and attached CM5). The case also optionally fits an antenna and cooler. +* <>, a 2.4 GHz and 5 GHz antenna for wireless connectivity through CM4 or CM5. +* <>, a passive heat sink to dissipate heat from CM5. + +[[case]] +=== CM5IO Case .Compute Module 5 IO Board Case image::images/cm5io-case.png[alt="Compute Module 5 IO Board Case", width="60%"] -The Case provides cut-outs for all externally-facing ports and LEDs on the CM5IO Board, and an attachment point for a Raspberry Pi Antenna Kit. +The Compute Module 5 IO Board Case provides physical protection for CM5IO and its attached CM5. It includes: + +* Cut-outs for externally facing connectors and LEDs. +* A pre-installed, controllable fan that you can remove. +* An attachment point for a *Raspberry Pi Antenna Kit*. +* Space for a *CM5 Cooler*. +* Space for accessories connected to the IO board, such as an M.2 SSD or PoE+ HAT+. .Compute Module 5 IO Board Case ports image::images/cm5io-case-front.png[alt="the port selection on the Compute Module 5 IO Board Case", width="60%"] -To mount a CM5IO Board within your Case, position your Board in the bottom section of the case, aligning the four mounting points inset slightly from each corner of the Board. Fasten four screws into the mounting points. Take care not to over-tighten the screws. +The CM5IO Case is a two-piece enclosure that, when assembled, measures 170 mm × 94 mm × 28 mm. It's made of sheet metal and weighs approximately 350 g. For thermal management, the case includes a pre-installed fan that directs airflow over your CM5 and CM5IO components. You can remove or replace the fan depending on your cooling requirements. You can also optionally add a <> for improved thermal performance. -To use the Case fan, connect the fan cable to the FAN (J14) port on the Board. +.CM5 case physical specification +image::images/cm5-case-physical.png[alt="CM5 Case physical specification", width="80%"] -To close the case, put the top section of the case on top of the bottom section of the case. Facing the front of the case, which has port pass-throughs, carefully align the screw holes on the left and right side of the case and the power button on the back of the case. Tighten four screws into the screw holes. Take care not to over-tighten the screws. +To mount a CM5IO inside your case: -TIP: The Case comes with a fan pre-installed. To close the case with the passive Cooler attached to your Compute Module, remove the fan. To remove the fan, remove the four screws positioned in the corners of the fan from the bottom of the top case. +. *Attach your CM5 to your CM5IO.* Rotate your CM5 90 degrees to the right to align the dual 100-pin connectors on your CM5 with those on your CM5IO and press gently but firmly to attach them. The mounting holes should also align. +. *Open the case.* Unscrew and remove the four screws (two on the left side of the case and two on the right side of the case) using a Phillips screwdriver. Then, separate the top of the case from the base. Keep the screws in a safe place. +. *Install your CM5IO assembly into the case.* Place your CM5IO (with CM5 attached) into the base of the case, aligning it with the four mounting holes near the corners of the board. Ensure all externally facing connectors align with the corresponding cut-outs at the front of the case. Then, secure your CM5IO assembly to the base by screwing four M2.5 screws into the four mounting holes. +. *Connect or remove the fan.* +** If using the pre-installed fan, plug the fan connector into the four-pin fan socket labelled *FAN (J14)* on your CM5IO. +** If you want to remove the fan, unscrew the four corner screws of the fan from the underside of the top of the case. +. *Optionally, attach an external antenna.* If you want to install an antenna, follow the instructions in <> on this page. +. *Optionally, attach the cooler.* If you want to install a cooler, follow the instructions in <>. If you're also attaching an antenna, attach the antenna's U.FL connector first for easier access. +. *Optionally, attach a camera or display.* If you're using a camera or a display, pass the flat cable through one of the slots at the back of the case and connect it to one of the *CAM/DISP* ports on your CM5IO. +. *Optionally, install an M.2 SSD.* If you want to install an M.2 SSD, insert it into the M.2 slot in the bottom-right corner of the CM5IO and secure it on the opposite end with a mounting screw. +. *Optionally, install a HAT.* If you want to install a HAT, align it with the 40-pin GPIO header and the mounting posts such that the HAT covers the battery slot, then press it firmly into place and secure it with screws. +. *Close the case.* Fold the top of the case back onto the base of the case, aligning the screw holes on the left and right sides of the case, and the power button on the back of the case. Screw the four screws back into place using a Phillips screwdriver, taking care not to overtighten them. -.CM5 Case physical specification -image::images/cm5-case-physical.png[alt="CM5 Case physical specification", width="80%"] +NOTE: The SD card slot is a push-push slot. To insert an SD card, push it into the SD card slot with the contacts facing downwards. To remove it, push it inwards towards the slot to release it and then pull it out. -=== Antenna +[[antenna]] +=== Antenna (CM4 and CM5) The Raspberry Pi Antenna Kit provides a certified external antenna to boost wireless reception on a CM4 or CM5. -.CM4 and CM5 Antenna +.CM4 and CM5 antenna image::images/cm4-cm5-antenna.jpg[alt="The Antenna, connected to CM4", width="60%"] -To attach the Antenna to your Compute Module and Case, complete the following steps: +The antenna supports dual-band Wi-Fi and attaches to the https://en.wikipedia.org/wiki/Hirose_U.FL[U.FL connector] on your CM4 or CM5. The antenna is 108 mm at full height; the SMA to U.FL cable is 205 mm long. -. Connect the https://en.wikipedia.org/wiki/Hirose_U.FL[U.FL connector] on the cable to the U.FL-compatible connector on your Compute Module. -. Secure the toothed washer onto the male SMA connector at the end of the cable, then insert the SMA connector, with the antenna facing outward, through the hole in the Case. -. Fasten the SMA connector into place with the retaining hexagonal nut and washer. -. Tighten the female SMA connector on the Antenna onto the male SMA connector. -. Adjust the Antenna to its final position by turning it up to 90°. +.CM4 and CM5 antenna physical specification +image::images/cm4-cm5-antenna-physical.png[alt="CM4 and CM5 antenna physical specification", width="80%"] -.CM4 and CM5 Antenna assembly diagram -image::images/cm4-cm5-antenna-assembly.svg[alt="CM4 and CM5 antenna assembly diagram", width="60%"] +You can use the antenna with the <>. To attach the antenna to your Compute Module through the CM5IO Case, complete the first four steps outlined in <>, and then complete following steps: -To **use** the Antenna with your Compute Module, add a `dtoverlay` instruction in xref:../computers/config_txt.adoc[`/boot/firmware/config.txt`]. Add the following line to the end of `config.txt`: +. *Connect the U.FL connector.* Connect the U.FL connector on the antenna cable to the U.FL-compatible connector on your Compute Module, next to the top-left mounting hole of your CM5. Do this before attaching a cooler (if using one) because the cooler can make it harder to attach the U.FL connector. +. *Insert the SMA connector.* Remove the rubber plug from the antenna port on the inside of the CM5IO Case. Then, from the inside of the case, push the SMA connector with the (flat side up) into the antenna port so that it extends through and is accessible from the outside. +. *Fasten the SMA connector into place.* Twist the retaining hexagonal nut and washer onto the SMA connector in a clockwise direction until it sits securely in place. Avoid excessive twisting when tightening to prevent damage. +. *Attach the antenna to the SMA connector.* Insert the SMA connector into the antenna port with the antenna facing outward and twist the antenna clockwise to secure it. +. *Adjust the antenna.* Move the antenna into its final position by turning it up to a 90 degree angle. -[source,ini] ----- -dtparam=ant2 ----- +You can now complete the remaining steps outlined in <> for mounting a CM5IO inside your case. -.CM4 and CM5 Antenna physical specification -image::images/cm4-cm5-antenna-physical.png[alt="CM4 and CM5 antenna physical specification", width="80%"] +.CM4 and CM5 antenna assembly diagram +image::images/cm4-cm5-antenna-assembly.svg[alt="CM4 and CM5 antenna assembly diagram", width="60%"] + +To use the Antenna with your Compute Module, add a `dtparam` instruction in xref:../computers/config_txt.adoc[`/boot/firmware/config.txt`]. Add the following line to the end of the `config.txt` file: `dtparam=ant2` -=== Cooler +[[cooler]] +=== CM5 Cooler -The CM5 Cooler helps dissipate heat from your CM5, improving CPU performance, longevity, and bumpiness. +The CM5 Cooler is a passive heat sink that helps dissipate heat from your CM5, improving CPU performance and longevity. -.CM5 Cooler +.CM5 cooler image::images/cm5-cooler.jpg[alt="CM5 Cooler", width="60%"] -To mount the Cooler to your CM5, attach the thermally conductive silicone at the bottom of the Cooler to the top of your CM5. Align the cut-out in the heatsink with the antenna https://en.wikipedia.org/wiki/Hirose_U.FL[U.FL connector]. Optionally, fasten screws in the mounting points found in each corner to secure the Cooler. If you omit the screws, the bond between your Cooler and your Compute Module will improve through time, use, and trust. +The CM5 Cooler dimensions are 41 mm × 56 mm × 12.7 mm. The cooler is an aluminium heat sink with a conductive silicone pad on the bottom. Newer versions of the <> allow both the cooler and pre-installed fan to be used inside the case at the same time. If you have an older version of the CM5IO Case, you must remove the fan from the case to allow space for the cooler. -.CM5 Cooler physical specification +.CM5 cooler physical specification image::images/cm5-cooler-physical.png[alt="CM5 Cooler physical specification", width="80%"] -NOTE: The CM5 Cooler is only compatible with the CM5IO Case if you remove the fan from the case. +To mount the cooler to your CM5: + +. Remove the protective paper from the silicone pad on the bottom of cooler. +. Attach the silicone at the bottom of the cooler to the top of your CM5. Place the cooler on your CM5 such that the cutout in the cooler is above the on-board antenna (the trapezoid-shaped area on the left of a CM5) and the https://en.wikipedia.org/wiki/Hirose_U.FL[U.FL connector] next to it (if it has one). +. Optionally, fasten screws in the mounting points found in each corner to secure the cooler. If you omit the screws, the bond between your cooler and your CM5 improves through time and use. diff --git a/documentation/asciidoc/computers/config_txt/boot.adoc b/documentation/asciidoc/computers/config_txt/boot.adoc index 541c7db8a..786df5f5c 100644 --- a/documentation/asciidoc/computers/config_txt/boot.adoc +++ b/documentation/asciidoc/computers/config_txt/boot.adoc @@ -5,13 +5,13 @@ These options specify the firmware files transferred to the VideoCore GPU prior to booting. `start_file` specifies the VideoCore firmware file to use. -`fixup_file` specifies the file used to fix up memory locations used in the `start_file` to match the GPU memory split. +`fixup_file` specifies the file used to fix up memory locations used in the `start_file` to match the GPU memory split. The `start_file` and the `fixup_file` are a matched pair - using unmatched files will stop the board from booting. This is an advanced option, so we advise that you use `start_x` and `start_debug` rather than this option. NOTE: Cut-down firmware (`start*cd.elf` and `fixup*cd.dat`) cannot be selected this way - the system will fail to boot. The only way to enable the cut-down firmware is to specify `gpu_mem=16`. The cut-down firmware removes support for codecs, 3D and debug logging as well as limiting the initial early-boot framebuffer to 1080p @16bpp - although KMS can replace this with up to 32bpp 4K framebuffer(s) at a later stage as with any firmware. -NOTE: The Raspberry Pi 5, Compute Module 5, and Raspberry Pi 500 firmware is self-contained in the bootloader EEPROM. +NOTE: The Raspberry Pi 5, 500, 500+, and Compute Module 5 firmware is self-contained in the bootloader EEPROM. === `cmdline` @@ -21,7 +21,7 @@ NOTE: The Raspberry Pi 5, Compute Module 5, and Raspberry Pi 500 firmware is sel `kernel` is the alternative filename on the boot partition for loading the kernel. The default value on the Raspberry Pi 1, Zero and Zero W, and Raspberry Pi Compute Module 1 is `kernel.img`. The default value on the Raspberry Pi 2, 3, 3+ and Zero 2 W, and Raspberry Pi Compute Modules 3 and 3+ is `kernel7.img`. The default value on the Raspberry Pi 4 and 400, and Raspberry Pi Compute Module 4 is `kernel8.img`, or `kernel7l.img` if `arm_64bit` is set to 0. -The Raspberry Pi 5, Compute Module 5, and Raspberry Pi 500 firmware defaults to loading `kernel_2712.img` because this image contains optimisations specific to those models (e.g. 16K page-size). If this file is not present, then the common 64-bit kernel (`kernel8.img`) will be loaded instead. +The Raspberry Pi 5, 500, 500+, and Compute Module 5 firmware defaults to loading `kernel_2712.img` because this image contains optimisations specific to those models (e.g. 16K page-size). If this file is not present, then the common 64-bit kernel (`kernel8.img`) will be loaded instead. === `arm_64bit` @@ -54,9 +54,15 @@ The following Raspberry Pi models support this flag: Flagship models since Raspberry Pi 5, Compute Modules since CM5, and Keyboard models since Pi 500 _only_ support the 64-bit kernel. Models that only support a 64-bit kernel ignore this flag. +=== `armstub` + +`armstub` is the filename on the boot partition from which to load the Arm stub. The default Arm stub is stored in firmware and is selected automatically based on the Raspberry Pi model and various settings. + +The stub is a small piece of Arm code that is run before the kernel. Its job is to set up low-level hardware like the interrupt controller before passing control to the kernel. + === `ramfsfile` -`ramfsfile` is the optional filename on the boot partition of a `ramfs` to load. +`ramfsfile` is the optional filename on the boot partition of a `ramfs` to load. NOTE: Newer firmware supports the loading of multiple `ramfs` files. You should separate the multiple file names with commas, taking care not to exceed the 80-character line length limit. All the loaded files are concatenated in memory and treated as a single `ramfs` blob. More information is available https://forums.raspberrypi.com/viewtopic.php?f=63&t=10532[on the forums]. @@ -64,6 +70,7 @@ NOTE: Newer firmware supports the loading of multiple `ramfs` files. You should `ramfsaddr` is the memory address to which the `ramfsfile` should be loaded. +[[initramfs]] === `initramfs` The `initramfs` command specifies both the ramfs filename *and* the memory address to which to load it. It performs the actions of both `ramfsfile` and `ramfsaddr` in one parameter. The address can also be `followkernel` (or `0`) to place it in memory after the kernel image. Example values are: `initramfs initramf.gz 0x00800000` or `initramfs init.gz followkernel`. As with `ramfsfile`, newer firmwares allow the loading of multiple files by comma-separating their names. @@ -73,7 +80,7 @@ NOTE: This option uses different syntax from all the other options, and you shou [[auto_initramfs]] === `auto_initramfs` -If `auto_initramfs` is set to `1`, look for an `initramfs` file using the same rules as the kernel selection. +If `auto_initramfs` is set to `1`, the firmware looks for an `initramfs` file to match the kernel. The file must be in the same location as the kernel image, and the name is derived from the name of the kernel by replacing the `kernel` prefix with `initramfs`, and removing any extension such as `.img`, e.g. `kernel8.img` requires `initramfs8`. You can make use of `auto_initramfs` with custom kernel names provided the names begin with `kernel` and `initramfs` respectively and everything else matches (except for the absence of the file extension on the initramfs). Otherwise, an explicit xref:config_txt.adoc#initramfs[`initramfs`] statement is required. [[disable_poe_fan]] === `disable_poe_fan` @@ -158,6 +165,8 @@ Default: `0x0` [[enable_rp1_uart]] ==== `enable_rp1_uart` +Raspberry Pi 5 only. + When set to `1`, firmware initialises RP1 UART0 to 115200bps and doesn't reset RP1 before starting the OS (separately configurable using `pciex4_reset=1`). This makes it easier to get UART output on the 40-pin header in early boot-code, for instance during bare-metal debug. @@ -172,6 +181,11 @@ By default, the PCIe x4 controller used by `RP1` is reset before starting the op Default: `1` +[[sha256]] +==== `sha256` + +If set to non-zero, enables the logging of SHA256 hashes for loaded files (the kernel, initramfs, Device Tree .dtb file, and overlays), as generated by the `sha256sum` utility. The logging output goes to the UART if enabled, and is also accessible via `sudo vclog --msg`. This option may be useful when debugging boot problems, but at the cost of potentially adding _many_ seconds to the boot time. Defaults to 0 on all platforms. + [[uart_2ndstage]] ==== `uart_2ndstage` @@ -188,6 +202,57 @@ If `erase_eeprom` is set to `1` then `recovery.bin` will erase the entire SPI EE Default: `0` +[[set_reboot_arg1]] +==== `set_reboot_arg1` +Raspberry Pi 5 only. + +Sets the value of `boot_arg1` to be passed via a reset-safe register to the bootloader after a reboot. +See xref:config_txt.adoc#boot_arg1[`boot_arg1`] for more details. +Default: `` + +[[set_reboot_order]] +==== `set_reboot_order` + +Raspberry Pi 5 only. + +Sets the value of xref:raspberry-pi.adoc#BOOT_ORDER[BOOT_ORDER] to be passed via a reset-safe register to the bootloader after a reboot. As with `tryboot`, this is a one-time setting and is automatically cleared after use. + +This property could be used to debug different xref:raspberry-pi.adoc#BOOT_ORDER[BOOT_ORDER] settings. Alternatively, it could be used in a provisioning system which has control over power and the `nRPIBOOT` GPIO to override the boot mode without specifying xref:config_txt.adoc#conditional-filters[conditional filter] statements in the EEPROM config. + +Default: `` + +[[kernel_watchdog_timeout]] +==== `kernel_watchdog_timeout` + +If set to a non-zero value (in seconds), this property enables a hardware watchdog timer that is handed over to the operating system (OS) at boot. If the OS does not regularly "kick" or reset the watchdog, the system will be reset after the specified timeout. + +This property sets the `systemd` `watchdog.open_timeout` parameter, which controls how long the OS has to initialize and start servicing the watchdog. The value is passed to the OS via the kernel command line. For ongoing operation, the OS must also regularly reset the watchdog, typically controlled by the `RuntimeWatchdogSec` parameter in `systemd`. For more information, see https://www.freedesktop.org/software/systemd/man/systemd-system.conf.html#RuntimeWatchdogSec=[systemd watchdog documentation]. + +[NOTE] +==== +On Raspberry Pi OS Bookworm and earlier, the `RuntimeWatchdogSec` parameter is **not enabled by default** and this setting must be configured first in `/etc/systemd/system.conf` before the firmware kernel watchdog can be used. + +If both `BOOT_WATCHDOG_TIMEOUT` (EEPROM/bootloader setting, only supported on Raspberry Pi 4 and 5) and `kernel_watchdog_timeout` are set, the bootloader will seamlessly hand over from the bootloader watchdog to the kernel watchdog at the point the OS is started. This provides continuous watchdog coverage from power-on through to OS runtime. + +It is preferred to use `kernel_watchdog_timeout` rather than `dtparam=watchdog` because `kernel_watchdog_timeout` explicitly sets the `open_timeout` parameter, ensuring the watchdog is active until systemd takes over. +==== + +This is useful for ensuring that the system can recover from OS hangs or crashes after the boot process has completed. + +Default: `0` (disabled) + +[[kernel_watchdog_partition]] +==== `kernel_watchdog_partition` + +If the kernel watchdog triggers (i.e. the OS fails to reset the watchdog within the timeout), this property specifies the partition number to boot from after the reset. This allows for automatic failover to a recovery or alternate partition. + +You can use this in conjunction with the xref:config_txt.adoc#the-expression-filter[expression filter] to apply different settings or select a different boot flow when the watchdog triggers a reboot to a specific partition. + +See also the xref:raspberry-pi.adoc#PARTITION[PARTITION] property for more information about how to use high partition numbers to detect a watchdog trigger. + +Default: `0` (default partition) + + [[eeprom_write_protect]] ==== `eeprom_write_protect` @@ -235,9 +300,9 @@ Default: `1` === Secure Boot configuration properties -[.whitepaper, title="How to use Raspberry Pi Secure Boot", subtitle="", link=https://pip.raspberrypi.com/categories/685-whitepapers-app-notes/documents/RP-003466-WP/Boot-Security-Howto.pdf] +[.whitepaper, title="How to use Raspberry Pi Secure Boot", subtitle="", link=https://pip.raspberrypi.com/documents/RP-003466-WP-Boot-Security-Howto.pdf] **** -This whitepaper describes how to implement secure boot on devices based on Raspberry Pi 4. For an overview of our approach to implementing secure boot implementation, please see the https://pip.raspberrypi.com/categories/685-whitepapers-app-notes/documents/RP-004651-WP/Raspberry-Pi-4-Boot-Security.pdf[Raspberry Pi 4 Boot Security] whitepaper. The secure boot system is intended for use with `buildroot`-based OS images; using it with Raspberry Pi OS is not recommended or supported. +This whitepaper describes how to implement secure boot on devices based on Raspberry Pi 4. For an overview of our approach to implementing secure boot implementation, please see the https://pip.raspberrypi.com/documents/RP-004651-WP-Raspberry-Pi-4-Boot-Security.pdf[Raspberry Pi 4 Boot Security] whitepaper. The secure boot system is intended for use with `buildroot`-based OS images; using it with Raspberry Pi OS is not recommended or supported. **** The following `config.txt` properties are used to program the `secure-boot` OTP settings. These changes are irreversible and can only be programmed via `RPIBOOT` when flashing the bootloader EEPROM image. This ensures that `secure-boot` cannot be set remotely or by accidentally inserting a stale SD card image. @@ -254,14 +319,21 @@ Default: `0` [[revoke_devkey]] ==== `revoke_devkey` -If this property is set to `1` then `recovery.bin` will write a value to OTP that prevents the ROM from loading old versions of the second stage bootloader which do not support `secure-boot`. This prevents `secure-boot` from being turned off by reverting to an older release of the bootloader. +Raspberry Pi 4 only. + +If this property is set to `1` then `recovery.bin` will write a value to OTP that prevents the ROM from loading old versions of the second stage bootloader which do not support `secure-boot`. This prevents `secure-boot` from being turned off by reverting to an older release of the bootloader. Therefore, this property must be set if `secure-boot` is enabled on production devices. + +This property is automatically is set by `recovery.bin` `2025/05/16` and newer if `program_pubkey=1`. + Default: `0` [[program_rpiboot_gpio]] ==== `program_rpiboot_gpio` -Compute Modules have a dedicated `nRPIBOOT` jumper to select `RPIBOOT` mode. Flagship and Keyboard Raspberry Pi devices with EEPROM lack a dedicated `nRPIBOOT` jumper. To select `RPIBOOT` mode on Flagship and Keyboard devices, pull one of the following GPIO pins low: +Raspberry Pi 4B and Raspberry Pi 400 only. + +Compute Module 4 and 4S have a dedicated `nRPIBOOT` jumper to select `RPIBOOT` mode. Raspberry Pi 4B and Raspberry Pi 400 lack a dedicated `nRPIBOOT` jumper so one of the following GPIOs must be selected for use as `nRPIBOOT`. * `2` * `4` @@ -270,11 +342,11 @@ Compute Modules have a dedicated `nRPIBOOT` jumper to select `RPIBOOT` mode. Fla * `7` * `8` -This property does not depend on `secure-boot`. However, you should verify that this GPIO configuration does not conflict with any HATs which might pull the GPIO low during boot. +The GPIO may be used as a general-purpose I/O pin after the OS has started. However, you should verify that this GPIO configuration does not conflict with any HATs which might pull the GPIO low during boot. -For safety, this property can _only_ be programmed via `RPIBOOT`. As a result, you must first clear the bootloader EEPROM using `erase_eeprom`. This causes the ROM to failover to `RPIBOOT` mode, which then allows this option to be set. +Although `secure-boot` requires this property to be set on Raspberry Pi 4B and Raspberry Pi 400, it does not depend on `secure-boot`. For example, `RPIBOOT` can be useful for automated testing. -On BCM2712, you can alternatively force `RPIBOOT` mode by holding down the power button while simultaneously connecting a USB-C power supply. +For safety, this OTP value can _only_ be programmed via `RPIBOOT`. As a result, you must first clear the bootloader EEPROM using `erase_eeprom`. The blank EEPROM causes the ROM to failover to `RPIBOOT` mode, which then allows this option to be set. Default: `{nbsp}` diff --git a/documentation/asciidoc/computers/config_txt/common.adoc b/documentation/asciidoc/computers/config_txt/common.adoc index 442aefa5e..39c4a225e 100644 --- a/documentation/asciidoc/computers/config_txt/common.adoc +++ b/documentation/asciidoc/computers/config_txt/common.adoc @@ -16,15 +16,15 @@ By default, Raspberry Pi OS includes a line in `/boot/firmware/config.txt` that When enabled, the firmware will automatically load overlays for recognised CSI cameras. -To disable, set `camera_auto_detect=0`. +To disable, set `camera_auto_detect=0` (or remove `camera_auto_detect=1`). ==== `display_auto_detect` -Enabled by default. +By default, Raspberry Pi OS includes a line in `/boot/firmware/config.txt` that enables this setting. When enabled, the firmware will automatically load overlays for recognised DSI displays. -To disable, set `display_auto_detect=0`. +To disable, set `display_auto_detect=0` (or remove `display_auto_detect=1`). ==== `dtoverlay` @@ -52,7 +52,7 @@ To disable, set `arm_boost=0`. ==== `power_force_3v3_pwm` -NOTE: This option applies only to Raspberry Pi 5, Compute Module 5, and Pi 500. +NOTE: This option applies only to Raspberry Pi 5, 500, 500+, and Compute Module 5. Forces PWM on 3.3V output from the GPIO header or CSI connector. diff --git a/documentation/asciidoc/computers/config_txt/conditional.adoc b/documentation/asciidoc/computers/config_txt/conditional.adoc index b8ede5b39..3cbce087b 100644 --- a/documentation/asciidoc/computers/config_txt/conditional.adoc +++ b/documentation/asciidoc/computers/config_txt/conditional.adoc @@ -14,31 +14,31 @@ The `[all]` filter is the most basic filter. It resets all previously set filter The conditional model filters apply according to the following table. |=== -| Filter | Applicable model(s) +| Filter | Applicable models | `[pi1]` -| Model 1A, Model 1B, Model 1A+, Model 1B+, Compute Module 1 +| 1A, 1B, 1A+, 1B+, Compute Module 1 | `[pi2]` -| Model 2B (BCM2836- or BCM2837-based) +| 2B (BCM2836- or BCM2837-based) | `[pi3]` -| Model 3B, Model 3B+, Model 3A+, Compute Module 3, Compute Module 3+ +| 3B, 3B+, 3A+, Compute Module 3, Compute Module 3+ | `[pi3+]` -| Model 3A+, Model 3B+ (also sees `[pi3]` contents) +| 3A+, 3B+ (also sees `[pi3]` contents) | `[pi4]` -| Model 4B, Pi 400, Compute Module 4, Compute Module 4S +| 4B, 400, Compute Module 4, Compute Module 4S | `[pi5]` -| Raspberry Pi 5, Compute Module 5, Pi 500 +| 5, 500, 500+, Compute Module 5 | `[pi400]` -| Pi 400 (also sees `[pi4]` contents) +| 400 (also sees `[pi4]` contents) | `[pi500]` -| Pi 500 (also sees `[pi5]` contents) +| 500/500+ (also sees `[pi5]` contents) | `[cm1]` | Compute Module 1 (also sees `[pi1]` contents) @@ -96,12 +96,152 @@ Some models of Raspberry Pi, including Zero, Compute Module, and Keyboard models The `[none]` filter prevents any settings that follow from being applied to any hardware. Although there is nothing that you can't do without `[none]`, it can be a useful way to keep groups of unused settings in config.txt without having to comment out every line. +[source,ini] +---- +# Bootloader EEPROM config. +# If PM_RSTS is partition 62 then set bootloader properties to disable +# SD high speed and show HDMI diagnostics +# Boot from partition 2 with debug option. +[partition=62] +# Only high (>31) partition can be remapped. +PARTITION=2 +SD_QUIRKS=0x1 +HDMI_DELAY=0 +---- + +Example `config.txt` - (Currently Raspberry Pi 5 onwards) +[source,ini] +---- +# config.txt - If the original requested partition number in PM_RSTS was a +# special number then use an alternate cmdline.txt +[partition=62] +cmdline=cmdline-recovery.txt +---- + +The raw value of the `PM_RSTS` register at bootup is available via `/proc/device-tree/chosen/bootloader/rsts` and the final partition number used for booting is available via `/proc/device-tree/chosen/bootloader/partition`. These are big-endian binary values. + +=== The expression filter + +The expression filter provides support for comparing unsigned integer "boot variables" to constants using a simple set of operators. It is intended to support OTA update mechanisms, debug and test. + +* The "boot variables" are `boot_arg1`, `boot_count`, `boot_partition` and `partition`. +* Boot variables are always lower case. +* Integer constants may either be written as decimal or as hex. +* Expression conditional filters have no side-effects e.g. no assignment operators. +* As with other filter types the expression filter cannot be nested. +* Use the `[all]` filter to reset expressions and all other conditional filter types. + +Syntax: +[source,ini] +---- +# ARG is a boot-variable +# VALUE and MASK are unsigned integer constants +[ARG=VALUE] # selected if (ARG == VALUE) +[ARG&MASK] # selected if ((ARG & VALUE) != 0) +[ARG&MASK=VALUE] # selected if ((ARG & MASK) == VALUE) +[ARGVALUE] # selected if (ARG > VALUE) + +---- + +==== `boot_arg1` +Raspberry Pi 5 and newer devices only. + +The `boot_arg1` variable is a 32-bit user defined value which is stored in a reset-safe register allowing parameters to be passed accross a reboot. + +Setting `boot_arg1` to 42 via `config.txt`: +[source,ini] +---- +set_reboot_arg1=42 +---- +The `set_reboot_arg1` property sets the value for the next boot. It does not change the current value as seen by the config parser. + +Setting `boot_arg1` to 42 via vcmailbox: +[source,console] +---- +sudo vcmailbox 0x0003808c 8 8 1 42 +---- + +Reading `boot_arg1` via vcmailbox: +[source,console] +---- +sudo vcmailbox 0x0003008c 8 8 1 0 +# Example output - boot_arg1 is 42 +# 0x00000020 0x80000000 0x0003008c 0x00000008 0x80000008 0x00000001 0x0000002a 0x0000000 +---- +The value of the `boot_arg1` variable when the OS was started can be read via xref:configuration.adoc#part4[device-tree] at `/proc/device-tree/chosen/bootloader/arg1` + +==== `bootvar0` +Raspberry Pi 5 and newer devices only. + +The `bootvar0` variable is a 32-bit user-defined value that is set through `rpi-eeprom-config`, and then can be used as a conditional variable in `config.txt`. + +For example, setting `bootvar0` to 42 via `rpi-eeprom-config`: +[source,ini] +---- +BOOTVAR0=42 +---- + +Using `bootvar0` conditionally in `config.txt`: +[source,ini] +---- +[bootvar0=42] +arm_freq=1000 +---- + +This allows a common image (that is, with the same `config.txt` file) to support different configurations based on the persistent `rpi-eeprom-config` settings. + +==== `boot_count` +Raspberry Pi 5 and newer devices only. + +The `boot_count` variable is an 8-bit value stored in a reset-safe register that is incremented at boot (wrapping back to zero at 256). It is cleared if power is disconnected. + +To read `boot_count` via vcmailbox: +[source,console] +---- +sudo vcmailbox 0x0003008d 4 4 0 +# Example - boot count is 3 +# 0x0000001c 0x80000000 0x0003008d 0x00000004 0x80000004 0x00000003 0x00000000 +---- + +Setting/clearing `boot_count` via vcmailbox: +[source,console] +---- +# Clear boot_count by setting it to zero. +sudo vcmailbox 0x0003808d 4 4 0 +---- +The value of `boot_count` when the OS was started can be read via xref:configuration.adoc#part4[device-tree] at `/proc/device-tree/chosen/bootloader/count` + +==== `boot_partition` +The `boot_partition` variable can be used to select alternate OS files (e.g. `cmdline.txt`) to be loaded, depending on which partition `config.txt` was loaded from after processing xref:config_txt.adoc#autoboot-txt[autoboot.txt]. This is intended for use with an `A/B` boot-system with `autoboot.txt` where it is desirable to be able to have identical files installed to the boot partition for both the `A` and `B` images. + +The value of the `boot_partition` can be different to the requested `partition` variable if it was overriden by setting `boot_partition` in xref:config_txt.adoc#autoboot-txt[autoboot.txt] or if the specified partion was not bootable and xref:raspberry-pi.adoc#PARTITION_WALK[PARTITION_WALK] was enabled in the EEPROM config. + +Example `config.txt` - select the matching root filesystem for the `A/B` boot file-system: +[source,ini] +---- +# Use different cmdline files to point to different root filesystems based on which partition the system booted from. +[boot_partition=1] +cmdline=cmdline_rootfs_a.txt # Points to root filesystem A + +[boot_partition=2] +cmdline=cmdline_rootfs_b.txt # Points to root filesystem B +---- + +The value of `boot_partition` i.e. the partition used to boot the OS can be read from xref:configuration.adoc#part4[device-tree] at `/proc/device-tree/chosen/bootloader/partition` + +==== `partition` +The `partition` variable can be used to select alternate boot flows according to the requested partition number (`sudo reboot N`) or via direct usage of the `PM_RSTS` watchdog register. + + === The `[tryboot]` filter This filter succeeds if the `tryboot` reboot flag was set. It is intended for use in xref:config_txt.adoc#autoboot-txt[autoboot.txt] to select a different `boot_partition` in `tryboot` mode for fail-safe OS updates. +The value of `tryboot` at the start of boot can be read via xref:configuration.adoc#part4[device-tree] at `/proc/device-tree/chosen/bootloader/tryboot` + === The `[EDID=*]` filter When switching between multiple monitors while using a single SD card in your Raspberry Pi, and where a blank config isn't sufficient to automatically select the desired resolution for each one, this allows specific settings to be chosen based on the monitors' EDID names. @@ -225,5 +365,5 @@ Filters of different types can be combined by listing them one after the other, # settings here apply to all hardware ---- - + Use the `[all]` filter to reset all previous filters and avoid unintentionally combining different filter types. diff --git a/documentation/asciidoc/computers/config_txt/gpio.adoc b/documentation/asciidoc/computers/config_txt/gpio.adoc index 2508cbd06..39d9c64bd 100644 --- a/documentation/asciidoc/computers/config_txt/gpio.adoc +++ b/documentation/asciidoc/computers/config_txt/gpio.adoc @@ -40,3 +40,30 @@ GPIO changes made through this mechanism do not have any direct effect on the ke Note also that there is a delay of a few seconds between power being applied and the changes taking effect - longer if booting over the network or from a USB mass storage device. +=== `enable_jtag_gpio` + +Setting `enable_jtag_gpio=1` selects Alt4 mode for GPIO pins 22-27, and sets up some internal SoC connections, enabling the JTAG interface for the Arm CPU. It works on all models of Raspberry Pi. + +|=== +| Pin # | Function + +| GPIO22 +| `ARM_TRST` + +| GPIO23 +| `ARM_RTCK` + +| GPIO24 +| `ARM_TDO` + +| GPIO25 +| `ARM_TCK` + +| GPIO26 +| `ARM_TDI` + +| GPIO27 +| `ARM_TMS` +|=== + + diff --git a/documentation/asciidoc/computers/config_txt/overclocking.adoc b/documentation/asciidoc/computers/config_txt/overclocking.adoc index 7eeefb8e1..1c7f33910 100644 --- a/documentation/asciidoc/computers/config_txt/overclocking.adoc +++ b/documentation/asciidoc/computers/config_txt/overclocking.adoc @@ -15,7 +15,7 @@ WARNING: Setting any overclocking parameters to values other than those used by | Option | Description | arm_freq -| Frequency of the ARM CPU in MHz. +| Frequency of the Arm CPU in MHz. | arm_boost | Increases `arm_freq` to the highest supported frequency for the board-type and firmware. Set to `1` to enable. @@ -55,9 +55,9 @@ WARNING: Setting any overclocking parameters to values other than those used by | over_voltage_sdram_p | SDRAM phy voltage adjustment. [-16,8] equates to [0.8V,1.4V] with 0.025V steps. Not supported on Raspberry Pi 4 or later devices. - + | force_turbo -| Forces turbo mode frequencies even when the ARM cores are not busy. Enabling this may set the warranty bit if `over_voltage_*` is also set. +| Forces turbo mode frequencies even when the Arm cores are not busy. Enabling this may set the warranty bit if `over_voltage_*` is also set. | initial_turbo | Enables https://forums.raspberrypi.com/viewtopic.php?f=29&t=6201&start=425#p180099[turbo mode from boot] for the given value in seconds, or until `cpufreq` sets a frequency. The maximum value is `60`. The November 2024 firmware update made the following changes: @@ -101,13 +101,17 @@ WARNING: Setting any overclocking parameters to values other than those used by | temp_soft_limit | *3A+/3B+ only*. CPU speed throttle control. This sets the temperature at which the CPU clock speed throttling system activates. At this temperature, the clock speed is reduced from 1400MHz to 1200MHz. Defaults to `60`, can be raised to a maximum of `70`, but this may cause instability. + +| core_freq_fixed +| Setting to 1 disables active scaling of the core clock frequency and ensures that any peripherals that use the core clock will maintain a consistent speed. The fixed clock speed is the higher/turbo frequency for the platform in use. Use this in preference to setting specific core_clock frequencies as it provides portability of config files between platforms. + |=== This table gives the default values for the options on various Raspberry Pi models, all frequencies are stated in MHz. [cols="m,^,^,^,^,^,^,^,^,^,^"] |=== -| Option | Pi 0/W | Pi1 | Pi2 | Pi3 | Pi3A+/Pi3B+ | CM4 & Pi4B <= R1.3 | Pi4B R1.4 | Pi 400 | Pi Zero 2 W | Pi 5 +| Option | Pi Zero W | Pi 1 | Pi 2 | Pi 3 | Pi 3A+/Pi 3B+ | CM4 & Pi 4B <= R1.3 | Pi 4B R1.4 | Pi 400 | Pi Zero 2 W | Pi 5/500/500+ | arm_freq | 1000 @@ -167,7 +171,7 @@ This table gives the default values for the options on various Raspberry Pi mode | 500 | 500 | 300 -| 910 +| 960 | hevc_freq | N/A @@ -335,9 +339,9 @@ NOTE: There is no need to use `hdmi_enable_4kp60` on Flagship models since Raspb ==== `force_turbo` -By default (`force_turbo=0`) the on-demand CPU frequency driver will raise clocks to their maximum frequencies when the ARM cores are busy, and will lower them to the minimum frequencies when the ARM cores are idle. +By default (`force_turbo=0`) the on-demand CPU frequency driver will raise clocks to their maximum frequencies when the Arm cores are busy, and will lower them to the minimum frequencies when the Arm cores are idle. -`force_turbo=1` overrides this behaviour and forces maximum frequencies even when the ARM cores are not busy. +`force_turbo=1` overrides this behaviour and forces maximum frequencies even when the Arm cores are not busy. === Clocks relationship @@ -345,10 +349,10 @@ By default (`force_turbo=0`) the on-demand CPU frequency driver will raise clock The GPU core, CPU, SDRAM and GPU each have their own PLLs and can have unrelated frequencies. The h264, v3d and ISP blocks share a PLL. -To view the Raspberry Pi's current frequency in KHz, type: `cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq`. Divide the result by 1000 to find the value in MHz. Note that this frequency is the kernel _requested_ frequency, and it is possible that any throttling (for example at high temperatures) may mean the CPU is actually running more slowly than reported. An instantaneous measurement of the actual ARM CPU frequency can be retrieved using the vcgencmd `vcgencmd measure_clock arm`. This is displayed in Hertz. +To view the Raspberry Pi's current frequency in KHz, type: `cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq`. Divide the result by 1000 to find the value in MHz. Note that this frequency is the kernel _requested_ frequency, and it is possible that any throttling (for example at high temperatures) may mean the CPU is actually running more slowly than reported. An instantaneous measurement of the actual Arm CPU frequency can be retrieved using the vcgencmd `vcgencmd measure_clock arm`. This is displayed in Hertz. === Monitoring core temperature -[.whitepaper, title="Cooling a Raspberry Pi device", subtitle="", link=https://pip.raspberrypi.com/categories/685-whitepapers-app-notes/documents/RP-003608-WP/Cooling-a-Raspberry-Pi-device.pdf] +[.whitepaper, title="Cooling a Raspberry Pi device", subtitle="", link=https://pip.raspberrypi.com/documents/RP-003608-WP-Cooling-a-Raspberry-Pi-device.pdf] **** This white paper goes through the reasons why your Raspberry Pi may get hot and why you might want to cool it back down, offering options on the cooling process. **** @@ -364,7 +368,7 @@ Divide the result by 1000 to find the value in degrees Celsius. Alternatively, y Hitting the temperature limit is not harmful to the SoC, but it will cause the CPU to throttle. A heat sink can help to control the core temperature, and therefore performance. This is especially useful if the Raspberry Pi is running inside a case. Airflow over the heat sink will make cooling more efficient. -When the core temperature is between 80°C and 85°C, the ARM cores will be throttled back. If the temperature exceeds 85°C, the ARM cores and the GPU will be throttled back. +When the core temperature is between 80°C and 85°C, the Arm cores will be throttled back. If the temperature exceeds 85°C, the Arm cores and the GPU will be throttled back. For the Raspberry Pi 3 Model B+, the PCB technology has been changed to provide better heat dissipation and increased thermal mass. In addition, a soft temperature limit has been introduced, with the goal of maximising the time for which a device can "sprint" before reaching the hard limit at 85°C. When the soft limit is reached, the clock speed is reduced from 1.4GHz to 1.2GHz, and the operating voltage is reduced slightly. This reduces the rate of temperature increase: we trade a short period at 1.4GHz for a longer period at 1.2GHz. By default, the soft limit is 60°C. This can be changed via the `temp_soft_limit` setting in `config.txt`. @@ -374,7 +378,7 @@ It is essential to keep the supply voltage above 4.8V for reliable performance. To monitor the Raspberry Pi's PSU voltage, you will need to use a multimeter to measure between the VCC and GND pins on the GPIO. More information is available in the xref:raspberry-pi.adoc#power-supply[power] section of the documentation. -If the voltage drops below 4.63V (±5%), the ARM cores and the GPU will be throttled back, and a message indicating the low voltage state will be added to the kernel log. +If the voltage drops below 4.63V (±5%), the Arm cores and the GPU will be throttled back, and a message indicating the low voltage state will be added to the kernel log. The Raspberry Pi 5 PMIC has built in ADCs that allow the supply voltage to be measured. To view the current supply voltage, run the following command: diff --git a/documentation/asciidoc/computers/config_txt/what_is_config_txt.adoc b/documentation/asciidoc/computers/config_txt/what_is_config_txt.adoc index e8fc1bf10..9f19a2368 100644 --- a/documentation/asciidoc/computers/config_txt/what_is_config_txt.adoc +++ b/documentation/asciidoc/computers/config_txt/what_is_config_txt.adoc @@ -14,6 +14,8 @@ Changes to `config.txt` only take effect after a reboot. You can view the curren NOTE: Not all config settings can be retrieved using `vcgencmd`. +Some legacy `config.txt` options are no longer officially supported. These are listed in xref:../computers/legacy_config_txt.adoc[Legacy config.txt options] and aren't included in this article. + === File format The `config.txt` file is read by the early-stage boot firmware, so it uses a very simple file format: **a single `property=value` statement on each line, where `value` is either an integer or a string**. Comments may be added, or existing config values may be commented out and disabled, by starting a line with the `#` character. diff --git a/documentation/asciidoc/computers/configuration/boot_folder.adoc b/documentation/asciidoc/computers/configuration/boot_folder.adoc index 98f4c7ff9..472e35b70 100644 --- a/documentation/asciidoc/computers/configuration/boot_folder.adoc +++ b/documentation/asciidoc/computers/configuration/boot_folder.adoc @@ -70,12 +70,12 @@ Various xref:linux_kernel.adoc#kernel[kernel] image files that correspond to Ras | `kernel.img` | BCM2835 -| Pi Zero, Pi 1 +| Pi Zero, Pi 1, CM1 | | `kernel7.img` | BCM2836, BCM2837 -| Pi Zero 2 W, Pi 2, Pi 3 +| Pi Zero 2 W, Pi 2, Pi 3, CM3, Pi 3+, CM3+ | Later revisions of Pi 2 use BCM2837 | `kernel7l.img` @@ -85,12 +85,12 @@ Various xref:linux_kernel.adoc#kernel[kernel] image files that correspond to Ras | `kernel8.img` | BCM2837, BCM2711, BCM2712 -| Pi Zero 2 W, Pi 2 (later revisions), Pi 3, CM3, Pi 3+, CM3+, Pi 4, CM4, CM4S, Pi 400, CM5, Pi 5, Pi 500 +| Pi Zero 2 W, Pi 2 (later revisions), Pi 3, CM3, Pi 3+, CM3+, Pi 4, CM4, CM4S, Pi 400, CM5, Pi 5, Pi 500, Pi 500+ | xref:config_txt.adoc#boot-options[64-bit kernel]. Earlier revisions of Raspberry Pi 2 (with BCM2836) do not support 64-bit kernels. | `kernel_2712.img` | BCM2712 -| Pi 5, CM5, Pi 500 +| Pi 5, CM5, Pi 500, Pi 500+ | Pi 5-optimized xref:config_txt.adoc#boot-options[64-bit kernel]. |=== diff --git a/documentation/asciidoc/computers/configuration/configuring-networking.adoc b/documentation/asciidoc/computers/configuration/configuring-networking.adoc index aea9de820..94b702dc1 100644 --- a/documentation/asciidoc/computers/configuration/configuring-networking.adoc +++ b/documentation/asciidoc/computers/configuration/configuring-networking.adoc @@ -10,7 +10,7 @@ NOTE: Starting with Raspberry Pi OS _Bookworm_, Network Manager is the default n Access Network Manager via the network icon at the right-hand end of the menu bar. If you are using a Raspberry Pi with built-in wireless connectivity, or if a wireless dongle is plugged in, click this icon to bring up a list of available wireless networks. If you see the message 'No APs found - scanning...', wait a few seconds, and Network Manager should find your network. -NOTE: Devices with dual-band wireless automatically disable networking until you assign a wireless LAN country. Flagship models since Raspberry Pi 3B+, Compute Modules since CM4, and Keyboard models support dual-band wireless. To set a wireless LAN country, open the Raspberry Pi Configuration application from the Preferences menu, select *Localisation* and select your country from the menu. +NOTE: Devices with dual-band wireless automatically disable networking until you assign a wireless LAN country. Flagship models since Raspberry Pi 3B+, Compute Modules since CM4, and Keyboard models support dual-band wireless. To set a wireless LAN country, open the Control Centre application from the **Preferences** menu, select *Localisation* and select your country from the menu. image::images/wifi2.png[wifi2] diff --git a/documentation/asciidoc/computers/configuration/device-tree.adoc b/documentation/asciidoc/computers/configuration/device-tree.adoc index 64085ba48..af8aad80b 100644 --- a/documentation/asciidoc/computers/configuration/device-tree.adoc +++ b/documentation/asciidoc/computers/configuration/device-tree.adoc @@ -9,7 +9,7 @@ User-provided parameters in `config.txt` are scanned, along with any overlays an [[part1]] === Device Trees -A Device Tree (DT) is a description of the hardware in a system. It should include the name of the base CPU, its memory configuration, and any peripherals (internal and external). A DT should not be used to describe the software, although by listing the hardware modules it does usually cause driver modules to be loaded. +A Device Tree (DT) is a description of the hardware in a system. It should include the name of the base CPU, its memory configuration, and any peripherals (internal and external). A DT should not be used to describe the software, although by listing the hardware modules it does usually cause driver modules to be loaded. NOTE: It helps to remember that DTs are supposed to be OS-neutral, so anything which is Linux-specific shouldn't be there. @@ -57,13 +57,13 @@ The following is a simple tree in the `.dts` format: This tree contains: * a required header: `/dts-v1/` -* The inclusion of another DTS file, conventionally named `*.dtsi` and analogous to a `.h` header file in C +* The inclusion of another DTS file, conventionally named `*.dtsi` and analogous to a `.h` header file in C * a single root node: `/` * a couple of child nodes: `node1` and `node2` * some children for node1: `child-node1` and `child-node2` * a label (`cousin`) and a reference to that label (`&cousin`) * several properties scattered through the tree -* a repeated node (`/node2`) +* a repeated node (`/node2`) Properties are simple key-value pairs where the value can either be empty or contain an arbitrary byte stream. While data types are not encoded in the data structure, there are a few fundamental data representations that can be expressed in a Device Tree source file. @@ -528,7 +528,7 @@ Each node has the name of an overlay that requires special handling. The propert * `bcm2835` for all Raspberry Pis built around the BCM2835, BCM2836, BCM2837, and RP3A0 SoCs * `bcm2711` for Raspberry Pi 4B, CM4, CM4S, and Pi 400 -* `bcm2712` for Raspberry Pi 5, CM5, and Pi 500 +* `bcm2712` for Raspberry Pi 5, CM5, Pi 500, and Pi 500+ A platform name with no value (an empty property) indicates that the current overlay is compatible with the platform; for example, `uart5` is compatible with the `bcm2711` platform. A non-empty value for a platform is the name of an alternative overlay to use in place of the requested one; asking for `disable-bt` on BCM2712 results in `disable-bt-pi5` being loaded instead. Any platform not included in an overlay's node is not compatible with that overlay. Any overlay not mentioned in the map is assumed to be compatible with all platforms. @@ -725,7 +725,7 @@ dtoverlay= [[part3.3]] ==== Board-specific labels and parameters -Raspberry Pi boards have two I2C interfaces. These are nominally split: one for the ARM, and one for VideoCore (the GPU). On almost all models, `i2c1` belongs to the ARM and `i2c0` to VC, where it is used to control the camera and read the HAT EEPROM. However, there are two early revisions of the Model B that have those roles reversed. +Raspberry Pi boards have two I2C interfaces. These are nominally split: one for the Arm CPU, and one for the VideoCore GPU. On almost all models, `i2c1` belongs to the CPU and `i2c0` to the GPU, where it is used to control the camera and read the HAT EEPROM. However, there are two early revisions of the Model B that have those roles reversed. To make it possible to use one set of overlays and parameters with all Raspberry Pis, the firmware creates some board-specific DT parameters. These are: @@ -833,7 +833,16 @@ For a list of supported overlays and parameters, see the https://github.com/rasp [[part4]] === Firmware parameters -The firmware uses the special https://www.kernel.org/doc/html/latest/devicetree/usage-model.html#runtime-configuration[/chosen] node to pass parameters between the bootloader and/or firmware and the operating system. Each property is stored as a 32-bit integer unless indicated otherwise. +The firmware uses the special https://www.kernel.org/doc/html/latest/devicetree/usage-model.html#runtime-configuration[/chosen] node to pass parameters between the bootloader and/or firmware and the operating system. + +* Each property is stored as a 32-bit unsigned integer unless indicated otherwise. +* Numbers in device-tree are stored in binary and are big-endian. + +Example shell command for reading a 32-bit unsigned integer property: +[source,console] +---- +printf "%d" "0x$(od "/proc/device-tree/chosen/bootloader/partition" -v -An -t x1 | tr -d ' ' )" +---- `overlay_prefix`:: _(string)_ The xref:config_txt.adoc#overlay_prefix[overlay_prefix] string selected by `config.txt`. @@ -845,9 +854,9 @@ The firmware uses the special https://www.kernel.org/doc/html/latest/devicetree/ `rpi-duid`:: _(string)_ Raspberry Pi 5 only. A string representation of the QR code on the PCB. -==== Common bootloader properties `/chosen/bootloader` +`rpi-serial64`:: _(string)_ A string representation of the 64-bit serial number. On flagship models since Raspberry Pi 5 this is same as the normal serial number (`/proc/device-tree/serial-number`). On earlier models the default serial number is still 32-bit but with newer firmware a 64-bit serial number is now available and is visible through this node. -Each property is stored as a 32-bit integer unless indicated otherwise. +==== Common bootloader properties `/chosen/bootloader` `boot-mode`:: The boot-mode used to load the kernel. See the xref:raspberry-pi.adoc#BOOT_ORDER[BOOT_ORDER] documentation for a list of possible boot-mode values. @@ -857,9 +866,17 @@ Each property is stored as a 32-bit integer unless indicated otherwise. `tryboot`:: Set to `1` if the `tryboot` flag was set at boot. +==== Boot variables `/chosen/bootloader` + +Raspberry Pi 5 only. + +`arg1`:: The value of the user defined reboot argument from the previous boot. See xref:config_txt.adoc#boot_arg1[boot_arg1] + +`count`:: The value of the 8-bit `boot_count` variable when the OS was started. See xref:config_txt.adoc#boot_count[boot_count] + ==== Power supply properties `/chosen/power` -Raspberry Pi 5 only. Each property is stored as a 32-bit integer unless indicated otherwise. +Raspberry Pi 5 only. `max_current`:: The maximum current in mA that the power supply can supply. The firmware reports the value indicated by the USB-C, USB-PD or PoE interfaces. For bench power supplies (e.g. connected to the GPIO header) define `PSU_MAX_CURRENT` in the bootloader configuration to indicate the power supply current capability. @@ -896,7 +913,7 @@ The format is defined by the https://usb.org/document-library/usb-power-delivery ==== BCM2711 and BCM2712 specific bootloader properties `/chosen/bootloader` -The following properties are specific to the BCM2711 and BCM2712 SPI EEPROM bootloaders. Each property is stored as a 32-bit integer unless indicated otherwise. +The following properties are specific to the BCM2711 and BCM2712 SPI EEPROM bootloaders. `build_timestamp`:: The UTC build time for the EEPROM bootloader. @@ -957,7 +974,7 @@ The following properties are specific to the BCM2711 and BCM2712 SPI EEPROM boot ==== BCM2711 and BCM2712 USB boot properties `/chosen/bootloader/usb` -The following properties are defined if the system was booted from USB. These may be used to uniquely identify the USB boot device. Each property is stored as a 32-bit integer. +The following properties are defined if the system was booted from USB. These may be used to uniquely identify the USB boot device. `usb-version`:: The USB major protocol version (2 or 3). diff --git a/documentation/asciidoc/computers/configuration/images/blanking.png b/documentation/asciidoc/computers/configuration/images/blanking.png index 6ec7406c7..0ef13f8a6 100644 Binary files a/documentation/asciidoc/computers/configuration/images/blanking.png and b/documentation/asciidoc/computers/configuration/images/blanking.png differ diff --git a/documentation/asciidoc/computers/configuration/images/key.png b/documentation/asciidoc/computers/configuration/images/key.png index ca0c65b11..6469f91fb 100755 Binary files a/documentation/asciidoc/computers/configuration/images/key.png and b/documentation/asciidoc/computers/configuration/images/key.png differ diff --git a/documentation/asciidoc/computers/configuration/images/network-hidden-authentication.png b/documentation/asciidoc/computers/configuration/images/network-hidden-authentication.png index 87f12a9aa..1b6310291 100644 Binary files a/documentation/asciidoc/computers/configuration/images/network-hidden-authentication.png and b/documentation/asciidoc/computers/configuration/images/network-hidden-authentication.png differ diff --git a/documentation/asciidoc/computers/configuration/images/network-hidden.png b/documentation/asciidoc/computers/configuration/images/network-hidden.png index 42d0d7948..1e2964305 100644 Binary files a/documentation/asciidoc/computers/configuration/images/network-hidden.png and b/documentation/asciidoc/computers/configuration/images/network-hidden.png differ diff --git a/documentation/asciidoc/computers/configuration/images/pi-configuration.png b/documentation/asciidoc/computers/configuration/images/pi-configuration.png index c7bee2fad..c5bbf319b 100644 Binary files a/documentation/asciidoc/computers/configuration/images/pi-configuration.png and b/documentation/asciidoc/computers/configuration/images/pi-configuration.png differ diff --git a/documentation/asciidoc/computers/configuration/images/wifi2.png b/documentation/asciidoc/computers/configuration/images/wifi2.png index 536abb0c1..627b04ea9 100755 Binary files a/documentation/asciidoc/computers/configuration/images/wifi2.png and b/documentation/asciidoc/computers/configuration/images/wifi2.png differ diff --git a/documentation/asciidoc/computers/configuration/led_blink_warnings.adoc b/documentation/asciidoc/computers/configuration/led_blink_warnings.adoc index 10eb1c251..5eebc6d7c 100644 --- a/documentation/asciidoc/computers/configuration/led_blink_warnings.adoc +++ b/documentation/asciidoc/computers/configuration/led_blink_warnings.adoc @@ -30,6 +30,10 @@ If a Raspberry Pi fails to boot for some reason, or has to shut down, in many ca | 10 | In HALT state +| 1 +| 2 +| SD card overcurrent detected + | 2 | 1 | Partition not FAT diff --git a/documentation/asciidoc/computers/configuration/raspi-config.adoc b/documentation/asciidoc/computers/configuration/raspi-config.adoc index 7f8a0461e..e20802967 100644 --- a/documentation/asciidoc/computers/configuration/raspi-config.adoc +++ b/documentation/asciidoc/computers/configuration/raspi-config.adoc @@ -5,7 +5,9 @@ === Getting started -To open the configuration tool from the desktop GUI, go to **Preferences** > **Raspberry Pi Configuration**. +To open the configuration tool from the desktop GUI, go to **Preferences** > **Control Centre**. + +NOTE: In previous versions of Raspberry Pi OS, the Control Centre application was called Raspberry Pi Configuration. Alternatively, run the following command to access the configuration tool via the terminal: @@ -14,7 +16,7 @@ Alternatively, run the following command to access the configuration tool via th $ sudo raspi-config ---- -TIP: Some advanced configuration is available in the `raspi-config` CLI, but not the Raspberry Pi Configuration GUI. +TIP: Some advanced configuration is available in the `raspi-config` CLI, but not the Control Centre GUI. To navigate the configuration tool from the terminal: @@ -271,7 +273,7 @@ Pass a wireless network name (SSID) and passphrase, if required. The following f The `` option indicates the visibility of the SSID. If the network broadcasts an open SSID, pass `0` or omit the option. If your SSID is hidden, pass `1`. Defaults to `0`. -The `` option indicates whether you intend to pass the passphrase as plaintext. If your passphrase includes a space or a special character like `!`, you must pass `0` and use quotes around your passphrase. Otherwise, you can pass `1` or omit the option. Defaults to `1`. To pass this option, you must specify a value for ``. +The `` option indicates whether the given passphrase is wrapped in an extra set of quotation marks. Most users can ignore this option: as an implementation detail, `raspi-config` may need to add quotation marks before passing the passphrase to other parts of the system, and a `` value of `0` indicates that the quotation marks are already present. A value of `1` indicates that the quotation marks are not present, and the implementation should add them as necessary. Defaults to `1`. To pass this option, you must specify a value for ``. For example, run the following commands to connect to a: @@ -293,7 +295,14 @@ $ sudo raspi-config nonint do_wifi_ssid_passphrase myssid mypassphrase 1 + [source,console] ---- -$ sudo raspi-config nonint do_wifi_ssid_passphrase myssid "my passphrase" 0 0 +$ sudo raspi-config nonint do_wifi_ssid_passphrase myssid 'my passphrase' +---- + +* non-hidden network named `myssid` with the passphrase `mypassphrase`, where you have already added extra quotes to the passphrase: ++ +[source,console] +---- +$ sudo raspi-config nonint do_wifi_ssid_passphrase myssid '"mypassphrase"' 0 0 ---- ==== Audio diff --git a/documentation/asciidoc/computers/configuration/screensaver.adoc b/documentation/asciidoc/computers/configuration/screensaver.adoc index f12900f3f..6fcd5d42d 100644 --- a/documentation/asciidoc/computers/configuration/screensaver.adoc +++ b/documentation/asciidoc/computers/configuration/screensaver.adoc @@ -1,59 +1,156 @@ == Screen blanking -You can configure your Raspberry Pi to blank the screen after a period of inactivity. By default, Raspberry Pi OS blanks the screen after ten minutes of inactivity when screen blanking is enabled. +You can configure your Raspberry Pi to blank the screen after a period of inactivity. When screen blanking is enabled, Raspberry Pi OS blanks the screen after ten minutes of inactivity by default. +How you manage screen blanking depends on your setup: + +* In the <>, you can configure screen blanking with graphical tools or from the command line. +* In <> (text-only without the desktop), screen blanking is controlled through kernel parameters. + +[[desktop]] === Desktop -You can control screen blanking using the *Screen Blanking* option in the Raspberry Pi Configuration menu. +When running Raspberry Pi OS using the desktop environment, you can control screen blanking through built-in configuration tools: the graphical menu (*Control Centre*) or the command-line interface (*CLI*). -==== Raspberry Pi Configuration +If you aren't running the desktop environment, you can manage screen blanking from the terminal interface on your Raspberry Pi. For instructions, see <>. -Click the Raspberry Pi button in the menu bar. Navigate to *Preferences* > *Raspberry Pi Configuration*. +==== Control Centre -image::images/pi-configuration.png[opening the Raspberry Pi Configuration menu from the desktop] +The *Control Centre* application allows you to turn screen blanking on or off without editing configuration files manually. -Select the *Display* tab. Toggle the *Screen Blanking* radio button into the on position. Press *OK* to confirm your selection. +1. Select the Raspberry Pi icon in the top-left corner of the menu bar. +2. Go to *Preferences > Control Centre*. ++ +image::images/pi-configuration.png[opening the Control Centre application from the desktop] +3. Open the *Display* tab in the *Control Centre* window. +4. Use the toggle to turn on *Screen Blanking*. +5. Select *Close* to confirm your selection. ++ +image::images/blanking.png[toggle Screen Blanking on in the Control Centre application] -image::images/blanking.png[toggle Screen Blanking on in the Raspberry Pi Configuration menu] +NOTE: In previous versions of Raspberry Pi OS, the Control Centre application was called Raspberry Pi Configuration. ==== CLI -You can enable and disable screen blanking with the `raspi-config` CLI tool. Run the following command to open the tool: +If you prefer using the terminal, use the `raspi-config` command-line tool to enable or disable screen blanking. This method is useful when working remotely over SSH or when you want quick access to system settings. -[source,console] ----- -$ sudo raspi-config ----- - -Use the arrow keys to navigate and the *Enter* key to select. Select `Display Options` > `Screen Blanking`. Choose `yes` with the arrow keys to enable screen blanking, or `no` to disable screen blanking. +1. Run the following command to open the tool: `sudo raspi-config`. +2. Navigate with the arrow keys and press **Enter** or **Return** to select `Display Options` *>* `Screen Blanking`. +3. Use the arrow keys on your keyboard to either: + - Choose `yes` to enable screen blanking. + - Choose `no` to disable screen blanking. +[[console]] === Console -The `dpms_timeout` screen blanking configuration used by Raspberry Pi Configuration only affects desktop sessions. In *console mode*, when your Raspberry Pi is connected to a monitor and keyboard with only a terminal for input, use the `consoleblank` setting in the kernel command line. +You can control screen blanking in *console mode* using the `consoleblank` kernel parameter. + +Unlike the screen blanking setting modified by the Control Centre and `raspi-config`, which only affects desktop sessions, the `consoleblank` parameter applies when your Raspberry Pi is running with a monitor and keyboard in a text-only terminal session. By setting `consoleblank` in the kernel command line, you can specify how long the console waits before turning off the screen. ==== Set console mode screen blanking -To change the console mode screen blanking configuration, open `/boot/firmware/cmdline.txt` in a text editor as an administrator: +To change the console mode screen blanking configuration: + +1. Use the following command to open `/boot/firmware/cmdline.txt` in a text editor as an administrator: `sudo nano /boot/firmware/cmdline.txt`. +2. Set the number of seconds before Raspberry Pi OS blanks the console. All parameters must remain on a single line. You can: + * Set how many seconds of inactivity before the screen blanks. For example, adding `consoleblank=600` blanks the screen after 600 seconds of inactivity. + * Add `consoleblank=0` to never blank the screen. +3. Use the following command to reboot the Raspberry Pi: `sudo reboot`. This is a necessary precursor for the changes to take effect. + +After reboot, the console blanking timeout follows your new setting. + +==== View the current screen blanking setting + +You can display the current console blank time (in seconds) with the following command: [source,console] ---- -$ sudo nano /boot/firmware/cmdline.txt +$ cat /sys/module/kernel/parameters/consoleblank ---- -You can adjust the number of seconds before Raspberry Pi OS blanks the console here. For instance, add `consoleblank=600` to disable display output after 600 seconds of inactivity. Set the value to `0` to never blank the screen. +== Custom fullscreen splash image + +You can configure your Raspberry Pi to display a fullscreen splash image during boot instead of the standard console log messages. -Changes to `cmdline.txt` only take effect after a reboot. Use the following command to reboot your Raspberry Pi: +[[file-reqs]] +=== File requirements + +The splash screen image must meet the following criteria: + +* *Maximum dimensions.* 1920 × 1080 pixels. + - If the image is smaller than the screen, the remaining area around your image is filled with a solid color taken from the top-left pixel of your image `(0, 0)`. + - Scaling isn't applied. If the screen is smaller than the image, the image is clipped and centred. +* *Maximum colours.* 224 unique colours. +* *Colour depth.* 24-bit (8 bits per channel, no alpha channel). +* *Format.* Uncompressed TGA. + +You can use ImageMagick's `convert` command to convert an image to the TGA format expected by the kernel. For example, to convert `image.png` to a suitably-formatted `splash-image.tga` file: [source,console] ---- -$ sudo reboot +$ sudo apt install imagemagick +$ convert image.png -colors 224 -depth 8 -type TrueColor -alpha off -compress none -define tga:bits-per-sample=8 splash-image.tga ---- -==== View current screen blanking setting +=== Set up a fullscreen splash image -You can display the current console blank time in seconds with the following command: +There are two ways to enable a fullscreen splash image on your Raspberry Pi. Depending on your technical expertise, you can either: +* <>.* This method is more straightforward, allowing you to enable the splash screen with minimal configuration. You install a pre-made package (`rpi-splash-screen-support`) that automates most of the setup. It copies your image, sets kernel parameters, and configures the system for you. +* <>.* This method is more technical, but gives you control over every step. You manually configure the splash image on the command line and then update your `initramfs` to contain the splash image. + +[[apt-package]] +==== Use the apt package + +Install the `rpi-splash-screen-support` package to simplify the set up of fullscreen splash images. The package provides the `configure-splash` tool, which sets the necessary kernel parameters and updates your `initramfs`. + +1. Install the package using the following command: ++ [source,console] ---- -$ cat /sys/module/kernel/parameters/consoleblank +$ sudo apt install rpi-splash-screen-support +---- +2. After the apt package is installed, run the following command to configure your splash image, replacing `` with the name or path of the image file. This path can be relative or absolute: ++ +[source,console] +---- +$ sudo configure-splash +---- +3. Run the following command to reboot your Raspberry Pi and see the splash image: ++ +[source,console] ---- +$ sudo reboot +---- + +If the image appears upside down when booting, edit the `convert` command in <> to add the `-flip` flag before the `splash-image.tga`. Then run `configure-splash` to update the image with the correct orientation. + +[[cli-splash]] +==== Edit the `cmdline.txt` system file + +The following method requires editing system files and manually updating the `initramfs`. + +1. Use the following command to open `/boot/firmware/cmdline.txt` in a text editor as an administrator: `sudo nano /boot/firmware/cmdline.txt`. +2. Disable on-screen console messages to prevent boot messages from covering your splash image. Edit `cmdline.txt` to remove the following: + - `console=tty1`. + - `quiet` (if present). + - Any references to `plymouth`, such as `plymouth.ignore-serial-consoles`. +3. Edit `cmdline.txt` to add the following parameters: + - `fullscreen_logo_name=logo.tga fullscreen_logo=1` to enable fullscreen splash. + - `vt.global_cursor_default=0` to remove the flashing cursor in the splash image. ++ +Your entry should end with something like the following: ++ +[source] +---- +fullscreen_logo_name=logo.tga fullscreen_logo=1 vt.global_cursor_default=0 +---- +4. Place the image file in the correct location. + - The kernel expects the image file in `/lib/firmware`. + - The TGA file is read from the `initramfs` during boot. + - The filename must match fullscreen_logo_name in `cmdline.txt`. + +For example code for embedding TGA images in `initramfs`, see the https://github.com/raspberrypi/rpi-splash-screen-support/blob/master/configure-splash[Raspberry Pi splash screen support tool] in GitHub. + +NOTE: *Step 2* doesn't prevent `getty` from launching a login prompt. Your splash image appears during boot, but when the system is ready for login, the console takes over, and the splash disappears. `getty` clears the splash screen and writes the login prompt over it when the system is ready. + diff --git a/documentation/asciidoc/computers/configuration/securing-the-raspberry-pi.adoc b/documentation/asciidoc/computers/configuration/securing-the-raspberry-pi.adoc index 530c77786..85a00c8d3 100644 --- a/documentation/asciidoc/computers/configuration/securing-the-raspberry-pi.adoc +++ b/documentation/asciidoc/computers/configuration/securing-the-raspberry-pi.adoc @@ -6,11 +6,11 @@ Here, we describe some common ways to improve the security of your Raspberry Pi. Prefixing a command with `sudo` runs it as a superuser. By default, that does not need a password. However, you can make your Raspberry Pi more secure by requiring a password for all commands run with `sudo`. -To force `sudo` to require a password, edit the `nopasswd` sudoers file for your user account, replacing the `` placeholder in the file name with your username: +To force `sudo` to require a password, edit the `010_pi-nopasswd` sudoers file: [source,console] ---- -$ sudo visudo /etc/sudoers.d/010_-nopasswd +$ sudo visudo /etc/sudoers.d/010_pi-nopasswd ---- Change the `` entry to the following, replacing `` with your username: diff --git a/documentation/asciidoc/computers/configuration/users.adoc b/documentation/asciidoc/computers/configuration/users.adoc index d9f45c13d..7818bd182 100644 --- a/documentation/asciidoc/computers/configuration/users.adoc +++ b/documentation/asciidoc/computers/configuration/users.adoc @@ -36,7 +36,7 @@ To grant the new user necessary permissions, like `sudo`, run the following comm [source,console] ---- -$ sudo usermod -a -G adm,dialout,cdrom,sudo,audio,video,plugdev,games,users,input,netdev,gpio,i2c,spi +$ sudo usermod -a -G adm,dialout,cdrom,sudo,audio,video,plugdev,games,users,input,render,netdev,lpadmin,gpio,i2c,spi ---- To check that the permissions were successfully granted, run the following command, replacing the `` placeholder with the username for the new user: @@ -48,6 +48,13 @@ $ sudo su - If the above command runs successfully, permissions were successfully configured for the user. +If you've changed your keyboard layout, you might find that the newly added user is using the "wrong" keyboard layout. To fix this, sign in as the new user and run: + +[source,console] +---- +$ sudo raspi-config nonint update_labwc_keyboard +---- + === Delete a user To delete a user, run the following command, replacing the `` placeholder with the username you would like to delete: diff --git a/documentation/asciidoc/computers/getting-started/configuring.adoc b/documentation/asciidoc/computers/getting-started/configuring.adoc index 633bca35f..49d7f7d0e 100644 --- a/documentation/asciidoc/computers/getting-started/configuring.adoc +++ b/documentation/asciidoc/computers/getting-started/configuring.adoc @@ -74,6 +74,8 @@ image::images/initial-setup/connect.png[alt="The Enable Raspberry Pi Connect pag Once your Raspberry Pi has internet access, this page helps you update your operating system and software to the latest versions. During the software update process, the wizard will remove the non-default browser if you opted to uninstall it in the browser selection step. Downloading updates may take several minutes. +NOTE: If you are updating your Raspberry Pi 500+ for the first time, this can take up to half an hour. Grab a cup of coffee or go for a walk while you wait. + image::images/initial-setup/update.png[alt="You can download the latest software updates during the wizard before you boot for the first time.",width="80%"] image::images/initial-setup/download.png[alt="You can download the latest software updates during the wizard before you boot for the first time.",width="80%"] diff --git a/documentation/asciidoc/computers/getting-started/images/recommended-software.png b/documentation/asciidoc/computers/getting-started/images/recommended-software.png index 11eb335ed..ea58679d4 100644 Binary files a/documentation/asciidoc/computers/getting-started/images/recommended-software.png and b/documentation/asciidoc/computers/getting-started/images/recommended-software.png differ diff --git a/documentation/asciidoc/computers/getting-started/setting-up.adoc b/documentation/asciidoc/computers/getting-started/setting-up.adoc index 0a3aa35fb..818217aac 100644 --- a/documentation/asciidoc/computers/getting-started/setting-up.adoc +++ b/documentation/asciidoc/computers/getting-started/setting-up.adoc @@ -26,11 +26,15 @@ You can use any high-quality power supply that provides the correct power mode. |Recommended power supply (voltage/current) |Raspberry Pi power supply -|Raspberry Pi 5 +|Raspberry Pi 500+ +|5V/5A +|https://www.raspberrypi.com/products/27w-power-supply/[27W USB-C power supply] + +|Raspberry Pi 5 and Raspberry Pi 500 |5V/5A, 5V/3A limits peripherals to 600mA |https://www.raspberrypi.com/products/27w-power-supply/[27W USB-C power supply] -|Raspberry Pi 4 Model B +|Raspberry Pi 4 Model B and Raspberry Pi 400 |5V/3A |https://www.raspberrypi.com/products/type-c-power-supply/[15W USB-C power supply] @@ -38,7 +42,7 @@ You can use any high-quality power supply that provides the correct power mode. |5V/2.5A |https://www.raspberrypi.com/products/micro-usb-power-supply/[12.5W Micro USB power supply] -|Raspberry Pi 2 (all models) +|Raspberry Pi 2 Model B |5V/2.5A |https://www.raspberrypi.com/products/micro-usb-power-supply/[12.5W Micro USB power supply] @@ -101,22 +105,19 @@ Raspberry Pi models have the following display connectivity: |Model |Display outputs -|Raspberry Pi 5 +|Raspberry Pi 5, Raspberry Pi 400, Raspberry Pi 500, and Raspberry Pi 500+ |2× micro HDMI -|Raspberry Pi 4 (all models) +|Raspberry Pi 4 Model B |2× micro HDMI, audio and composite out via 3.5mm http://en.wikipedia.org/wiki/Phone_connector_(audio)#TRRS_standards[TRRS] jack |Raspberry Pi 3 (all models) |HDMI, audio and composite out via 3.5mm http://en.wikipedia.org/wiki/Phone_connector_(audio)#TRRS_standards[TRRS] jack -|Raspberry Pi 2 (all models) +|Raspberry Pi 2 Model B |HDMI, audio and composite out via 3.5mm http://en.wikipedia.org/wiki/Phone_connector_(audio)#TRRS_standards[TRRS] jack -|Raspberry Pi 1 Model B+ -|HDMI, audio and composite out via 3.5mm http://en.wikipedia.org/wiki/Phone_connector_(audio)#TRRS_standards[TRRS] jack - -|Raspberry Pi 1 Model A+ +|Raspberry Pi 1 (all models) |HDMI, audio and composite out via 3.5mm http://en.wikipedia.org/wiki/Phone_connector_(audio)#TRRS_standards[TRRS] jack |Raspberry Pi Zero (all models) @@ -142,10 +143,11 @@ All variants of the Raspberry Pi 1, 2, 3, and 4 include a 3.5mm auxiliary http:/ The following Raspberry Pi models come with Wi-Fi and Bluetooth connectivity: * Flagship models since Raspberry Pi 3 Model B +* All Keyboard models * All Zero W models * All Pico W models * Compute Modules configured with wireless (available since CM4) -The "Model B" suffix indicates variants with an Ethernet port; "Model A" indicates no Ethernet port. If your Raspberry Pi doesn't have an Ethernet port, you can still connect to a wired internet connection using a USB-to-Ethernet adapter. +The "Model B" suffix indicates variants with an Ethernet port; "Model A" indicates no Ethernet port. The Keyboard models also include an Ethernet port. If your Raspberry Pi doesn't have an Ethernet port, you can still connect to a wired internet connection using a USB-to-Ethernet adapter. image::images/peripherals/cable-net.png[alt="Plugging an Ethernet cable into a Raspberry Pi.",width="80%"] diff --git a/documentation/asciidoc/computers/keyboard-computers.adoc b/documentation/asciidoc/computers/keyboard-computers.adoc new file mode 100644 index 000000000..895b1f658 --- /dev/null +++ b/documentation/asciidoc/computers/keyboard-computers.adoc @@ -0,0 +1 @@ +include::keyboard-computers/intro.adoc[] diff --git a/documentation/asciidoc/computers/keyboard-computers/images/M2-step-1.jpg b/documentation/asciidoc/computers/keyboard-computers/images/M2-step-1.jpg new file mode 100755 index 000000000..06b2f2178 Binary files /dev/null and b/documentation/asciidoc/computers/keyboard-computers/images/M2-step-1.jpg differ diff --git a/documentation/asciidoc/computers/keyboard-computers/images/M2-step-2.jpg b/documentation/asciidoc/computers/keyboard-computers/images/M2-step-2.jpg new file mode 100755 index 000000000..68a806c06 Binary files /dev/null and b/documentation/asciidoc/computers/keyboard-computers/images/M2-step-2.jpg differ diff --git a/documentation/asciidoc/computers/keyboard-computers/images/M2-step-3.jpg b/documentation/asciidoc/computers/keyboard-computers/images/M2-step-3.jpg new file mode 100755 index 000000000..551d9e842 Binary files /dev/null and b/documentation/asciidoc/computers/keyboard-computers/images/M2-step-3.jpg differ diff --git a/documentation/asciidoc/computers/keyboard-computers/images/M2-step-4.jpg b/documentation/asciidoc/computers/keyboard-computers/images/M2-step-4.jpg new file mode 100755 index 000000000..d04bad275 Binary files /dev/null and b/documentation/asciidoc/computers/keyboard-computers/images/M2-step-4.jpg differ diff --git a/documentation/asciidoc/computers/keyboard-computers/images/M2-step-5.jpg b/documentation/asciidoc/computers/keyboard-computers/images/M2-step-5.jpg new file mode 100755 index 000000000..5863f6ab8 Binary files /dev/null and b/documentation/asciidoc/computers/keyboard-computers/images/M2-step-5.jpg differ diff --git a/documentation/asciidoc/computers/keyboard-computers/images/M2-step-6.jpg b/documentation/asciidoc/computers/keyboard-computers/images/M2-step-6.jpg new file mode 100755 index 000000000..025262bbb Binary files /dev/null and b/documentation/asciidoc/computers/keyboard-computers/images/M2-step-6.jpg differ diff --git a/documentation/asciidoc/computers/keyboard-computers/images/M2step1.jpg b/documentation/asciidoc/computers/keyboard-computers/images/M2step1.jpg new file mode 100644 index 000000000..268aefb89 Binary files /dev/null and b/documentation/asciidoc/computers/keyboard-computers/images/M2step1.jpg differ diff --git a/documentation/asciidoc/computers/keyboard-computers/images/M2step2.jpg b/documentation/asciidoc/computers/keyboard-computers/images/M2step2.jpg new file mode 100644 index 000000000..a827e0390 Binary files /dev/null and b/documentation/asciidoc/computers/keyboard-computers/images/M2step2.jpg differ diff --git a/documentation/asciidoc/computers/keyboard-computers/images/M2step3.jpg b/documentation/asciidoc/computers/keyboard-computers/images/M2step3.jpg new file mode 100644 index 000000000..fe68a3042 Binary files /dev/null and b/documentation/asciidoc/computers/keyboard-computers/images/M2step3.jpg differ diff --git a/documentation/asciidoc/computers/keyboard-computers/images/M2step4.jpg b/documentation/asciidoc/computers/keyboard-computers/images/M2step4.jpg new file mode 100644 index 000000000..0037242a6 Binary files /dev/null and b/documentation/asciidoc/computers/keyboard-computers/images/M2step4.jpg differ diff --git a/documentation/asciidoc/computers/keyboard-computers/images/M2step5.jpg b/documentation/asciidoc/computers/keyboard-computers/images/M2step5.jpg new file mode 100644 index 000000000..37d5ae832 Binary files /dev/null and b/documentation/asciidoc/computers/keyboard-computers/images/M2step5.jpg differ diff --git a/documentation/asciidoc/computers/keyboard-computers/images/M2step6.jpg b/documentation/asciidoc/computers/keyboard-computers/images/M2step6.jpg new file mode 100644 index 000000000..73941696b Binary files /dev/null and b/documentation/asciidoc/computers/keyboard-computers/images/M2step6.jpg differ diff --git a/documentation/asciidoc/computers/keyboard-computers/intro.adoc b/documentation/asciidoc/computers/keyboard-computers/intro.adoc new file mode 100644 index 000000000..8337af515 --- /dev/null +++ b/documentation/asciidoc/computers/keyboard-computers/intro.adoc @@ -0,0 +1,734 @@ +Raspberry Pi keyboard computers are complete personal computers built into a keyboard. They include the same system-on-chip (SoC) as Raspberry Pi single-board computers (SBC). Raspberry Pi offers three keyboard computers: + +* *Raspberry Pi 400*, based on Raspberry Pi 4 (4 GB), released 2020. +* *Raspberry Pi 500*, based on Raspberry Pi 5 (8 GB), released 2024. +* *Raspberry Pi 500+*, based on Raspberry Pi 5 (16 GB), released 2025. + +Raspberry Pi keyboard computers come in different regional variants affecting keyboard layout and required power supply. + +== Features + +The features of your Raspberry Pi keyboard computer depend on the model. + +*Raspberry Pi 500* and *Raspberry Pi 500+* are faster than *Raspberry Pi 400* due to the Cortex-A76 CPU, increased RAM, and upgraded GPU. The main differences between the Raspberry Pi 400 keyboard computer and the Raspberry Pi 500 and 500+ keyboard computers are: + +* *Processor.* Raspberry Pi 400 uses Cortex-A72 at 1.8 GHz; both Raspberry Pi 500 and 500+ use Cortex-A76 at 2.4 GHz, providing higher performance and efficiency. +* *Memory (RAM).* Raspberry Pi 400 includes 4 GB of RAM; Raspberry Pi 500 includes 8 GB of RAM; Raspberry Pi 500+ includes 16 GB of RAM, providing smoother multitasking and support for more demanding applications. +* *GPU.* Raspberry Pi 400 includes VideoCore VI at 500 MHz; both Raspberry Pi 500 and 500+ include VideoCore VII at 910 MHz, providing faster graphics and improved video decoding. +* *HDR video.* All Raspberry Pi keyboard computers include two micro-HDMI ports, providing 4K displays, but Raspberry Pi 500 and 500+ also support HDR on HDMI outputs. +* *Power button.* Raspberry Pi 400 doesn't have a power button and is instead turned on and off with a combination of key presses; both Raspberry Pi 500 and 500+ do have a power button. +* *SoC.* Raspberry Pi 400 includes the Broadcom chip, BCM2711; both Raspberry Pi 500 and 500+ use the Broadcom chip, BCM2712, in combination with the RP1 I/O controller. + +Raspberry Pi 500+ offers additional features, including: + +* Mechanical keys with customisable RGB LEDs and replaceable keycaps. For more information, see <>. For instructions, see <> and <>. +* Internal 256 GB M.2 SSD, which is replaceable. This SSD comes installed with Raspberry Pi OS. For instructions, see <>. +* More RAM (16 GB). For a comparison, see the following table. + +[cols="1,1,1,1", options="header"] +|=== +| |Raspberry Pi 400 |Raspberry Pi 500 |Raspberry Pi 500+ + +| *Dimensions* +| 286 × 122 × 23 mm +| 286 × 122 × 23 mm +| 312 × 123 × 35 mm + +| *Keys* +| 78, 79, or 83 membrane keys depending on regional variant +| 78, 79, or 83 membrane keys depending on regional variant +| 84, 85, or 88 mechanical keys depending on regional variant + +| *Processor* +| Quad-core 64-bit Arm processor (Cortex-A72 at 1.8 GHz) +| Quad-core 64-bit Arm processor (Cortex-A76 at 2.4 GHz) +| Quad-core 64-bit Arm processor (Cortex-A76 at 2.4 GHz) + +| *SoC and I/O controller* +| BCM2711 SoC +| BCM2712 SoC and RP1 I/O controller +| BCM2712 SoC and RP1 I/O controller + +| *Memory (RAM)* +| 4 GB synchronous dynamic RAM (SDRAM) +| 8 GB synchronous dynamic RAM (SDRAM) +| 16 GB synchronous dynamic RAM (SDRAM) + +| *GPU* +| VideoCore VI at 500 MHz +| VideoCore VII at 910 MHz +| VideoCore VII at 910 MHz + +| *Video output* +| Two micro-HDMI ports that provide either a single 4K display at 60 Hz or two 4K displays at 30Hz +| Two micro-HDMI ports that provide 4K displays at 60 Hz plus HDR support +| Two micro-HDMI ports that provide 4K displays at 60 Hz plus HDR support + +| *Thermal control* +| Aluminium integrated heatsink +| Aluminium integrated heatsink +| Aluminium integrated heatsink + +| *Wireless connectivity* +| Dual-band Wi-Fi and BLE +| Dual-band Wi-Fi and BLE +| Dual-band Wi-Fi and BLE + +| *USB ports* +| Two USB 3.0 ports; one USB 2.0 port +| Two USB 3.0 ports; one USB 2.0 port +| Two USB 3.0 ports; one USB 2.0 port + +| *Gigabit Ethernet* +| Yes +| Yes +| Yes + +| *GPIO* +| Horizontal 40-pin GPIO header +| Horizontal 40-pin GPIO header +| Horizontal 40-pin GPIO header + +| *Storage* +| microSD card slot +| microSD card slot +| microSD card slot and M.2 SSD drive + +| *Power input* +| 5 V at 3 A (15 W) through USB-C +| 5 V at 5 A (25 W) through USB-C +| 5 V at 5 A (25 W) through USB-C + +| *Power button* +| Key combination (*Fn* + *F10*) +| Dedicated button +| Dedicated button + +| *Customisability* +| +| Key remapping +| Key remapping; RGB backlighting; ability to change keycaps +|=== + +== Keyboard computer kits + +Raspberry Pi keyboard computers are available as standalone keyboards or as part of a kit, including basic accessories to get started. + +=== Raspberry Pi 400 kit + +* Raspberry Pi 400 keyboard computer. +* 15 W Raspberry Pi USB-C power supply. +* Raspberry Pi USB mouse. +* 16 GB microSD card, pre-programmed with Raspberry Pi OS. +* micro-HDMI cable. +* _Beginner's Guide_ book. + +=== Raspberry Pi 500 kit + +* Raspberry Pi 500 keyboard computer. +* 27 W Raspberry Pi USB-C power supply. +* Raspberry Pi USB mouse. +* 32 GB A2-class microSD card, pre-programmed with Raspberry Pi OS. +* micro-HDMI cable. +* _Beginner's Guide_ book. + +=== Raspberry Pi 500+ kit + +* Raspberry Pi 500+ keyboard computer, including an SSD pre-programmed with Raspberry Pi OS. +* 27 W Raspberry Pi USB-C power supply. +* Raspberry Pi USB mouse. +* micro-HDMI cable. +* Spudger (opening tool) for access to the M.2 SSD (also provided with the standalone keyboard). +* Keycap puller for removing keycaps (also provided with the standalone keyboard). +* _Beginner's Guide_ book. + +== Getting started + +To get up and running with your Raspberry Pi keyboard computer, you can follow the instructions at xref:../computers/getting-started.adoc#setting-up-your-raspberry-pi[Getting started with your Raspberry Pi]. + +If you have a Raspberry Pi 500+ or got your 400 or 500 as part of a kit that includes a microSD card pre-programmed with Raspberry Pi OS, you can skip ahead in the instructions to xref:../computers/getting-started.adoc#set-up-your-raspberry-pi[Set up your Raspberry Pi]. + +[[mechanical-keys]] +== Raspberry Pi 500+ mechanical keys + +Each key on Raspberry Pi 500+ has its own mechanical switch underneath the keycap that registers a key press. Raspberry Pi 500+ uses Gateron KS-33 low-profile mechanical switches. By default, Gateron KS-33 switches use coloured stems to indicate switch type (clicky, tactile, or linear). Raspberry Pi 500+ uses clicky Gateron KS-33 switches with a custom grey stem. + +Keycaps attach to the cross-shaped stem on top of the Gateron switches. These switches have Cherry MX-compatible, cross-shaped stems, which is the industry standard. For guidance and instructions on removing and replacing keycaps on your Raspberry Pi 500+, see <> on this page. + +== Raspberry Pi 500+ customisation + +Raspberry Pi 500+ is the most recent keyboard computer. It offers the following customisation options: + +* Replaceable M.2 SSD storage. For instructions, see <>. +* Keycap set changes. For instructions, see <>. +* Backlighting presets, colours, and brightness. For instructions, see <>. + +For more advanced users, Raspberry Pi 500+ also allows: + +* LED configuration beyond the built-in presets. +* On-the-fly key remapping. + +For more information, see <>. + +[[replace-m2]] +=== Replace your M.2 SSD + +You can expand storage capacity by replacing the M.2 SSD in your Raspberry Pi 500+. You can also use this slot to install a different PCIe peripheral. The Raspberry Pi 500+ supports devices that use the M.2 M key edge connector in the form factors 2230, 2242, 2260, and 2280. + +To complete this procedure, you need a cross head screwdriver, a flat head screwdriver, and the provided plastic opening tool (spudger). + +1. *Unscrew the keyboard.* Locate the five screws on the bottom of the keyboard and unscrew them using a cross head screwdriver. Keep the screws in a safe place. ++ +image::images/M2-step-1.jpg[alt="Unscrew keyboard"] + +2. *Loosen the top of the keyboard from the bottom of the keyboard.* Position the spudger into the indentation at the front of the keyboard and then angle the spudger upwards to start splitting the keyboard. ++ +image::images/M2-step-2.jpg[alt="Spudger"] + +3. *Detach the top of the keyboard from the bottom of the keyboard.* Wedge and swipe the spudger along the opening groove at the front of the keyboard to detach the top of the keyboard from the bottom. ++ +image::images/M2-step-3.jpg[alt="Slide spudger along groove"] + +4. *Open the keyboard.* Place the bottom of the keyboard on a flat surface and fold (don't lift) the top of the keyboard over to lay it face down on the same surface. Be careful not to pull the top and bottom parts away from each other entirely because they're attached with a flexible cable. ++ +image::images/M2-step-4.jpg[alt="Fold open the keyboard"] + +5. *Release the M.2 SSD.* By hand or with a flat head screwdriver, turn the screw on the right side of the M.2 SSD anticlockwise to loosen it. Remove the screw and keep it in a safe place. The M.2 SSD springs up when you remove the screw. ++ +image::images/M2-step-5.jpg[alt="Fold open the keyboard"] + +6. *Pull out the M.2 SSD.* Pull the M.2 SSD away from and then out of the keyboard. ++ +image::images/M2-step-6.jpg[alt="Pull out M.2 SSD"] + +7. *Add a new M.2 SSD.* Insert another M.2 SSD by sliding it into the slot at the left side. The SSD card fits in only one orientation. Hold the newly inserted M.2 SSD down and replace the screw on the right side of it, turning the screw clockwise to tighten. +8. *Close the keyboard.* Fold the top of the keyboard back onto the bottom of the keyboard and click it back into place. +9. *Screw the keyboard shut.* Place and turn the five screws back into place with your cross head screwdriver. + +[[replace-keycaps]] +=== Change your keycaps + +You can swap out the default keycaps on your Raspberry Pi 500+ for custom sets. Because the Gateron KS-33 switches on Raspberry Pi 500+ use the industry standard Cherry MX stem shape, most third-party keycaps that are designed for Cherry MX are compatible. Avoid taller profiles that could hit the keyboard frame or produce too much noise. For more guidance on choosing alternative keycaps, see <>, <>, and <> in this section. + +To remove a keycap: + +1. Insert the prongs of the keycap puller on opposite sides of a keycap that you want to remove or replace. Allow the prongs to fall below the keycap. +2. Press the sides of the prongs to grip the keycap, ensuring equal pressure on both sides. +3. Gently pull the keycap straight up off of the keyboard. Avoid pulling at an angle. + +NOTE: You can also remove keycaps to allow you to clean underneath them. + +You can now replace the keycap with another one, or reinstall the same keycap in its original place: + +1. Align the keycap by lining up its cross-shaped stem underneath it with the cross-shaped stem on the corresponding switch. +2. Press the keycap down gently but firmly until the keycap is fully seated and feels secure. + +[[layout]] +==== Keyboard layout + +Keycaps are available in various languages, with US layouts being the most widely available, followed by UK layouts. Other languages can be harder to source. + +The Raspberry Pi 500+ keyboard has a modified 75% layout, which means that some keys are non-standard and might not have matching keycaps in typical sets: + +* *Power key.* The power key in the top-right corner of the keyboard might not be included in other keycap sets. +* *Lighting labels.* The lighting labels on the *F4*, *F5*, and *F6* keys of Raspberry Pi 500+ are non-standard. +* *Volume labels.* The volume labels on the *F10*, *F11*, and *F12* keys of Raspberry Pi 500+ are non-standard. +* *System Request key.* The *SysRq* key on Raspberry Pi 500+ is non-standard. +* *Insert key.* The *Ins* key on Raspberry Pi 500+ is non-standard. +* *Command key.* The *Cmd* key typically says *Win* on keycap sets, and third-party keycap sets don't include the Raspberry Pi logo. + +[[profiles]] +==== Keycap profiles + +The low-profile keycaps included on Raspberry Pi 500+ perform like traditional mechanical keys while also keeping the keyboard compact. We recommend *DSA* or *Cherry* profiles for replacement keycaps: + +* *DSA* keycaps have a flat profile and can be swapped across rows. +* *Cherry* keycaps are generally compatible, but have different sculpted profiles for ergonomics. This means that each row can have a slightly different height or angle. For a consistent feel, check row alignment. + +NOTE: *XDA*, *OEM*, and *SA* keycaps aren't recommended because they're taller, and can therefore produce more noise or come into contact with the keyboard frame. + +[[lighting]] +==== Lighting + +The LEDs on the Raspberry Pi 500+ keyboard light the top half of the keycaps, which means that fully opaque keycaps might block illumination. + +[[backlighting]] +=== Customise your backlighting + +Raspberry Pi 500+ has most backlighting turned off by default. The only lighting that's enabled by default includes: + +* The activity LED behind the power button when the Raspberry Pi 500+ keyboard is on. This LED: + - Is red when Raspberry Pi 500+ is receiving power but is turned off. + - Is green when Raspberry Pi 500+ is turned on. + - Blinks with SD card activity. +* The rainbow lighting animation that travels through the keys when you start up the Raspberry Pi 500+ keyboard. Advanced users can turn this off for particular backlighting presets using the configuration software. For more information, see <> in <>. +* The Caps Lock indicator that lights up when active. + +Raspberry Pi 500+ supports other RGB backlighting presets, powered by https://github.com/raspberrypi/vial-qmk[Vial QMK firmware]. For instructions, see <>. + +[[choose-presets]] +==== Choose backlight preset + +Raspberry Pi 500+ comes with seven presets, which are the saved lighting profiles on your Raspberry Pi 500+ keyboard. To cycle forwards through these presets, press *Fn* + *F4* on the keyboard; to cycle backwards through these presets, press *Fn* + *Shift* + *F4* on the keyboard. + +[cols="1,5,16", options="header"] +|=== + +| |Preset name |Description + +| *0* +| *Off* +| The default preset that only lights the power key, the startup animation, and the Caps Lock indicator. + +| *1* +| *Solid Colour White* +| Solid white backlight. + +| *2* +| *Solid Colour* +| Solid colour backlight, which you can change using *Fn* + *F3*. + +| *3* +| *Gradient Left Right* +| Fixed rainbow backlight. + +| *4* +| *Cycle Pinwheel* +| Animated rainbow backlight, where the keys cycle through different colours in a rainbow pattern across the keyboard. + +| *5* +| *Typing Heatmap* +| The more you press a key, the closer to red it gets and the more the keys around it light up. + +| *6* +| *Solid Reactive Simple* +| Reactive keyboard, where the keys light up when you press them. You can choose which colour using *Fn* + *F3*. +|=== + +[[backlight-controls]] +==== Backlight controls + +You can customise the RGB backlighting colour (depending on the preset) and brightness using the following keyboard shortcuts: + +* *Change colour.* Press *Fn* + *F3* to cycle forwards through 16 backlight colours; press *Fn* + *Shift* + *F3* to cycle backwards through the colours. +* *Adjust brightness.* Press *Fn* + *F5* to reduce the brightness; press *Fn* + *F6* to increase the brightness. + +NOTE: The *Shift* key on your keyboard either cycles backwards through available options, or inverts the key function. For example, *Fn* + *Shift* + *F5* increases the brightness instead of decreasing it. + +[[advanced]] +== Advanced software settings + +Raspberry Pi offers firmware that controls the built-in keyboard on Raspberry Pi 500 and 500+. With this tool, you can: + +* Enable and configure advanced LED settings for Raspberry Pi 500+. For more information, see <>. +* Remap keys on both Raspberry Pi 500 and 500+. For more information, see <>. +* Play a Flappy Bird-style game on Raspberry Pi 500+. For information, see <>. + + +For more information and options beyond those described in this page, see the https://github.com/raspberrypi/rpi-keyboard-config/blob/main/README.md[README for the configurator tool] on GitHub. + +=== Firmware setup + +To use software-controlled lighting and to remap keys, you must first update the keyboard firmware and install the configuration tool: + +. Install the firmware update package. Run the following command: `sudo apt install rpi-keyboard-fw-update`. +. Update to the latest keyboard firmware update, which checks for and installs the firmware required for advanced functionality. Run the following command: `sudo rpi-keyboard-fw-update`. +. Install the configuration tool, which allows you to adjust LEDs and remap keys. Run the following command: `sudo apt install rpi-keyboard-config`. + +You can see the keyboard firmware source code in the https://github.com/raspberrypi/vial-qmk[Vial QMK] repository on GitHub. + +=== Basic information commands + +Use the following commands as appropriate to view the current state of your keyboard computer before customising its lighting or remapping its keys. + +[cols="3,5", options="header"] +|=== +|Command|Description + +| `rpi-keyboard-config info --ascii`|View keyboard model, lock status, and layout diagram. If you don't need the layout diagram, remove `--ascii` from the command. + +| `rpi-keyboard-config help`|List all available commands with brief descriptions. + +| `rpi-keyboard-config list-effects`|List all available lighting effects, which can be applied temporarily or to a preset. + +|`rpi-keyboard-config preset get`|List all current presets, numbered 0 to 6. + +|=== + +[[advanced-led]] +=== Advanced LED settings + +Advanced users can customise Raspberry Pi 500+ backlighting beyond the basic presets. Specifically, the `rpi-keyboard-config` software allows you to: + +* Add other lighting effects to your Raspberry Pi 500+, temporarily or as presets. For information, see <>. +* Set a different startup animation for each preset. For information, see <>. +* Add speed, saturation, and hue parameters to an effect or preset. For information, see <>. +* Control global hue and brightness. For information, see <>. +* Control individual LED lighting by configuring and then applying the `direct` effect. For information, see <>. + +NOTE: Advanced LED settings are only available for Raspberry Pi 500+ because only this model of keyboard computer has backlit keys. + +[[effects]] +==== Lighting effects + +You can control Raspberry Pi 500+ backlighting through various effects and parameters. With the exception of the power button, which is unaffected by any effect, keyboard lighting effects are controlled through the configuration software. With this software, you can: + +* Temporarily apply an effect to the keyboard until you shut down and restart the keyboard, or until you start to cycle through the presets again. Cycling through the presets continues from the last preset before you applied a temporary effect. +* Assign an effect to one of the seven keyboard presets. The default presets are listed in <>. You can also add parameters and startup animations to presets. + +Use the following commands to choose, apply, and view a temporary effect on your keyboard. + +[cols="2,3", options="header"] +|=== +|Command|Description + +| `rpi-keyboard-config list-effects`|List available lighting effects. + +| `rpi-keyboard-config effect "effect-name"`|Temporarily apply an effect, replacing `effect-name` with the name of the effect, as listed in the output of the previous command. + +| `rpi-keyboard-config effect`|View the currently active effect. + +|=== + +You can also adjust the following parameters for an effect: speed, saturation, and hue. For example, the following command changes the speed of the `"Cycle Spiral"` effect to 42. + +[source,console] +---- +$ rpi-keyboard-config effect "Cycle Spiral" --speed 42 +---- + +Any parameter you add must be a number between 0 and 255. For more information about these parameters, including when they are and aren't useful to add, see <>. + +[[view-presets]] +==== View presets + +You can use the configuration software to check which preset you're on, move between them, or see details about each one. Each preset has an index number between 0 and 6, representing the seven available slots. + +[cols="1,1,1", options="header"] +|=== +|Command|Description|Example (assuming default presets) + +| `rpi-keyboard-config preset index`|Show the index of the current preset.|If you're currently on the *Gradient Left Right* preset, this command tells you that you're on preset 3. + +| `rpi-keyboard-config preset index X`|Skip to a different position in the preset cycle, where `X` is the index of the preset (a number between `0` and `6`).|The following command takes you to the *Typing Heatmap* preset: +`rpi-keyboard-config preset index 5`. + +| `rpi-keyboard-config preset get`|List all current presets.|This command lists the seven presets, numbered 0 to 6. Default presets are summarised in <>. + +| `rpi-keyboard-config preset get X`|Show details about a specific preset, where `X` is the index of the preset (a number between `0` and `6`). |The following command tells you that preset 5 is the *Typing Heatmap* preset: +`rpi-keyboard-config preset get 5`. + +|=== + +[[reassign]] +==== Reassign presets + +You can reassign presets to use different effects. For information about effects, including how to obtain a list of available effects, see <>. + +NOTE: Changes you make to presets persist every time you restart your Raspberry Pi 500+. You can reset your presets to default at any time using the instructions in <>. + +The following example changes the *Gradient Left Right* (`3`) preset to an effect that you specify in the quotation marks. + +[source,console] +---- +$ rpi-keyboard-config preset set 3 "effect-name" +---- + +While reassigning a preset, you can add one or more of the following parameters: speed, hue, or saturation. You can also set a specific startup animation for that preset. For information about these options, see <> and <>. + +For example, the following command replaces the default *Gradient Left Right* preset with the *Rainbow Beacon* effect at a speed of 140. It would also replace the default startup animation for that preset so that the startup animation finishes on white LEDs and then fades into the *Rainbow Beacon* effect. + +[source,console] +---- +$ rpi-keyboard-config preset set 3 "Rainbow Beacon" --speed 140 --startup-animation "START_ANIM_W_FADE_SAT" +---- + +[[startup]] +==== Change preset startup animation + +For each preset, you can specify a startup animation with the following command: + +[source,console] +---- +$ --startup-animation "name_of_animation" +---- + +Replace `name_of_animation` with one of the following five possible startup animations: + +[cols="1,3", options="header"] +|=== +|Startup animation name|Description + +|`START_ANIM_NONE`|No startup animation. + +|`START_ANIM_B_NO_FADE`|Pulsing rainbow animation followed by blank LEDs and then immediately into the chosen effect. + +|`START_ANIM_B_FADE_VAL`|Pulsing rainbow animation followed by blank LEDs fading into the chosen effect. This is the *default* startup animation. + +|`START_ANIM_W_NO_FADE`|Pulsing rainbow animation followed by white LEDs and then immediately into the chosen effect. + +|`START_ANIM_W_FADE_SAT`|Pulsing rainbow animation followed by white LEDs fading into the chosen effect. + +|=== + +For example, the following command would replace the startup animation for preset 3 with a pulsing rainbow animation that finishes on white LEDs and then fades into the preset: + +[source,console] +---- +$ rpi-keyboard-config preset set 3 --startup-animation "START_ANIM_W_FADE_SAT" +---- + +[[parameters]] +==== Effect and preset parameters + +You can add the following speed, saturation, and hue parameters to any effect or preset: + +* *Speed.* To set the speed, add `--speed X` to the command, where `X` is a number between 0 and 255. If you don't add the speed parameter, the default speed is 128. +* *Saturation.* To set the saturation, add `--sat X` to the command, where `X` is a number between 0 and 255. If you don't add the saturation parameter, the default is 255 (maximum saturation). +* *Hue.* To set the hue, add `--hue X` to the command, where `X` is a number between 0 and 255. If you don't set a hue, the default is to use the global hue of the keyboard, which is set with *Fn + F3* on the keyboard. For more information, see <>. + +Some effects and presets are unaffected by some parameters. For example, a solid colour is a static effect and so isn't affected by a speed change. + +[[global-lighting]] +==== Global lighting controls + +Hue and brightness are managed on a range of 0 to 255. You can view and set the hue and brightness of your Raspberry Pi 500+ by adding `hue` and `brightness` to the `rpi-keyboard-config` command. + +[cols="2,3", options="header"] +|=== +|Command|Description + +| `rpi-keyboard-config hue`|Show the current global hue (colour) of your Raspberry Pi 500+. + +| `rpi-keyboard-config hue X`|Set the global hue, where `X` is a number between 0 and 255. + +| `rpi-keyboard-config brightness`|Show the current lighting brightness of your Raspberry Pi 500+. + +| `rpi-keyboard-config brightness X`|Set the lighting brightness, where `X` is a number between 0 and 255. +|=== + +[[direct]] +==== Individual LED controls + +You can customise the backlighting of individual LEDs on your Raspberry Pi 500+. This is useful for precise visual tweaks and for creating unique backlight patterns. + +All the individual LED customisations that you can make are applied to an effect called `direct`. You then apply the `direct` effect either: + +* Temporarily using the instructions in <>. +* By assigning it to a preset using the instructions on <>. + +If the `direct` effect is not already applied by one of the preceding methods, it is automatically temporarily applied when running any of the individual LED customisations. + +The following table lists commands to set LED colours (globally or for each LED), and save and load LED configurations. + +[cols="2,3", options="header"] +|=== +|Command|Description + +| `rpi-keyboard-config leds clear`|Turn off all LEDs except the power button. + +| `rpi-keyboard-config leds set --colour `|Specify the colour of all the LEDs. Replace `` with either with the common colour name (for example, `red`), HSV numbers ranging from 0 to 255 in quotation marks (for example, `"0,255,255"`), or RGB numbers in quotation marks (for example, `"rgb(255,0,0)"`). + +| `rpi-keyboard-config led set "," --colour `|Specify the colour of a specific LED, where the LED is the row and column co-ordinates (`","`). You can check the LED row and column co-ordinates, as well as what each of the keys is currently set to, with the following command: `rpi-keyboard-config info --ascii`. + +|`rpi-keyboard-config leds save`|Save your LED configuration. To use the saved configuration, you can then either assign the `direct` effect to a preset using the instructions in <>, or load the configuration directly using the `load` command, below. + +|`rpi-keyboard-config leds load`|Temporarily apply the `direct` effect to load the saved LED configuration. This is useful if you haven't assigned the `direct` effect to a preset. + +|=== + +In the following example, the specific LED referenced by the row and column co-ordinates (`"2,6"`) is set to green with hue-saturation-value (HSV) numbers (`"85,255,255"`): + +[source,console] +---- +$ rpi-keyboard-config led set "2,6" --colour "85,255,255" +---- + +[[reset-presets]] +==== Reset presets and LED customisations + +The following command resets your presets to the default settings and clears your saved LED customisations: + +[source,console] +---- +$ rpi-keyboard-config reset-presets +---- + +[[remapping]] +=== Remap keys on your keyboard + +Advanced users can remap the keys on both a Raspberry Pi 500 and 500+, allowing you to customise your keyboard layout to match your workflow or gaming needs. + +Use the `rpi-keyboard-config` software to: + +* List all keycodes available for remapping. For information, see <>. +* Check the current keymap. For information, see <>. +* Remap the keys on your keyboard. For information, see <>. +* Watch key presses in the configuration software. For information, see <>. +* Edit up to four key-mapping layers. For information, see <>. +* Reset your keyboard to the default key mapping. For information, see <>. + +The Raspberry Pi 500 and 500+ are compatible with https://get.vial.today/[Vial]. You can use the Vial web UI to remap your keys. For information, see <>. + +[[keycodes]] +==== List keycodes + +To remap your keyboard, you need to know the keycodes for the keys you want to assign on your Raspberry Pi 500 or 500+. The following command lists all possible keycodes: + +[source,console] +---- +$ rpi-keyboard-config list-keycodes +---- + +You can also list only the keycodes in a specific category using `--category`. For example, the following command lists all the keycodes for the `basic` category: + +[source,console] +---- +$ rpi-keyboard-config list-keycodes --category basic +---- + +[[keymap]] +==== View keymap + +Use the following command to see how keys are currently mapped on all positions on your keyboard: + +[source,console] +---- +$ rpi-keyboard-config key get-all +---- + +Use the following command to see the keycode for a specific key at a position that you specify with the key's row and column co-ordinates. Replace `` and `` with the appropriate numbers: + +[source,console] +---- +$ rpi-keyboard-config key get +---- + +NOTE: You can check a key's row-column co-ordinates using `rpi-keyboard-config info --ascii`. This provides a layout diagram of the keyboard. + +For example, to get the keycode for the *Q* key (with the row-column co-ordinates `2 2`) on your keyboard: + +[source,console] +---- +$ rpi-keyboard-config key 2 2 +---- + +[[remap]] +==== Remap keys + +Use the following command to set a different keycode at a position that you specify with the key's row and column. Replace `` and `` with the appropriate numbers, and replace `` with the keycode that you want to map to the specified key. + +[source,console] +---- +$ rpi-keyboard-config key set +---- + +NOTE: You can check a key's row-column co-ordinates using `rpi-keyboard-config info --ascii`. You can check a key's keycode using `rpi-keyboard-config list-keycodes`. + +For example, if you wanted to remap *Q* (with the row-column co-ordinates `2 2`) on your keyboard as *R* (with the keycode `KC_R`): + +[source,console] +---- +$ rpi-keyboard-config key set 2 2 KC_R +---- + +[[watch]] +==== Watch key presses + +You can read the state of keys to monitor key activity inside the configuration tool to tell you which keys are pressed and released. Before you can do this, you must unlock the keyboard. + +To check the lock status of your keyboard: + +[source,console] +---- +$ rpi-keyboard-config info +---- + +To unlock your keyboard so that you can then watch key presses: + +[source,console] +---- +$ rpi-keyboard-config unlock +---- + +The configuration tool guides you through holding down specific keys until a countdown completes. By default, the keys are *Enter* + *Escape*, which light up in red to guide you. If you've remapped these keys, the unlock sequence uses the physical positions of those keys, not their new labels; the command tells you which remapped keys to press for your setup. + +When the keyboard is unlocked, you can monitor key activity with the following command: + +[source,console] +---- +$ rpi-keyboard-config key watch +---- + +This prints to the terminal whenever a key is pressed or released. For LED feedback, the keys on the keyboard also light up red as you press them. To remove the light-up functionality while watching key presses, add `--no-leds` to the above command: + +[source,console] +---- +$ rpi-keyboard-config key watch --no-leds +---- + +Lock your keyboard when you're done. The following `lock` command doesn't require any confirmation; it locks the keyboard immediately. + +[source,console] +---- +$ rpi-keyboard-config lock +---- + +[[layers]] +==== Manage layers + +You can set different key mappings on different layers. There are four layers that you can edit, numbered 0–3; the default layer is 0. By default, the *Fn* key changes the keyboard from layer 0 to layer 1. You can add `--layer` to any of the following commands, as appropriate: + +* `rpi-keyboard-config key get-all` +* `rpi-keyboard-config key get` +* `rpi-keyboard-config key set` + +[[reset-keymap]] +==== Reset to default keyboard layout + +The following command resets your keyboard layout to the default key mappings, including resetting all layers: + +[source,console] +---- +$ rpi-keyboard-config reset-keymap +---- + +[[vial]] +==== Remap keys with Vial + +Vial works with your keyboard firmware to configure your keyboard in real time. + +. On your Raspberry Pi 500 or 500+, go to https://vial.rocks/[Vial web interface]. +. In the window that appears, select your keyboard and click **Connect**. +. Use the Vial web interface to change your key mappings. + +For information about how to use Vial, see the https://get.vial.today/[Vial documentation]. + +NOTE: We recommend that you use Vial only for working with the key mapping and not for customising the RGB LEDs. + +=== Return to default settings + +Your software-controlled preferences are saved in flash memory and persist after reboot and firmware updates. To reset your backlight settings and keyboard layout, wipe the flash area that they're stored in with the following command: + +[source,console] +---- +$ sudo rpi-keyboard-fw-update -w -i +---- + +This clears all customisations and restores the keyboard to default backlighting and key mapping. + +If the keyboard layout has been misconfigured to the extent that input on the Raspberry Pi 500+ is no longer possible, you can still complete a reset to default settings by connecting an external USB keyboard to one of the available USB ports and entering the command from that device instead. + +[[flappy-bird]] +=== Flappy Bird game + +For a bit of fun, the following command allows you to use the keyboard backlighting to play a basic Flappy Bird-style game on Raspberry Pi 500+: + +[source,console] +---- +$ rpi-keyboard-config game +---- + +The game uses your keyboard backlighting as the "screen", and the lights flash in patterns to represent the bird and pipes. Your goal is to keep the bird from hitting pipes, similar to the original Flappy Bird. Press the space bar to fly over pipes (lit-up LEDs). Your "bird" continues to drop until you press the space bar. Your score is determined by the number of pipes you've successfully passed, which is indicated by the number of purple LEDs along the top of the keyboard. + +To exit the game, press *Q* on your keyboard. diff --git a/documentation/asciidoc/computers/legacy_config_txt.adoc b/documentation/asciidoc/computers/legacy_config_txt.adoc index 0b020dad3..e16a75db3 100644 --- a/documentation/asciidoc/computers/legacy_config_txt.adoc +++ b/documentation/asciidoc/computers/legacy_config_txt.adoc @@ -2,8 +2,6 @@ include::legacy_config_txt/legacy.adoc[] include::legacy_config_txt/boot.adoc[] -include::legacy_config_txt/gpio.adoc[] - include::legacy_config_txt/overclocking.adoc[] include::legacy_config_txt/conditional.adoc[] diff --git a/documentation/asciidoc/computers/legacy_config_txt/boot.adoc b/documentation/asciidoc/computers/legacy_config_txt/boot.adoc index b7e735639..a570062de 100644 --- a/documentation/asciidoc/computers/legacy_config_txt/boot.adoc +++ b/documentation/asciidoc/computers/legacy_config_txt/boot.adoc @@ -29,12 +29,6 @@ WARNING: This setting is deprecated. Use `arm_64bit` instead to enable 64-bit ke Sets board-specific control bits. -=== `armstub` - -`armstub` is the filename on the boot partition from which to load the ARM stub. The default ARM stub is stored in firmware and is selected automatically based on the Raspberry Pi model and various settings. - -The stub is a small piece of ARM code that is run before the kernel. Its job is to set up low-level hardware like the interrupt controller before passing control to the kernel. - === `arm_peri_high` Set `arm_peri_high` to `1` to enable high peripheral mode on Raspberry Pi 4. It is set automatically if a suitable DTB is loaded. @@ -75,17 +69,6 @@ The `boot_delay_ms` command means wait for a given number of milliseconds in `st On the Raspberry Pi 4B, if this value is set to `0` then the interrupts will be routed to the Arm cores using the legacy interrupt controller, rather than via the GIC-400. The default value is `1`. -[[sha256]] -=== `sha256` - -If set to non-zero, enables the logging of SHA256 hashes for loaded files (the kernel, initramfs, Device Tree .dtb file, and overlays), as generated by the `sha256sum` utility. The logging output goes to the UART if enabled, and is also accessible via `sudo vclog --msg`. This option may be useful when debugging boot problems, but at the cost of potentially adding _many_ seconds to the boot time. Defaults to 0 on all platforms. - -=== `uart_2ndstage` - -Setting `uart_2ndstage=1` causes the second-stage loader (`bootcode.bin` on devices prior to the Raspberry Pi 4, or the boot code in the EEPROM for Raspberry Pi 4 devices) and the main firmware (`start*.elf`) to output diagnostic information to UART0. - -Be aware that output is likely to interfere with Bluetooth operation unless it is disabled (`dtoverlay=disable-bt`) or switched to the other UART (`dtoverlay=miniuart-bt`), and if the UART is accessed simultaneously to output from Linux, then data loss can occur leading to corrupted output. This feature should only be required when trying to diagnose an early boot loading problem. - [[upstream_kernel]] === `upstream_kernel` diff --git a/documentation/asciidoc/computers/legacy_config_txt/gpio.adoc b/documentation/asciidoc/computers/legacy_config_txt/gpio.adoc deleted file mode 100644 index b564be601..000000000 --- a/documentation/asciidoc/computers/legacy_config_txt/gpio.adoc +++ /dev/null @@ -1,28 +0,0 @@ -== Legacy GPIO control -(See also xref:config_txt.adoc#gpio-control[config.txt GPIO control].) - -=== `enable_jtag_gpio` - -Setting `enable_jtag_gpio=1` selects Alt4 mode for GPIO pins 22-27, and sets up some internal SoC connections, enabling the JTAG interface for the Arm CPU. It works on all models of Raspberry Pi. - -|=== -| Pin # | Function - -| GPIO22 -| ARM_TRST - -| GPIO23 -| ARM_RTCK - -| GPIO24 -| ARM_TDO - -| GPIO25 -| ARM_TCK - -| GPIO26 -| ARM_TDI - -| GPIO27 -| ARM_TMS -|=== diff --git a/documentation/asciidoc/computers/legacy_config_txt/memory.adoc b/documentation/asciidoc/computers/legacy_config_txt/memory.adoc index 11996ade0..7edd2327a 100644 --- a/documentation/asciidoc/computers/legacy_config_txt/memory.adoc +++ b/documentation/asciidoc/computers/legacy_config_txt/memory.adoc @@ -50,5 +50,5 @@ The `gpu_mem_1024` command sets the GPU memory in megabytes for Raspberry Pis wi === `disable_l2cache` -Setting this to `1` disables the CPU's access to the GPU's L2 cache and requires a corresponding L2 disabled kernel. Default value on BCM2835 is `0`. On BCM2836, BCM2837, BCM2711, and BCM2712, the ARMs have their own L2 cache and therefore the default is `1`. The standard Raspberry Pi `kernel.img` and `kernel7.img` builds reflect this difference in cache setting. +Setting this to `1` disables the CPU's access to the GPU's L2 cache and requires a corresponding L2 disabled kernel. Default value on BCM2835 is `0`. On BCM2836, BCM2837, BCM2711, and BCM2712, the Arm CPUs have their own L2 cache and therefore the default is `1`. The standard Raspberry Pi `kernel.img` and `kernel7.img` builds reflect this difference in cache setting. diff --git a/documentation/asciidoc/computers/linux_kernel/building.adoc b/documentation/asciidoc/computers/linux_kernel/building.adoc index 6fe3f916f..f659797b6 100644 --- a/documentation/asciidoc/computers/linux_kernel/building.adoc +++ b/documentation/asciidoc/computers/linux_kernel/building.adoc @@ -64,10 +64,10 @@ To prepare the default configuration, run the appropriate commands from the tabl [cols="8,<.^20a,60a"] |=== -| Architecture | Model | Command +| Architecture | Raspberry Pi Model | Command .12+^.^| 64-bit -| Raspberry Pi 3 +| 3 .9+.^| [source,console] ---- @@ -76,16 +76,16 @@ $ KERNEL=kernel8 $ make bcm2711_defconfig ---- | Compute Module 3 -| Raspberry Pi 3+ +| 3+ | Compute Module 3+ -| Raspberry Pi Zero 2 W -| Raspberry Pi 4 -| Pi 400 +| Zero 2 W +| 4 +| 400 | Compute Module 4 | Compute Module 4S -.^| Raspberry Pi 5 +.^| 5 .3+.^| [source,console] ---- @@ -93,11 +93,11 @@ $ cd linux $ KERNEL=kernel_2712 $ make bcm2712_defconfig ---- -| Pi 500 +| 500/500+ | Compute Module 5 .14+^.^| 32-bit -| Raspberry Pi 1 +| 1 .4+.^| [source,console] ---- @@ -110,7 +110,7 @@ $ make bcmrpi_defconfig | Zero W -| Raspberry Pi 2 +| 2 .6+.^| [source,console] ---- @@ -118,14 +118,14 @@ $ cd linux $ KERNEL=kernel7 $ make bcm2709_defconfig ---- -| Raspberry Pi 3 +| 3 | Compute Module 3 -| Raspberry Pi 3+ +| 3+ | Compute Module 3+ | Zero 2 W -| Raspberry Pi 4 +| 4 .4+.^| [source,console] ---- @@ -133,7 +133,7 @@ $ cd linux $ KERNEL=kernel7l $ make bcm2711_defconfig ---- -| Pi 400 +| 400 | Compute Module 4 | Compute Module 4S |=== @@ -296,49 +296,49 @@ Enter the following commands to build the sources and Device Tree files: [cols="8,<.^20a,60a"] |=== -| Target Architecture | Target Model | Command +| Target Architecture | Target Raspberry Pi Model | Command -.10+^.^| 64-bit -| Raspberry Pi 3 +.12+^.^| 64-bit +| 3 .9+.^| [source,console] ---- $ cd linux $ KERNEL=kernel8 $ make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- bcm2711_defconfig ---- -| Raspberry Pi Compute Module 3 -| Raspberry Pi 3+ -| Raspberry Pi Compute Module 3+ -| Raspberry Pi Zero 2 W -| Raspberry Pi 4 -| Raspberry Pi 400 -| Raspberry Pi Compute Module 4 -| Raspberry Pi Compute Module 4S +| Compute Module 3 +| 3+ +| Compute Module 3+ +| Zero 2 W +| 4 +| 400 +| Compute Module 4 +| Compute Module 4S -.^| Raspberry Pi 5 -.1+.^| +.^| 5 +.3+.^| [source,console] ---- $ cd linux $ KERNEL=kernel_2712 $ make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- bcm2712_defconfig ---- - +| 500/500+ +| Compute Module 5 .14+^.^| 32-bit - -| Raspberry Pi 1 +| 1 .4+.^| [source,console] ---- $ cd linux $ KERNEL=kernel $ make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- bcmrpi_defconfig ---- -| Raspberry Pi Compute Module 1 -| Raspberry Pi Zero -| Raspberry Pi Zero W +| Compute Module 1 +| Zero +| Zero W -| Raspberry Pi 2 +| 2 .6+.^| [source,console] ---- @@ -346,13 +346,13 @@ $ cd linux $ KERNEL=kernel7 $ make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- bcm2709_defconfig ---- -| Raspberry Pi 3 -| Raspberry Pi Compute Module 3 -| Raspberry Pi 3+ -| Raspberry Pi Compute Module 3+ -| Raspberry Pi Zero 2 W +| 3 +| Compute Module 3 +| 3+ +| Compute Module 3+ +| Zero 2 W -| Raspberry Pi 4 +| 4 .4+.^| [source,console] ---- @@ -360,9 +360,9 @@ $ cd linux $ KERNEL=kernel7l $ make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- bcm2711_defconfig ---- -| Raspberry Pi 400 -| Raspberry Pi Compute Module 4 -| Raspberry Pi Compute Module 4S +| 400 +| Compute Module 4 +| Compute Module 4S |=== [[cross-compiled-customisation]] diff --git a/documentation/asciidoc/computers/os/graphics-utilities.adoc b/documentation/asciidoc/computers/os/graphics-utilities.adoc index b37e8ab81..3c44bfcaf 100644 --- a/documentation/asciidoc/computers/os/graphics-utilities.adoc +++ b/documentation/asciidoc/computers/os/graphics-utilities.adoc @@ -84,7 +84,7 @@ This returns the current frequency of the specified clock. Accepts the following | clock | Description | `arm` -| ARM core(s) +| Arm core(s) | `core` | GPU core diff --git a/documentation/asciidoc/computers/os/images/thonny-venv.png b/documentation/asciidoc/computers/os/images/thonny-venv.png index 5025e4fd2..f255b406e 100644 Binary files a/documentation/asciidoc/computers/os/images/thonny-venv.png and b/documentation/asciidoc/computers/os/images/thonny-venv.png differ diff --git a/documentation/asciidoc/computers/os/playing-audio-and-video.adoc b/documentation/asciidoc/computers/os/playing-audio-and-video.adoc index d6db63ed5..11cc62593 100644 --- a/documentation/asciidoc/computers/os/playing-audio-and-video.adoc +++ b/documentation/asciidoc/computers/os/playing-audio-and-video.adoc @@ -16,7 +16,7 @@ You can also launch VLC from the command line. For the examples below, we used a [source,console] ---- -$ wget --trust-server-names http://rptl.io/big-buck-bunny +$ wget --trust-server-names http://rpltd.co/big-buck-bunny ---- To play the clip in VLC from the command line, run the following command: @@ -62,7 +62,7 @@ For the examples below, we used a short audio clip. To download this clip from R [source,console] ---- -$ wget --trust-server-names http://rptl.io/startup-music +$ wget --trust-server-names http://rpltd.co/startup-music ---- To play the clip in VLC from the command line, run the following command: diff --git a/documentation/asciidoc/computers/os/rpi-os-introduction.adoc b/documentation/asciidoc/computers/os/rpi-os-introduction.adoc index f2ab3376e..10fb0d555 100644 --- a/documentation/asciidoc/computers/os/rpi-os-introduction.adoc +++ b/documentation/asciidoc/computers/os/rpi-os-introduction.adoc @@ -4,6 +4,17 @@ Raspberry Pi OS is a free, Debian-based operating system optimised for the Raspb Because Raspberry Pi OS is derived from Debian, it follows a staggered version of the https://wiki.debian.org/DebianReleases[Debian release cycle]. Releases happen roughly every 2 years. -The latest version of Raspberry Pi OS is based on https://www.raspberrypi.com/news/bookworm-the-new-version-of-raspberry-pi-os/[Debian Bookworm]. The previous version was based on https://www.raspberrypi.com/news/raspberry-pi-os-debian-bullseye/[Debian Bullseye]. +The latest version of Raspberry Pi OS is based on https://www.raspberrypi.com/news/trixie-the-new-version-of-raspberry-pi-os/[Debian Trixie]. The previous version was based on https://www.raspberrypi.com/news/bookworm-the-new-version-of-raspberry-pi-os/[Debian Bookworm]. -You can find images of Raspberry Pi OS at https://www.raspberrypi.com/software/operating-systems/[raspberrypi.com/software/operating-systems/] +== Get Raspberry Pi OS + +Raspberry Pi OS is available through the xref:../computers/getting-started.adoc#raspberry-pi-imager[Raspberry Pi Imager]. +You can also find images of Raspberry Pi OS at https://www.raspberrypi.com/software/operating-systems/[raspberrypi.com/software/operating-systems/]. + +We provide 64- and 32-bit versions of the OS in the following editions: + +* **Raspberry Pi OS with desktop.** This is the default version of Raspberry Pi OS shown in Raspberry Pi Imager. It includes applications such as the Chromium web browser, Firefox web browser, VLC media player, and the Thonny Python environment. +* **Raspberry Pi OS with desktop and recommended software.** This is listed as "Raspberry Pi OS Full" in Raspberry Pi Imager. It also includes the LibreOffice suite, KiCad, a programming environment for Scratch, and many other applications. +* **Raspberry Pi OS Lite.** This version doesn't include a graphical desktop experience. Use it for headless servers and similar use cases. We recommend this version for your Raspberry Pi 1, 2, and Zero computers. + +If you're already running a previous version of Raspberry Pi OS and want to instead use the latest major version, we recommend that you don't perform an in-place upgrade. Instead, start again with a new image. For more information, see <>. \ No newline at end of file diff --git a/documentation/asciidoc/computers/os/updating.adoc b/documentation/asciidoc/computers/os/updating.adoc index 6078bdde6..224762eb3 100644 --- a/documentation/asciidoc/computers/os/updating.adoc +++ b/documentation/asciidoc/computers/os/updating.adoc @@ -160,7 +160,7 @@ $ sudo rpi-update $ sudo reboot ---- -[.whitepaper, title="Updating Raspberry Pi firmware", subtitle="", link=https://pip.raspberrypi.com/categories/685-whitepapers-app-notes/documents/RP-003476-WP/Updating-Pi-firmware.pdf] +[.whitepaper, title="Updating Raspberry Pi firmware", subtitle="", link=https://pip.raspberrypi.com/documents/RP-003476-WP-Updating-Pi-firmware.pdf] **** This whitepaper documents how to update the VideoCore firmware in a Raspberry Pi OS image. **** @@ -175,14 +175,64 @@ $ sudo apt update $ sudo apt install --reinstall raspi-firmware ---- -[NOTE] -==== -If you still run Raspberry Pi OS Bullseye, you must instead reinstall `raspberrypi-kernel` using the following command: +=== Convert Raspberry Pi OS Lite into Raspberry Pi OS Desktop +You can add the packages that turn the Lite version into the Desktop version by using `apt`. + +. Install your preferred desktop windowing system. +* To install Wayland (recommended), run: ++ +[source,console] +---- +$ sudo apt install rpd-wayland-core +---- +* To install X, run: ++ +[source,console] +---- +$ sudo apt install rpd-x-core +---- +. Install the Raspberry Pi theme and Control Centre. ++ +[source,console] +---- +$ sudo apt install rpd-theme +$ sudo apt install rpd-preferences +---- +. Add the applications. ++ +[source,console] +---- +$ sudo apt install rpd-applications +$ sudo apt install rpd-utilities +$ sudo apt install rpd-developer +$ sudo apt install rpd-graphics +---- +. Add the extra features for your chosen windowing system, such as screenshot and remote desktop capabilities. +* For Wayland, run: ++ [source,console] ---- -$ sudo apt install --reinstall libraspberrypi0 libraspberrypi-{bin,dev,doc} raspberrypi-{kernel,bootloader} +$ sudo apt install rpd-wayland-extras ---- +* For X, run: ++ +[source,console] +---- +$ sudo apt install rpd-x-extras +---- +. Restart your Raspberry Pi to enter the desktop environment. ++ +[source,console] +---- +$ sudo reboot +---- + +You now have all the packages that comprise Raspberry Pi OS Desktop. + +If you want to return to the Lite version of Raspberry Pi OS, you can remove these packages. Alternatively, to have the Lite experience without removing the desktop packages you've installed, use xref:../computers/configuration.adoc#raspi-config[raspi-config] to set your Raspberry Pi to boot to the command line. + +You can also install the recommended applications included in Raspberry Pi OS Full by going to your Raspberry Pi main menu and selecting **Preferences > Recommended Software**. + + -Reboot your Raspberry Pi with `sudo reboot` to put these changes into effect. -==== diff --git a/documentation/asciidoc/computers/processors/bcm2711.adoc b/documentation/asciidoc/computers/processors/bcm2711.adoc index 70ea47ee8..4d199dfa7 100644 --- a/documentation/asciidoc/computers/processors/bcm2711.adoc +++ b/documentation/asciidoc/computers/processors/bcm2711.adoc @@ -1,12 +1,12 @@ == BCM2711 -This is the Broadcom chip used in the Raspberry Pi 4 Model B, Compute Module 4, and Pi 400. The architecture of the BCM2711 is a considerable upgrade on that used by the SoCs in earlier Raspberry Pi models. It continues the quad-core CPU design of the BCM2837, but uses the more powerful ARM A72 core. It has a greatly improved GPU feature set with much faster input/output, due to the incorporation of a PCIe link that connects the USB 2 and USB 3 ports, and a natively attached Ethernet controller. It is also capable of addressing more memory than the SoCs used before. +This is the Broadcom chip used in the Raspberry Pi 4 Model B, Compute Module 4, and Pi 400. The architecture of the BCM2711 is a considerable upgrade on that used by the SoCs in earlier Raspberry Pi models. It continues the quad-core CPU design of the BCM2837, but uses the more powerful Arm A72 core. It has a greatly improved GPU feature set with much faster input/output, due to the incorporation of a PCIe link that connects the USB 2 and USB 3 ports, and a natively attached Ethernet controller. It is also capable of addressing more memory than the SoCs used before. -The ARM cores are capable of running at up to 1.5 GHz, making the Raspberry Pi 4 about 50% faster than the Raspberry Pi 3B+. The new VideoCore VI 3D unit now runs at up to 500 MHz. The ARM cores are 64-bit, and while the VideoCore is 32-bit, there is a new Memory Management Unit, which means it can access more memory than previous versions. +The Arm cores are capable of running at up to 1.5 GHz, making the Raspberry Pi 4 about 50% faster than the Raspberry Pi 3B+. The new VideoCore VI 3D unit now runs at up to 500 MHz. The Arm cores are 64-bit, and while the VideoCore is 32-bit, there is a new Memory Management Unit, which means it can access more memory than previous versions. The BCM2711 chip continues to use the heat spreading technology started with the BCM2837B0, which provides better thermal management. -*Processor:* Quad-core https://en.wikipedia.org/wiki/ARM_Cortex-A72[Cortex-A72] (ARM v8) 64-bit SoC @ 1.5 GHz. +*Processor:* Quad-core https://en.wikipedia.org/wiki/ARM_Cortex-A72[Cortex-A72] (Armv8-A) 64-bit SoC @ 1.5 GHz. *Memory:* Accesses up to 8GB LPDDR4-2400 SDRAM (depending on model) diff --git a/documentation/asciidoc/computers/processors/bcm2712.adoc b/documentation/asciidoc/computers/processors/bcm2712.adoc index cc1d56a67..e4a97e657 100644 --- a/documentation/asciidoc/computers/processors/bcm2712.adoc +++ b/documentation/asciidoc/computers/processors/bcm2712.adoc @@ -1,13 +1,13 @@ == BCM2712 -Broadcom BCM2712 is the 16nm application processor used in Raspberry Pi 5, Compute Module 5, and Pi 500. It is the successor to the BCM2711 device used in Raspberry Pi 4, and shares many common architectural features with other devices in the BCM27xx family, used on earlier Raspberry Pi products. +Broadcom BCM2712 is the 16nm application processor used in Raspberry Pi 5, 500, 500+, and Compute Module 5. It is the successor to the BCM2711 device used in Raspberry Pi 4, and shares many common architectural features with other devices in the BCM27xx family, used on earlier Raspberry Pi products. Built around a quad-core Arm Cortex-A76 CPU cluster, clocked at up to 2.4GHz, with 512KB per-core L2 caches and a 2MB shared L3 cache, it integrates an improved 12-core VideoCore VII GPU; a hardware video scaler and HDMI controller capable of driving dual 4Kp60 displays; and a Raspberry Pi-developed HEVC decoder and Image Signal Processor. A 32-bit LPDDR4X memory interface provides up to 17GB/s of memory bandwidth, while ×1 and ×4 PCI Express interfaces support high-bandwidth external peripherals; on Raspberry Pi 5 the latter is used to connect to the Raspberry Pi RP1 south bridge, which provides the bulk of the external-facing I/O functionality on the platform. -Headline features include: +Headline features include: * Quad-core Arm Cortex-A76 @ 2.4GHz -** ARMv8-A ISA +** Armv8-A ISA ** 64KByte I and D caches ** 512KB L2 per core, 2MB shared L3 * New Raspberry Pi-developed ISP @@ -15,7 +15,7 @@ Headline features include: * Improved HVS and display pipeline ** Dual 4Kp60 support * VideoCore V3D VII -** ~2-2.5× faster (more hardware, 1GHz versus 600MHz on Pi 4) +** ~2-2.5× faster (more hardware, 960MHz versus 500MHz on Pi 4) ** OpenGL ES 3.1, Vulkan 1.3 * 4Kp60 HEVC hardware decode ** Other CODECs run in software @@ -24,3 +24,20 @@ Headline features include: ** H264 1080p30 encode (from ISP) ~30–40% CPU In aggregate, the new features present in BCM2712 deliver a performance uplift of 2-3× over Raspberry Pi 4 for common CPU or I/O-intensive use cases. + +=== Vulnerabilities and mitigations + +The Cortex-A76 CPU used in the BCM2712 SoC has known vulnerabilites that are all mitigated in Raspberry Pi OS. + +To determine the full list of vulnerabilities and the mitigations, you can use the following command line which will list all those in place. + +```bash +$ lscpu | grep Vulnerability | grep -v "Not affected" +Vulnerability Spec store bypass: Mitigation; Speculative Store Bypass disabled via prctl +Vulnerability Spectre v1: Mitigation; __user pointer sanitization +Vulnerability Spectre v2: Mitigation; CSV2, BHB +``` + +WARNING: The list above was correct as of April 2025 but may have been superceded. You should use `lscpu` on your Raspberry Pi to get up to date information. This is especially important when using a third-party operating system, as these may not include all the latest mitigations in their Linux kernel builds. The Arm processors used by Raspberry Pi Ltd do not use microcode, so all mitigations are at the kernel level. + +The vulnerability information reported by `lscpu` is based on the currently executing kernel's detection scheme. It may not accurately reflect the true vulnerability status of the hardware, especially if the OS lacks recent kernel updates. Further vulnerability information on the CPU vendor advisories can be obtained from https://developer.arm.com/Arm%20Security%20Center/Speculative%20Processor%20Vulnerability referencing the Vendor ID and Model name reported by `lscpu`. diff --git a/documentation/asciidoc/computers/processors/bcm2836.adoc b/documentation/asciidoc/computers/processors/bcm2836.adoc index 7ae9ceb9b..478a072d7 100644 --- a/documentation/asciidoc/computers/processors/bcm2836.adoc +++ b/documentation/asciidoc/computers/processors/bcm2836.adoc @@ -1,8 +1,10 @@ == BCM2836 -The Broadcom chip used in the Raspberry Pi 2 Model B. The underlying architecture in BCM2836 is identical to BCM2835. The only significant difference is the removal of the ARM1176JZF-S processor and replacement with a quad-core Cortex-A7 cluster. +The Broadcom chip used in early models of Raspberry Pi 2 Model B. The underlying architecture in BCM2836 is identical to BCM2835. The only significant difference is the replacement of the ARM1176JZF-S processor with a quad-core Cortex-A7 cluster. You should refer to: * https://datasheets.raspberrypi.com/bcm2836/bcm2836-peripherals.pdf[BCM2836 ARM-local peripherals] -* http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0464f/index.html[Cortex-A7 MPcore Processor Reference Manual] +* https://developer.arm.com/documentation/ddi0464/f/[Cortex-A7 MPcore Processor Reference Manual] + +IMPORTANT: This SoC is discontinued. Later Raspberry Pi 2 Model B revisions use a different SoC. For more information, see https://pip.raspberrypi.com/documents/RP-004577-PC-1?disposition=inline[Raspberry Pi 2 Model B Product Change Note]. \ No newline at end of file diff --git a/documentation/asciidoc/computers/processors/bcm2837.adoc b/documentation/asciidoc/computers/processors/bcm2837.adoc index 16694e5f9..cd19ee555 100644 --- a/documentation/asciidoc/computers/processors/bcm2837.adoc +++ b/documentation/asciidoc/computers/processors/bcm2837.adoc @@ -1,10 +1,12 @@ == BCM2837 -This is the Broadcom chip used in the Raspberry Pi 3 Model B, later models of the Raspberry Pi 2 Model B, and the Raspberry Pi Compute Module 3. The underlying architecture of the BCM2837 is identical to the BCM2836. The only significant difference is the replacement of the ARMv7 quad core cluster with a quad-core ARM Cortex A53 (ARMv8) cluster. +This is the Broadcom chip used in early models of Raspberry Pi 3 Model B, some models of Raspberry Pi 2 Model B, and Raspberry Pi Compute Module 3. The underlying architecture of the BCM2837 is identical to the BCM2836. The only significant difference is the replacement of the Armv7 quad core cluster with a quad-core Arm Cortex A53 (Armv8) cluster. -The ARM cores run at 1.2GHz, making the device about 50% faster than the Raspberry Pi 2. The VideoCore IV runs at 400MHz. +The Arm cores run at 1.2 GHz, making the device about 50% faster than the Raspberry Pi 2. The VideoCore IV runs at 400 MHz. -Please refer to the following BCM2836 document for details on the ARM peripherals specification, which also applies to the BCM2837. +Please refer to the following BCM2836 document for details on the Arm peripherals specification, which also applies to the BCM2837. -* https://datasheets.raspberrypi.com/bcm2836/bcm2836-peripherals.pdf[BCM2836 ARM-local peripherals] +* https://datasheets.raspberrypi.com/bcm2836/bcm2836-peripherals.pdf[BCM2836 Arm-local peripherals] * https://developer.arm.com/documentation/ddi0500/latest/[Cortex-A53 MPCore Processor Technical Reference Manual] + +IMPORTANT: This SoC is discontinued. Raspberry Pi devices that include this chip are either End-of-Life or use a different SoC. For more information, see https://pip.raspberrypi.com/documents/RP-001029-PC-1?disposition=inline[Raspberry Pi 3 Model B Product Change Notification], https://pip.raspberrypi.com/documents/RP-009284-PC-2?disposition=inline[Raspberry Pi 2 Model B revisions 1.1 and 1.2 Obsolescence Notice 1], and https://pip.raspberrypi.com/documents/RP-009286-PC?disposition=inline[Raspberry Pi Compute Module 3 and Compute Module 3 Lite Obsolescence Notice 2]. \ No newline at end of file diff --git a/documentation/asciidoc/computers/processors/bcm2837b0.adoc b/documentation/asciidoc/computers/processors/bcm2837b0.adoc index 3589bdf10..46edf394e 100644 --- a/documentation/asciidoc/computers/processors/bcm2837b0.adoc +++ b/documentation/asciidoc/computers/processors/bcm2837b0.adoc @@ -1,8 +1,8 @@ == BCM2837B0 -This is the Broadcom chip used in the Raspberry Pi 3 Models A+, B+, and the Raspberry Pi Compute Module 3+. The underlying architecture of the BCM2837B0 is identical to the BCM2837 chip used in other versions of the Raspberry Pi. The ARM core hardware is the same, only the frequency is rated higher. +This is the Broadcom chip used in later models of Raspberry Pi 2 Model B, later models of Raspberry Pi 3 Model B, Raspberry Pi 3 Models A+, B+, and Raspberry Pi Compute Module 3+. The underlying architecture of the BCM2837B0 is identical to the BCM2837 chip used in other versions of the Raspberry Pi. The Arm core hardware is the same; only the frequency is rated higher. -The ARM cores are capable of running at up to 1.4GHz, making the 3B+/3A+ about 17% faster than the original Raspberry Pi 3. The VideoCore IV runs at 400MHz. The ARM core is 64-bit, while the VideoCore IV is 32-bit. +The Arm cores are capable of running at up to 1.4 GHz, making the 3B+ and 3A+ about 17% faster than the original Raspberry Pi 3. The VideoCore IV runs at 400 MHz. The Arm core is 64-bit, while the VideoCore IV is 32-bit. The BCM2837B0 chip is packaged slightly differently to the BCM2837, and most notably includes a heat spreader for better thermals. This allows higher clock frequencies, and more accurate monitoring and control of the chip's temperature. diff --git a/documentation/asciidoc/computers/processors/rp3a0.adoc b/documentation/asciidoc/computers/processors/rp3a0.adoc index 4ec33136a..6faeed7bf 100644 --- a/documentation/asciidoc/computers/processors/rp3a0.adoc +++ b/documentation/asciidoc/computers/processors/rp3a0.adoc @@ -1,6 +1,6 @@ == RP3A0 -The Raspberry Pi RP3A0 is our first System-in-Package (SiP) consisting of a Broadcom BCM2710A1 — which is the silicon die packaged inside the Broadcom xref:processors.adoc#bcm2837[BCM2837] chip which is used on the xref:raspberry-pi.adoc#raspberry-pi-3-model-b-2[Raspberry Pi 3] — along with 512MB of DRAM. +The Raspberry Pi RP3A0 is our first System-in-Package (SiP) consisting of a Broadcom BCM2710A1 — which is the silicon die packaged inside the Broadcom xref:processors.adoc#bcm2837[BCM2837] chip which is used on the xref:raspberry-pi.adoc#raspberry-pi-3-model-b-2[Raspberry Pi 3] — along with 512MB of DRAM. It is used by the xref:raspberry-pi.adoc#raspberry-pi-zero-2-w[Raspberry Pi Zero 2 W]. @@ -8,12 +8,12 @@ image:images/RP3A0-crosssection.png[width="70%"] The RP3A0 is a Quad-core 64-bit Arm Cortex A53 CPU clocked at 1 GHz, although with a heat sink or other cooling solution in place, the chip can be potentially overclocked to 1.2 GHz. -Please refer to the following BCM2836 document for details on the ARM peripherals specification, which also applies to the BCM2837 and RP3A0. +Please refer to the following BCM2836 document for details on the Arm peripherals specification, which also applies to the BCM2837 and RP3A0. -* https://datasheets.raspberrypi.com/bcm2836/bcm2836-peripherals.pdf[BCM2836 ARM-local peripherals] +* https://datasheets.raspberrypi.com/bcm2836/bcm2836-peripherals.pdf[BCM2836 Arm-local peripherals] * https://developer.arm.com/documentation/ddi0500/latest/[Cortex-A53 MPCore Processor Technical Reference Manual] [NOTE] ==== -The original xref:raspberry-pi.adoc#raspberry-pi-zero[Raspberry Pi Zero] uses Package-on-Package (PoP) DRAM, where the DRAM is soldered directly on top of the xref:processors.adoc#bcm2835[BCM2835] chip. +The original xref:raspberry-pi.adoc#raspberry-pi-zero[Raspberry Pi Zero] uses Package-on-Package (PoP) DRAM, where the DRAM is soldered directly on top of the xref:processors.adoc#bcm2835[BCM2835] chip. ==== diff --git a/documentation/asciidoc/computers/raspberry-pi/boot-gpio.adoc b/documentation/asciidoc/computers/raspberry-pi/boot-gpio.adoc index 6545bc3c9..337261155 100644 --- a/documentation/asciidoc/computers/raspberry-pi/boot-gpio.adoc +++ b/documentation/asciidoc/computers/raspberry-pi/boot-gpio.adoc @@ -87,4 +87,4 @@ NOTE: The various boot modes are attempted in the numerical order of the GPIO li SD0 is the Broadcom SD card/MMC interface. When the boot ROM within the SoC runs, it always connects SD0 to the built-in microSD card slot. On Compute Modules with an eMMC device, SD0 is connected to that; on the Compute Module Lite SD0 is available on the edge connector and connects to the microSD card slot in the CMIO carrier board. SD1 is the Arasan SD card/MMC interface which is also capable of SDIO. All Raspberry Pi models with built-in wireless LAN use SD1 to connect to the wireless chip via SDIO. -The default pull resistance on the GPIO lines is 50KΩ, as documented on page 102 of the https://datasheets.raspberrypi.com/bcm2835/bcm2835-peripherals.pdf[BCM2835 ARM peripherals datasheet]. A pull resistance of 5KΩ is recommended to pull a GPIO line up: this will allow the GPIO to function but not consume too much power. +The default pull resistance on the GPIO lines is 50KΩ, as documented on page 102 of the https://datasheets.raspberrypi.com/bcm2835/bcm2835-peripherals.pdf[BCM2835 Arm peripherals datasheet]. A pull resistance of 5KΩ is recommended to pull a GPIO line up: this will allow the GPIO to function but not consume too much power. diff --git a/documentation/asciidoc/computers/raspberry-pi/boot-nvme.adoc b/documentation/asciidoc/computers/raspberry-pi/boot-nvme.adoc index ac29d4d35..6db6a0b27 100644 --- a/documentation/asciidoc/computers/raspberry-pi/boot-nvme.adoc +++ b/documentation/asciidoc/computers/raspberry-pi/boot-nvme.adoc @@ -1,6 +1,6 @@ == NVMe SSD boot -NVMe (Non-Volatile Memory express) is a standard for external storage access over a PCIe bus. You can connect NVMe drives via the PCIe slot on Compute Module 4 IO Board, the M.2 slot on Compute Module 5 IO Board, and Raspberry Pi 5 using an M.2 HAT+. With some additional configuration, you can boot from an NVMe drive. +NVMe (Non-Volatile Memory express) is a standard for external storage access over a PCIe bus. You can connect NVMe drives via the PCIe slot on Compute Module 4 IO Board, the M.2 slot on Compute Module 5 IO Board, and Raspberry Pi 5 using an M.2 HAT+ or M.2 HAT+ Compact. With some additional configuration, you can boot from an NVMe drive. === Prerequisites @@ -8,7 +8,7 @@ NVMe (Non-Volatile Memory express) is a standard for external storage access ove * NVMe M.2 SSD * an adapter to convert from PCIe to an M.2 standard. -** For Raspberry Pi 5, we recommend the xref:../accessories/m2-hat-plus.adoc[M.2 HAT+], which converts from the Raspberry Pi's *PCIe FFC* slot to an M Key interface. +** For Raspberry Pi 5, we recommend the xref:../accessories/m2-hat-plus.adoc[M.2 HAT+ or M.2 HAT+ Compact], which converts from the Raspberry Pi's *PCIe FFC* slot to an M Key interface. ** For the CM4, search for a "PCI-E 3.0 ×1 lane to M.2 NGFF M-Key SSD NVMe PCI Express adapter card" To check that your NVMe drive is connected correctly, boot your Raspberry Pi from another storage device (such as an SD card) and run `ls -l /dev/nvme*`. Example output is shown below. @@ -29,21 +29,14 @@ $ sudo apt update && sudo apt full-upgrade === Edit the bootloader boot priority -Use the Raspberry Pi Configuration CLI to update the bootloader: +Use the Raspberry Pi Software Configuration Tool to update the bootloader: [source,console] ---- $ sudo raspi-config ---- -Under `Advanced Options` > `Bootloader Order`, specify that the bootloader should attempt to boot from `NVMe` first: - -[source,console] ----- -$ sudo rpi-eeprom-update -a ----- - -Then, reboot with `sudo reboot`. Your Raspberry Pi should boot from NVMe. +Under `Advanced Options` > `Boot Order`, specify an option that includes NVMe. It will then write these changes to the bootloader and return to the Config Tool, in which you can `Finish` and reboot. Your Raspberry Pi will use the new boot order now. For CM4, use `rpiboot` to update the bootloader. You can find instructions for building `rpiboot` and configuring the IO board to switch the ROM to usbboot mode in the https://github.com/raspberrypi/usbboot[USB boot GitHub repository]. diff --git a/documentation/asciidoc/computers/raspberry-pi/bootflow-legacy.adoc b/documentation/asciidoc/computers/raspberry-pi/bootflow-legacy.adoc index 29e7c821d..346c513f5 100644 --- a/documentation/asciidoc/computers/raspberry-pi/bootflow-legacy.adoc +++ b/documentation/asciidoc/computers/raspberry-pi/bootflow-legacy.adoc @@ -39,7 +39,7 @@ Next, the boot ROM checks each of the boot sources for a file called `bootcode.b [NOTE] ==== * If there is no SD card inserted, the SD boot mode takes five seconds to fail. To reduce this and fall back to USB more quickly, you can either insert an SD card with nothing on it or use the GPIO bootmode OTP setting described above to only enable USB. -* The default pull for the GPIOs is defined on page 102 of the https://datasheets.raspberrypi.com/bcm2835/bcm2835-peripherals.pdf[ARM Peripherals datasheet]. If the value at boot time does not equal the default pull, then that boot mode is enabled. +* The default pull for the GPIOs is defined on page 102 of the https://datasheets.raspberrypi.com/bcm2835/bcm2835-peripherals.pdf[Arm Peripherals datasheet]. If the value at boot time does not equal the default pull, then that boot mode is enabled. * USB enumeration is a means of enabling power to the downstream devices on a hub, then waiting for the device to pull the D+ and D- lines to indicate if it is either USB 1 or USB 2. This can take time: on some devices it can take up to three seconds for a hard disk drive to spin up and start the enumeration process. Because this is the only way of detecting that the hardware is attached, we have to wait for a minimum amount of time (two seconds). If the device fails to respond after this maximum timeout, it is possible to increase the timeout to five seconds using `program_usb_boot_timeout=1` in `config.txt`. * MSD boot takes precedence over Ethernet boot. * It is no longer necessary for the first partition to be the FAT partition, as the MSD boot will continue to search for a FAT partition beyond the first one. diff --git a/documentation/asciidoc/computers/raspberry-pi/display-parallel-interface.adoc b/documentation/asciidoc/computers/raspberry-pi/display-parallel-interface.adoc index a5d615ee3..7b0b3c396 100644 --- a/documentation/asciidoc/computers/raspberry-pi/display-parallel-interface.adoc +++ b/documentation/asciidoc/computers/raspberry-pi/display-parallel-interface.adoc @@ -1,6 +1,6 @@ == Display Parallel Interface (DPI) -[.whitepaper, title="Using a DPI Display on the Raspberry Pi", subtitle="", link=https://pip.raspberrypi.com/categories/685-whitepapers-app-notes/documents/RP-003471-WP/Using-a-DPI-display.pdf] +[.whitepaper, title="Using a DPI Display on the Raspberry Pi", subtitle="", link=https://pip.raspberrypi.com/documents/RP-003471-WP-Using-a-DPI-display.pdf] **** Display Parallel Interface (DPI) displays can be connected to Raspberry Pi devices via the 40-pin general-purpose input/output (GPIO) connector as an alternative to using the dedicated Display Serial Interface (DSI) or High-Definition Multimedia Interface (HDMI) ports. **** diff --git a/documentation/asciidoc/computers/raspberry-pi/eeprom-bootloader.adoc b/documentation/asciidoc/computers/raspberry-pi/eeprom-bootloader.adoc index c69ff7830..5ad20922a 100644 --- a/documentation/asciidoc/computers/raspberry-pi/eeprom-bootloader.adoc +++ b/documentation/asciidoc/computers/raspberry-pi/eeprom-bootloader.adoc @@ -34,7 +34,7 @@ Default: `0` [[UART_BAUD]] ==== `UART_BAUD` -Raspberry Pi 5 only. +Flagship models since Raspberry Pi 5 only. Changes the baud rate for the bootloader UART. @@ -62,6 +62,15 @@ On Flagship models since Raspberry Pi 5 and Keyboard models since Pi 500, this p Default: `1` on Compute Modules since CM5 and Keyboard models; otherwise `0` +[[WAIT_FOR_POWER_BUTTON]] +==== `WAIT_FOR_POWER_BUTTON` + +Flagship models since Raspberry Pi 5 only. + +If this property and `POWER_OFF_ON_HALT` are both set to `1` then the bootloader will immediately power-off and wait for the power to be pressed on the first boot after the power supply has been removed. This means that instead of booting immediately after power-loss the system will wait for the power button to be pressed. + +Default: `0` + [[BOOT_ORDER]] ==== `BOOT_ORDER` @@ -137,6 +146,31 @@ The `BOOT_ORDER` property defines the sequence for the different boot modes. It | Try NVMe first, followed by USB-MSD then repeat |=== + +[[BOOT_WATCHDOG_TIMEOUT]] +==== `BOOT_WATCHDOG_TIMEOUT` + +If set to a non-zero value (in seconds), enables a hardware watchdog timer in the bootloader. If the OS is not started within the specified time, the watchdog will reset the system. + +The bootloader watchdog is automatically cancelled as soon as the Arm CPU is started. It does **not** monitor the OS after the handover from the bootloader. + +This is useful for unattended or remote systems to ensure recovery from failed boots (e.g. if the OS never loads). + +Default: `0` (disabled) + +[[BOOT_WATCHDOG_PARTITION]] +==== `BOOT_WATCHDOG_PARTITION` + +If the bootloader watchdog triggers, this property specifies the partition number to boot from after the reset. This allows for automatic failover to a recovery or alternate partition. + +If not set, the bootloader will retry the default partition (0). + +You can use this in conjunction with the xref:config_txt.adoc#the-expression-filter[expression filter] to apply different settings or select a different boot flow when the watchdog triggers a reboot to a specific partition. + +See also the xref:raspberry-pi.adoc#PARTITION[PARTITION] property for more information about how to use high partition numbers to detect a watchdog trigger. + +Default: `0` + [[MAX_RESTARTS]] ==== `MAX_RESTARTS` @@ -151,6 +185,38 @@ The number of times that SD boot will be retried after failure before moving to `-1` means infinite retries. +Default: `0` + +[[SD_OVERCURRENT_CHECK]] +==== `SD_OVERCURRENT_CHECK` + +Raspberry Pi 4 Model B, Raspberry Pi 5, Raspberry Pi 500, and Raspberry Pi 500+ only. + +Before booting, the bootloader checks the SD power switch overcurrent signal. The overcurrent signal occurs if the SD card is damaged and has a short circuit which will cause it to get hot. + +If an over-current condition is detected, the bootloader switches off power to the SD card and waits five seconds before probing the SD card again. This error is displayed on the diagnostic screen, the UART and the activity LED (1 long, 2 short flashes). + +The overcurrent check can be switched from an error to a non-blocking warning by setting `SD_OVERCURRENT_CHECK=0` in the bootloader config. + +Default: `1` + + +[[SD_QUIRKS]] +==== `SD_QUIRKS` + +The `SD_QUIRKS` property provides a set of options to support device bringup and workaround interoperability issues. + +The flags are implemented as a bit-field. Undefined bits are reserved for future use and should be set to zero. + +[cols="1m,3"] +|=== +| Value | Behaviour + +| 0x1 +| Disable SD High Speed modes. The card clock is limited to 12.5 MHz +|=== + + Default: `0` [[NET_BOOT_MAX_RETRIES]] @@ -268,7 +334,7 @@ MAC_ADDRESS_OTP=0,1 The first value (row 0 in the example) contains the OUI and the most significant 8 bits of the MAC address. The second value (row 1 in the example) stores the remaining 16-bits of the MAC address. This is the same format as used for the Raspberry Pi MAC address programmed at manufacture. -Any two customer rows may be selected and combined in either order. +Any two customer rows may be selected and combined in either order. The `Customer OTP` rows are OTP registers 36 to 43 in the `vcgencmd otp_dump` output so if the first two rows are programmed as follows then `MAC_ADDRESS_OTP=0,1` would give a MAC address of `e4:5f:01:20:24:7e`. @@ -472,6 +538,19 @@ Max length: 32 characters The `PARTITION` option may be used to specify the boot partition number, if it has not explicitly been set by the `reboot` command (e.g. `sudo reboot N`) or by `boot_partition=N` in `autoboot.txt`. This could be used to boot from a rescue partition if the user presses a button. +The latest firmware also allows high partition numbers (> 31) to be overriden. This allows a custom setup of the system hardware watchdog to trigger a reboot with a special high partition number (e.g. 62) which can be detected by the bootloader (using a conditional filter) and remapped to a recovery partition. + +Example: +[source,ini] +---- +# System watchdog fired - boot the rescue partition with additional options +# Disable SD high speed mode and enable HDMI diagnostics immediately. +[partition=62] +PARTITION=2 +HDMI_DELAY=0 +SD_QUIRKS=1 +---- + [source,ini] ---- # Boot from partition 2 if GPIO 7 is pulled low @@ -481,6 +560,21 @@ PARTITION=2 Default: 0 +[[PARTITION_WALK]] +==== `PARTITION_WALK` +This property is designed to improve the reliability of `A/B` boot schemes using `autoboot.txt` by searching for bootable partitions if the specified partition does not appear to be bootable. If `PARTITION_WALK=1` and the requested partition is not bootable and does not have a valid `autoboot.txt` then the bootloader will check each partition in turn (up to 8 and wrapping to 0) to see if it is bootable (contains `start4.elf` on a Pi4, or `config.txt` and a suitable device-tree on Pi 5 or newer). + +During the "partition walk" `autoboot.txt` files are not processed to avoid cycling dependencies. It is assumed that the requested boot partition has failed and the system is attempting recovery. + +Default: `0` + +[[BOOTVAR0]] +==== `BOOTVAR0` + +Allows setting the conditional variable `bootvar0` used by `config.txt`. See xref:config_txt.adoc#bootvar0[bootvar0]. + +Default: `0` + [[PSU_MAX_CURRENT]] ==== `PSU_MAX_CURRENT` @@ -602,6 +696,42 @@ XHCI_DEBUG=0x3 Default: `0x0` (no USB debug messages enabled) +[[SDRAM_BANKLOW]] +==== `SDRAM_BANKLOW` + +SDRAM_BANKLOW controls how the SDRAM banks are arranged within the system address space. The number of bank bits may be selectively mapped to being located in the MSBs of the address, or being located between the row and column address bits. +This setting can significantly affect SDRAM performance. + +When unset, the bootloader will choose the preferred option. This is currently 3 on Pi 4 family and 1 on Pi 5 family. + +[cols="1m,3"] +|=== +| BANKLOW | Address Bit Mapping + +| 0 +| Address = {bank[3:0], row, column} + +| 1 +| Address = {bank[3:1], row, bank[0], column} + +| 2 +| Address = {bank[3:2], row, bank[1:0], column} + +| 3 +| Address = {bank[3], row, bank[2:0], column} + +| 4 +| Address = {row, bank[3:0], column} +|=== + +This setting also causes the bootloader to add a setting for the number of NUMA regions to be used by the kernel ("numa=fake="). +For best performance these settings should be left as default. + +Note: on a Pi 5 family device, if NUMA is not available in the kernel then performance will be adversely affected. +Manually choosing SDRAM_BANKLOW=3 will mitigate this performance hit, although for highest performance, ensure NUMA is available. + +Default: unset (use bootloader recommended setting) + [[config_txt]] ==== `[config.txt]` section diff --git a/documentation/asciidoc/computers/raspberry-pi/frequency-management.adoc b/documentation/asciidoc/computers/raspberry-pi/frequency-management.adoc index cb57b7099..e71d65294 100644 --- a/documentation/asciidoc/computers/raspberry-pi/frequency-management.adoc +++ b/documentation/asciidoc/computers/raspberry-pi/frequency-management.adoc @@ -34,7 +34,7 @@ Due to possible system stability problems involved with running an undervoltage, NOTE: This setting has been removed on 5-series devices and is effectively always mode 3. -In addition, a more stepped CPU governor is also used to produce finer-grained control of ARM core frequencies, which means the DVFS is more effective. The steps are now 1500MHz, 1000MHz, 750MHz, and 600MHz. These steps can also help when the SoC is being throttled, and mean that throttling all the way back to 600MHz is much less likely, giving an overall increase in fully loaded performance. +In addition, a more stepped CPU governor is also used to produce finer-grained control of Arm core frequencies, which means the DVFS is more effective. The steps are now 1500MHz, 1000MHz, 750MHz, and 600MHz. These steps can also help when the SoC is being throttled, and mean that throttling all the way back to 600MHz is much less likely, giving an overall increase in fully loaded performance. The default CPU governor is `ondemand`. The governor can be manually changed with the `cpufreq-set` command (from the `cpufrequtils` package) to reduce idle power consumption: @@ -65,7 +65,7 @@ To ensure the best performance for your Raspberry Pi, use an active cooling solu For Raspberry Pi 4, add the https://www.raspberrypi.com/products/raspberry-pi-4-case-fan/[Raspberry Pi 4 Case Fan] to the lid of the Raspberry Pi 4 case. -==== Raspberry Pi 5 fans +==== Raspberry Pi 5 fans For Raspberry Pi 5, use one of the official fan options: @@ -84,6 +84,8 @@ As the temperature of the Raspberry Pi 5 increases, the fan reacts in the follow Temperature decreases use the same mapping with a 5°C **hysteresis**; fan speed decreases when the temperature drops to 5°C below each of the above thresholds. +NOTE: The temperature, hysteresis and speed figures given above can be adjusted by using the various `fan_tempN`, `fan_tempN_hyst` and `fan_tempN_speed` dtoverlay settings (where `N` is 0, 1, 2 or 3). See https://github.com/raspberrypi/linux/blob/rpi-6.12.y/arch/arm/boot/dts/overlays/README[the overlays README] for full details. For example, adding `dtparam=fan_temp0=55000` to `/boot/firmware/config.txt` will cause the fan to remain off until the Raspberry Pi 5's temperature reaches 55°C. + At boot the fan is turned on, and the tachometer input is checked to see if the fan is spinning. If it is, then the `cooling_fan` device tree overlay is enabled. This overlay is in `bcm2712-rpi-5-b.dtb` by default, but with `status=disabled`. ==== Raspberry Pi 5 fan connector pinout diff --git a/documentation/asciidoc/computers/raspberry-pi/images/500plus.png b/documentation/asciidoc/computers/raspberry-pi/images/500plus.png new file mode 100644 index 000000000..4a8d2c0f2 Binary files /dev/null and b/documentation/asciidoc/computers/raspberry-pi/images/500plus.png differ diff --git a/documentation/asciidoc/computers/raspberry-pi/images/500plusfront.png b/documentation/asciidoc/computers/raspberry-pi/images/500plusfront.png new file mode 100644 index 000000000..9a7bd7400 Binary files /dev/null and b/documentation/asciidoc/computers/raspberry-pi/images/500plusfront.png differ diff --git a/documentation/asciidoc/computers/raspberry-pi/images/pi_gpio_drive_strength_diagram.png b/documentation/asciidoc/computers/raspberry-pi/images/pi_gpio_drive_strength_diagram.png index c757cb166..ea9e3b165 100644 Binary files a/documentation/asciidoc/computers/raspberry-pi/images/pi_gpio_drive_strength_diagram.png and b/documentation/asciidoc/computers/raspberry-pi/images/pi_gpio_drive_strength_diagram.png differ diff --git a/documentation/asciidoc/computers/raspberry-pi/introduction.adoc b/documentation/asciidoc/computers/raspberry-pi/introduction.adoc index 1058dd9d5..f4ad2bbae 100644 --- a/documentation/asciidoc/computers/raspberry-pi/introduction.adoc +++ b/documentation/asciidoc/computers/raspberry-pi/introduction.adoc @@ -2,19 +2,21 @@ Raspberry Pi makes computers in several different **series**: -* The *Flagship* series, often referred to by the shorthand "Raspberry Pi", offers high-performance hardware, a full Linux operating system, and a variety of common ports in a form factor roughly the size of a credit card. -* The *Keyboard* series, offers high-performance Flagship hardware, a full Linux operating system, and a variety of common ports bundled inside a keyboard form factor. -* The *Zero* series offers a full Linux operating system and essential ports at an affordable price point in a minimal form factor with low power consumption. -* The *Compute Module* series, often referred to by the shorthand "CM", offers high-performance hardware and a full Linux operating system in a minimal form factor suitable for industrial and embedded applications. Compute Module models feature hardware equivalent to the corresponding flagship models, but with fewer ports and no on-board GPIO pins. Instead, users should connect Compute Modules to a separate baseboard that provides the ports and pins required for a given application. +* **<>.** The flagship Raspberry Pi series offers high-performance hardware, a full Linux operating system, and a variety of common ports in a form factor roughly the size of a credit card. +* **<>.** Raspberry Pi keyboard computers combine SBC hardware, a full Linux operating system, and common ports inside a compact keyboard case. +* **<>.** Small and affordable models in a minimal form factor that provide a full Linux operating system and essential ports with low power consumption. +* **<>.** Boards designed for embedded and industrial applications that provide the same hardware as flagship SBCs but in a smaller form factor with no on-board connectors. Instead, they connect to a separate baseboard that supplies the necessary ports and pins. +* **<>.** Small and versatile boards that don't run Linux. Instead of removable storage, programs are flashed directly onto on-board memory. Pico microcontrollers are ideal for real-time control and lightweight embedded projects. -Additionally, Raspberry Pi makes the *Pico* series of tiny, versatile https://en.wikipedia.org/wiki/Microcontroller[microcontroller] boards. Pico models do not run Linux or allow for removable storage, but instead allow programming by flashing a binary onto on-board flash storage. - -=== Flagship series +[[flagship-series]] +=== Flagship single-board computer (SBC) series *Model B* indicates the presence of an Ethernet port. *Model A* indicates a lower-cost model in a smaller form factor with no Ethernet port, reduced RAM, and fewer USB ports to limit board height. -[cols="6a,2,2,3,5"] +IMPORTANT: Raspberry Pi 2 Model B revisions 1.1 and 1.2 have reached End-of-Life (EoL) due to the discontinuation of the core SoC used in these products. The official EoL date was 16 October 2025. Raspberry Pi 2 Model B revision 1.3 offers the same mechanical footprint and a BCM2837B0 processor, and so is recommended for existing designs. For more information, see the official https://pip.raspberrypi.com/documents/RP-009284-PC-2[Obsolescence Notice]. + +[cols="6a,3,2,3,5"] |=== | Model | SoC | Memory | GPIO | Connectivity @@ -23,175 +25,183 @@ Additionally, Raspberry Pi makes the *Pico* series of tiny, versatile https://en image::images/model-b.jpg[alt="Raspberry Pi Model B"] | xref:processors.adoc#bcm2835[BCM2835] a| -256MB +256 MB -512MB | 26-pin GPIO header +512 MB | 26-pin GPIO header a| * HDMI -* 2× USB 2.0 -* standard 15-pin, 1.0mm pitch, 16mm width, CSI (camera) port -* standard 15-pin, 1.0mm pitch, 16mm width, DSI (display) port -* 3.5mm audio jack +* 2 × USB 2.0 +* standard 15-pin, 1.0 mm pitch, 16 mm width, CSI (camera) port +* standard 15-pin, 1.0 mm pitch, 16 mm width, DSI (display) port +* 3.5 mm audio jack * RCA composite video -* 100Mb/s Ethernet RJ45 +* 100 Mb/s Ethernet RJ45 * SD card slot -* micro USB power +* micro-USB power ^.^a| .Raspberry Pi Model A image::images/model-a.jpg[alt="Raspberry Pi Model A",width="80%"] -| xref:processors.adoc#bcm2835[BCM2835] | 256MB | 26-pin GPIO header +| xref:processors.adoc#bcm2835[BCM2835] | 256 MB | 26-pin GPIO header a| * HDMI * USB 2.0 -* standard 15-pin, 1.0mm pitch, 16mm width, CSI (camera) port -* standard 15-pin, 1.0mm pitch, 16mm width, DSI (display) port -* 3.5mm audio jack +* standard 15-pin, 1.0 mm pitch, 16 mm width, CSI (camera) port +* standard 15-pin, 1.0 mm pitch, 16 mm width, DSI (display) port +* 3.5 mm audio jack * RCA composite video * SD card slot -* micro USB power +* micro-USB power ^.^a| .Raspberry Pi Model B+ image::images/model-b-plus.jpg[alt="Raspberry Pi Model B+"] -| xref:processors.adoc#bcm2835[BCM2835] | 512MB | 40-pin GPIO header +| xref:processors.adoc#bcm2835[BCM2835] | 512 MB | 40-pin GPIO header a| * HDMI -* 4× USB 2.0 -* standard 15-pin, 1.0mm pitch, 16mm width, CSI (camera) port -* standard 15-pin, 1.0mm pitch, 16mm width, DSI (display) port -* 3.5mm AV jack -* 100Mb/s Ethernet RJ45 +* 4 × USB 2.0 +* standard 15-pin, 1.0 mm pitch, 16 mm width, CSI (camera) port +* standard 15-pin, 1.0 mm pitch, 16 mm width, DSI (display) port +* 3.5 mm AV jack +* 100 Mb/s Ethernet RJ45 * microSD card slot -* micro USB power +* micro-USB power ^.^a| .Raspberry Pi Model A+ image::images/model-a-plus.jpg[alt="Raspberry Pi Model A+"] | xref:processors.adoc#bcm2835[BCM2835] a| -256MB +256 MB -512MB | 40-pin GPIO header +512 MB | 40-pin GPIO header a| * HDMI * USB 2.0 -* standard 15-pin, 1.0mm pitch, 16mm width, CSI (camera) port -* standard 15-pin, 1.0mm pitch, 16mm width, DSI (display) port +* standard 15-pin, 1.0 mm pitch, 16 mm width, CSI (camera) port +* standard 15-pin, 1.0 mm pitch, 16 mm width, DSI (display) port * 3.5mm AV jack * microSD card slot -* micro USB power +* micro-USB power ^.^a| .Raspberry Pi 2 Model B image::images/2-model-b.jpg[alt="Raspberry Pi 2 Model B"] -| xref:processors.adoc#bcm2836[BCM2836] (in version 1.2, switched to xref:processors.adoc#bcm2837[BCM2837]) | 1 GB | 40-pin GPIO header +a| +* revision 1.1: xref:processors.adoc#bcm2836[BCM2836] +* revision 1.2: xref:processors.adoc#bcm2837[BCM2837] +* revision 1.3: xref:processors.adoc#bcm2837b0[BCM2837B0] + ^.^a| 1 GB | 40-pin GPIO header a| * HDMI -* 4× USB 2.0 -* standard 15-pin, 1.0mm pitch, 16mm width, CSI (camera) port -* standard 15-pin, 1.0mm pitch, 16mm width, DSI (display) port -* 3.5mm AV jack -* 100Mb/s Ethernet RJ45 +* 4 × USB 2.0 +* standard 15-pin, 1.0 mm pitch, 16 mm width, CSI (camera) port +* standard 15-pin, 1.0 mm pitch, 16 mm width, DSI (display) port +* 3.5 mm AV jack +* 100 Mb/s Ethernet RJ45 * microSD card slot -* micro USB power +* micro-USB power ^.^a| .Raspberry Pi 3 Model B image::images/3-model-b.jpg[alt="Raspberry Pi 3 Model B"] -| xref:processors.adoc#bcm2837[BCM2837] | 1 GB | 40-pin GPIO header +a| +* revision 1.1: xref:processors.adoc#bcm2837[BCM2837] +* revision 1.2: xref:processors.adoc#bcm2837b0[BCM2837B0] + ^.^a| 1 GB | 40-pin GPIO header a| * HDMI -* 4× USB 2.0 -* standard 15-pin, 1.0mm pitch, 16mm width, CSI (camera) port -* standard 15-pin, 1.0mm pitch, 16mm width, DSI (display) port -* 3.5mm AV jack -* 100Mb/s Ethernet RJ45 -* 2.4GHz single-band 802.11n Wi-Fi (35Mb/s) +* 4 × USB 2.0 +* standard 15-pin, 1.0 mm pitch, 16 mm width, CSI (camera) port +* standard 15-pin, 1.0 mm pitch, 16 mm width, DSI (display) port +* 3.5 mm AV jack +* 100 Mb/s Ethernet RJ45 +* 2.4 Ghz single-band 802.11n Wi-Fi (35 Mb/s) * Bluetooth 4.1, Bluetooth Low Energy (BLE) * microSD card slot -* micro USB power +* micro-USB power ^.^a| .Raspberry Pi 3 Model B+ image::images/3-model-b-plus.jpg[alt="Raspberry Pi 3 Model B+"] -| xref:processors.adoc#bcm2837b0[BCM2837b0] | 1GB | 40-pin GPIO header +| xref:processors.adoc#bcm2837b0[BCM2837B0] | 1 GB | 40-pin GPIO header a| * HDMI -* 4× USB 2.0 -* standard 15-pin, 1.0mm pitch, 16mm width, CSI (camera) port -* standard 15-pin, 1.0mm pitch, 16mm width, DSI (display) port -* 3.5mm AV jack -* 300Mb/s Ethernet RJ45 with PoE support -* 2.4/5GHz dual-band 802.11ac Wi-Fi (100Mb/s) +* 4 × USB 2.0 +* standard 15-pin, 1.0 mm pitch, 16 mm width, CSI (camera) port +* standard 15-pin, 1.0 mm pitch, 16 mm width, DSI (display) port +* 3.5 mm AV jack +* 300 Mb/s Ethernet RJ45 with PoE support +* 2.4/5 GHz dual-band 802.11ac Wi-Fi (100 Mb/s) * Bluetooth 4.2, Bluetooth Low Energy (BLE) * microSD card slot -* micro USB power +* micro-USB power ^.^a| .Raspberry Pi 3 Model A+ image::images/3-model-a-plus.jpg[alt="Raspberry Pi 3 Model A+"] -| xref:processors.adoc#bcm2837b0[BCM2837b0] | 512 MB | 40-pin GPIO header +| xref:processors.adoc#bcm2837b0[BCM2837B0] | 512 MB | 40-pin GPIO header a| * HDMI * USB 2.0 -* standard 15-pin, 1.0mm pitch, 16mm width, CSI (camera) port -* standard 15-pin, 1.0mm pitch, 16mm width, DSI (display) port -* 3.5mm AV jack -* 2.4/5GHz dual-band 802.11ac Wi-Fi (100Mb/s) +* standard 15-pin, 1.0 mm pitch, 16 mm width, CSI (camera) port +* standard 15-pin, 1.0 mm pitch, 16 mm width, DSI (display) port +* 3.5 mm AV jack +* 2.4/5 Ghz dual-band 802.11ac Wi-Fi (100 Mb/s) * Bluetooth 4.2, Bluetooth Low Energy (BLE) * microSD card slot -* micro USB power +* micro-USB power ^.^a| .Raspberry Pi 4 Model B image::images/4-model-b.jpg[alt="Raspberry Pi 4 Model B"] | xref:processors.adoc#bcm2711[BCM2711] a| -1GB +1 GB -2GB +2 GB -4GB +4 GB -8GB | 40-pin GPIO header +8 GB | 40-pin GPIO header a| -* 2× micro HDMI -* 2× USB 2.0 -* 2× USB 3.0 -* standard 15-pin, 1.0mm pitch, 16mm width, CSI (camera) port -* standard 15-pin, 1.0mm pitch, 16mm width, DSI (display) port -* 3.5mm AV jack -* Gigabit (1Gb/s) Ethernet RJ45 with PoE+ support -* 2.4/5GHz dual-band 802.11ac Wi-Fi (120Mb/s) +* 2 × micro-HDMI +* 2 × USB 2.0 +* 2 × USB 3.0 +* standard 15-pin, 1.0 mm pitch, 16 mm width, CSI (camera) port +* standard 15-pin, 1.0 mm pitch, 16 mm width, DSI (display) port +* 3.5 mm AV jack +* Gigabit (1 Gb/s) Ethernet RJ45 with PoE+ support +* 2.4/5 GHz dual-band 802.11ac Wi-Fi (120 Mb/s) * Bluetooth 5, Bluetooth Low Energy (BLE) * microSD card slot -* USB-C power (5V 3A (15W)) +* USB-C power; 5 V at 3 A (15W) ^.^a| .Raspberry Pi 5 image::images/5.jpg[alt="Raspberry Pi 5"] | xref:processors.adoc#bcm2712[BCM2712] a| -2GB +2 GB -4GB +4 GB -8GB +8 GB -16GB | 40-pin GPIO header +16 GB | 40-pin GPIO header a| -* 2× micro HDMI -* 2× USB 2.0 -* 2× USB 3.0 -* 2× mini 22-pin, 0.5mm (fine) pitch, 11.5mm width, combined CSI (camera)/DSI (display) ports +* 2 × micro-HDMI +* 2 × USB 2.0 +* 2 × USB 3.0 +* 2 × mini 22-pin, 0.5 mm (fine) pitch, 11.5 mm width, combined CSI (camera)/DSI (display) ports * single-lane https://datasheets.raspberrypi.com/pcie/pcie-connector-standard.pdf[PCIe FFC connector] * https://datasheets.raspberrypi.com/debug/debug-connector-specification.pdf[UART connector] * RTC battery connector * xref:raspberry-pi.adoc#raspberry-pi-5-fan-connector-pinout[four-pin JST-SH PWM fan connector] -* Gigabit (1Gb/s) Ethernet RJ45 with PoE+ support -* 2.4/5GHz dual-band 802.11ac Wi-Fi 5 (300Mb/s) +* Gigabit (1 Gb/s) Ethernet RJ45 with PoE+ support +* 2.4/5 GHz dual-band 802.11ac Wi-Fi 5 (300 Mb/s) * Bluetooth 5, Bluetooth Low Energy (BLE) * microSD card slot -* USB-C power (5V 5A (25W), or 5V 3A (15W) with a 600mA peripheral limit) +* USB-C power; 5 V at 5 A (25W); or 5 V at 3 A (15 W) with a 600 mA peripheral limit |=== For more information about the ports on the Raspberry Pi flagship series, see the xref:raspberry-pi.adoc#schematics-and-mechanical-drawings[Schematics and mechanical drawings]. -=== Keyboard series +[[keyboard-computers]] +=== Keyboard computer (X00) series -Keyboard series devices use model identifiers of the form ``, where `X` indicates the corresponding Flagship series device. For instance, "Raspberry Pi 500" is the keyboard version of the Raspberry Pi 5. +Keyboard series devices use model identifiers of the form ``, where `X` indicates the corresponding flagship single-board computer (SBC) series device. For example, Raspberry Pi 400 is the keyboard version of Raspberry Pi 4. For more detailed information about Raspberry Pi keyboard computers, see xref:keyboard-computers.adoc[Keyboard computers]. [cols="6a,2,2,3,5"] |=== @@ -200,44 +210,57 @@ Keyboard series devices use model identifiers of the form ``, where `X` ind ^.^a| .Raspberry Pi 400 image::images/400.jpg[alt="Raspberry Pi 400"] -| xref:processors.adoc#bcm2711[BCM2711] | 4GB | 40-pin GPIO header +| xref:processors.adoc#bcm2711[BCM2711] | 4 GB | 40-pin GPIO header a| -* 2× micro HDMI +* 2 × micro-HDMI * USB 2.0 -* 2× USB 3.0 -* Gigabit (1Gb/s) Ethernet RJ45 -* 2.4/5GHz dual-band 802.11ac Wi-Fi (120Mb/s) +* 2 × USB 3.0 +* Gigabit (1 Gb/s) Ethernet RJ45 +* 2.4/5 GHz dual-band 802.11ac Wi-Fi (120 Mb/s) * Bluetooth 5, Bluetooth Low Energy (BLE) * microSD card slot -* USB-C power (5V 3A (15W)) +* USB-C power; 5 V at 3 A (15W) ^.^a| .Raspberry Pi 500 image::images/500.png[alt="Raspberry Pi 500"] -| xref:processors.adoc#bcm2712[BCM2712] | 8GB | 40-pin GPIO header +| xref:processors.adoc#bcm2712[BCM2712] | 8 GB | 40-pin GPIO header +a| +* 2 × micro-HDMI +* USB 2.0 +* 2 × USB 3.0 +* Gigabit (1 Gb/s) Ethernet RJ45 +* 2.4/5 GHz dual-band 802.11ac Wi-Fi 5 (300 Mb/s) +* Bluetooth 5, Bluetooth Low Energy (BLE) +* microSD card slot +* USB-C power; 5 V at 5 A (25W); or 5 V at 3 A (15W) with a 600 mA peripheral limit +^.^a| +.Raspberry Pi 500+ +image::images/500plus.png[alt="Raspberry Pi 500+"] +| xref:processors.adoc#bcm2712[BCM2712] | 16 GB | 40-pin GPIO header a| -* 2× micro HDMI +* 2 × micro-HDMI * USB 2.0 -* 2× USB 3.0 -* Gigabit (1Gb/s) Ethernet RJ45 -* 2.4/5GHz dual-band 802.11ac Wi-Fi 5 (300Mb/s) +* 2 × USB 3.0 +* Gigabit (1 Gb/s) Ethernet RJ45 +* 2.4/5 GHz dual-band 802.11ac Wi-Fi 5 (300 Mb/s) * Bluetooth 5, Bluetooth Low Energy (BLE) * microSD card slot -* USB-C power (5V 5A (25W), or 5V 3A (15W) with a 600mA peripheral limit) +* Internal M.2 SSD (256 GB) +* USB-C power; 5 V at 5 A (25W) |=== +[[zero-series]] === Zero series -Models with the *H* suffix have header pins pre-soldered to the GPIO header. Models that lack the *H* suffix do not come with header pins attached to the GPIO header; the user must solder pins manually or attach a third-party pin kit. +Models with the *H* suffix have header pins pre-soldered to the GPIO header. Models that lack the *H* suffix don't come with header pins attached to the GPIO header; the user must solder pins manually or attach a third-party pin kit. All Zero models have the following connectivity: -* a microSD card slot -* a mini HDMI port -* 2× micro USB ports (one for input power, one for external devices) +* A microSD card slot +* A mini HDMI port +* 2 × micro-USB ports (one for input power, one for external devices) -Since version 1.3 of the original Zero, all Zero models also include: - -* a mini 22-pin, 0.5mm (fine) pitch, 11.5mm width, CSI (camera) port +Since version 1.3 of the original Zero, all Zero models also include a mini 22-pin, 0.5 mm (fine) pitch, 11.5 mm width, CSI (camera) port. [cols="3a,1,1,1,2"] |=== @@ -246,39 +269,44 @@ Since version 1.3 of the original Zero, all Zero models also include: ^.^a| .Raspberry Pi Zero image::images/zero.jpg[alt="Raspberry Pi Zero"] -| xref:processors.adoc#bcm2835[BCM2835] | 512MB | 40-pin GPIO header (unpopulated) ^| none +| xref:processors.adoc#bcm2835[BCM2835] | 512 MB | 40-pin GPIO header (unpopulated) ^| none ^.^a| .Raspberry Pi Zero W image::images/zero-w.jpg[alt="Raspberry Pi Zero W"] -| xref:processors.adoc#bcm2835[BCM2835] | 512MB | 40-pin GPIO header (unpopulated) +| xref:processors.adoc#bcm2835[BCM2835] | 512 MB | 40-pin GPIO header (unpopulated) a| -* 2.4GHz single-band 802.11n Wi-Fi (35Mb/s) +* 2.4 GHz single-band 802.11n Wi-Fi (35 Mb/s) * Bluetooth 4.0, Bluetooth Low Energy (BLE) ^.^a| .Raspberry Pi Zero WH image::images/zero-wh.jpg[alt="Raspberry Pi Zero WH"] -| xref:processors.adoc#bcm2835[BCM2835] | 512MB | 40-pin GPIO header +| xref:processors.adoc#bcm2835[BCM2835] | 512 MB | 40-pin GPIO header a| -* 2.4GHz single-band 802.11n Wi-Fi (35Mb/s) +* 2.4 GHz single-band 802.11n Wi-Fi (35 Mb/s) * Bluetooth 4.0, Bluetooth Low Energy (BLE) ^.^a| .Raspberry Pi Zero 2 W image::images/zero-2-w.jpg[alt="Raspberry Pi Zero 2 W"] -| xref:processors.adoc#rp3a0[RP3A0] | 512MB | 40-pin GPIO header (unpopulated) +| xref:processors.adoc#rp3a0[RP3A0] | 512 MB | 40-pin GPIO header (unpopulated) a| -* 2.4GHz single-band 802.11n Wi-Fi (35Mb/s) +* 2.4 GHz single-band 802.11n Wi-Fi (35 Mb/s) * Bluetooth 4.2, Bluetooth Low Energy (BLE) ^.^a| .Raspberry Pi Zero 2 WH image::images/zero-2-wh.png[alt="Raspberry Pi Zero 2 WH"] -| xref:processors.adoc#rp3a0[RP3A0] | 512MB | 40-pin GPIO header +| xref:processors.adoc#rp3a0[RP3A0] | 512 MB | 40-pin GPIO header a| -* 2.4GHz single-band 802.11n Wi-Fi (35Mb/s) +* 2.4 GHz single-band 802.11n Wi-Fi (35 Mb/s) * Bluetooth 4.2, Bluetooth Low Energy (BLE) |=== +[[compute-module-series]] === Compute Module series +IMPORTANT: Raspberry Pi Compute Module 3 (CM3) and Compute Module 3 Lite (CM3Lite) have reached End-of-Life (EoL) due to the discontinuation of the core SoC used in these products. The official EoL date was 16 October 2025. The closest equivalent to CM3 is Raspberry Pi Compute Module 3+, which offers the same mechanical footprint, improved thermal design, and a BCM2837B0 processor, and so is recommended for existing designs. For new designs requiring the SODIMM form factor, we recommend Compute Module 4S. For all other new designs, we recommend Compute Module 4 or Compute Module 5. For more information, see the official https://pip.raspberrypi.com/documents/RP-009286-PC[Obsolescence Notice]. + +For more detailed information about the Raspberry Pi Compute Module hardware, see xref:compute-module.adoc[Compute Module hardware]. + [cols="3a,1,1,1,1,2"] |=== | Model | SoC | Memory | Storage | Form factor | Wireless Connectivity @@ -286,72 +314,72 @@ a| ^.^a| .Raspberry Pi Compute Module 1 image::images/compute-module-1.jpg[alt="Raspberry Pi Compute Module 1"] -| xref:processors.adoc#bcm2835[BCM2835] | 512MB -| 4GB | DDR2 SO-DIMM ^| none +| xref:processors.adoc#bcm2835[BCM2835] | 512 MB +| 4 GB | DDR2 SODIMM ^| none ^.^a| .Raspberry Pi Compute Module 3 image::images/compute-module-3.jpg[alt="Raspberry Pi Compute Module 3"] -| xref:processors.adoc#bcm2837[BCM2837] | 1GB +| xref:processors.adoc#bcm2837[BCM2837] | 1 GB a| -0GB (Lite) +0 GB (Lite) -4GB | DDR2 SO-DIMM ^| none +4 GB | DDR2 SODIMM ^| none ^.^a| .Raspberry Pi Compute Module 3+ image::images/compute-module-3-plus.jpg[alt="Raspberry Pi Compute Module 3+"] -| xref:processors.adoc#bcm2837b0[BCM2837b0] | 1GB +| xref:processors.adoc#bcm2837b0[BCM2837B0] | 1 GB a| -0GB (Lite) +0 GB (Lite) -8GB +8 GB -16GB +16 GB -32GB | DDR2 SO-DIMM ^| none +32 GB | DDR2 SODIMM ^| none ^.^a| .Raspberry Pi Compute Module 4S image::images/compute-module-4s.jpg[alt="Raspberry Pi Compute Module 4S"] | xref:processors.adoc#bcm2711[BCM2711] a| -1GB +1 GB -2GB +2 GB -4GB +4 GB -8GB +8 GB a| -0GB (Lite) +0 GB (Lite) -8GB +8 GB -16GB +16 GB -32GB | DDR2 SO-DIMM ^| none +32 GB | DDR2 SODIMM ^| none ^.^a| .Raspberry Pi Compute Module 4 image::images/compute-module-4.jpg[alt="Raspberry Pi Compute Module 4"] | xref:processors.adoc#bcm2711[BCM2711] a| -1GB +1 GB -2GB +2 GB -4GB +4 GB -8GB +8 GB a| -0GB (Lite) +0 GB (Lite) -8GB +8 GB -16GB +16 GB -32GB +32 GB | dual 100-pin high density connectors a| optional: -* 2.4/5GHz dual-band 802.11ac Wi-Fi 5 (300Mb/s) +* 2.4/5 GHz dual-band 802.11ac Wi-Fi 5 (300 Mb/s) * Bluetooth 5, Bluetooth Low Energy (BLE) ^.^a| @@ -359,30 +387,31 @@ a| optional: image::images/compute-module-5.png[alt="Raspberry Pi Compute Module 5"] | xref:processors.adoc#bcm2712[BCM2712] a| -2GB +2 GB -4GB +4 GB -8GB +8 GB + +16 GB a| -0GB (Lite) +0 GB (Lite) -16GB +16 GB -32GB +32 GB -64GB +64 GB | dual 100-pin high density connectors a| optional: -* 2.4/5GHz dual-band 802.11ac Wi-Fi 5 (300Mb/s) +* 2.4/5 GHz dual-band 802.11ac Wi-Fi 5 (300 Mb/s) * Bluetooth 5, Bluetooth Low Energy (BLE) |=== -NOTE: Compute Modules that use the physical DDR2 SO-DIMM form factor are *not* compatible with DDR2 SO-DIMM electrical specifications. - -For more information about Raspberry Pi Compute Modules, see xref:../computers/compute-module.adoc[the Compute Module documentation]. +NOTE: Compute Modules that use the physical DDR2 SODIMM form factor are *not* compatible with DDR2 SODIMM electrical specifications. +[[pico-series]] === Pico microcontrollers Models with the *H* suffix have header pins pre-soldered to the GPIO header. Models that lack the *H* suffix do not come with header pins attached to the GPIO header; the user must solder pins manually or attach a third-party pin kit. @@ -394,34 +423,34 @@ Models with the *H* suffix have header pins pre-soldered to the GPIO header. Mod | .Raspberry Pi Pico image::images/pico.png[alt="Raspberry Pi Pico"] -| xref:../microcontrollers/silicon.adoc#rp2040[RP2040] | 264KB | 2MB | two 20-pin GPIO headers (unpopulated) ^| none +| xref:../microcontrollers/silicon.adoc#rp2040[RP2040] | 264 KB | 2 MB | two 20-pin GPIO headers (unpopulated) ^| none | .Raspberry Pi Pico H image::images/pico-h.png[alt="Raspberry Pi Pico H"] -| xref:../microcontrollers/silicon.adoc#rp2040[RP2040] | 264KB | 2MB | two 20-pin GPIO headers ^| none +| xref:../microcontrollers/silicon.adoc#rp2040[RP2040] | 264 KB | 2 MB | two 20-pin GPIO headers ^| none | .Raspberry Pi Pico W image::images/pico-w.png[alt="Raspberry Pi Pico W"] -| xref:../microcontrollers/silicon.adoc#rp2040[RP2040] | 264KB | 2MB | two 20-pin GPIO headers (unpopulated) -| -* 2.4GHz single-band 802.11n Wi-Fi (10Mb/s) +| xref:../microcontrollers/silicon.adoc#rp2040[RP2040] | 264 KB | 2 MB | two 20-pin GPIO headers (unpopulated) +a| +* 2.4 GHz single-band 802.11n Wi-Fi (10 Mb/s) * Bluetooth 5.2, Bluetooth Low Energy (BLE) | .Raspberry Pi Pico WH image::images/pico-wh.png[alt="Raspberry Pi Pico WH"] -| xref:../microcontrollers/silicon.adoc#rp2040[RP2040] | 264KB | 2MB | two 20-pin GPIO headers -| -* 2.4GHz single-band 802.11n Wi-Fi (10Mb/s) +| xref:../microcontrollers/silicon.adoc#rp2040[RP2040] | 264 KB | 2 MB | two 20-pin GPIO headers +a| +* 2.4 GHz single-band 802.11n Wi-Fi (10 Mb/s) * Bluetooth 5.2, Bluetooth Low Energy (BLE) | .Raspberry Pi Pico 2 image::images/pico-2.png[alt="Raspberry Pi Pico 2"] -| xref:../microcontrollers/silicon.adoc#rp2350[RP2350] | 520KB | 4MB | two 20-pin GPIO headers (unpopulated) ^| none +| xref:../microcontrollers/silicon.adoc#rp2350[RP2350] | 520 KB | 4 MB | two 20-pin GPIO headers (unpopulated) ^| none | .Raspberry Pi Pico 2 W image::images/pico-2-w.png[alt="Raspberry Pi Pico 2 W"] -| xref:../microcontrollers/silicon.adoc#rp2350[RP2350] | 520KB | 4MB | two 20-pin GPIO headers (unpopulated) a| -* 2.4GHz single-band 802.11n Wi-Fi (10Mb/s) +| xref:../microcontrollers/silicon.adoc#rp2350[RP2350] | 520 KB | 4 MB | two 20-pin GPIO headers (unpopulated) a| +* 2.4 GHz single-band 802.11n Wi-Fi (10 Mb/s) * Bluetooth 5.2, Bluetooth Low Energy (BLE) |=== diff --git a/documentation/asciidoc/computers/raspberry-pi/otp-bits.adoc b/documentation/asciidoc/computers/raspberry-pi/otp-bits.adoc index 46bb496dd..c9efabb22 100644 --- a/documentation/asciidoc/computers/raspberry-pi/otp-bits.adoc +++ b/documentation/asciidoc/computers/raspberry-pi/otp-bits.adoc @@ -54,6 +54,7 @@ This is available via device-tree in `/proc/device-tree/chosen/rpi-boardrev-ext` * Raspberry Pi 400 ** Bits 0-7: The default keyboard country code used by https://github.com/raspberrypi-ui/piwiz[piwiz] +`35` :: High 32 bits of 64-bit serial number `36-43`:: xref:raspberry-pi.adoc#industrial-use-of-the-raspberry-pi[customer OTP values] `45`:: MPG2 decode key `46`:: WVC1 decode key @@ -110,7 +111,8 @@ This is passed to the operating system in the Device Tree, e.g. `/proc/device-tr This is passed to the operating system in the Device Tree, e.g. `/proc/device-tree/soc/serial@7d50c000/bluetooth/local-bd-address` `77-84`:: xref:raspberry-pi.adoc#industrial-use-of-the-raspberry-pi[customer OTP values] -86:: board country - The default keyboard country code used by https://github.com/raspberrypi-ui/piwiz[piwiz] + +`86`:: board country - The default keyboard country code used by https://github.com/raspberrypi-ui/piwiz[piwiz] If set, this is available via Device Tree in `/proc/device-tree/chosen/rpi-country-code` `87-88`:: xref:raspberry-pi.adoc#industrial-use-of-the-raspberry-pi[customer Ethernet MAC address] diff --git a/documentation/asciidoc/computers/raspberry-pi/power-supplies.adoc b/documentation/asciidoc/computers/raspberry-pi/power-supplies.adoc index af3bbd6e6..68a2d011f 100644 --- a/documentation/asciidoc/computers/raspberry-pi/power-supplies.adoc +++ b/documentation/asciidoc/computers/raspberry-pi/power-supplies.adoc @@ -90,6 +90,11 @@ All Raspberry Pi models with a PoE-capable Ethernet jack require a HAT to draw p | 1.6A (600mA if using a 3A power supply) | 800mA +| Pi 500+ +| 5.0A +| 1.6A +| 800mA (with LEDs off and SSD inactive) + | Zero | 1.2A | Limited by PSU, board, and connector ratings only @@ -122,22 +127,22 @@ $ vcgencmd get_config usb_max_current_enable The following table describes the amount of power (in amps) drawn by different Raspberry Pi models during various workloads: |=== -| | | Raspberry Pi 1B+ | Raspberry Pi 2B | Raspberry Pi 3B | Raspberry Pi Zero | Raspberry Pi 4B +| | | Raspberry Pi 1B+ | Raspberry Pi 2B | Raspberry Pi 3B | Raspberry Pi Zero | Raspberry Pi 4B | Boot | Max | 0.26 | 0.40 | 0.75 | 0.20 | 0.85 -| | Avg | 0.22 | 0.22 | 0.35 | 0.15 | 0.7 +| | Avg | 0.22 | 0.22 | 0.35 | 0.15 | 0.7 | Idle | Avg | 0.20 | 0.22 | 0.30 | 0.10 | 0.6 -| Video playback (H.264) | Max | 0.30 | 0.36 |0.55 |0.23 | 0.85 -| | Avg | 0.22 | 0.28 | 0.33 | 0.16 | 0.78 -| Stress | Max | 0.35 | 0.82 | 1.34 | 0.35 | 1.25 -| | Avg | 0.32 | 0.75 | 0.85 | 0.23 | 1.2 -| Halt current | | | | 0.10 | 0.055 | 0.023 +| Video playback (H.264) | Max | 0.30 | 0.36 |0.55 |0.23 | 0.85 +| | Avg | 0.22 | 0.28 | 0.33 | 0.16 | 0.78 +| Stress | Max | 0.35 | 0.82 | 1.34 | 0.35 | 1.25 +| | Avg | 0.32 | 0.75 | 0.85 | 0.23 | 1.2 +| Halt current | | | | 0.10 | 0.055 | 0.023 |=== NOTE: These measurements used a standard Raspberry Pi OS image (current as of 26 Feb 2016, or June 2019 for the Raspberry Pi 4), at room temperature, with the Raspberry Pi connected to a HDMI monitor, USB keyboard, and USB mouse. The Raspberry Pi 3 Model B was connected to a wireless LAN access point, the Raspberry Pi 4 was connected to Ethernet. All these power measurements are approximate and do not take into account power consumption from additional USB devices; power consumption can easily exceed these measurements if multiple additional USB devices or a HAT are connected to the Raspberry Pi. -[.whitepaper, title="Extra PMIC features on Raspberry Pi 4 and Compute Module 4", subtitle="", link=https://pip.raspberrypi.com/categories/685-whitepapers-app-notes/documents/RP-004340-WP/Extra-PMIC-features-on-Raspberry-Pi-4-and-Compute-Module-4.pdf] +[.whitepaper, title="Extra PMIC features on Raspberry Pi 4, Raspbery Pi 5 and Compute Module 4", subtitle="", link=https://pip.raspberrypi.com/documents/RP-004340-WP-Extra-PMIC-features-on-Raspberry-Pi-4-and-Compute-Module-4.pdf] **** -A number of different PMIC devices have been used on both Raspberry Pi 4 and CM4. All the PMICs provide extra functionality alongside that of voltage supply. This document describes how to access these features in software. +A number of different PMIC devices have been used on Raspberry Pi 4, Raspberry Pi 5 and CM4. All the PMICs provide extra functionality alongside that of voltage supply. This document describes how to access these features in software. **** ==== Decrease Raspberry Pi 5 wattage when turned off @@ -161,7 +166,7 @@ If you see warnings, switch to a higher quality power supply and cable. Low qual Voltages can drop for a variety of reasons. You may have plugged in too many high-demand USB devices. The power supply could be inadequate. Or the power supply cable could use wires that are too thin. -[.whitepaper, title="Making a more resilient file system", subtitle="", link=https://pip.raspberrypi.com/categories/685-whitepapers-app-notes/documents/RP-003610-WP/Making-a-more-resilient-file-system.pdf] +[.whitepaper, title="Making a more resilient file system", subtitle="", link=https://pip.raspberrypi.com/documents/RP-003610-WP-Making-a-more-resilient-file-system.pdf] **** Raspberry Pi devices are frequently used as data storage and monitoring devices, often in places where sudden power-downs may occur. As with any computing device, power dropouts can cause storage corruption. diff --git a/documentation/asciidoc/computers/raspberry-pi/raspberry-pi-industrial.adoc b/documentation/asciidoc/computers/raspberry-pi/raspberry-pi-industrial.adoc index faf0f06f0..41e63c407 100644 --- a/documentation/asciidoc/computers/raspberry-pi/raspberry-pi-industrial.adoc +++ b/documentation/asciidoc/computers/raspberry-pi/raspberry-pi-industrial.adoc @@ -4,7 +4,7 @@ Raspberry Pi is often used as part of another product. This documentation descri === One-time programmable settings -[.whitepaper, title="Using the one-time programmable memory on Raspberry Pi single-board computers", subtitle="", link=https://pip.raspberrypi.com/categories/685-whitepapers-app-notes/documents/RP-003611-WP/Using-the-One-time-programmable-memory-on-Raspberry-Pi-single-board-computers.pdf] +[.whitepaper, title="Using the one-time programmable memory on Raspberry Pi single-board computers", subtitle="", link=https://pip.raspberrypi.com/documents/RP-003611-WP-Using-the-One-time-programmable-memory-on-Raspberry-Pi-single-board-computers.pdf] **** All Raspberry Pi single-board computers (SBCs) have an inbuilt area of one-time programmable (OTP) memory, which is actually part of the main system on a chip (SoC). As its name implies, OTP memory can be written to (i.e. a binary 0 can be changed to a 1) only once. Once a bit has been changed to 1, it can never be returned to 0. One way of looking at the OTP is to consider each bit as a fuse. Programming it involves deliberately blowing the fuse — an irreversible process, as you cannot get inside the chip to replace it! diff --git a/documentation/asciidoc/computers/raspberry-pi/revision-codes.adoc b/documentation/asciidoc/computers/raspberry-pi/revision-codes.adoc index 09100d04b..e75cef87d 100644 --- a/documentation/asciidoc/computers/raspberry-pi/revision-codes.adoc +++ b/documentation/asciidoc/computers/raspberry-pi/revision-codes.adoc @@ -15,7 +15,7 @@ Revision : a02082 Serial : 00000000765fc593 ---- -NOTE: All Raspberry Pi computers report `BCM2835`, even those with BCM2836, BCM2837, BCM2711, and BCM2712 processors. You should not use this string to detect the processor. Decode the revision code using the information below, or `cat /sys/firmware/devicetree/base/model`. +NOTE: All Raspberry Pi computers report `BCM2835`, even those with BCM2836, BCM2837, BCM2711, and BCM2712 processors. You should not use this string to detect the processor. Decode the revision code using the information below, or `cat /sys/firmware/devicetree/base/model`. Depending on which kernel you're running, your `cpuinfo` might also have a "Model" line, and might not have a "Hardware" line. === Old-style revision codes @@ -210,6 +210,10 @@ NOQuuuWuFMMMCCCCPPPPTTTTTTTTRRRR | | 5: 8GB +| +| +| 6: 16GB + | CCCC (bits 16-19) | Manufacturer | 0: Sony UK @@ -256,103 +260,103 @@ NOQuuuWuFMMMCCCCPPPPTTTTTTTTRRRR | TTTTTTTT (bits 4-11) | Type -| 0: A +| 0x00: A | | -| 1: B +| 0x01: B | | -| 2: A+ +| 0x02: A+ | | -| 3: B+ +| 0x03: B+ | | -| 4: 2B +| 0x04: 2B | | -| 5: Alpha (early prototype) +| 0x05: Alpha (early prototype) | | -| 6: CM1 +| 0x06: CM1 | | -| 8: 3B +| 0x08: 3B | | -| 9: Zero +| 0x09: Zero | | -| a: CM3 +| 0x0a: CM3 | | -| c: Zero W +| 0x0c: Zero W | | -| d: 3B+ +| 0x0d: 3B+ | | -| e: 3A+ +| 0x0e: 3A+ | | -| f: Internal use only +| 0x0f: Internal use only | | -| 10: CM3+ +| 0x10: CM3+ | | -| 11: 4B +| 0x11: 4B | | -| 12: Zero 2 W +| 0x12: Zero 2 W | | -| 13: 400 +| 0x13: 400 | | -| 14: CM4 +| 0x14: CM4 | | -| 15: CM4S +| 0x15: CM4S | | -| 16: Internal use only +| 0x16: Internal use only | | -| 17: 5 +| 0x17: 5 | | -| 18: CM5 +| 0x18: CM5 | | -| 19: 500 +| 0x19: 500/500+ | | -| 1a: CM5 Lite +| 0x1a: CM5 Lite | RRRR (bits 0-3) | Revision @@ -690,6 +694,12 @@ NOTE: This list is not exhaustive - there may be codes in use that are not in th | 8GB | Sony UK +| e04190 +| 500+ +| 1.0 +| 16GB +| Sony UK + | b041a0 | CM5 Lite | 1.0 @@ -766,7 +776,7 @@ import subprocess cmd = "cat /proc/cpuinfo | awk '/Revision/ {print $3}'" revcode = subprocess.check_output(cmd, shell=True) -code = int(revcode, 16) +code = int(revcode, 16) new = (code >> 23) & 0x1 model = (code >> 4) & 0xff mem = (code >> 20) & 0x7 @@ -815,22 +825,22 @@ Raspberry Pi models have the following device tree values: |=== | Device Name | Make | Model | CPU Make | CPU -| Pi 500 | `raspberrypi` | `500` | `brcm` | `bcm2712` +| Raspberry Pi 500 /500+ | `raspberrypi` | `500` | `brcm` | `bcm2712` | Compute Module 5 | `raspberrypi` | `5-compute-module` | `brcm` | `bcm2712` | Raspberry Pi 5 | `raspberrypi` | `5-model-b` | `brcm` | `bcm2712` -| Pi 400 | `raspberrypi` | `400` | `brcm` | `bcm2711` +| Raspberry Pi 400 | `raspberrypi` | `400` | `brcm` | `bcm2711` | Compute Module 4S | `raspberrypi` | `4s-compute-module` | `brcm` | `bcm2711` | Compute Module 4 | `raspberrypi` | `4-compute-module` | `brcm` | `bcm2711` | Raspberry Pi 4 Model B | `raspberrypi` | `4-model-b` | `brcm` | `bcm2711` -| Zero 2 W | `raspberrypi` | `model-zero-2-w` | `brcm` | `bcm2837` +| Raspberry Pi Zero 2 W | `raspberrypi` | `model-zero-2-w` | `brcm` | `bcm2837` | Compute Module 3+ | `raspberrypi` | `3-plus-compute-module` | `brcm` | `bcm2837` | Compute Module 3 | `raspberrypi` | `3-compute-module` | `brcm` | `bcm2837` | Raspberry Pi 3 Model A+ | `raspberrypi` | `3-model-a-plus` | `brcm` | `bcm2837` | Raspberry Pi 3 Model B+ | `raspberrypi` | `3-model-b-plus` | `brcm` | `bcm2837` | Raspberry Pi 3 Model B | `raspberrypi` | `3-model-b` | `brcm` | `bcm2837` | Raspberry Pi 2 Model B | `raspberrypi` | `2-model-b` | `brcm` | `bcm2836` -| Zero W | `raspberrypi` | `model-zero-w` | `brcm` | `bcm2835` -| Zero | `raspberrypi` | `model-zero` | `brcm` | `bcm2835` +| Raspberry Pi Zero W | `raspberrypi` | `model-zero-w` | `brcm` | `bcm2835` +| Raspberry Pi Zero | `raspberrypi` | `model-zero` | `brcm` | `bcm2835` | Compute Module 1 | `raspberrypi` | `compute-module` | `brcm` | `bcm2835` | Raspberry Pi Model A+ | `raspberrypi` | `model-a-plus` | `brcm` | `bcm2835` | Raspberry Pi Model B+ | `raspberrypi` | `model-b-plus` | `brcm` | `bcm2835` diff --git a/documentation/asciidoc/computers/remote-access/find-your-ip-address.adoc b/documentation/asciidoc/computers/remote-access/find-your-ip-address.adoc index 326ee3d7e..d3a946e62 100644 --- a/documentation/asciidoc/computers/remote-access/find-your-ip-address.adoc +++ b/documentation/asciidoc/computers/remote-access/find-your-ip-address.adoc @@ -114,7 +114,7 @@ PING raspberrypi.local (192.168.1.131): 56 data bytes 64 bytes from 192.168.1.131: icmp_seq=0 ttl=255 time=2.618 ms ---- -TIP: If you change the system hostname of your Raspberry Pi using Raspberry Pi Configuration, `raspi-config`, or `/etc/hostname`, Avahi updates the `.local` mDNS address. If you don't remember the hostname of your Raspberry Pi, you can install Avahi on another device, then use https://linux.die.net/man/1/avahi-browse[`avahi-browse`] to browse all the hosts and services on your local network. +TIP: If you change the system hostname of your Raspberry Pi using Control Centre, `raspi-config`, or `/etc/hostname`, Avahi updates the `.local` mDNS address. If you don't remember the hostname of your Raspberry Pi, you can install Avahi on another device, then use https://linux.die.net/man/1/avahi-browse[`avahi-browse`] to browse all the hosts and services on your local network. === Check your router's list of devices diff --git a/documentation/asciidoc/computers/remote-access/images/network-tooltip.png b/documentation/asciidoc/computers/remote-access/images/network-tooltip.png index 86351ee3b..38e9fc34d 100644 Binary files a/documentation/asciidoc/computers/remote-access/images/network-tooltip.png and b/documentation/asciidoc/computers/remote-access/images/network-tooltip.png differ diff --git a/documentation/asciidoc/computers/remote-access/images/raspberry-pi-configuration.png b/documentation/asciidoc/computers/remote-access/images/raspberry-pi-configuration.png index 2c99724c1..d7667147b 100644 Binary files a/documentation/asciidoc/computers/remote-access/images/raspberry-pi-configuration.png and b/documentation/asciidoc/computers/remote-access/images/raspberry-pi-configuration.png differ diff --git a/documentation/asciidoc/computers/remote-access/images/vnc-enable.png b/documentation/asciidoc/computers/remote-access/images/vnc-enable.png index 4c81b61ea..37a6f7123 100644 Binary files a/documentation/asciidoc/computers/remote-access/images/vnc-enable.png and b/documentation/asciidoc/computers/remote-access/images/vnc-enable.png differ diff --git a/documentation/asciidoc/computers/remote-access/images/vnc-tigervnc-desktop.png b/documentation/asciidoc/computers/remote-access/images/vnc-tigervnc-desktop.png index e8420b865..5fed688dd 100644 Binary files a/documentation/asciidoc/computers/remote-access/images/vnc-tigervnc-desktop.png and b/documentation/asciidoc/computers/remote-access/images/vnc-tigervnc-desktop.png differ diff --git a/documentation/asciidoc/computers/remote-access/ssh.adoc b/documentation/asciidoc/computers/remote-access/ssh.adoc index aaa58862a..c6861b784 100644 --- a/documentation/asciidoc/computers/remote-access/ssh.adoc +++ b/documentation/asciidoc/computers/remote-access/ssh.adoc @@ -11,7 +11,7 @@ By default, Raspberry Pi OS disables the SSH server. Enable SSH in one of the fo ====== On the desktop:: + -. From the *Preferences* menu, launch *Raspberry Pi Configuration*. +. From the *Preferences* menu, launch *Control Centre*. . Navigate to the *Interfaces* tab. . Select *Enabled* next to *SSH*. . Click *OK*. @@ -76,7 +76,7 @@ NOTE: If you receive a `connection timed out` error, you may have entered the wr ==== Forward X11 over SSH -NOTE: On Raspberry Pi 4 and 5, Raspberry Pi OS Bookworm uses the Wayland window server by default. You can only forward X11 if you use the X window server. To enable window forwarding over X11, switch your desktop to the X window server in Raspberry Pi Configuration. +NOTE: Raspberry Pi OS uses the Wayland window server by default. You can only forward X11 if you use the X window server. To enable window forwarding over X11, switch your desktop to the X window server in Control Centre or the Raspberry Pi configuration CLI. NOTE: X11 is no longer installed by default on many desktop environments. Install a third-party X server such as https://www.xquartz.org/[XQuartz] to use X11 forwarding. @@ -180,14 +180,14 @@ On the computer you use to remotely connect to the Raspberry Pi, use the followi $ ssh-copy-id @ ---- -When prompted, enter the password for your user account on the Raspberry Pi. +When prompted, enter the password for your user account on the Raspberry Pi. You can now connect to your Raspberry Pi without entering a password. ==== Manually copy a public key to your Raspberry Pi If your operating system does not support `ssh-copy-id`, you can instead copy your public key with xref:remote-access.adoc#scp[`scp`]. -First, _on your Raspberry Pi_, create the directory where Linux expects to find keys: +First, _on your Raspberry Pi_, create the directory where Linux expects to find keys: [source,console] ---- diff --git a/documentation/asciidoc/computers/remote-access/vnc.adoc b/documentation/asciidoc/computers/remote-access/vnc.adoc index e7ee1c300..a482e3178 100644 --- a/documentation/asciidoc/computers/remote-access/vnc.adoc +++ b/documentation/asciidoc/computers/remote-access/vnc.adoc @@ -21,19 +21,19 @@ TIP: Once enabled, you can access your WayVNC configuration at `/etc/wayvnc/`. ==== Enable VNC Server Graphically . Boot into the graphical desktop on your Raspberry Pi. -. Click the Raspberry Pi icon in the system tray of your desktop. -. Select *Preferences* > *Raspberry Pi Configuration* from the menu. +. Select the Raspberry Pi icon in the system tray of your desktop. +. Select *Preferences* > *Control Centre* from the menu. + -- -image::images/raspberry-pi-configuration.png[alt="Select Raspberry Pi Configuration from the Preferences menu in the system tray",width="80%"] +image::images/raspberry-pi-configuration.png[alt="Select Control Centre from the Preferences menu in the system tray",width="80%"] -- . Navigate to the *Interfaces* tab. -. Click the radio button next to *VNC* into the active position. +. Toggle the radio button next to *VNC* into the active position. + -- image::images/vnc-enable.png[alt="In the Interfaces tab, click the VNC toggle into the active position to enable VNC.",width="80%"] -- -. Click the *OK* button to save your configuration changes. +. Select the *OK* button to save your configuration changes. ==== Enable the VNC server on the command line @@ -88,8 +88,8 @@ image::images/vnc-tigervnc-cert-signer-warning.png[alt="TigerVNC warning about c -- image::images/vnc-tigervnc-username-password.png[alt="Entering a username and password to authenticate via TigerVNC",width="60%"] -- -. Click the "OK" button to authenticate with the VNC server. If your credentials are correct, TigerVNC should open a window containing the desktop corresponding to your account on the Raspberry Pi. You should be able to move your mouse and keyboard to input text and interact with the desktop. +. Click the "OK" button to authenticate with the VNC server. If your credentials are correct, TigerVNC should open a window containing the desktop corresponding to your account on the Raspberry Pi. You should be able to use your mouse and keyboard to interact with the desktop and input text. + -- image::images/vnc-tigervnc-desktop.png[alt="The desktop of a Raspberry Pi after successfully authenticating with TigerVNC",width="60%"] --- +-- \ No newline at end of file diff --git a/documentation/asciidoc/computers/software-sources.adoc b/documentation/asciidoc/computers/software-sources.adoc new file mode 100644 index 000000000..4a6d0b0ec --- /dev/null +++ b/documentation/asciidoc/computers/software-sources.adoc @@ -0,0 +1,191 @@ +At Raspberry Pi we're trying to open source as much of our code as possible to make it easy to use and adapt for your own uses. Raspberry Pi develops and supports software specifically for our products and focuses its energy on software which provides the most optimal user experience. For example, drivers which optimize multimedia acceleration such as the 3D, HEVC decode, the camera imaging pipeline, AI acceleration, dual HDMI and audio. + +== Finding software sources in Raspberry Pi OS + +When looking for software which is distributed with Raspberry Pi OS, there are often upstream software sources that we patch to create our downstream packages (those tagged with `pass:[+rpt]`). To view the source for those packages it is usually easier to fetch through apt. To do this, you first need to edit your apt lists to include the source packages. The following files should be edited to change each "Types: deb" line to "Types: deb deb-src": + +* `+/etc/apt/sources.list.d/debian.sources+` (on 64-bit images) +or +* `+/etc/apt/sources.list.d/raspbian.sources+` (on 32-bit images) +and +* `+/etc/apt/sources.list.d/raspi.sources+` + +Next you must update the package lists: + +[source,console] +---- +$ sudo apt update +---- + +Now you can fetch the package source, for example: + +[source,console] +---- +$ apt source labwc +---- + +Next, you need to install a helper package: + +[source,console] +---- +$ sudo apt install devscripts +---- + +Finally you can build the package using the standard Debian building process. + +[source,console] +---- +$ sudo apt build-dep labwc +$ cd labwc-0.8.4 +$ debuild -uc -us +---- + +== Our GitHub organizations + +The other place you can find our software in a more standard form is in our GitHub repositories, we have three GitHub organisations we use to store our sources: + +* https://github.com/raspberrypi +* https://github.com/raspberrypi-ui +* https://github.com/RPi-Distro + +== List of categorized sources + +The following is a curated list of repositories that most people are interested in: + +=== Main sources + +https://github.com/raspberrypi/linux:: +This repository contains the source code for the downstream Linux kernel supported and working on all versions of Raspberry Pi from Pi 1 to Pi 5. + +https://github.com/raspberrypi/firmware:: +This repository contains the closed source firmware, although the following two links are useful: +* https://github.com/raspberrypi/firmware/commits/master/[Changelog for the firmware] +* https://github.com/raspberrypi/firmware/blob/master/boot/overlays/README[Device tree overlay README] + +https://github.com/raspberrypi/rpi-eeprom:: +Installation scripts and binaries for the Raspberry Pi 4 and Raspberry Pi 5 bootloader EEPROMs including the https://github.com/raspberrypi/rpi-eeprom/releases[releases] and https://github.com/raspberrypi/rpi-eeprom/blob/master/releases.md[release notes]. + +=== Libraries and applications + +https://github.com/raspberrypi/utils:: +A collection of useful utilities such as pinctrl, piolib and raspinfo, also gpiolib a Raspberry Pi supported method of directly accessing GPIO pins. + +https://github.com/raspberrypi/libcamera:: +A libcamera library implementation for controlling the Raspberry Pi's ISP and cameras. + +https://github.com/raspberrypi/rpicam-apps:: +A C++ library and application suite for image/video processing and encoding with Raspberry Pi cameras using libcamera. + +https://github.com/raspberrypi/picamera2:: +A Python library for using and controlling the Raspberry Pi cameras. + +https://github.com/raspberrypi/drmu:: +A library for directly controlling and accessing multimedia interfaces. + +=== Desktop + +https://github.com/raspberrypi-ui/rpd-metas:: +The metapackages used to create the desktop. + +https://github.com/raspberrypi-ui/wf-panel-pi:: +The taskbar displayed at the top of the screen when running the Wayland-based desktop. + +https://github.com/raspberrypi-ui/lxpanel-pi:: +The taskbar displayed at the top of the screen when running the legacy X-based desktop. + +https://github.com/raspberrypi-ui/pplug-batt:: +https://github.com/raspberrypi-ui/pplug-bluetooth:: +https://github.com/raspberrypi-ui/pplug-clock:: +https://github.com/raspberrypi-ui/pplug-cpu:: +https://github.com/raspberrypi-ui/pplug-cputemp:: +https://github.com/raspberrypi-ui/pplug-ejecter:: +https://github.com/raspberrypi-ui/pplug-gpu:: +https://github.com/raspberrypi-ui/pplug-menu:: +https://github.com/raspberrypi-ui/pplug-netman:: +https://github.com/raspberrypi-ui/pplug-power:: +https://github.com/raspberrypi-ui/pplug-updater:: +https://github.com/raspberrypi-ui/pplug-volumepulse:: +The plugins displayed on the taskbars. + +https://github.com/raspberrypi-ui/pcmanfm:: +https://github.com/raspberrypi-ui/libfm:: +The file manager used by the desktop, which also displays the desktop background. + +https://github.com/raspberrypi-ui/rpcc:: +The Control Centre application. + +https://github.com/raspberrypi-ui/rc_gui:: +The Raspberry Pi configuration plugin for Control Centre. + +https://github.com/raspberrypi-ui/appset:: +The appearance settings plugin for Control Centre. + +https://github.com/raspberrypi-ui/rasputin:: +The mouse and keyboard settings plugin for Control Centre. + +https://github.com/raspberrypi-ui/raindrop:: +The screen configuration plugin for Control Centre. + +https://github.com/raspberrypi-ui/rpinters:: +The printer settings plugin for Control Centre. + +=== Applications + +https://github.com/raspberrypi-ui/agnostics:: +The Diagnostics application used to check SD cards. + +https://github.com/raspberrypi-ui/bookshelf:: +The code for the Bookshelf application which allows you to download and read e-books and past issues of the Raspberry Pi Official Magazine. + +https://github.com/raspberrypi-ui/piclone:: +The SD Card Copier application which allows cards and drives to be cloned. + +https://github.com/raspberrypi-ui/rp-prefapps:: +The Recommended Software application which allows selected programs to be installed or removed. + +=== Debug + +https://github.com/raspberrypi/rpi-analyse-boot:: +A boot analysis service that gathers boot-time metrics from various different sources. + +=== Tools + +https://github.com/raspberrypi/rpi-imager:: +The code for the Raspberry Pi Imager application which flashes an operating system to an SD card. + +https://github.com/raspberrypi/rpi-image-gen:: +A build system for developing an operating system for an embedded Raspberry Pi system. + +https://github.com/raspberrypi/usbboot:: +A tool to boot a Raspberry Pi over USB for provisioning Compute Module and Raspberry Pi devices. + +https://github.com/raspberrypi/rpi-sb-provisioner:: +A tool to mass provision Raspberry Pi devices, including secure boot and encrypted file systems. (Raspberry Pi 5, Compute Module 4, and Compute Module 5 are supported.) + +=== Feedback + +http://github.com/raspberrypi/trixie-feedback:: +A repo specifically reserved for bug-reporting for the current Raspberry Pi OS release. + +=== Raspberry Pi Pico + +https://marketplace.visualstudio.com/items?itemName=raspberry-pi.raspberry-pi-pico:: +This is where you can go to download and install the Microsoft Visual Studio Code extension for the Raspberry Pi Pico SDK. + +https://github.com/raspberrypi/pico-setup:: +Quick-start installation tool for the Raspberry Pi Pico SDK for command line use. + +https://github.com/raspberrypi/pico-sdk:: +The Raspberry Pi Pico SDK sources. + +https://github.com/raspberrypi/debugprobe:: +Sources for the Raspberry Pi Debug Probe, providing both SWD and UART easily. + +https://github.com/raspberrypi/openocd:: +The Raspberry Pi downstream OpenOCD sources. + +https://github.com/raspberrypi/pico-examples:: +Examples for Raspberry Pi Pico. + +https://github.com/raspberrypi/picotool:: +Tool for interacting with RP-series devices in BOOTSEL mode. diff --git a/documentation/asciidoc/microcontrollers/debug-probe/getting-started.adoc b/documentation/asciidoc/microcontrollers/debug-probe/getting-started.adoc index 54fcb5d34..aec938471 100644 --- a/documentation/asciidoc/microcontrollers/debug-probe/getting-started.adoc +++ b/documentation/asciidoc/microcontrollers/debug-probe/getting-started.adoc @@ -14,7 +14,7 @@ Connect the following: ** Debug Probe `TX` connected to Pico H `RX` pin ** Debug Probe `GND` connected to Pico H `GND` pin -NOTE: If you have a non-H Pico or Pico W (without a JST-SH connector) you can still connect it to a Debug Probe. Solder a male connector to the `SWCLK`, `GND`, and `SWDIO` header pins on the board. Using the alternate 3-pin JST-SH connector to 0.1-inch header (female) cable included with the Debug Probe, connect to the Debug Probe "D" port. Connect `SWCLK`, `GND`, and `SWDIO` on the Pico or Pico W to the `SC`, `GND`, and `SD` pins on the Debug Probe, respectively. +NOTE: If you have a non-H Pico or Pico W (without a JST-SH connector) you can still connect it to a Debug Probe. Solder a male connector to the `SWCLK`, `GND`, and `SWDIO` header pins on the board. Using the alternate 3-pin JST-SH connector to 0.1-inch header (female) cable included with the Debug Probe, connect to the Debug Probe "D" port. Connect `SWCLK`, `GND`, and `SWDIO` on the Pico or Pico W to the `SC` (orange wire), `GND` (black wire), and `SD` (yellow wire) pins on the Debug Probe, respectively. image:images/wiring.png[width="70%"] diff --git a/documentation/asciidoc/microcontrollers/debug-probe/installing-tools.adoc b/documentation/asciidoc/microcontrollers/debug-probe/installing-tools.adoc index 69ab3024c..1ac3f94b4 100644 --- a/documentation/asciidoc/microcontrollers/debug-probe/installing-tools.adoc +++ b/documentation/asciidoc/microcontrollers/debug-probe/installing-tools.adoc @@ -1,66 +1,12 @@ == Install tools -To use the Debug Probe, install the following tools. +To use the Debug Probe, OpenOCD and the GNU Project Debugger (GDB) are required. An Integrated Development Environment (IDE) may also be useful. -=== Install OpenOCD +On Raspberry Pi OS, most Linux variants, macOS, and Microsoft Windows, it is recommended to install our VS Code extension. This extension bundles OpenOCD, Arm toolchains, GDB, and register definitions for Pico-series microcontrollers. -You need to install OpenOCD. +See Chapter 3 of our https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf[Getting Started with Raspberry Pi Pico] guide. -To install OpenOCD, run the following command in a terminal: +Alternatively, tools can be manually installed by following Appendix C in the guide. -[source,console] ----- -$ sudo apt install openocd ----- +NOTE: Manual installation of the tools on Windows is not recommended. -To run OpenOCD, use the `openocd` command in your terminal. - -==== Install OpenOCD on macOS - -First, install the https://brew.sh/[Homebrew] package manager: - -[source,console] ----- -$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" ----- - -To install OpenOCD on macOS, run the following commands: - -[source,console] ----- -$ brew install openocd ----- - -To run OpenOCD, use the `openocd` command in your terminal. - -=== Install GDB - -We also need to install the GNU debugger (GDB). - -==== Linux - -Install `gdb-multiarch`: - -[source,console] ----- -$ sudo apt install gdb-multiarch ----- - -==== macOS - -Run the following command to install `gdb`: - -[source,console] ----- -$ brew install arm-none-eabi-gdb ----- - -You can safely ignore the request for "special privileges" messages on installation. - -==== MS Windows - -GDB is available as part of our https://github.com/raspberrypi/pico-setup-windows/releases/latest[Pico setup for Windows installer]. It is also included in the https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads[Arm GNU Toolchain Downloads]. - -Alternatively information about manual installation can be found in Chapter 9 and Appendix A of our https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf[Getting Started with Raspberry Pi Pico] book. - -NOTE: Manual installation of GDB on Windows is not recommended. diff --git a/documentation/asciidoc/microcontrollers/debug-probe/introduction.adoc b/documentation/asciidoc/microcontrollers/debug-probe/introduction.adoc index 80e0f9fba..eb32d9516 100644 --- a/documentation/asciidoc/microcontrollers/debug-probe/introduction.adoc +++ b/documentation/asciidoc/microcontrollers/debug-probe/introduction.adoc @@ -4,13 +4,13 @@ image::images/debug-probe.jpg[width="100%"] The Raspberry Pi Debug Probe is a USB device that provides both a UART serial port and a standard Arm Serial Wire Debug (SWD) interface. The probe is designed for easy, solderless, plug-and-play debugging. It has the following features: -* USB to ARM https://developer.arm.com/documentation/ihi0031/a/The-Serial-Wire-Debug-Port\--SW-DP-/Introduction-to-the-ARM-Serial-Wire-Debug\--SWD\--protocol[Serial Wire Debug] (SWD) port +* USB to Arm https://developer.arm.com/documentation/ihi0031/a/The-Serial-Wire-Debug-Port\--SW-DP-/Introduction-to-the-ARM-Serial-Wire-Debug\--SWD\--protocol[Serial Wire Debug] (SWD) port * USB to UART bridge * Compatible with the https://developer.arm.com/documentation/101451/0100/About-CMSIS-DAP[CMSIS-DAP] standard * Works with https://openocd.org/[OpenOCD] and other tools supporting CMSIS-DAP * Open source, easily upgradeable firmware -NOTE: For more information on the Raspberry Pi three-pin debug connector see the https://rptl.io/debug-spec[specification]. +NOTE: For more information on the Raspberry Pi three-pin debug connector see the https://rpltd.co/debug-spec[specification]. This makes it easy to use a Raspberry Pi Pico on platforms such as Windows, macOS, and Linux that lack a GPIO header to connect directly to the Pico's serial UART or SWD port. @@ -32,7 +32,9 @@ Orange:: TX/SC (Output from Probe) Black:: GND Yellow:: RX/SD (Input to Probe or I/O) -While the cable with three-pin JST-SH connectors is intended to be used with the https://rptl.io/debug-spec[standard three-pin connector] which newer Raspberry Pi boards use for the SWD debug port and UART connectors. +The cable with three-pin JST-SH connectors is intended to be used with the https://rpltd.co/debug-spec[standard three-pin connector] that newer Raspberry Pi boards use for the SWD debug port and UART connectors. + +WARNING: When the target is powered from a separate power source or computer, ensure a common reference before connecting signal lines. Either remove power from the target or connect GND between the target and the Raspberry Pi Debug Probe first; you can attach RX, TX, SC, and SD after GND is connected. Potential voltage differences between the two systems can cause damage to the probe. The Debug Probe has five LEDs, a red LED to indicate power, and four more activity indicator LEDs diff --git a/documentation/asciidoc/microcontrollers/debug-probe/swd-connection.adoc b/documentation/asciidoc/microcontrollers/debug-probe/swd-connection.adoc index 1dcc14cee..7b7fbfa95 100644 --- a/documentation/asciidoc/microcontrollers/debug-probe/swd-connection.adoc +++ b/documentation/asciidoc/microcontrollers/debug-probe/swd-connection.adoc @@ -1,12 +1,14 @@ -== Serial Wire Debug (SWD) +== Starting a Debug Session -Serial Wire Debug (SWD) is a two-pin interface (https://developer.arm.com/documentation/101761/1-0/Debug-and-trace-interface/Serial-Wire-Debug-signals[SWDIO and SWCLK]) alternative to the JTAG four- or five-pin debugging interface standard. +The Debug Probe will let you load binaries via the SWD port and OpenOCD: you will not need to unplug, and then push-and-hold, the BOOTSEL button every time you push a new binary to your Pico. Using the Debug Probe to upload new binaries is an entirely hands-off affair. -=== Uploading new programs to your Pico +GDB is then used to debug the binary running on the Pico. -The Pico Debug Probe will let you load binaries via the SWD port and OpenOCD: you will not need to unplug, and then push-and-hold, the BOOTSEL button every time you push a new binary to your Pico. Using the Debug Probe uploading new binaries is an entirely hands off affair. +We recommend the use of the Raspberry Pi Pico VSCode extension, which integrates the use of OpenOCD and GDB, to upload and debug programs. See Chapter 4 of https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf[Getting started with Raspberry Pi Pico] for more information. -Once you have built a binary: +=== Standalone program upload + +Once you have built a binary: [source,console] ---- @@ -15,11 +17,11 @@ $ sudo openocd -f interface/cmsis-dap.cfg -f target/rp2040.cfg -c "adapter speed NOTE: When you use the Debug Probe to upload a binary the ELF version of the file is used, not the UF2 file that you would use when you drag-and-drop. -=== Debugging with SWD +=== Standalone debug session -It'll also let you use `openocd` in server mode, and connect GDB, which gives you break points and "proper" debugging. +This will use `openocd` in server mode, and connect GDB, which gives you breakpoints and single-step over a console interface. -[IMPORTANT] +[IMPORTANT] ====== To allow debugging, you must build your binaries as `Debug` rather than `Release` build type, e.g. @@ -35,10 +37,12 @@ $ make -j4 ---- In a debug build you will get more information when you run it under the debugger, as the compiler builds your program with the information to tell GDB what your program is doing. - -See Chapter 6 of https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf[Getting started with Raspberry Pi Pico] for more information. ====== +NOTE: For computers that are _not_ Raspberry Pis, a variant of GDB that can debug Arm processors is required. Use one of the following alternatives depending on your operating system and device: +* On Linux devices, use `gdb-multiarch`. +* On macOS and Windows devices, use `arm-none-eabi-gdb` from the toolchain on https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads[Arm's website] + To start an OpenOCD server, run the following command: [source,console] @@ -55,8 +59,3 @@ $ gdb blink.elf > monitor reset init > continue ---- - -GDB doesn't work on all platforms. Use one of the following alternatives instead of `gdb`, depending on your operating system and device: - -* On Linux devices that are _not_ Raspberry Pis, use `gdb-multiarch`. -* On macOS devices, use `arm-none-eabi-gdb`. diff --git a/documentation/asciidoc/microcontrollers/debug-probe/updating-firmware.adoc b/documentation/asciidoc/microcontrollers/debug-probe/updating-firmware.adoc index f0c3af0b9..4fb879a5c 100644 --- a/documentation/asciidoc/microcontrollers/debug-probe/updating-firmware.adoc +++ b/documentation/asciidoc/microcontrollers/debug-probe/updating-firmware.adoc @@ -2,14 +2,21 @@ Firmware for the Debug Probe is available as a UF2 file distributed by Raspberry Pi. -The latest version of the Debug Probe firmware is version 2.2. If you're running an older version, or if you have accidentally overwritten the firmware on your Debug Probe, you can find the latest release of the firmware in https://github.com/raspberrypi/debugprobe/releases/latest[the debugprobe GitHub repository]. +The latest version of the Debug Probe firmware is version 2.2.3. If you're running an older version, or if you have accidentally overwritten the firmware on your Debug Probe, you can find the latest release of the firmware in https://github.com/raspberrypi/debugprobe/releases/latest[the debugprobe GitHub repository]. -Download `debugprobe.uf2` from the latest release. +To check the firmware version of your Debug Probe, run: +[source, console] +---- +$ lsusb -v -d 2e8a:000c | grep bcdDevice +---- +This will report `bcdDevice 2.23` for Debug Probe firmware version 2.2.3. -Pinch to remove the top of the Debug Probe enclosure. +NOTE: The `Info : CMSIS-DAP: FW Version = 2.0.0` line reported by `openocd` only refers to the CMSIS-DAP protocol level (which is different to the Debug Probe firmware version). -Push and hold the BOOTSEL button as you plug the Debug Probe into your computer to mount a volume called "RPI-RP2". +To update the firmware version of your Debug Probe: -Copy `debugprobe.uf2` onto the "RPI-RP2" volume. The volume will dismount automatically after the file finishes copying onto the device. - -Your Debug Probe will reboot and now runs an updated version of the Debug Probe firmware. It is now ready for debugging. +1. Download `debugprobe.uf2` from the latest release. +1. Pinch to remove the top of the Debug Probe enclosure. +1. Push and hold the BOOTSEL button as you plug the Debug Probe into your computer, to mount a volume called "RPI-RP2". +1. Copy `debugprobe.uf2` onto the "RPI-RP2" volume. The volume will dismount automatically after the file finishes copying onto the device. +1. Your Debug Probe will reboot and now runs an updated version of the Debug Probe firmware. It is now ready for debugging. diff --git a/documentation/asciidoc/microcontrollers/microcontroller_docs.adoc b/documentation/asciidoc/microcontrollers/microcontroller_docs.adoc index 8b242e97e..12c3b197e 100644 --- a/documentation/asciidoc/microcontrollers/microcontroller_docs.adoc +++ b/documentation/asciidoc/microcontrollers/microcontroller_docs.adoc @@ -46,5 +46,5 @@ https://datasheets.raspberrypi.com/pico/raspberry-pi-pico-c-sdk.pdf[Raspberry Pi https://datasheets.raspberrypi.com/pico/raspberry-pi-pico-python-sdk.pdf[Raspberry Pi Pico Python SDK]:: A MicroPython environment for RP2040 microcontrollers -The API level Doxygen documentation for the Raspberry Pi Pico C/{cpp} SDK is also available https://rptl.io/pico-doxygen[as a micro-site]. +The API level Doxygen documentation for the Raspberry Pi Pico C/{cpp} SDK is also available https://rpltd.co/pico-doxygen[as a micro-site]. diff --git a/documentation/asciidoc/microcontrollers/silicon/rp2040.adoc b/documentation/asciidoc/microcontrollers/silicon/rp2040.adoc index f55dc79f2..f80c1c515 100644 --- a/documentation/asciidoc/microcontrollers/silicon/rp2040.adoc +++ b/documentation/asciidoc/microcontrollers/silicon/rp2040.adoc @@ -37,7 +37,7 @@ power Key features: -* Dual ARM Cortex-M0+ @ 133MHz +* Dual Arm Cortex-M0+ @ 133MHz * 264kB on-chip SRAM in six independent banks * Support for up to 16MB of off-chip Flash memory via dedicated QSPI bus * DMA controller @@ -54,7 +54,7 @@ Key features: ** USB 1.1 controller and PHY, with host and device support ** 8 PIO state machines -[.whitepaper, title="Power switching RP2040 for low standby current applications", subtitle="", link=https://pip.raspberrypi.com/categories/685-whitepapers-app-notes/documents/RP-004339-WP/Power-switching-RP2040-for-low-standby-current-applications.pdf] +[.whitepaper, title="Power switching RP2040 for low standby current applications", subtitle="", link=https://pip.raspberrypi.com/documents/RP-004339-WP-Power-switching-RP2040-for-low-standby-current-applications.pdf] **** Even in deep sleep RP2040 draws a typical current of ~180μA, and sleep current is very dependent on PVT: process (current varies from chip to chip), voltage (current varies linearly with voltage), and temperature (current varies nonlinearly with temperature). diff --git a/documentation/asciidoc/services/bookshelf.adoc b/documentation/asciidoc/services/bookshelf.adoc new file mode 100644 index 000000000..2b6d45eea --- /dev/null +++ b/documentation/asciidoc/services/bookshelf.adoc @@ -0,0 +1,3 @@ +include::bookshelf/intro.adoc[] + +include::bookshelf/subscription.adoc[] \ No newline at end of file diff --git a/documentation/asciidoc/services/bookshelf/images/bookshelf-with-padlock.png b/documentation/asciidoc/services/bookshelf/images/bookshelf-with-padlock.png new file mode 100644 index 000000000..4070f60be Binary files /dev/null and b/documentation/asciidoc/services/bookshelf/images/bookshelf-with-padlock.png differ diff --git a/documentation/asciidoc/services/bookshelf/intro.adoc b/documentation/asciidoc/services/bookshelf/intro.adoc new file mode 100644 index 000000000..9cdda30f3 --- /dev/null +++ b/documentation/asciidoc/services/bookshelf/intro.adoc @@ -0,0 +1,11 @@ +[[bookshelf]] +== Introduction + +The Bookshelf application in Raspberry Pi OS provides access to books and magazines published by Raspberry Pi Press. Since Raspberry Pi OS Trixie, this also includes contributor-only titles. + +* Free titles are indicated by the cloud icon and can be downloaded by anyone. +* Contributor-only titles are indicated by the padlock symbol unless you're signed in with a xref:../services/id.adoc[Raspberry Pi ID] that's associated with a contribution or a subscription to the print magazine. Some contributor-only titles later become available to all. + +image::images/bookshelf-with-padlock.png[width="80%"] + +Bookshelf is included in the Raspberry Pi OS Desktop and Raspberry Pi OS Full images. diff --git a/documentation/asciidoc/services/bookshelf/subscription.adoc b/documentation/asciidoc/services/bookshelf/subscription.adoc new file mode 100644 index 000000000..a6b24a021 --- /dev/null +++ b/documentation/asciidoc/services/bookshelf/subscription.adoc @@ -0,0 +1,24 @@ +[[contribute]] +== Become a contributor (Raspberry Pi OS Trixie and later) + +Contributor-only titles are available to users who are signed in to Bookshelf with a xref:../services/id.adoc[Raspberry Pi ID] that's associated with one of the following things: + +* An email address that has a https://raspberrypipress.imbmsubscriptions.com/[subscription to our print magazine] +* A https://magazine.raspberrypi.com/bookshelf/link[monthly contribution] + +To set up a monthly contribution: + +. In Bookshelf, select **Contribute...** in the bottom left to open the contributor page on the Raspberry Pi website. +. If you don't have a Raspberry Pi ID already, you can create one now. If you have an existing Raspberry Pi ID, sign in with your username and password. +. Sign up for a monthly contribution. +. Select **Sign in to Bookshelf** to open Bookshelf and store your ID that identifies you as a contributor. + +The **Contribute...** button is no longer shown and all titles can now be downloaded. + +You can sign in with your Raspberry Pi ID and access available titles from any number of devices. If you move to a new Raspberry Pi or flash your SD with a different version of Raspberry Pi OS, sign in and download your favourite titles again. + +== Download titles + +Double-click on any of the available titles to download them as a PDF and open them in the default PDF reader. + +If you stop your monthly contribution, you keep any titles that you've already downloaded. These PDF files are stored in the **Bookshelf** folder of your home directory and remain accessible through Bookshelf. \ No newline at end of file diff --git a/documentation/asciidoc/services/connect.adoc b/documentation/asciidoc/services/connect.adoc index e67bd3b16..1b6adb991 100644 --- a/documentation/asciidoc/services/connect.adoc +++ b/documentation/asciidoc/services/connect.adoc @@ -6,3 +6,4 @@ include::connect/use.adoc[] include::connect/troubleshooting.adoc[] +include::connect/security.adoc[] diff --git a/documentation/asciidoc/services/connect/images/browser-sign-in.png b/documentation/asciidoc/services/connect/images/browser-sign-in.png index 87c50da7e..81bbb213a 100644 Binary files a/documentation/asciidoc/services/connect/images/browser-sign-in.png and b/documentation/asciidoc/services/connect/images/browser-sign-in.png differ diff --git a/documentation/asciidoc/services/connect/images/configure-plugin.png b/documentation/asciidoc/services/connect/images/configure-plugin.png new file mode 100644 index 000000000..81f7f12c2 Binary files /dev/null and b/documentation/asciidoc/services/connect/images/configure-plugin.png differ diff --git a/documentation/asciidoc/services/connect/images/device.png b/documentation/asciidoc/services/connect/images/device.png index 0e4e6bbd2..a3bef029d 100644 Binary files a/documentation/asciidoc/services/connect/images/device.png and b/documentation/asciidoc/services/connect/images/device.png differ diff --git a/documentation/asciidoc/services/connect/images/devices.png b/documentation/asciidoc/services/connect/images/devices.png index 73b5859ac..c6f9d48f1 100644 Binary files a/documentation/asciidoc/services/connect/images/devices.png and b/documentation/asciidoc/services/connect/images/devices.png differ diff --git a/documentation/asciidoc/services/connect/images/disable-animate-icon.png b/documentation/asciidoc/services/connect/images/disable-animate-icon.png new file mode 100644 index 000000000..b329a2b00 Binary files /dev/null and b/documentation/asciidoc/services/connect/images/disable-animate-icon.png differ diff --git a/documentation/asciidoc/services/connect/images/disallow-remote-shell.png b/documentation/asciidoc/services/connect/images/disallow-remote-shell.png index 348d0ac0f..dffe0f5ec 100644 Binary files a/documentation/asciidoc/services/connect/images/disallow-remote-shell.png and b/documentation/asciidoc/services/connect/images/disallow-remote-shell.png differ diff --git a/documentation/asciidoc/services/connect/images/disallow-screen-sharing.png b/documentation/asciidoc/services/connect/images/disallow-screen-sharing.png index 52d4d17aa..5deb8a2bf 100644 Binary files a/documentation/asciidoc/services/connect/images/disallow-screen-sharing.png and b/documentation/asciidoc/services/connect/images/disallow-screen-sharing.png differ diff --git a/documentation/asciidoc/services/connect/images/hero.png b/documentation/asciidoc/services/connect/images/hero.png index 5f13e18a2..b1a0b9841 100644 Binary files a/documentation/asciidoc/services/connect/images/hero.png and b/documentation/asciidoc/services/connect/images/hero.png differ diff --git a/documentation/asciidoc/services/connect/images/new-device.png b/documentation/asciidoc/services/connect/images/new-device.png index 8753ada4f..08b794e71 100644 Binary files a/documentation/asciidoc/services/connect/images/new-device.png and b/documentation/asciidoc/services/connect/images/new-device.png differ diff --git a/documentation/asciidoc/services/connect/images/remote-shell-disabled.png b/documentation/asciidoc/services/connect/images/remote-shell-disabled.png index 991c1e295..1196bf4fa 100644 Binary files a/documentation/asciidoc/services/connect/images/remote-shell-disabled.png and b/documentation/asciidoc/services/connect/images/remote-shell-disabled.png differ diff --git a/documentation/asciidoc/services/connect/images/remote-shell-in-progress.png b/documentation/asciidoc/services/connect/images/remote-shell-in-progress.png index b6eaaeceb..fc75efc7f 100644 Binary files a/documentation/asciidoc/services/connect/images/remote-shell-in-progress.png and b/documentation/asciidoc/services/connect/images/remote-shell-in-progress.png differ diff --git a/documentation/asciidoc/services/connect/images/remote-shell-notification.png b/documentation/asciidoc/services/connect/images/remote-shell-notification.png index 2bb47d88f..29d22a96d 100644 Binary files a/documentation/asciidoc/services/connect/images/remote-shell-notification.png and b/documentation/asciidoc/services/connect/images/remote-shell-notification.png differ diff --git a/documentation/asciidoc/services/connect/images/screen-sharing-disabled.png b/documentation/asciidoc/services/connect/images/screen-sharing-disabled.png index f5a3d7d03..75c2950f2 100644 Binary files a/documentation/asciidoc/services/connect/images/screen-sharing-disabled.png and b/documentation/asciidoc/services/connect/images/screen-sharing-disabled.png differ diff --git a/documentation/asciidoc/services/connect/images/screen-sharing-in-progress.png b/documentation/asciidoc/services/connect/images/screen-sharing-in-progress.png index 2c3398f9a..ff840eb8e 100644 Binary files a/documentation/asciidoc/services/connect/images/screen-sharing-in-progress.png and b/documentation/asciidoc/services/connect/images/screen-sharing-in-progress.png differ diff --git a/documentation/asciidoc/services/connect/images/screen-sharing-notification.png b/documentation/asciidoc/services/connect/images/screen-sharing-notification.png index 439d43748..54287856f 100644 Binary files a/documentation/asciidoc/services/connect/images/screen-sharing-notification.png and b/documentation/asciidoc/services/connect/images/screen-sharing-notification.png differ diff --git a/documentation/asciidoc/services/connect/images/screen-sharing.png b/documentation/asciidoc/services/connect/images/screen-sharing.png index 94fc1e871..18938febd 100644 Binary files a/documentation/asciidoc/services/connect/images/screen-sharing.png and b/documentation/asciidoc/services/connect/images/screen-sharing.png differ diff --git a/documentation/asciidoc/services/connect/images/sign-in-email.png b/documentation/asciidoc/services/connect/images/sign-in-email.png index 0ed30d7fc..57875a219 100644 Binary files a/documentation/asciidoc/services/connect/images/sign-in-email.png and b/documentation/asciidoc/services/connect/images/sign-in-email.png differ diff --git a/documentation/asciidoc/services/connect/images/sign-in.png b/documentation/asciidoc/services/connect/images/sign-in.png index 7b66320e9..8a3991925 100644 Binary files a/documentation/asciidoc/services/connect/images/sign-in.png and b/documentation/asciidoc/services/connect/images/sign-in.png differ diff --git a/documentation/asciidoc/services/connect/images/static-icon.png b/documentation/asciidoc/services/connect/images/static-icon.png new file mode 100644 index 000000000..336eb3bc2 Binary files /dev/null and b/documentation/asciidoc/services/connect/images/static-icon.png differ diff --git a/documentation/asciidoc/services/connect/images/turn-on-connect.png b/documentation/asciidoc/services/connect/images/turn-on-connect.png index 96c749c79..142ad9e3f 100644 Binary files a/documentation/asciidoc/services/connect/images/turn-on-connect.png and b/documentation/asciidoc/services/connect/images/turn-on-connect.png differ diff --git a/documentation/asciidoc/services/connect/install.adoc b/documentation/asciidoc/services/connect/install.adoc index 7c8224c22..321984e02 100644 --- a/documentation/asciidoc/services/connect/install.adoc +++ b/documentation/asciidoc/services/connect/install.adoc @@ -1,37 +1,7 @@ -[[install-connect]] -== Install +[[install-connect-lite]] +== Install Connect Lite -If Connect isn't already installed in your version of Raspberry Pi OS, open a Terminal window. Run the following command to update your system and packages: - -[source,console] ----- -$ sudo apt update -$ sudo apt full-upgrade ----- - -Run the following command on your Raspberry Pi to install Connect: - -[source,console] ----- -$ sudo apt install rpi-connect ----- - -You can also install Connect from the Recommended Software application. - -After installation, use the `rpi-connect` command line interface to start Connect for your current user: - -[source,console] ----- -$ rpi-connect on ----- - -Alternatively, click the Connect icon in the menu bar to open a dropdown menu and select *Turn On Raspberry Pi Connect*: - -image::images/turn-on-connect.png[width="80%"] - -=== Connect Lite - -We distribute an alternate *Lite* variant of Connect that only supports remote shell access, with no ability to screen share. +For Raspberry Pi OS Lite, we distribute an alternate *Lite* variant of Connect that only supports remote shell access, with no ability to screen share. Run the following command on your Raspberry Pi to install Connect Lite: @@ -49,11 +19,9 @@ $ rpi-connect on xref:connect.adoc#enable-remote-shell-at-all-times[Enable user-lingering] to make your device accessible even when your user account isn't logged in. -TIP: Lite commands use the same `rpi-connect` name as the full version of Connect. `rpi-connect-lite` is just a package name. - -=== Manually start and stop Connect +== Manually start and stop Connect -To start Connect from the command line, run the following command: +To start Connect or Connect Lite from the command line, run the following command: [source,console] ---- diff --git a/documentation/asciidoc/services/connect/introduction.adoc b/documentation/asciidoc/services/connect/introduction.adoc index 56db23adc..bfccb6487 100644 --- a/documentation/asciidoc/services/connect/introduction.adoc +++ b/documentation/asciidoc/services/connect/introduction.adoc @@ -4,10 +4,10 @@ Raspberry Pi Connect provides secure access to your Raspberry Pi from anywhere i image::images/hero.png[width="100%"] -To use Connect, xref:connect.adoc#install-connect[install the Connect software] and xref:connect.adoc#link-connect[link your device with an account] on your Raspberry Pi. Then visit https://connect.raspberrypi.com[connect.raspberrypi.com] to access the desktop or a shell running on your Raspberry Pi in a browser window. +Connect is installed by default in Raspberry Pi OS Desktop and Raspberry Pi OS Full (desktop with recommended software). Raspberry Pi OS Lite doesn't include Connect by default, but you can xref:connect.adoc#install-connect-lite[install Connect Lite]. -Connect uses a secure, encrypted connection. By default, Connect communicates directly between your Raspberry Pi and your browser. However, when Connect can't establish a direct connection between your Raspberry Pi and your browser, we use a relay server. In such cases, Raspberry Pi only retains the metadata required to operate Connect. +To use Connect, xref:connect.adoc#link-connect[link your device with a Connect account]. Visit https://connect.raspberrypi.com[connect.raspberrypi.com] to access the desktop or a shell running on your Raspberry Pi in a browser window. -Connect is currently in the Beta phase of development. +Connect uses a secure, encrypted connection. By default, Connect communicates directly between your Raspberry Pi and your browser. However, when Connect can't establish a direct connection between your Raspberry Pi and your browser, we use a relay server. In such cases, Raspberry Pi only retains the metadata required to operate Connect. NOTE: To use Connect, your Raspberry Pi must run https://www.raspberrypi.com/news/bookworm-the-new-version-of-raspberry-pi-os/[Raspberry Pi OS Bookworm] or later. diff --git a/documentation/asciidoc/services/connect/security.adoc b/documentation/asciidoc/services/connect/security.adoc new file mode 100644 index 000000000..356e2a9a8 --- /dev/null +++ b/documentation/asciidoc/services/connect/security.adoc @@ -0,0 +1,17 @@ +== Security + +All connections between Raspberry Pi devices and the user's browser use https://webrtc.org[WebRTC]: the same real-time communication technology used by Zoom, Microsoft Teams, and Google Meet. + +This means that all screen sharing and remote shell access traffic is encrypted using https://en.wikipedia.org/wiki/Datagram_Transport_Layer_Security[DTLS] on the Raspberry Pi device and the user's browser. We don't (and can't) decrypt the traffic, ensuring your data remains private. + +Furthermore, traffic is mostly peer-to-peer, meaning that the encrypted traffic doesn't pass through our infrastructure. Instead, the encrypted traffic is sent directly between your Raspberry Pi device and your browser. This makes it impossible for us to observe it. + +In situations where direct peer-to-peer connections aren't possible (for example, due to networking issues), only encrypted data is relayed through one of our https://en.wikipedia.org/wiki/Traversal_Using_Relays_around_NAT[TURN] servers. These servers are hosted in London and California, and your traffic is routed through the relay closest to you. We don't have the keys to decrypt this data, and it's neither logged nor stored. + +The Raspberry Pi Connect API temporarily stores the IP addresses and ports required to negotiate a peer-to-peer connection. All traffic to this API is encrypted using https://en.wikipedia.org/wiki/HTTPS[HTTP over TLS], supporting only TLS 1.2 and newer for security. This ensures that connection information is never sent in the clear. This metadata is stored securely for at most 1 minute, and deleted as soon as a connection is established. + +Raspberry Pi Connect, along with its API and software components, has undergone security assessments by penetration testing and security analysts at https://cure53.de[Cure53]. + +For more details on WebRTC security, see https://webrtc-security.github.io/[A Study of WebRTC Security]. + +For **Connect for Organisations** customers, we provide an audit log to review activity from the past 90 days. To preserve privacy, we store only the country code when geolocating events by IP address. diff --git a/documentation/asciidoc/services/connect/troubleshooting.adoc b/documentation/asciidoc/services/connect/troubleshooting.adoc index d05876ab3..aaf45e767 100644 --- a/documentation/asciidoc/services/connect/troubleshooting.adoc +++ b/documentation/asciidoc/services/connect/troubleshooting.adoc @@ -6,10 +6,12 @@ * Connect does not support on-screen keyboards. For full functionality, use a physical keyboard. -* Connect requires a browser that implements https://caniuse.com/?search=es2020[ECMAScript 2020] (ES11) as it makes use of https://caniuse.com/?feats=mdn-javascript_operators_optional_chaining,mdn-javascript_operators_nullish_coalescing,mdn-javascript_builtins_globalthis,es6-module-dynamic-import,bigint,mdn-javascript_builtins_promise_allsettled,mdn-javascript_builtins_string_matchall,mdn-javascript_statements_export_namespace,mdn-javascript_operators_import_meta[features] unavailable in older browsers. +* Connect requires a browser that implements https://caniuse.com/?search=es2022[ECMAScript 2022] (ES13) as it makes use of features unavailable in older browsers. * Browsers intercept certain keys and key combinations. As a result, you can't type these keys into your Connect window. Screen sharing includes a toolbar to simulate some of the most popular intercepted keys. +* Upgrading `rpi-connect` and `rpi-connect-lite` using Connect's remote shell is not supported. The upgrade process will terminate all remote shell sessions and drop all connections. To upgrade Connect in a remote shell session, use a tool like `screen` or `tmux` to ensure the process continues uninterrupted after your connection is closed. + * To upgrade from version 1 to version 2, you must first upgrade the package you currently have installed before switching between `rpi-connect` and `rpi-connect-lite`. This ensures that Connect's services properly migrate to the version 2 format. If you currently have `rpi-connect` installed, run the following command: + [source,console] @@ -35,14 +37,49 @@ Replacing globally-enabled rpi-connect services with user-enabled ones... ==== Screen sharing not available -If Connect states that screen sharing is unavailable, it cannot connect to the dedicated Connect WayVNC service. +If Connect states that screen sharing is unavailable, one or more requirements for screen sharing support are not met. To help debug the problem, `rpi-connect` and `rpi-connect-lite` include the `doctor` command. Use `rpi-connect doctor` to identify issues with screen sharing. -To find out more about the cause of the issue, run the following commands to check the status of the Connect WayVNC service: +Run the following command: [source,console] ---- -$ systemctl --user status rpi-connect-wayvnc -$ journalctl --user --follow --unit rpi-connect-wayvnc +$ rpi-connect doctor +---- + +If all is well, you should see output similar to the following: + +---- +Screen sharing is supported by this version of rpi-connect +✓ Wayland compositor available +✓ Screen sharing services enabled and active +✓ Communication with Raspberry Pi Connect WebSocket server +✓ Communication with Raspberry Pi Connect API +✓ Authentication with Raspberry Pi Connect API +✓ Peer-to-peer connection candidate via STUN +✓ Peer-to-peer connection candidate via TURN +---- + +If there is an issue, you will see something like so: + +---- +Screen sharing is supported by this version of rpi-connect +✓ Wayland compositor available +✗ Screen sharing services enabled and active - Please run rpi-connect on to enable and start all required services +✓ Communication with Raspberry Pi Connect WebSocket server +✓ Communication with Raspberry Pi Connect API +✓ Authentication with Raspberry Pi Connect API +✓ Peer-to-peer connection candidate via STUN +✓ Peer-to-peer connection candidate via TURN + +✗ Some checks failed +---- + +If you have repeated issues trying to run Connect's required services, run the following commands to check their status in more detail: + +[source,console] +---- +$ systemctl --user status rpi-connect-wayvnc.service rpi-connect-wayvnc-watcher.path +$ journalctl --follow --user-unit rpi-connect-wayvnc.service --user-unit rpi-connect-wayvnc-watcher.path ---- If the service fails to start or doesn't exist, ensure that your environment meets the following criteria: @@ -63,7 +100,6 @@ For screen sharing, Connect can only share an existing graphical desktop session Connect usually communicates between devices without requiring changes to your network or firewall. However, especially restrictive networks can sometimes block Connect communication. To help debug problems with such networks, `rpi-connect` and `rpi-connect-lite` include the `rpi-connect doctor` command. `rpi-connect doctor` runs a series of tests to check that Connect communication functions properly on your network. - To run these tests on your device, run the following command: [source,console] @@ -74,6 +110,10 @@ $ rpi-connect doctor If Connect can communicate properly on your network, you should see output similar to the following: ---- +Screen sharing is supported by this version of rpi-connect +✓ Wayland compositor available +✓ Screen sharing services enabled and active +✓ Communication with Raspberry Pi Connect WebSocket server ✓ Communication with Raspberry Pi Connect API ✓ Authentication with Raspberry Pi Connect API ✓ Peer-to-peer connection candidate via STUN @@ -82,8 +122,7 @@ If Connect can communicate properly on your network, you should see output simil If Connect can't communicate properly on your network, you'll see an "x" instead of a check next to the failing test case. Ask your network administrator to enable the following connections on your network: -* unauthenticated HTTPS requests to the Raspberry Pi Connect API on port 443 of `api.connect.raspberrypi.com` -* authenticated requests to the Raspberry Pi Connect API on port 443 of `api.connect.raspberrypi.com` +* HTTPS requests to the Raspberry Pi Connect API and WebSocket server on port 443 of `api.connect.raspberrypi.com` and `ws.connect.raspberrypi.com` * requests to Raspberry Pi Connect STUN or TURN servers on UDP port 3478 of all of the following: ** `stun.raspberrypi.com` ** `turn1.raspberrypi.com` @@ -111,6 +150,7 @@ You should see output similar to the following: ---- Signed in: yes +Subscribed to events: yes Screen sharing: allowed (0 sessions active) Remote shell: allowed (0 sessions active) ---- @@ -183,5 +223,5 @@ To view logs for the Connect service and its dedicated WayVNC server, run the fo [source,console] ---- -$ journalctl --user --follow --unit rpi-connect --unit rpi-connect-wayvnc +$ journalctl --follow --user-unit rpi-connect --user-unit rpi-connect-wayvnc ---- diff --git a/documentation/asciidoc/services/connect/use.adoc b/documentation/asciidoc/services/connect/use.adoc index 9e331d585..2388242c4 100644 --- a/documentation/asciidoc/services/connect/use.adoc +++ b/documentation/asciidoc/services/connect/use.adoc @@ -7,15 +7,15 @@ Now that you've installed and started Connect on your Raspberry Pi device, you m ====== Desktop:: + -If you're using the Connect plugin for the menu bar, click **Turn On Raspberry Pi Connect** for the first time to open your browser, prompting you to sign in with your Raspberry Pi ID: +From the Connect icon in the menu bar, select **Turn On Raspberry Pi Connect** for the first time to open your browser, prompting you to sign in with your Raspberry Pi ID: + image::images/browser-sign-in.png[width="80%"] + -Alternatively, choose **Sign In...** from the dropdown menu: +If you have already turned on Connect, choose **Sign In...** from the dropdown menu: + image::images/sign-in.png[width="80%"] + -If you don't already have a Raspberry Pi ID, click *create one for free* to xref:id.adoc#create-a-raspberry-pi-id[create one]. +If you don't already have a Raspberry Pi ID, select *create one for free* to xref:id.adoc#create-a-raspberry-pi-id[create one]. CLI:: + @@ -26,7 +26,7 @@ Use the following command to generate a link that will connect your device with $ rpi-connect signin ---- + -This command should output something like the following: +This command outputs something like the following: + ---- Complete sign in by visiting https://connect.raspberrypi.com/verify/XXXX-XXXX @@ -38,17 +38,17 @@ Visit the verification URL on any device and sign in with your Raspberry Pi ID t === Finish linking your Raspberry Pi -After authenticating, assign a name to your device. Choose a name that uniquely identifies the device. Click the **Create device and sign in** button to continue. +After authenticating, assign a name to your device. Choose a name that uniquely identifies the device. Select the **Create device and sign in** button to continue. image::images/new-device.png[width="80%"] -You can now remotely connect to your device. The Connect icon in your menu bar will turn blue to indicate that your device is now signed in to the Connect service. You should receive an email notification indicating that a new device is linked to your Connect account. +You can now remotely connect to your device. The Connect icon in your menu bar turns blue to indicate that your device is signed in to the Connect service. You should receive an email notification indicating that a new device is linked to your Connect account. image::images/sign-in-email.png[width="70%"] WARNING: If you receive an email that says a device that you do not recognise has signed into Connect, change your Raspberry Pi ID password immediately. xref:connect.adoc#manage-devices[Remove the device from Connect] to permanently disassociate it from your account. Consider xref:id.adoc#enable-two-factor-authentication[enabling two-factor authentication] to keep your account secure. -Click the Connect icon in your menu bar to open the Connect menu. This menu allows you to turn Connect on and off, sign in and out, and allow or disallow remote access methods. +Open the Connect menu by selecting the Connect icon in your menu bar. This menu allows you to turn Connect on and off, sign in and out, and allow or disallow remote access methods. TIP: Connect signs communication with your device serial number. Moving your SD card between devices will sign you out of Connect. @@ -68,7 +68,7 @@ Connect redirects you to the Raspberry Pi ID service to sign in. After signing i image::images/devices.png[width="80%"] -Click the **Connect via** button to the right of the device you would like to access. Select the **Screen sharing** option from the menu. This opens a browser window that displays your device's desktop. +Select the **Connect via** button to the right of the device you want to access. Select the **Screen sharing** option from the menu. This opens a browser window that displays your device's desktop. image::images/waiting-for-screen-sharing.png[width="80%"] @@ -82,19 +82,19 @@ Once connected, a green dot appears next to the **Screen sharing** badge in the image::images/screen-sharing-in-progress.png[width="80%"] -The Connect icon in the system tray turns purple and displays a closed circle when a screen sharing session is in progress. A desktop notification will appear whenever a screen sharing session starts. +The Connect icon in the system tray rotates when a screen sharing session is in progress. A desktop notification appears whenever a screen sharing session starts. image::images/screen-sharing-notification.png[width="80%"] ==== Stop screen sharing -To close a screen sharing session, click the **Disconnect** button above your desktop. +To close a screen sharing session, select the **Disconnect** button above your desktop. image::images/screen-sharing-ended.png[width="80%"] ==== Disallow screen sharing -To turn off screen sharing, click the Connect icon in the menu bar and unselect **Allow Screen Sharing**. Your device remains signed into Connect, but you won't be able to create a screen sharing session from the Connect dashboard. +To turn off screen sharing, select the Connect icon in the menu bar then deselect **Allow Screen Sharing**. Your device remains signed in to Connect, but you can't create a screen sharing session from the Connect dashboard. image::images/disallow-screen-sharing.png[width="80%"] @@ -111,8 +111,8 @@ image::images/screen-sharing-disabled.png[width="80%"] To re-enable screen sharing, do one of the following: -* click the Connect icon in the menu bar and select **Allow Screen Sharing** -* run the following command: +* Select the Connect icon in the menu bar and then choose **Allow Screen Sharing** +* Run the following command: + [source,console] ---- @@ -129,7 +129,7 @@ Connect redirects you to the Raspberry Pi ID service to sign in. After signing i image::images/devices.png[width="80%"] -Click the **Connect via** button to the right of the device you would like to access. Select the **Remote shell** option from the menu. This opens a shell session on your device. +Select the **Connect via** button to the right of the device you would like to access. Select the **Remote shell** option from the menu. This opens a shell session on your device. image::images/waiting-for-remote-shell.png[width="80%"] @@ -145,7 +145,7 @@ image::images/remote-shell-in-progress.png[width="80%"] TIP: Every remote shell connection creates a brand new connection, just like SSH. To persist background commands and configuration across multiple sessions, use `screen` or `tmux`. -The Connect icon in the menu bar turns purple and displays a closed circle when a remote shell session is in progress. A desktop notification will appear whenever a remote shell session starts. +The Connect icon in the menu bar rotates when a remote shell session is in progress. A desktop notification appears whenever a remote shell session starts. image::images/remote-shell-notification.png[width="80%"] @@ -159,7 +159,7 @@ image::images/remote-shell-ended.png[width="80%"] ==== Disallow remote shell access -To turn off remote shell access, click the Connect icon in the menu bar and unselect **Allow Remote Shell Access**. Your device remains signed into Connect, but you won't be able to create a remote shell session from the Connect dashboard. +To turn off remote shell access, select the Connect icon in the menu bar and then deselect **Allow Remote Shell Access**. Your device remains signed in to Connect, but you can't create a remote shell session from the Connect dashboard. image::images/disallow-remote-shell.png[width="80%"] @@ -176,8 +176,8 @@ image::images/remote-shell-disabled.png[width="80%"] To re-enable remote shell access, do one of the following: -* click the Connect system tray icon and select **Allow Remote Shell Access** -* run the following command: +* Select the Connect system tray icon and choose **Allow Remote Shell Access** +* Run the following command: + [source,console] ---- @@ -195,13 +195,27 @@ $ loginctl enable-linger TIP: We recommend enabling user-lingering on all headless Raspberry Pi OS Lite setups to prevent your device from becoming unreachable after a remote reboot. +== Disabling the animated icon + +To disable the animated icon when a screen sharing or remote shell session are in progress, right-click the Connect icon in the menu bar and select **Configure Plugin...**. + +image::images/configure-plugin.png[width="80%"] + +Select the **Animate Icon** toggle to switch to an alternate icon. + +image::images/disable-animate-icon.png[width="80%"] + +When a screen sharing or remote shell session is in progress, the Connect icon turns blue. + +image::images/static-icon.png[width="80%"] + == Manage devices The Connect dashboard lists all of the devices linked with your Connect account and shows you the various ways you can access them. image::images/devices.png[width="80%"] -Click on a device name to open the device details page. This screen provides low-level information about your device. You can also edit the device name or remove the device from Connect. +Select a device name to open the device details page. This screen provides low-level information about your device. You can also edit the device name or remove the device from Connect. image::images/device.png[width="80%"] @@ -228,7 +242,7 @@ Run the following command on your device to sign out of your Raspberry Pi ID, wh $ rpi-connect signout ---- -Alternatively, click the Connect icon in the menu bar and click "Sign Out". +Alternatively, select the Connect icon in the menu bar and choose "Sign Out". TIP: To fully remove a device from your Connect account, xref:connect.adoc#manage-devices[remove it from the Connect dashboard]. diff --git a/documentation/images/Bookshelf-SMALL.png b/documentation/images/Bookshelf-SMALL.png new file mode 100644 index 000000000..b8931da99 Binary files /dev/null and b/documentation/images/Bookshelf-SMALL.png differ diff --git a/documentation/images/full-sized/Bookshelf.png b/documentation/images/full-sized/Bookshelf.png new file mode 100644 index 000000000..b7f2192cd Binary files /dev/null and b/documentation/images/full-sized/Bookshelf.png differ diff --git a/documentation/images/full-sized/keyboard-computers.png b/documentation/images/full-sized/keyboard-computers.png new file mode 100644 index 000000000..36973962d Binary files /dev/null and b/documentation/images/full-sized/keyboard-computers.png differ diff --git a/documentation/images/full-sized/software-sources.png b/documentation/images/full-sized/software-sources.png new file mode 100644 index 000000000..64cf707be Binary files /dev/null and b/documentation/images/full-sized/software-sources.png differ diff --git a/documentation/images/keyboard-computers-SMALL.png b/documentation/images/keyboard-computers-SMALL.png new file mode 100644 index 000000000..97a0cd796 Binary files /dev/null and b/documentation/images/keyboard-computers-SMALL.png differ diff --git a/documentation/images/placeholder/placeholder_circle-SMALL.png b/documentation/images/placeholder/placeholder_circle-SMALL.png new file mode 100644 index 000000000..d87e8121a Binary files /dev/null and b/documentation/images/placeholder/placeholder_circle-SMALL.png differ diff --git a/documentation/images/placeholder/placeholder_circle.png b/documentation/images/placeholder/placeholder_circle.png index d87e8121a..258267657 100644 Binary files a/documentation/images/placeholder/placeholder_circle.png and b/documentation/images/placeholder/placeholder_circle.png differ diff --git a/documentation/images/placeholder/placeholder_square-SMALL.png b/documentation/images/placeholder/placeholder_square-SMALL.png new file mode 100644 index 000000000..b51bc8fb1 Binary files /dev/null and b/documentation/images/placeholder/placeholder_square-SMALL.png differ diff --git a/documentation/images/placeholder/placeholder_square.png b/documentation/images/placeholder/placeholder_square.png index b51bc8fb1..8583725b8 100644 Binary files a/documentation/images/placeholder/placeholder_square.png and b/documentation/images/placeholder/placeholder_square.png differ diff --git a/documentation/images/placeholder/placeholder_triangle-SMALL.png b/documentation/images/placeholder/placeholder_triangle-SMALL.png new file mode 100644 index 000000000..0ee52120c Binary files /dev/null and b/documentation/images/placeholder/placeholder_triangle-SMALL.png differ diff --git a/documentation/images/placeholder/placeholder_triangle.png b/documentation/images/placeholder/placeholder_triangle.png index 0ee52120c..17d54ff2d 100644 Binary files a/documentation/images/placeholder/placeholder_triangle.png and b/documentation/images/placeholder/placeholder_triangle.png differ diff --git a/documentation/index.json b/documentation/index.json index d0000060f..8be16f78c 100644 --- a/documentation/index.json +++ b/documentation/index.json @@ -29,12 +29,6 @@ "image": "full-sized/The-config-txt-file.png", "subpath": "config_txt.adoc" }, - { - "title": "Legacy `config.txt` options", - "description": "Options which may be useful for OSes other than Raspberry Pi OS", - "image": "full-sized/Legacy-config-txt.png", - "subpath": "legacy_config_txt.adoc" - }, { "title": "The Linux kernel", "description": "How to configure and build a custom kernel for your Raspberry Pi", @@ -60,11 +54,17 @@ "subpath": "ai.adoc" }, { - "title": "Raspberry Pi hardware", - "description": "Technical information about Raspberry Pi hardware", + "title": "Raspberry Pi computer hardware", + "description": "Technical information about Raspberry Pi computer hardware", "image": "full-sized/Raspberry-Pi-Hardware.png", "subpath": "raspberry-pi.adoc" }, + { + "title": "Keyboard computers", + "description": "Technical information about Raspberry Pi keyboard computers", + "image": "full-sized/keyboard-computers.png", + "subpath": "keyboard-computers.adoc" + }, { "title": "Compute Module hardware", "description": "Technical information about Raspberry Pi Compute Module hardware", @@ -76,6 +76,18 @@ "description": "Technical information about the CPUs used by Raspberry Pi", "image": "full-sized/Processors.png", "subpath": "processors.adoc" + }, + { + "title": "Software sources", + "description": "Open source software by Raspberry Pi", + "image": "full-sized/software-sources.png", + "subpath": "software-sources.adoc" + }, + { + "title": "Legacy `config.txt` options", + "description": "Options which might be useful for OSes other than Raspberry Pi OS", + "image": "full-sized/Legacy-config-txt.png", + "subpath": "legacy_config_txt.adoc" } ] }, @@ -221,7 +233,7 @@ "description": "Supports Arm Serial Wire Debug (SWD), and acts as a UART bridge", "image": "full-sized/Debug-Probe.png", "subpath": "debug-probe.adoc" - }, + }, { "title": "MicroPython", "description": "Getting started with MicroPython", @@ -247,10 +259,16 @@ "subpath": "id.adoc" }, { - "title": "Raspberry Pi Connect (Beta)", + "title": "Raspberry Pi Connect", "description": "Connect to your Raspberry Pi from your browser", "image": "full-sized/Connect-BIG.png", "subpath": "connect.adoc" + }, + { + "title": "Bookshelf", + "description": "Read titles published by Raspberry Pi Press", + "image": "full-sized/Bookshelf.png", + "subpath": "bookshelf.adoc" } ] }, @@ -260,4 +278,4 @@ "directory": "pico-sdk" } ] -} +} \ No newline at end of file diff --git a/documentation/redirects/datasheets.csv b/documentation/redirects/datasheets.csv index 241df2db5..ab8531255 100644 --- a/documentation/redirects/datasheets.csv +++ b/documentation/redirects/datasheets.csv @@ -26,18 +26,6 @@ /documentation/hardware/computemodule/datasheets/rpi_DATA_CM_2p0.pdf,https://datasheets.raspberrypi.com/cm/cm1-and-cm3-datasheet.pdf /documentation/hardware/computemodule/datasheets/rpi_DATA_CM_1p0.pdf,https://datasheets.raspberrypi.com/cm/cm1-and-cm3-datasheet.pdf /documentation/hardware/computemodule/datasheets/rpi_DATA_CM3plus_1p0.pdf,https://datasheets.raspberrypi.com/cm/cm3-plus-datasheet.pdf -/documentation/hardware/computemodule/dt-blob-cam1.bin,https://datasheets.raspberrypi.com/cmio/dt-blob-cam1.bin -/documentation/hardware/computemodule/dt-blob-cam1.dts,https://datasheets.raspberrypi.com/cmio/dt-blob-cam1.dts -/documentation/hardware/computemodule/dt-blob-disp0-only.bin,https://datasheets.raspberrypi.com/cmio/dt-blob-disp0-only.bin -/documentation/hardware/computemodule/dt-blob-disp0-only.dts,https://datasheets.raspberrypi.com/cmio/dt-blob-disp0-only.dts -/documentation/hardware/computemodule/dt-blob-disp1-cam1.bin,https://datasheets.raspberrypi.com/cmio/dt-blob-disp1-cam1.bin -/documentation/hardware/computemodule/dt-blob-disp1-cam1.dts,https://datasheets.raspberrypi.com/cmio/dt-blob-disp1-cam1.dts -/documentation/hardware/computemodule/dt-blob-disp1-cam2.bin,https://datasheets.raspberrypi.com/cmio/dt-blob-disp1-cam2.bin -/documentation/hardware/computemodule/dt-blob-disp1-cam2.dts,https://datasheets.raspberrypi.com/cmio/dt-blob-disp1-cam2.dts -/documentation/hardware/computemodule/dt-blob-disp1-only.bin,https://datasheets.raspberrypi.com/cmio/dt-blob-disp1-only.bin -/documentation/hardware/computemodule/dt-blob-disp1-only.dts,https://datasheets.raspberrypi.com/cmio/dt-blob-disp1-only.dts -/documentation/hardware/computemodule/dt-blob-dualcam.bin,https://datasheets.raspberrypi.com/cmio/dt-blob-dualcam.bin -/documentation/hardware/computemodule/dt-blob-dualcam.dts,https://datasheets.raspberrypi.com/cmio/dt-blob-dualcam.dts /documentation/hardware/computemodule/example1-overlay.dts,https://datasheets.raspberrypi.com/cm/example1-overlay.dts /documentation/hardware/computemodule/minimal-cm-dt-blob.dts,https://datasheets.raspberrypi.com/cm/minimal-cm-dt-blob.dts /documentation/linux/software/libcamera/rpi_SOFT_libcamera_1p0.pdf,https://datasheets.raspberrypi.com/camera/raspberry-pi-camera-guide.pdf @@ -79,5 +67,3 @@ /documentation/hardware/computemodule/designdata/rpi_DSGN_CMCDA_1p1.zip,https://datasheets.raspberrypi.com/cmcda/RPi-CMCDA-1P1.zip /documentation/hardware/computemodule/designdata/rpi_DSGN_CMIO_1p2.zip,https://datasheets.raspberrypi.com/cmio/RPi-CMIO-R1P2.zip /documentation/hardware/computemodule/designdata/rpi_DSGN_CMIO_3p0.zip,https://datasheets.raspberrypi.com/cmio/RPi-CMIO-R3P0.zip -/documentation/hardware/raspberrypi/bootmodes/pxetools/prepare_pxetools,https://datasheets.raspberrypi.com/soft/prepare_pxetools.sh -/documentation/hardware/raspberrypi/bootmodes/pxetools/pxetools,https://datasheets.raspberrypi.com/soft/pxetools.py diff --git a/jekyll-assets/_includes/footer.html b/jekyll-assets/_includes/footer.html index efe0c2197..c278ebebf 100644 --- a/jekyll-assets/_includes/footer.html +++ b/jekyll-assets/_includes/footer.html @@ -161,6 +161,7 @@
  • Our Approved Resellers
  • Jobs
  • Accessibility
    • +
  • Modern slavery statement
  • Site use terms and conditions
  • Acceptable use
  • Cookies
    • @@ -180,6 +181,7 @@
    For industry
    Documentation