Making psplash work on your PiTFT display in a Raspberry Pi Yocto project

psplash is a simple splash screen that shows a static image with an animated progress bar. It is the default splash screen shown by any Poky based project, unless overridden. This post assumes you know how to override a recipe with a .bbappend file, add files to a recipe, and patch the recipe source.

The directory structure for psplash in my own layer.


I wanted to have my PiTFT 2.8 show the splash screen instead of the display plugged into the HDMI port of my Raspberry Pi 3. The HDMI display is identified in /dev/ as fb0, and the PiTFT screen is identified as fb1.

The PiTFT 2.8 has a resolution of 320 x 240 pixels, so I created two images to show on the screen to test the splash screen:

The 320 x 240 splash screen.
The very exciting progress bar splash screen which has a single pixel of white border around it.


The splash screen will not show up on /dev/fb1 (PiTFT 2.8) without some modifications to psplash and init scripts:

  1. The psplash executable needs an argument to direct output to /dev/fb1
  2. The /dev/fb1 device is not ready until udev has ran, this will cause psplash to fail if executed before the device is ready
  3. The image files need to be overwritten by your layers recipe, to show your customized graphics
  4. The source code of psplash needs patching for configuration, to accommodate to your graphics

To remedy the previous points, the following actions were taken:

Direct psplash output to /dev/fb1

To direct the output to /dev/fb1, the file psplash-init was copied to my own layer under the equivalent path for psplash. The file was then added to the SRC_URI variable in the .bbappend file. I found the file from poky-sumo/meta/recipes-core/psplash/files. Two things had to be changed:

# change this:
if [ ! -e /dev/fb0 ]; then
    echo "Framebuffer /dev/fb0 not detected"
    echo "Boot splashscreen disabled"
    exit 0;
# to this:
if [ ! -e /dev/fb1 ]; then
    echo "Framebuffer /dev/fb1 not detected"
    echo "Boot splashscreen disabled"
    exit 0;

# and this:
/usr/bin/psplash --angle $rotation &
# to this:
/usr/bin/psplash --angle $rotation --fbdev 1 &

Run psplash-init after udev

psplash-init script is installed into the init.d directories. Specify the following variable to control the runlevels and behavior of the script:

INITSCRIPT_PARAMS = "start 5 S . stop 20 0 1 6 ."

This will run the psplash-init only after the /dev/fb1 is available (after udev). Adjust the runlevel values as necessary for your system. Refer to update-rc.d.bbclass chapter in Yocto documentation.

Replace the images

Replacing the images is as simple as adding the new images to the files directory of the psplash directory of your layer.

Configuring psplash is as easy as loading the recipe up in the Yocto devtool and making the configuration changes to the source header files. The variables are well named and behave as expected:

-#define POKY_IMG_WIDTH (427)
-#define POKY_IMG_HEIGHT (214)
+#define POKY_IMG_WIDTH (320)
+#define POKY_IMG_HEIGHT (240)

(Optional) Remove text above progress bar

