Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Explode the Pi 5 documentation all over the place #3522

Merged
merged 3 commits into from
Feb 19, 2024
Merged

Explode the Pi 5 documentation all over the place #3522

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
687b4c9
Explode the Pi 5 documentation all over the place
nathan-contino Jan 31, 2024
df51d42
Incorporate feedback from al, tom
nathan-contino Feb 1, 2024
e0fbc65
minor cleanup
nathan-contino Feb 2, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions documentation/asciidoc/accessories/camera/synchronous_cameras.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ For correct operation, both cameras require a 1.65V pull up voltage on the XVS l

image::images/synchronous_camera_wiring.jpg[alt="Image showing potential divider setup",width="50%"]

Create a potential divider from two 10kΩ resistors to 3.3V and ground (to make 1.65V with an effective source impedence of 5kΩ). This can be connected to either Raspberry Pi.
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 the GND and XVS test points of each HQ Camera board to each other.

Expand Down Expand Up @@ -62,7 +62,7 @@ To operate as source and sink together, the Global Shutter Cameras also require

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 impedence of 5kΩ). This can be connected to either Raspberry Pi.
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.

Expand Down
2 changes: 1 addition & 1 deletion documentation/asciidoc/computers/camera/rpicam_hello.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ Please refer to the xref:camera_software.adoc#common-command-line-options[comman

==== The tuning file

Raspberry Pi's `libcamera` implementation includes a tuning file for each different type of camera module. This is a file that describes or tunes the parameters that will be passed to the algorithms and hardware to produce the best image quality. `libcamera` is only able to automaticaly determine the image sensor being used, not the module as a whole, even though the whole module affects the "tuning". For this reason it is sometimes necessary to override the default tuning file for a particular sensor.
Raspberry Pi's `libcamera` implementation includes a tuning file for each different type of camera module. This is a file that describes or tunes the parameters that will be passed to the algorithms and hardware to produce the best image quality. `libcamera` is only able to automatically determine the image sensor being used, not the module as a whole, even though the whole module affects the "tuning". For this reason it is sometimes necessary to override the default tuning file for a particular sensor.

For example, the no-IR-filter (NoIR) versions of sensors require different AWB settings to the standard versions, so the IMX219 NoIR being used with a Pi 4 or earlier device should be run using:

Expand Down
2 changes: 2 additions & 0 deletions documentation/asciidoc/computers/raspberry-pi.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,8 @@ include::raspberry-pi/raspberry-pi-industrial.adoc[]

include::raspberry-pi/otp-bits.adoc[]

include::raspberry-pi/pcie.adoc[]

include::raspberry-pi/power-button.adoc[]

include::raspberry-pi/power-supplies.adoc[]
Expand Down
4 changes: 2 additions & 2 deletions documentation/asciidoc/computers/raspberry-pi/frequency-management.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ Due to the architecture of the SoCs used on Raspberry Pi devices, and the use of

=== Adding heatsinks

Whilst heatsinks are not necessary to prevent overheating damage to the SoC — the thermal throttling mechanism handles that — a heatsink or small fan will help if you wish to reduce the amount of thermal throttling that takes place. Depending on the exact circumstances, mounting the Raspberry Pi vertically can also help with heat dissipation, as doing so can improve air flow. For Raspberry Pi 5, a https://www.raspberrypi.com/products/raspberry-pi-5-case/[case with an integrated fan] is available; if you prefer to keep your Raspberry Pi uncased, we also manufacture an https://www.raspberrypi.com/products/active-cooler/[Active Cooler] that can be mounted on the Raspberry Pi 5 itself.
Thanks to built-in throttling, heatsinks are not necessary to prevent overheating damage to the SoC. However, a heatsink or small fan can reduce thermal throttling and improve performance. Mount the Raspberry Pi vertically for the best airflow and thus slightly improved heat dissipation.

=== Fan cases

