Search by Tags

Splash Screen on TorizonCore

 

Article updated at 17 Feb 2021
Compare with Revision


Subscribe for this article updates

Select the version of your OS from the tabs below. If you don't know the version you are using, run the command cat /etc/os-release or cat /etc/issue on the board.



Remember that you can always refer to the Torizon Documentation, there you can find a lot of relevant articles that might help you in the application development.

Torizon 5.0.0

Introduction

TorizonCore uses Plymouth splash screen running in user space. Plymouth is started from an initial minimal root file system (initramfs) very early during boot. Hence customizing the splash screen requires customizing the initramfs. TorizonCore ships with a script that allows adding a custom splash screen logo to the initramfs.

There are different phases of development with different methods for customizing the splash screen:

  • Evaluation and prototyping: you can use the convenient script ostree-customize-playmouth.sh provided in the TorizonCore image.
  • Development and production: you must use the TorizonCore Builder Tool.

This article complies to the Typographic Conventions for Torizon Documentation.

Limitations

The Apalis iMX8 does not have a splash screen, due to limitations on the NXP DRM driver.

Prerequisites

  • The custom splash screen needs to be a png file with a maximum size of your screen's resolution (-32 pixel in height for the waiting animation). Typically a resolution of around 600x400 is used. Currently, the background is always black.
  • A Toradex SoM with Torizon installed.
  • A TorizonCore image downloaded.

Evaluation: Add a Custom Splash Screen Directly from TorizonCore

Since the initramfs is stored in OSTree, customizing the splash screen requires a new OSTree commit. TorizonCore ships with the ostree-customize-plymouth.sh script which does most of the work. It requires three parameters:

# ostree-customize-plymouth.sh [splash] [ostree ref] [new ostree branch]

Being:

  • splash: the path to the png image.
  • ostree ref: the reference to the base tree from OSTree.
  • new ostree branch: the name of a new branch to which you will commit the changes.

Warning: you are advised to always start from a vanilla TorizonCore OSTree reference before running the tool for the second time.

Get the Current OSTree Reference

To get the reference to the base tree (typically the current running tree) you can use ostree admin status to display the current reference:

# ostree admin status
* torizon e0d44cf2f894bf834f7d799abeccd4ad1e5226cd1caff2324179950ca3676990.0
    Version: 4.0.0-devel-20200218+build.118
    origin refspec: e0d44cf2f894bf834f7d799abeccd4ad1e5226cd1caff2324179950ca3676990

The value is displayed as origin refspec.

Create New OSTree Commit

With the png in place and the base reference above a new OSTree commit with the customized initramfs can be created. See an example below that uses an image named fast-banana.png and creates a new branch named apalis-imx6/torizon/torizon-core-docker-customized:

# sudo ostree-customize-plymouth.sh fast-banana.png \
       e0d44cf2f894bf834f7d799abeccd4ad1e5226cd1caff2324179950ca3676990 \
       apalis-imx6/torizon/torizon-core-docker-customized

Deploy New OSTree Commit

This new OSTree commit can be deployed using:

# sudo ostree admin deploy "apalis-imx6/torizon/torizon-core-docker-customized"
# sudo reboot

On reboot, you should be able to see the new splash screen showing up.

Revert to the Vanilla TorizonCore OSTree Reference

The script ostree-customize-plymouth.sh "overwrites" the default splash screen by appending a new splash screen to the initramfs of the currently running root file system. This means that if the tool is used on an already customized root file system, the initramfs will append another splash screen, making the initramfs unnecessary larger.

Given the origin refspec from the previous example, run ostree admin switch [ostree ref] to revert to the vanilla TorizonCore OSTree reference:

# sudo ostree admin switch e0d44cf2f894bf834f7d799abeccd4ad1e5226cd1caff2324179950ca3676990
# sudo reboot

Development and Production: Add a Custom Splash Screen with TorizonCore Builder

The TorizonCore Builder Tool is the recommended method for customizing TorizonCore.

Additional prerequisites

Installing TorizonCore Builder

To install TorizonCore Builder, follow the instructions below, in order.

Create and enter a working directory where your customization will be stored:

$ mkdir ~/tcbworkdir
$ cd ~/tcbworkdir

Use the setup script named tcb-env-setup.sh, available on the Toradex Github, to setup TorizonCore Builder:

$ wget https://raw.githubusercontent.com/toradex/tcb-env-setup/master/tcb-env-setup.sh
$ source tcb-env-setup.sh

Verify that the command torizoncore-builder is available:

$ torizoncore-builder --help

Warning: Make sure to: (1) source the script, (2) every time you open a new terminal, (3) inside the working directory you have previously created. Otherwise, it will not work as intended and, most importantly, the torizoncore-builder alias will not be created properly.

Applying a Splash Screen to a Custom Image

There are two possible approaches to apply the customization and generate a custom Toradex Easy Installer image, described in the next two sections Approach 1 and Approach 2. These approaches in some cases are interchangeable and in some not as described in the next sections.

