Chapter 1: Introduction

This article demonstrates how to customize the images and logos displayed during the boot process: The U-Boot splash image, the Linux kernel logo, the Yocto PSplash image, the Linux Pre-login message and the Wayland wallpaper. This is typically used by customers to display their own company or product logo.

1.1. Software Requirements

First, setup your host environment and get the source code of the Yocto release you want to use: Go to variwiki.com, click on the SOM you are using and on “Developers Guide” under the Yocto version you want to use, and then click on “Build Yocto from source code”, and follow the instructions there.

1.2. BSP Custom Image and Logo Sections

The following chapters are independent from each other, and you can follow them in any order you like:

Chapter 2: U-Boot Splash Screen

This chapter explains how to change the U-Boot splash screen image.

2.1. Important Information

  • U-Boot of the following SOMs has support to display a splash screen before the Linux kernel starts booting the system for:
  • The default U-Boot Splash Screen logo from Variscite:
U-Boot Splash Screen logo from Variscite

Click on the photo to see the size

2.2. How to Change the U-Boot Splash Screen

  1. Create your wanted image in an 8-bit BMP (bitmap image file) format.

E.g. To convert an image from PNG format (e.g., splash.png) to the desired 8-bit BMP format:

$ convert splash.png -depth 8 -compress none BMP3:splash.bmp

  1. Now choose one of the following options:

2.1 Directly overwrite the default image in the relevant Variscite meta layer:

Replace the splash.bmp image file in the BSP U-Boot Splash Screen folder:

YOCTO_FOLDER/sources/META-VARISCITE/recipes-bsp/u-boot/u-boot-splash/

Where META-VARISCITE is one of the following, depending on the SOM and Yocto version:

            • meta-variscite-bsp-imx
            • meta-variscite-fslc
            • meta-variscite-imx

2.2 Alternatively, you can add your splash.bmp image to your own meta layer (if you have one):

Add the following folder to your layer and copy your splash.bmp to it:

 YOCTO_FOLDER/sources/YOUR_META_LAYER/recipes-bsp/u-boot/u-boot-splash/

Now, create the following file:

 YOCTO_FOLDER/sources/YOUR_META_LAYER/recipes-bsp/u-boot/u-boot-splash.bbappend

And write the following line* in it:

 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"

  1. Continue to follow the instructions on the relevant “Build Yocto from source code” page on variwiki.com to build a new image and write it to an SD card.
  1. Boot the system and you should see the new U-Boot Splash Screen image on the display.


Chapter 3: Linux Kernel Logo

This chapter explains how to change the default Linux kernel logo.

3.1. Important Information

  • The default logo size is 80×80, and the splash logo supports only 224 colors.
    • If a higher number of colors is used in the source image, then the ppmquant tool will reduce it to 224 colors.
  • The number of displayed logos is equal to the number of cores, e.g.:
    1 core → 1 logo; 2 cores → 2 logos; 4 cores → 4 logos, etc.
    • To fill the display with a single logo, the logo must be in the same resolution as the display.
  • The logos are aligned to the upper left corner of the screen.
  • The default Linux kernel logo from Variscite:

Linux kernel logo from Variscite

3.2. How to Change the Linux Kernel Logo

  1. Create your wanted image in a PNG format, e.g., logo.png.
  2. Convert the logo.png file to a 224 colors PPM format.

  2.1 Install the required package to convert the logo:

$ sudo apt install netpbm

  2.2 Then, convert the logo file using the pngtopnm tool:

$ pngtopnm logo.png | ppmquant 224 | pnmnoraw > logo_linux_clut224.ppm

NOTE: This guide shows how to overwrite the default Linux logo – so the converted PPM file should be called logo_linux_clut224.ppm.
If you want to learn how to add another kernel configuration for your logo, instead, see this patch from Variscite as a reference.

  1. Copy the logo_linux_clut224.ppm file to the following folder:

 YOCTO_FOLDER/sources/META-VARISCITE/recipes-kernel/linux/files/

Where META-VARISCITE is one of the following, depending on the SOM and Yocto version:

        • meta-variscite-bsp-ti
        • meta-variscite-bsp-imx
        • meta-variscite-fslc
        • meta-variscite-imx
  1. Now, create the following file:

 YOCTO_FOLDER/sources/META-VARISCITE/recipes-kernel/linux/linux-variscite_%.bbappend