To remove the text bar altogether (and eliminating the black background box behind it, undefine the following environment variable. Setting the variable to empty string still produces the black background box above the progress bar, because the source code checks for any definition of the variable.

+/* #define PSPLASH_STARTUP_MSG */
Posted in embeddedlinux, raspberrypi, yocto | Comments Off on Making psplash work on your PiTFT display in a Raspberry Pi Yocto project

Update: Handheld console project

Using Yocto I was able to build an image for the Raspberry Pi. I followed the instructions in a blog post on Jumpnow Technologies blog. This got me started on making progress.

The instructions include adding a layer to your Yocto project, found here on GitHub:

Working with this layer gave me insight into the Yocto system and allowed me to gain a deeper understanding of the build process. It was a solid starting block for the project, which now has these steps completed:

Getting started

I built the basic console image as per instructions. It boots into the console and sets up the PiTFT 2.8″ display. The display is available as non-accelerated framebuffer on /dev/fb1, and fb0 remains as the main HDMI display. There is a blog post detailing how to get accelerated content on the PiTFT display here. Graphics acceleration ended up not being a requirement, however.

Add an emulator of your choice

I added snes9x-rpi from meta-game-emulators into the project. I patched the source code with the help of the Yocto devtool to make it compile correctly. The emulator uses the SDL library and runs games smoothly on the Raspberry Pi 3 (I upgraded).

Define video modes

The snes9x-rpi emulator, when ran, complained about “No video mode large enough for 320×240”. I found this strange as my main display on the HDMI connector was 1600×1200 and displayed the console correctly. The PiTFT also has a resolution of 320×240. The solution was to add a .bbappend file for fbset-modes recipe to include the proper video mode definitions. To get the video mode definitions, run fbset -i -fb /dev/fb* where * is the number of the frame buffer you want to query. Append the output into /etc/fb.modes file. The file is left empty on purpose in the original recipe.


# Replace contents of fb.modes with appropriate configuration

# Intentionally overwrites the SRC_URI variable!
SRC_URI = "file://fb.modes"


mode "320x240"
    geometry 320 240 320 240 32
    timings 0 0 0 0 0 0 0
    rgba 8/16,8/8,8/0,8/24

The only purpose of fbset-modes recipe is to include this file. That is why I thought it appropriate to replace the variable contents.

Enabling audio

This was surprisingly easy. Add the following line to your config.txt on the boot partition:


…and add alsa to the DISTRO_FEATURES variable in your local.conf or your image recipe.

Be sure to include alsa-utils package to your image. It contains all the useful tools to control audio on your device.

Running a game

To run a game on the PiTFT display instead of the default HDMI display, define the environment variable SDL_FBDEV:

SDL_FBDEV=/dev/fb1 snes9x-rpi <romname>

Next steps

Now the basics are under control, I can move on to making the system truly mobile. There are some housekeeping related items coming up, such as removing dependencies to the Jumpnow Technologies layer, and defining my own image recipe for the build. I want only the essential packages running in the system. Another goal is to make the root file system read-only. Other goals include:

  • Connect a USB SNES controller to the system
  • Connect a battery management circuit and read battery status of the device
  • Connect a set of tiny speakers to the system for audio
  • Tie it all together with a simple launcher software that starts on boot
  • Customize the boot screens for a professional, polished look
Posted in embeddedlinux, raspberrypi | Comments Off on Update: Handheld console project

A handheld console project for Raspberry Pi

So I had a stray Raspberry Pi Model A hanging around in the cupboard which I stumbled upon just recently. Having dabbled with embedded Linux more and more recently, I figured this would be the perfect opportunity to start developing something interesting for it and put it to good use.

I have always enjoyed gaming a lot, but I never got into portable gaming. Mobile games don’t really cut it, either. It has to be something like a GameBoy, but less bulkier. Like a Nintendo DS, but more versatile. Preferably the whole system would be under my control. And a ton of battery life… Like, a TON. As much as I can comfortably hold in my hands. I hate charging devices.

I read about the topic for a while and came to the conclusion that it is very much possible to emulate older consoles on this hardware, and that software for that purpose has already existed for a long time. There are complete packages for Raspberry Pi that achieve this purpose, namely Retropie. Including this in the distro or adapting parts of it should be no problem. More of this later.

To make it extra retro, it needs a proper display. Something low-powered and already with a fitting resolution, such as 320 x 240. A crisp TFT display was found, called PiTFT. This uses the SPI bus to communicate with the Raspberry Pi. There are solutions to make the display support OpenGL accelerated sources, but that is beyond the scope of this post.

It looks awesome. Perfect for some low-res gameplay.

Other components of the system will feature small speakers, power management and distribution, and custom distribution for the Raspberry Pi. The controls will be modified later from an SNES USB controller. I’ll write a post regarding that later.

Wanting full control of the software, nothing less than a completely custom embedded Linux distribution will suffice. This will be achieved with The Yocto Project. This will enable me to build a system fully configured to my specific needs, and it’s perfect practice for bigger projects in professional environments.

I’ll update the blog with baby steps as I go figure the whole thing out.

Posted in embeddedlinux, raspberrypi | Comments Off on A handheld console project for Raspberry Pi

A Kickoff Post

I suppose I have to start somewhere, might as well do it now.

The site has really been empty for a long while now and I’m looking into changing that soon.

I have a few personal projects in mind and I was thinking I’d post some progress updates here as they go forward.

Might also involve random programming related posts.

Stay tuned!

Posted in misc | Comments Off on A Kickoff Post