To learn about TorizonCore Builder workflow and the different approaches to use the tool, with explanatory diagrams, please refer to the TorizonCore Builder - Workflow article.

Attention: Both approaches generate a custom Toradex Easy Installer image as output, so the approaches should be followed separately and not in sequence.

Approach 1: Applying a Splash Screen to a Custom Image: Using the Build Command

TorizonCore Builder build command generates a custom TorizonCore image with the splash screen, ready to be installed with Toradex Easy Installer, named torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM in the example below. This is achieved using a configuration YAML file, tcbuild.yml as default.

This is the recommended approach on production programming and on CI/CD (continuous integration / continuous development) pipelines.

To learn about TorizonCore Builder workflow and the different approaches to use the tool, with explanatory diagrams, please refer to the TorizonCore Builder - Workflow article.

It requires a Toradex Easy Installer image of TorizonCore (preferably without containers), torizon-core-docker-colibri-imx6-Tezi_5.3.0+build.7.tar in this case, as input. The splash screen image is passed as customization: splash-screen.

tcbuild.yaml
# Sample configuration file:
input:
  easy-installer:
    local: images/torizon-core-docker-colibri-imx6-Tezi_5.3.0+build.7.tar
#Sample customization: insert a Splash Screen
customization:
  # >> Splash screen:
  splash-screen: splash.png
output:
  easy-installer:
    local: torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM

The file splash.png should be available before running the build command. A demo image can be downloaded by clicking on the button below:

Example Splash Screen Image

Build The Custom Toradex Easy Installer Image

Build The Custom Image

To generate the TorizonCore image, run the command below, in the same directory where the tcbuild.yaml file is:

$ torizoncore-builder build

...
1091 metadata, 12741 content objects imported; 412.2 MB content written                                                                                                                                   
Pulling done.
Deploying OSTree with checksum 58629613a342197c31c5911d0874aac1b0fcb46b68a63f59760c03bacc4df08a
Deploying done.
Copy files not under OSTree control from original deployment.
Packing rootfs...
Packing rootfs done.

=>> Build command successfully executed!

In case of using a configuration file with a different name than tcbuild.yaml, run the command specifying the configuration file name:

$ torizoncore-builder build -f <configuration_file_name>

Deploy The Custom Toradex Easy Installer Image

To deploy the custom Toradex Easy Installer image to the board, click on the link below and choose between the available options.

Deploy The Custom Toradex Easy Installer Image

Approach 2: Applying a Splash Screen to a Custom Image: Using Standalone Commands

In this second approach, instead of using a configuration YAML file and a one-step command, the generation of the custom TorizonCore with the splash screen is done using standalone commands, each performing one step towards this generation.

This approach is especially useful when making incremental changes, generating multiple images with different splash screens (or other customizations like different device tree overlays). As you will see, applying a splash screen to an image of TorizonCore that has other customizations is just a matter of performing the apply, merge and deploy stages.

To learn about TorizonCore Builder workflow and the different approaches to use the tool, with explanatory diagrams, please refer to the TorizonCore Builder - Workflow article.

To generate a custom Toradex Easy Installer image with the splash screen follow the sequence of steps below.

Unpack an Input Image

You just need to execute this once. Then, you are ready to apply multiple changes to the image. For example, in addition to applying a splash screen, you can also apply an external kernel module, a new device tree, among other possibilities.

If you have not unpacked an image yet, download a base TorizonCore image (preferably without containers) inside the TorizonCore Builder working directory, then run the command below to unpack it. In the example below the torizon-core-docker-colibri-imx6-Tezi_5.3.0+build.7.tar image is used as a reference:

$ torizoncore-builder images unpack torizon-core-docker-colibri-imx6-Tezi_5.3.0+build.7.tar

If you want to change the TorizonCore base image, download the new image and run the images unpack command again, passing the new image as the argument.

For more details about the images unpack command, please check the images unpack command in the commands manual.

Instead of using the images unpack you can use the images download command. This command checks which is the connected Toradex SoM, downloads the compatible latest quarterly release of a TorizonCore image without containers, and unpacks this image.

$ torizoncore-builder images download --remote-host 192.168.1.117 --remote-username torizon --remote-password torizon

Change the arguments --remote-host,--remote-username and --remote-password to your board IP Address, username and password, respectively.

For more details on how the images download command works, please check the images download command in the commands manual.

Apply The Splash Screen

To apply the splash screen file, in this case splash.png, to the custom Toradex Easy Installer image, run the command below:

$ torizoncore-builder splash splash.png

/storage/splash/usr/share/plymouth/themes/spinner/                                                                                                                                                   
 splash screen merged to initramfs

A demo splash.png image can be downloaded by clicking on the button below:

Example Splash Screen Image

For more details about the splash command, please check the spash command in the commands manual.

Merge Changes

Merge the splash screen (as well as other customizations like an external kernel module or a new device tree) into the base Toradex Easy Installer image of TorizonCore - use whatever branch name you want.