And write the following* in it:

FILESEXTRAPATHS:prepend = "${THISDIR}/${PN}:" 

SRC_URI:append = " file://logo_linux_clut224.ppm" 


# uncomment the following lines for NXP builds 

#TARGET_DEFCONFIG="${B}/.config" 


# uncomment the following lines for TI builds 

#TARGET_DEFCONFIG="${S}/arch/arm64/configs/am62x_var_defconfig" 


do_configure:prepend() { 

    # Add the kernel_defconf_variable function 

    kernel_defconf_variable() { 

       CONF_SED_SCRIPT="$CONF_SED_SCRIPT /CONFIG_$1[ =]/d;" 

       if test "$2" = "n" 

       then 

           echo "# CONFIG_$1 is not set" >>  ${TARGET_DEFCONFIG} 

       else 

           echo "CONFIG_$1=$2" >>  ${TARGET_DEFCONFIG} 

       fi 

    } 

    # logo support, if you supply logo_linux_clut224.ppm in SRC_URI, 

    # then it's going to be used 

    if [ -e ${WORKDIR}/logo_linux_clut224.ppm ]; then 

        install -m 0644 ${WORKDIR}/logo_linux_clut224.ppm ${S}/drivers/video/logo/logo_linux_clut224.ppm 

        # Call kernel_defconf_variable for each config variable kernel_defconf_variable LOGO y 

        kernel_defconf_variable LOGO_LINUX_CLUT224 y 

        kernel_defconf_variable LOGO_VARISCITE_CLUT224 n 

     fi 

}

Just remember to uncomment the right option for TARGET_DEFCONFIG variable depending on NXP or TI BSP in use. 

5. Continue to follow the instructions on the relevant “Build Yocto from source code” page on variwiki.com to build a new image and write it to an SD card.

6. Boot the system and you should see the new Linux kernel logo on the display.

* See also the Yocto Linux Kernel Logo page on variwiki.com.


Chapter 4: Yocto PSplash

This chapter explains how to change the Yocto PSplash image.

4.1. Important Information

  • Linux release 5.4.70 and earlier releases require the psplash image as a header file, while the newer Linux release versions include the script to convert the PNG file to a header file. For example, see the difference between Zeus 5.4.70 (psplash-poky-img.h) and Dunfell 5.4.85 (psplash-poky-img.png).
    All releases newer than 5.4.70 use only the PNG format.
  • The default Yocto PSplash logo from Variscite:

 

Yocto PSplash logo from Variscite


4.2. How to Change the PSplash Image on New Yocto Releases (PNG file)

  1. Create your wanted image in a PNG format, and name it psplash-poky.png.

  1.1 Now choose one of the following options:

1.1.1 Directly overwrite the default image in the relevant Variscite meta layer:

Replace the psplash-poky.png image file in the following folder:

 YOCTO_FOLDER/sources/META-VARISCITE/recipes-core/psplash/files/

Where META-VARISCITE is one of the following, depending on the SOM and Yocto version:

            • meta-variscite-sdk-ti
            • meta-variscite-sdk-imx
            • meta-variscite-fslc
            • meta-variscite-imx

1.1.2 Alternatively, you can add your psplash-poky.png image to your own meta layer (if you have one):

Add the following folder to your layer and copy your psplash-poky.png to it:

 YOCTO_FOLDER/sources/YOUR_META_LAYER/recipes-core/psplash/files/

Now, create the following file:

 YOCTO_FOLDER/sources/YOUR_META_LAYER/recipes-core/psplash/psplash_git.bbappend

And write the following line* in it:

 FILESEXTRAPATHS:prepend := "${THISDIR}/files:"

4.3. How to Change the PSplash Image on Old Yocto Releases (header file)

  1. Create your wanted image in a PNG format, and name it psplash-poky-img.png.

  1.1 Install the required package to convert the PNG image file:

$ sudo apt install libgdk-pixbuf2.0-dev

1.2 Use the following script to convert the psplash-poky-img.png image file to a psplash compatible header file:

Run it like this:
$ ./make-image-header.sh psplash-poky-img.png POKY

1.3 Now choose one of the following options:

1.3.1 Directly overwrite the default image in the relevant Variscite meta layer:

Replace the psplash-poky-img.h image file in the following folder:

 YOCTO_FOLDER/sources/META-VARISCITE/recipes-core/psplash/files/

