Search by Tags

Splash Screen on TorizonCore

 
Applicable for


Article updated at 17 Sep 2020
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.

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 screens resolution (-32 pixel in height for the waiting animation). Typically a resolution 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 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

Development: 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.

In summary, you will need to:

  • Use the splash command to apply the custom splash screen.
  • Optionally, make other changes with commands such as isolate and dt to apply various types of customization.
  • Use the union command to capture all open changes into a OSTree branch.
  • Use the deploy command to deploy to the board or a TorizonCore image to validate your customization.
  • Use the push command to push a custom TorizonCore image to the 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