Search by Tags

Splash Screen on TorizonCore

Applicable for

Article updated at 17 Mar 2020
Subscribe for this article updates


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.


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 script which does most of the work. It requires three parameters:

# [splash] [ostree ref] [new ostree branch]


  • 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 fast-banana.png \
       e0d44cf2f894bf834f7d799abeccd4ad1e5226cd1caff2324179950ca3676990 \

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 "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