Where META-VARISCITE is one of the following, depending on the SOM and Yocto version:

            • meta-variscite-fslc
            • meta-variscite-imx

1.3.2 Alternatively, you can add your psplash-poky-img.h image to your own meta layer (if you have one):

Add the following folder to your layer and copy your psplash-poky-img.h to it:

 YOCTO_FOLDER/sources/YOUR_META_LAYER/recipes-core/psplash/files/

Now, create the following file:

 YOCTO_FOLDER/sources/YOUR_META_LAYER/recipes-core/psplash/psplash_git.bbappend

And write the following line* in it:

 FILESEXTRAPATHS:prepend := "${THISDIR}/files:"

4.4. Build the Image and Boot the System

  1. Continue to follow the instructions on the relevant “Build Yocto from source code” page on variwiki.com to build a new image and write it to an SD card.
  2. Boot the system and you should see the new PSplash image on the display.


Chapter 5: Linux Pre-login Message

This chapter explains how to change the Linux Pre-login message.

5.1. Important Information

  • The pre-login message is taken from the following files in the target filesystem:
    • /etc/issue – This file contains the text to be printed before the login prompt.
    • /etc/issue.net – This file contains the text to be printed before the login prompt of a telnet session.

For more information, run the following on your host machine:

$ man 5 issue

    • The “\” character needs to be escaped with another “\”, so “\\” is printed as “\” in the pre-login message.
    • The default Variscite Pre-login Message:
