Skip to content

Commit

Permalink
Updates to the HDMI configuration documentation
Browse files Browse the repository at this point in the history 
Fixes #2310 #2957 #3067
  • Loading branch information
@lurch
lurch committed Sep 6, 2023
1 parent 8fe6a71 commit 60877a6
Show file tree
Hide file tree
Showing 5 changed files with 51 additions and 152 deletions.
2 changes: 2 additions & 0 deletions documentation/asciidoc/computers/configuration.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ include::configuration/use-a-proxy.adoc[]

include::configuration/hdmi-config.adoc[]

include::configuration/display-resolution.adoc[]

include::configuration/display-rotation.adoc[]

include::configuration/audio-config.adoc[]
Expand Down
34 changes: 34 additions & 0 deletions documentation/asciidoc/computers/configuration/display-resolution.adoc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
== Setting your display's resolution

If you find yourself in circumstances where the Raspberry Pi may not be able to determine the best mode, or you specifically wish to set a non-default resolution, you can manually set the resolution by editing various config files. Which config file you need to edit depends on whether you're booting to the desktop environment or booting to the CLI (text console).

=== Setting the desktop environment resolution

If you are running the Raspberry Pi desktop then the resolution is most easily changed by using the `Screen Configuration Utility` from the desktop `Preferences` menu. This will bring up a graphical representation of the display or displays connected to the Raspberry Pi. Right click on the display you wish to modify and select the required option.

It is also possible to change these settings by editing config files, although the method for doing this depends on whether you're running the Wayland or X11 backend. Type
[,bash]
----
ps ax | grep [w]ayfire
----
into a Terminal window, and if you get `/usr/bin/wayfire` displayed then you're running Wayland, and if you get no output you're running X11.

NOTE: In the current version of Raspberry Pi OS Bookworm, Raspberry Pi 4 and 400 default to using Wayland to display the desktop environment; whereas earlier models of Raspberry Pi default to using X11 to display the desktop environment.

==== Manually setting the desktop environment resolution for Wayland

Under Wayland you can set a custom display resolution by editing the `.config/wayfire.ini` file in your home directory. You need to edit the existing `[output:]` section, or add a new `[output:]` section for your display device if one doesn't exist. For example:
----
[output:HDMI-A-1]
mode = 1920x1080@60
----

The second half of the `[output:]` line (`HDMI-A-1` in the example shown here) matches the display options <<the-kernel-command-line,described for KMS>>.
The `mode` line is _similar_ to that used by KMS, but slightly different. Consult the https://github.com/WayfireWM/wayfire-wiki/blob/master/Configuration.md#output-configuration[Wayfire documentation] for more extensive information.

// TODO: ==== Manually setting the desktop environment resolution for X11

=== Manually setting the text console resolution

This is achieved by editing the KMS settings - see <<the-kernel-command-line,configuring the kernel command line>> for more details.

2 changes: 1 addition & 1 deletion documentation/asciidoc/computers/configuration/display-rotation.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ The options to rotate the display of your Raspberry Pi depend on whether you're

If you are running the Raspberry Pi desktop then rotation is most easily achieved by using the `Screen Configuration Utility` from the desktop `Preferences` menu. This will bring up a graphical representation of the display or displays connected to the Raspberry Pi. Right click on the display you wish to rotate and select the required option.

It is also possible to change these settings using the command line, although the method for doing this depends on whether you're running the X11 or Wayland backend. Type
It is also possible to change these settings using the command line, although the method for doing this depends on whether you're running the Wayland or X11 backend. Type
[,bash]
----
ps ax | grep [w]ayfire
Expand Down
145 changes: 2 additions & 143 deletions documentation/asciidoc/computers/configuration/hdmi-config.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,148 +2,7 @@

In the vast majority of cases, simply plugging your HDMI-equipped monitor into the Raspberry Pi using a standard HDMI cable will automatically result in the Raspberry Pi using the best resolution the monitor supports. The Raspberry Pi Zero, Zero W and Zero 2 W use a mini HDMI port, so you will need a mini-HDMI-to-full-size-HDMI lead or adapter. On the Raspberry Pi 4 and Raspberry Pi 400 there are two micro HDMI ports, so you will need a micro-HDMI-to-full-size-HDMI lead or adapter for each display you wish to attach. You should connect any HDMI leads before turning on the Raspberry Pi.

The Raspberry Pi 4 can drive up to two displays, with a resolution up to 1080p at a 60Hz refresh rate. At 4K resolution, if you connect two displays then you are limited to a 30Hz refresh rate. You can also drive a single display at 4K with a 60Hz refresh rate: this requires that the display is attached to the HDMI port adjacent to the USB-C power input (labelled HDMI0). You must also enable 4Kp60 output by setting the `hdmi_enable_4kp60=1` flag in config.txt. This flag can also be set using the 'Raspberry Pi Configuration' tool within the desktop environment.
The Raspberry Pi 4 (and Pi 400) can drive up to two displays, with a resolution up to 1080p at a 60Hz refresh rate. At 4K resolution, if you connect two displays then you are limited to a 30Hz refresh rate. You can also drive a single display at 4K with a 60Hz refresh rate: this requires that the display is attached to the HDMI port adjacent to the USB-C power input (labelled HDMI0). You must also enable 4Kp60 output by setting the `hdmi_enable_4kp60=1` flag in `config.txt`.