As an example, to commit changes into a branch named custom-branch use the command below, accordingly with the TorizonCore Builder version:

$ torizoncore-builder union custom-branch

Applying changes from STORAGE/dt.
Commit 58629613a342197c31c5911d0874aac1b0fcb46b68a63f59760c03bacc4df08a has been generated for changes and is ready to be deployed.
$ torizoncore-builder union --union-branch=custom-branch

Warning: We recommend that you switch to the latest version of TorizonCore Builder to enjoy its simpler and more consistent user interface besides other improvements and bug fixes.

For more details about the union command, please check the union command in the commands manual.

Deploy The Custom Toradex Easy Installer Image

To deploy the custom Toradex Easy Installer image to the board, click on the link below and choose between the available options.

Deploy The Custom Toradex Easy Installer Image

Verifying The New Custom Image On The Device

After rebooting, in your target device's terminal, verify that your new custom image of TorizonCore is active on the device with the command below:

# sudo ostree admin status

Password: 
* torizon 58629613a342197c31c5911d0874aac1b0fcb46b68a63f59760c03bacc4df08a.0
    Version: 5.3.0+build.7-tcbuilder.20211008140217
    origin refspec: tcbuilder:58629613a342197c31c5911d0874aac1b0fcb46b68a63f59760c03bacc4df08a
  torizon 36ad904617b170339b6ded7b9dce87ed8cf0f76473b897fdd832d91e82eb1ddc.0 (rollback)
    Version: 5.3.0+build.7
    origin refspec: tcbuilder:36ad904617b170339b6ded7b9dce87ed8cf0f76473b897fdd832d91e82eb1ddc

Where 58629613a342197c31c5911d0874aac1b0fcb46b68a63f59760c03bacc4df08a is the OSTree commit hash and should be the same as:

  • The one in the output of the union command in the case of the standalone commands
  • The one in the "Deploying OSTree with checksum ..." part of the output of the build command.

Torizon 4.0.0

Introduction

TorizonCore uses Plymouth splash screen running in user space. Plymouth is started from an initial minimal root file system (initramfs) very early during boot. Hence customizing the splash screen requires customizing the initramfs. TorizonCore ships with a script which allows to add a custom splash screen logo to the initramfs.

This article complies to the Typographic Conventions for Torizon Documentation.

Prerequisites

The custom splash screen needs to be a png file with a maximum size of your screens resolution (-32 pixel in height for the waiting animation). Typically a resolution around 600x400 is used. Currently the background is always black.

How to Add a Custom Splash Screen

Since the initramfs is stored in the OSTree of TorizonCore, customizing the splash screen requires a new OSTree commit. TorizonCore ships with the ostree-customize-plymouth.sh script which does most of the work. It requires three parameters:

# ostree-customize-plymouth.sh [splash] [ostree ref] [new ostree branch]

Being:

  • splash: the path to the png image.
  • ostree ref: the reference to the base tree from OSTree.
  • new ostree branch: the name of a new branch to which you will commit the changes.

Warning: you are advised to always start from a vanilla TorizonCore OSTree reference before running the tool for the second time.

Get the Current OSTree Reference

To get the reference to the base tree (typically the current running tree) you can use ostree admin status to display the current reference:

# ostree admin status
* torizon e0d44cf2f894bf834f7d799abeccd4ad1e5226cd1caff2324179950ca3676990.0
    Version: 4.0.0-devel-20200218+build.118
    origin refspec: e0d44cf2f894bf834f7d799abeccd4ad1e5226cd1caff2324179950ca3676990

The value is displayed as origin refspec.

Create New OSTree Commit

With the png in place and the base reference above a new OSTree commit with the customzied initramfs can be created. See an example below that uses an image named fast-banana.png and creates a new branch named apalis-imx6/torizon/torizon-core-docker-customized:

# sudo ostree-customize-plymouth.sh fast-banana.png \
       e0d44cf2f894bf834f7d799abeccd4ad1e5226cd1caff2324179950ca3676990 \
       apalis-imx6/torizon/torizon-core-docker-customized

Deploy New OSTree Commit

This new OSTree commit can be deployed using:

# sudo ostree admin deploy "apalis-imx6/torizon/torizon-core-docker-customized"
# sudo reboot

On reboot you should be able to see the new splash screen showing up.

Revert to the Vanilla TorizonCore OSTree Reference

The script ostree-customize-plymouth.sh "overwrites" the default splash screen by appending a new splash screen to the initramfs of the currently running root file system. This means that if the tool is used on an already customized root file system, the initramfs will append another splash screen, making the initramfs unnecessary larger.

Given the origin refspec from the previous example, run ostree admin switch [ostree ref] to revert to the vanilla TorizonCore OSTree reference:

# sudo ostree admin switch e0d44cf2f894bf834f7d799abeccd4ad1e5226cd1caff2324179950ca3676990
# sudo reboot