From 183de3de6834383fd5c9e5aea395c3d618670118 Mon Sep 17 00:00:00 2001 From: Jeunese Date: Mon, 13 Oct 2025 13:43:02 +0100 Subject: [PATCH] Splash screen documentation Co-authored-by: Andrew Scheller Co-authored-by: Kat Shann --- .../computers/configuration/screensaver.adoc | 141 +++++++++++++++--- 1 file changed, 118 insertions(+), 23 deletions(-) diff --git a/documentation/asciidoc/computers/configuration/screensaver.adoc b/documentation/asciidoc/computers/configuration/screensaver.adoc index 66523154c..94dd1c19e 100644 --- a/documentation/asciidoc/computers/configuration/screensaver.adoc +++ b/documentation/asciidoc/computers/configuration/screensaver.adoc @@ -1,61 +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 Control Centre. +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*). + +If you aren't running the desktop environment, you can manage screen blanking from the terminal interface on your Raspberry Pi. For instructions, see <>. ==== Control Centre -Click the Raspberry Pi button in the menu bar. Navigate to *Preferences* > *Control Centre*. +The *Control Centre* application allows you to turn screen blanking on or off without editing configuration files manually. + +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] NOTE: In previous versions of Raspberry Pi OS, the Control Centre application was called Raspberry Pi Configuration. -image::images/pi-configuration.png[opening the Control Centre menu from the desktop] +==== CLI -Select the *Display* tab. Toggle the *Screen Blanking* radio button into the on position. Press *OK* to confirm your selection. +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. -image::images/blanking.png[toggle Screen Blanking on in the Control Centre menu] +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. -==== CLI +[[console]] +=== Console + +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. -You can enable and disable screen blanking with the `raspi-config` CLI tool. Run the following command to open the tool: +==== Set console mode screen blanking + +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 raspi-config +$ cat /sys/module/kernel/parameters/consoleblank ---- -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. +== Custom fullscreen splash image -=== Console +You can configure your Raspberry Pi to display a fullscreen splash image during boot instead of the standard console log messages. -The `dpms_timeout` screen blanking 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. +[[file-reqs]] +=== File requirements -==== Set console mode screen blanking +The splash screen image must meet the following criteria: -To change the console mode screen blanking configuration, open `/boot/firmware/cmdline.txt` in a text editor as an administrator: +* *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 nano /boot/firmware/cmdline.txt +$ 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 ---- -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. +=== Set up a fullscreen splash image + +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. -Changes to `cmdline.txt` only take effect after a reboot. Use the following command to reboot your Raspberry Pi: +[[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] +---- +$ 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 ---- -==== View current screen blanking setting - -You can display the current console blank time in seconds with the following command: - -[source,console] +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]] +==== 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] ---- -$ cat /sys/module/kernel/parameters/consoleblank +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. +