If you are running the 3D graphics driver (also known as the FKMS driver), then in the Preferences menu you will find a graphical application for setting up standard displays, including multi-display setups.
The Screen Configuration tool (`arandr`) is a graphical tool for selecting display modes and setting up multiple displays. You can find this tool in the desktop Preferences menu. Use the Layout menu option to select the screen, resolution, and orientation. If you're using a multi-screen setup, drag around the displays to any position you want. When you have the required setup, click the Apply button to apply the settings.

[NOTE]
====
The Screen Configuration tool (`arandr`) is a graphical tool for selecting display modes and setting up multiple displays. You can find this tool in the desktop Preferences menu, but only if the 3D graphics driver is being used, as it is this driver that provides the required mode setting functionality. Use the Configure menu option to select the screen, resolution, and orientation. If you're using a multi-screen setup, drag around the displays to any position you want. When you have the required setup, click the Tick button to apply the settings.
====

If you are using legacy graphics drivers, or find yourself in circumstances where the Raspberry Pi may not be able to determine the best mode, or you may specifically wish to set a non-default resolution, the rest of this page may be useful.

NOTE: All the commands are documented fully in the xref:config_txt.adoc#video-options[config.txt] section of the documentation.

=== HDMI Groups and Mode

HDMI has two common groups: CEA (Consumer Electronics Association, the standard typically used by TVs) and DMT (Display Monitor Timings, the standard typically used by monitors). Each group advertises a particular set of modes, where a mode describes the resolution, frame rate, clock rate, and aspect ratio of the output.

=== What Modes does my Device Support?

You can use the `tvservice` application on the command line to determine which modes are supported by your device, along with other useful data:

* `tvservice -s` displays the current HDMI status, including mode and resolution
* `tvservice -m CEA` lists all supported CEA modes
* `tvservice -m DMT` lists all supported DMT modes

If you are using a Raspberry Pi 4 with more than one display attached, then `tvservice` needs to be told which device to ask for information. You can get display IDs for all attached devices by using:

`tvservice -l`

You can specify which display `tvservice` uses by adding `-v <display id>` to the `tvservice` command, e.g:

* `tvservice -v 7 -m CEA`, lists all supported CEA modes for display ID 7

=== Setting a Specific HDMI Mode

Setting a specific mode is done using the `hdmi_group` and `hdmi_mode` config.txt entries. The group entry selects between CEA or DMT, and the mode selects the resolution and frame rate. You can find tables of modes on the config.txt xref:config_txt.adoc#video-options[Video Configuration] page, but you should use the `tvservice` command described above to find out exactly which modes your device supports.

On the Raspberry Pi 4 and Raspberry Pi 400 to specify the HDMI port, add an index identifier to the `hdmi_group` or `hdmi_mode` entry in config.txt, e.g. `hdmi_mode:0` or `hdmi_group:1`.

=== Setting a Custom HDMI Mode

There are two options for setting a custom mode: `hdmi_cvt` and `hdmi_timings`.

`hdmi_cvt` sets a custom Coordinated Video Timing entry, which is described fully here: xref:legacy_config_txt.adoc#custom-mode[Video Configuration]

In certain rare cases it may be necessary to define the exact clock requirements of the HDMI signal. This is a fully custom mode, and it is activated by setting `hdmi_group=2` and `hdmi_mode=87`. You can then use the `hdmi_timings` config.txt command to set the specific parameters for your display.
`hdmi_timings` specifies all the timings that an HDMI signal needs to use. These timings are usually found in the datasheet of the display being used.

[source]
----
hdmi_timings=<h_active_pixels> <h_sync_polarity> <h_front_porch> <h_sync_pulse> <h_back_porch> <v_active_pixels> <h_sync_polarity> <h_front_porch> <h_sync_pulse> <h_back_porch> <v_active_lines> <v_sync_polarity> v_front_porch> <v_sync_pulse> <v_back_porch> <v_sync_offset_a> <v_sync_offset_b> <pixel_rep> <frame_rate> <interlaced> <pixel_freq> <aspect_ratio>
----

|===
| Timing | Purpose

| `h_active_pixels`
| The horizontal resolution

| `h_sync_polarity`
| 0 or 1 to define the horizontal sync polarity

| `h_front_porch`
| Number of horizontal front porch pixels

| `h_sync_pulse`
| Width of horizontal sync pulse

| `h_back_porch`
| Number of horizontal back porch pixels

| `v_active_lines`
| The vertical resolution

| `v_sync_polarity`
| 0 or 1 to define the vertical sync polarity

| `v_front_porch`
| Number of vertical front porch pixels

| `v_sync_pulse`
| Width of vertical sync pulse

| `v_back_porch`
| Number of vertical back porch pixels

| `v_sync_offset_a`
| Leave at 0

| `v_sync_offset_b`
| Leave at 0

| `pixel_rep`
| Leave at 0

| `frame_rate`
| Frame rate of mode