Expand All @@ -77,7 +77,7 @@ Temperature decreases use the same mapping with a 5°C **hysteresis**; fan speed

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`.

The official fan is a Coolcox https://www.coolcox.com/products/pdf/CC3007.pdf[CC3007H05S] part.
INFO: Both fan options use the Coolcox https://www.coolcox.com/products/pdf/CC3007.pdf[CC3007H05S] part.

==== Fan connector pinout

Expand Down
52 changes: 24 additions & 28 deletions documentation/asciidoc/computers/raspberry-pi/pcie.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,45 +5,28 @@ image::images/pcie.jpg[alt="Raspberry Pi connector for PCIe",width="70%"]

Raspberry Pi 5 has an FPC connector on the right-hand side of the board. This connector breaks out a PCIe Gen 2.0 ×1 interface for fast peripherals.

For more information about the PCIe FPC connector pinout and other details needed to create third-party devices, accessories, and HATs, see the https://datasheets.raspberrypi.com/pcie/pcie-connector-standard.pdf[Raspberry Pi Connector for PCIe] standards document. It should be read alongside the https://datasheets.raspberrypi.com/hat/hat-plus-specification.pdf[Raspberry Pi HAT+ Specification].

=== Enabling PCIe

By default the PCIe connector is not enabled. To enable it, add the following line to `/boot/firmware/config.txt`:

[source]
----
dtparam=pciex1
----
To connect a PCIe https://datasheets.raspberrypi.com/hat/hat-plus-specification.pdf[HAT+ device], connect it to your Raspberry Pi. Your Raspberry Pi should automatically detect the device. To connect a non-HAT+ device, connect it to your Raspberry Pi, then <<enable-pcie, manually enable PCIe>>.

Reboot with `sudo reboot` for the configuration changes to take effect.

NOTE: You can also use the alias `nvme`.
For more information about the PCIe FPC connector pinout and other details needed to create third-party devices, accessories, and HATs, see the https://datasheets.raspberrypi.com/pcie/pcie-connector-standard.pdf[Raspberry Pi Connector for PCIe] standards document. It should be read alongside the https://datasheets.raspberrypi.com/hat/hat-plus-specification.pdf[Raspberry Pi HAT+ Specification].

NOTE: Enumeration of PCIe devices behind a switch is https://github.com/raspberrypi/firmware/issues/1833[not currently supported].

=== PCIe Gen 3.0
=== Enable PCIe

The connection is certified for Gen 2.0 speeds (5 GT/sec), but you can force Gen 3.0 (10 GT/sec) speeds if you add the following lines to your `/boot/firmware/config.txt`.
By default, the PCIe connector is not enabled unless connected to a HAT+ device. To enable the connector, add the following line to `/boot/firmware/config.txt`:

[source]
[source,perl]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is this tagged as perl?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This syntax doesn't have a reasonable highlighting equivalent in our toolbox, so I just chose something that renders equal signs a different color so it's slightly easier to read large blocks of text with equal signs in between. Perl was a slightly arbitrary choice, but I tested bash and a couple of others and the square bracket [] syntax seems to mess up the highlighting. Perl, as we know, tolerates just about any string of characters without breaking, so I went with that 😄

----
# Enable the PCIe external connector
dtparam=pciex1

# Force Gen 3.0 speeds
dtparam=pciex1_gen=3
----

WARNING: The Raspberry Pi 5 is not certified for Gen 3.0 speeds, and connections to PCIe devices at these speeds may be unstable.
Reboot with `sudo reboot` for the configuration changes to take effect.

Reboot your Raspberry Pi with `sudo reboot` for these settings to take effect.
NOTE: You can also use the alias `nvme`.

=== Boot from PCIe

NOTE: Boards that follow the https://datasheets.raspberrypi.com/hat/hat-plus-specification.pdf[HAT+ standard] don't require this configuration.

Once enabled, and after rebooting, an NVMe disk attached via the PCIe should be visible. However, your Raspberry Pi won't try to boot from the NVMe drive. If you wish to enable boot support you will need to change the `BOOT_ORDER` in the bootloader configuration. Edit the EEPROM configuration with the following command:
By default, Raspberry Pi devices do not boot from PCIe storage. To enable boot from PCIe, change the `BOOT_ORDER` in the bootloader configuration. Edit the EEPROM configuration with the following command:

[source,console]
----
Expand All @@ -52,16 +35,29 @@ $ sudo rpi-eeprom-config --edit

Replace the `BOOT_ORDER` line with the following line:

[source]
[source,perl]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As above - why perl?

----
BOOT_ORDER=0xf416
----

To boot from a non-HAT+ device, also add the following line:

[source]
[source,perl]
----
PCIE_PROBE=1
----

After saving your changes, reboot your Raspberry Pi to update the EEPROM.
After saving your changes, reboot your Raspberry Pi with `sudo reboot` to update the EEPROM.

=== PCIe Gen 3.0

WARNING: The Raspberry Pi 5 is not certified for Gen 3.0 speeds. PCIe Gen 3.0 connections may be unstable.

The connection is certified for Gen 2.0 speeds (5 GT/sec), but you can force Gen 3.0 (10 GT/sec) speeds. To enable PCIe Gen 3.0 speeds, add the following line to `/boot/firmware/config.txt`:

[source,perl]
----
dtparam=pciex1_gen=3
----

Reboot your Raspberry Pi with `sudo reboot` for these settings to take effect.
4 changes: 2 additions & 2 deletions documentation/asciidoc/computers/raspberry-pi/power-button.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,9 @@ NOTE: This section only applies to Raspberry Pi models with a power button, such

When you plug your Raspberry Pi into power for the first time, it will automatically turn on and boot into the operating system without having to push the button.

If you run Raspberry Pi Desktop, you can initiate a clean shutdown by briefly pressing the power button. A menu will appear asking whether you want to shutdown, reboot, or logout.
If you run Raspberry Pi Desktop, you can initiate a clean shutdown by briefly pressing the power button. A window will appear asking whether you want to shutdown, reboot, or logout.

Select an option from the menu or press the power button again to initiate a clean shutdown.
Select an option or press the power button again to initiate a clean shutdown.

NOTE: If you run Raspberry Pi Desktop, you can press the power button twice in quick succession to shut down. If you run Raspberry Pi OS Lite without a desktop, press the power button a single time to initiate a shutdown.

Expand Down
3 changes: 1 addition & 2 deletions documentation/asciidoc/computers/raspberry-pi/power-supplies.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,6 @@ The Ethernet jack on Raspberry Pi 5 is PoE+ capable, supporting the IEEE 802.3at
.Raspberry Pi 5 PoE header
image::images/poe.jpg[alt="The PoE connector,width="70%"]


=== Typical power requirements

|===
Expand Down Expand Up @@ -147,7 +146,7 @@ This should drop the power consumption when powered down to around 0.01W.

On all models of Raspberry Pi since the Raspberry Pi B+ (2014) except the Zero range, there is low-voltage detection circuitry that will detect if the supply voltage drops below 4.63V (±5%). This will result in an entry being added to the kernel log.

If you see warnings, switch to a better power supply and cable. Low power can corrupt storage or cause unpredictable behaviour within the Raspberry Pi.
If you see warnings, switch to a higher quality power supply and cable. Low quality power supplies can corrupt storage or cause unpredictable behaviour within the Raspberry Pi.

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.

Expand Down
Loading