__      __        _          _ _
\ \    / /       (_)        (_) |
 \ \  / /_ _ _ __ _ ___  ___ _| |_ ___
  \ \/ / _` | '__| / __|/ __| | __/ _ \
   \  / (_| | |  | \__ \ (__| | ||  __/
    \/ \__,_|_|  |_|___/\___|_|\__\___|
          2022 Variscite, Ltd.

The content of the default Variscite issue file, with the escaped “\” characters:

__      __        _          _ _
\\ \\    / /       (_)        (_) |
 \\ \\  / /_ _ _ __ _ ___  ___ _| |_ ___
  \\ \\/ / _` | '__| / __|/ __| | __/ _ \\
   \\  / (_| | |  | \\__ \\ (__| | ||  __/
    \\/ \\__,_|_|  |_|___/\\___|_|\\__\\___|
          2022 Variscite, Ltd.


5.2. Change the Pre-login Message

  1. Create your wanted pre-login message/s in a text format, and name them issue and/or issue.net.
  2. Choose one of the following options:

2.1 Directly overwrite the default pre-login message file/s in the relevant Variscite meta layer:
Replace the issue and/or issue.net files in the following folder:

 YOCTO_FOLDER/sources/META-VARISCITE/recipes-core/base-files/base-files/

Where META-VARISCITE is one of the following, depending on the SOM and Yocto version:

          • meta-variscite-sdk-common
          • meta-variscite-sdk-ti
          • meta-variscite-sdk-imx
          • meta-variscite-fslc
          • meta-variscite-imx

2.2 Alternatively, you can add your issue and/or issue.net files to your own meta layer (if you have one):
Add the following folder to your layer and copy your issue and/or issue.net files to it:

 YOCTO_FOLDER/sources/YOUR_META_LAYER/recipes-core/base-files/base-files/
Now, create the following file:

 YOCTO_FOLDER/sources/YOUR_META_LAYER/recipes-core/base-files/ base-files_%.bbappend
And write the following line* in it:

 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"

  1. Continue to follow the instructions on the relevant “Build Yocto from source code” page on variwiki.com to build a new image and write it to an SD card.
  2. Boot the system and you should see the new pre-login message in the terminal.


Chapter 6: Wayland/Weston Background

This chapter explains how to change the Wayland/Weston background color or wallpaper.

6.1. Important Information

  • The Wayland desktop’s default background looks like this:

Wayland/Weston Background of Variscite

 

6.2. Change the Weston Background Color and/or Add a Background Image

  1. The relevant default Weston configuration file is located at:
YOCTO_FOLDER/sources/META-VARISCITE/recipes-graphics/wayland/weston-init/IMX_FOLDER/weston.in

Where META-VARISCITE is one of the following, depending on the SOM and Yocto version:

            • meta-variscite-sdk-ti
            • meta-variscite-sdk-imx
            • meta-variscite-fslc
            • meta-variscite-imx

and IMX_FOLDER is one of the following, depending on the Yocto version:

            • imx-nxp-bsp
            • imx
  • To change the background color, use the background-color property under the [shell] section in ini.

The background-color property takes an unsigned integer value which consists of 4 hexadecimal digit pairs, for Alpha, Red, Green and Blue channels (0xAARRGGBB).

Note: The alpha channel is a color component that represents the degree of transparency (or opacity) of a color (i.e., the red, green and blue channels).

For example:

background-color value Color
0xff000000 Solid black
0xffff0000 Solid red
0xff00ff00 Solid green
0xff0000ff Solid blue
0x7fxxxxxx ~50% translucent color (the color itself is determined by the x values)
0x7fff0000 ~50% translucent red
0xccxxxxxx 20% translucent color (the color itself is determined by the x values)
0x33xxxxxx 80% translucent color (the color itself is determined by the x values)
0x00xxxxxx 100% translucent – no color at all

 

  • To add a background image, use the background-image and background-type properties under the [shell] section in weston.ini.

The background-image property takes a string of a path to an image file.

The background-type property determines how the background image is drawn. It takes one of the following strings:

centered, scale, scale-crop or tile (tile is the default).

centered – shows the image once, centered. If the image is smaller than the output, the rest of the surface will be in background color. If the image size does fit the output, it will be cropped left and right, or top and bottom.
scale – means scaled to fit the output precisely, not preserving aspect ratio.
scale-crop – preserves aspect ratio, scales the background image just big enough to cover the output, and centers it. The image ends up cropped from left and right, or top and bottom, if the aspect ratio does not match the output.
Tile – repeats the background image to fill the output.

  1. Choose one of the following options:

2.1 Directly edit the weston.ini file mentioned above, in the relevant Variscite meta layer.

For example, to use a background image file called /etc/xdg/weston/wallpaper.png, centered, over a solid blue background color, add the following lines under the [shell] section in weston.ini:

background-color=0xff0000ff
background-image=/etc/xdg/weston/wallpaper.png
background-type=centered

If you chose to add a background image (e.g. /etc/xdg/weston/wallpaper.png), you also need to add it to the build:

Create your wallpaper.png image file and copy it to:

   YOCTO_FOLDER/sources/META-VARISCITE/recipes-graphics/wayland/weston-init/

Now, edit the following file:

   YOCTO_FOLDER/sources/META-VARISCITE/recipes-graphics/wayland/weston-init.bbappend with the following changes:

      • Add SRC_URI:append= ” file://wallpaper.png” to the file*, outside of any functions. This will fetch the image and make it available to install in the next step.
      • Append the following line to the do_install:append() function* to install it to the file system:

install -D -p -m0644 ${WORKDIR}/wallpaper.png ${D}${sysconfdir}/xdg/weston/

2.2 Alternatively, you can add a weston.ini file to your own meta layer (if you have one):

Add the following folder to your layer and copy the above mentioned weston.ini file to it:

 YOCTO_FOLDER/sources/YOUR_META_LAYER/recipes-graphics/wayland/weston-init/IMX_FOLDER/

Edit the new weston.ini file in your layer for your liking (see example in the previous section).

Now, create the following file:

   YOCTO_FOLDER/sources/YOUR_META_LAYER/recipes-graphics/wayland/weston-init.bbappend

And write the following line* in it:

   FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"

If you chose to add a background image (e.g. /etc/xdg/weston/wallpaper.png), you also need to add it to the build:

Create your wallpaper.png image file and copy it to:

   YOCTO_FOLDER/sources/YOUR_META_LAYER/recipes-graphics/wayland/weston-init/

Now, edit the following file:

   YOCTO_FOLDER/sources/YOUR_META_LAYER/recipes-graphics/wayland/weston-init.bbappend

and append the following* to it:

   SRC_URI:append= " file://wallpaper.png"
   do_install:append() {
      install -D -p -m0644 ${WORKDIR}/wallpaper.png ${D}${sysconfdir}/xdg/weston/
   }
  1. Continue to follow the instructions on the relevant “Build Yocto from source code” page on variwiki.com to build a new image and write it to an SD card.
  2. Boot the system and you should see the new Wayland background.

 

* Note that the prepend/append Yocto syntax was changed starting from Yocto Hardknott. If you are using a Yocto version older than Hardknott, replace “:append” and “:prepend” with “_append” and “_prepend”, respectively.