| `interlaced`
| 0 for non-interlaced, 1 for interlaced

| `pixel_freq`
| The mode pixel frequency

| `aspect_ratio`
| The aspect ratio required
|===

`aspect_ratio` should be one of the following:

|===
| Ratio | `aspect_ratio` ID

| `4:3`
| 1

| `14:9`
| 2

| `16:9`
| 3

| `5:4`
| 4

| `16:10`
| 5

| `15:9`
| 6

| `21:9`
| 7

| `64:27`
| 8
|===

For the Raspberry Pi 4 and Raspberry Pi 400 to specify the HDMI port, you can add an index identifier to the config.txt. e.g. `+hdmi_cvt:0=...+` or `+hdmi_timings:1=...+`. If no port identifier is specified, the settings are applied to port 0.

=== Troubleshooting your HDMI

In some rare cases you may need to increase the HDMI drive strength, for example when there is speckling on the display or when you are using very long cables. There is a config.txt item to do this, `config_hdmi_boost`, which is documented on the xref:config_txt.adoc#video-options[config.txt video page].

NOTE: The Raspberry Pi 4B does not yet support `config_hdmi_boost`, support for this option will be added in a future software update.
20 changes: 12 additions & 8 deletions documentation/asciidoc/computers/configuration/kernel-command-line-config.adoc
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
== The Kernel Command Line

The Linux kernel accepts a command line of parameters during boot. On the Raspberry Pi, this command line is defined in a file in the boot partition, called cmdline.txt. This is a simple text file that can be edited using any text editor, e.g. Nano.
The Linux kernel accepts a command line of parameters during boot. On the Raspberry Pi, this command line is defined in a file in the boot partition, called `cmdline.txt`. This is a simple text file that can be edited using any text editor, e.g. Nano.

----
sudo nano /boot/cmdline.txt
Expand All @@ -25,24 +25,26 @@ There are many kernel command line parameters, some of which are defined by the
* quiet: sets the default kernel log level to `KERN_WARNING`, which suppresses all but very serious log messages during boot.

[discrete]
===== Display Entries in FKMS and KMS modes
===== Setting the KMS display mode

The firmware automatically adds a preferred resolution and overscan settings via an entry such as:
The "legacy firmware" and "FKMS" display modes used in earlier versions of Raspberry Pi OS are no longer supported; KMS (Kernel Mode Setting) is now used instead.

If no `video` entry is present in `cmdline.txt` then the Linux kernel will read the EDID of an HDMI-connected monitor, and automatically pick the best display resolution supported by your monitor / television. If you're using Raspberry Pi OS Lite, or the "boot to CLI" mode of Raspberry Pi OS, and you want to change the resolution of the text console, then you'll need to add a `video` setting to `cmdline.txt`, for example:

[source]
----
video=HDMI-A-1:1920x1080M@60,margin_left=0,margin_right=0,margin_top=0,margin_bottom=0
video=HDMI-A-1:1920x1080M@60
----

This default entry can be modified by duplicating the entry above manually in /boot/cmdline.txt and making required changes to the margin parameters. In addition, it is possible to add rotation and reflect parameters as documented in the standard https://github.com/raspberrypi/linux/blob/rpi-6.1.y/Documentation/fb/modedb.rst[Linux framebuffer documentation]. By default the `margin_*` options are set from the `overscan` entries in config.txt, if present. The firmware can be prevented from making any KMS specific changes to the command line by adding `disable_fw_kms_setup=1` to `config.txt`

An example entry may be as follows:
In addition, it is possible to add rotation and reflect parameters as documented in the standard https://github.com/raspberrypi/linux/blob/rpi-6.1.y/Documentation/fb/modedb.rst[Linux framebuffer documentation]. An example entry may be as follows:

[source]
----
video=HDMI-A-1:1920x1080M@60,margin_left=0,margin_right=0,margin_top=0,margin_bottom=0,rotate=90,reflect_x`
video=HDMI-A-1:1920x1080M@60,rotate=90,reflect_x`
----

NOTE: It is not possible to specify the rotation and reflection parameters without also explictly specifying the resolution.

Possible options for the display type, the first part of the `video=` entry, are as follows:

[cols="^,<"]
Expand Down Expand Up @@ -73,3 +75,5 @@ NOTE: On Raspberry Pi 4 this controller is disabled by default, and is only conn
* dwc_otg.speed: sets the speed of the USB controller built into the processor on Raspberry Pi computers. `dwc_otg.speed=1` will set it to full speed (USB 1.0), which is slower than high speed (USB 2.0). This option should not be set except during troubleshooting of problems with USB devices.
* smsc95xx.turbo_mode: enables/disables the wired networking driver turbo mode. `smsc95xx.turbo_mode=N` turns turbo mode off.
* usbhid.mousepoll: specifies the mouse polling interval. If you have problems with a slow or erratic wireless mouse, setting this to 0 might help: `usbhid.mousepoll=0`.
* drm.edid_firmware=HDMI-A-1:edid/your_edid.bin: Override your monitor's built-in EDID with the contents of `/usr/lib/firmware/edid/your_edid.bin`

0 comments on commit 60877a6

Please sign in to comment.