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 which allows to add 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.

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. It includes the splash command for splash screen customization.

The following are the basic steps you will need to customize an image using TorizonCore Builder:

Installing TorizonCore Builder

To use TorizonCore Builder, you need to create an alias. Follow the installation instructions on the TorizonCore Builder article. Make sure to:

  • Unpack the TorizonCore image, as explained in the article.
  • Use an empty working directory and navigate to it. This directory is shared (bind-mounted) with the TorizonCore Builder container, and it stores temporary files and the final image.

Applying the Splash Screen Into Your Customized Image

You will also need the file for your "splash screen". I am going to use the fast-banana.png file. Once you have this file in place, you should execute:

$ torizoncore-builder splash --image fast-banana.png
/storage/splash/usr/share/plymouth/themes/spinner/                                                                                                                                                   
 splash screen merged to initramfs

The next step is to create a "branch" in OSTree with your new splash screen. See an example of a new branch called splash-with-logo-v1.

$ torizoncore-builder union --union-branch=splash-with-logo-v1
Commit b98ef2e44692fd8cbf6793df9a194f34ac0ff40a05886d1e21bbc8df61e513eb has been generated for changes and ready to be deployed.

Now you can deploy the customized image directly in the device:

$ torizoncore-builder deploy --remote-host <IP address or hostname.local> --remote-username <torizon username> --remote-password <torizon password> splash-with-logo-v1 --reboot

Or create a new Toradex Easy Installer image with the customized splash screen:

$ torizoncore-builder deploy --output-directory splash-with-logo-v1 splash-with-logo-v1

Deploying With Torizon OTA

Get Started With Torizon OTA

Alternatively or in addition to creating a custom image for Toradex Easy Installer, you can deploy your custom splash screen using the Torizon OTA. Learn how to do it on Signing and Pushing TorizonCore Images to Torizon OTA.

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