NAP Blog
Launch app in kiosk mode on Raspberry Pi 4

Introduction

This document explains how to launch a NAP application on a Raspberry PI 4B in kiosk mode, without a desktop manager, outputting to a single (X) window using Raspbian Bullseye Lite. The command line is hidden and replaced with a splash image. This guide serves as an example and can be applied to pretty much any type of (graphical) application. Feel free to adjust it where appropiate.

Make Image

Download and write the Bullseye Lite image to SD card or use the Raspberry Pi Imager to create the image for you.

Insert card in Raspberry Pi and boot.

Install Packages

Use the following command to install the required packages:

sudo apt-get install --no-install-recommends \
xserver-xorg-video-all xserver-xorg-input-all \
xserver-xorg-core xinit x11-xserver-utils \
unclutter \
mesa-vulkan-drivers \
plymouth plymouth-themes pix-plym-splash

This installs the X Window system display server. The server will be started by the xinit program when you log in. Other required packages include the mesa vulkan driver to render graphics using NAP and Plymouth to display the splash screen during boot.

Boot

Configuration

Open boot/config.txt for writing:

sudo nano boot/config.txt

Add the following lines:

Disable Overscan

disable_overscan=1

Reduce Boot Time

Disable the rainbow image, bluetooth overlay and set boot delay time to 0 seconds.

disable_splash=1
dtoverlay=disable-bt
boot_delay=0

Clock speeds

Boost the default CPU & GPU clock speed (if required). I found these settings work well with a passively cooled Raspberry Pi 4 using heat-sinks. Use & tweak at your own risk!

over_voltage=6
arm_freq=1900
v3d_freq=750
isp_freq=750

Command Line

Open boot/cmdline.txt for writing:

sudo nano boot/cmdline.txt

Add the follwing arguments to the existing arguments:

video=HDMI-A-1:400x1280M@60,rotate=270 splash quiet plymouth.ignore-serial-consoles vt.global_cursor_default=0

This tells the commandline to:

  • Output kernel messages to the specified HDMI output at the given resolution and screen orientation
  • Use a splash screen via the Plymouth module
  • Set the default kernel log level to KERN_WARNING, which suppresses all but very serious log messages during boot.
  • Hide the blinking terminal cursor.

Make sure to adjust the HDMI settings based on your display requirements.

Services

Disable the bluetooth service by executing the following command:

sudo systemctl disable hciuart.service

Splash Screen

Set Theme

Enter the following command to change the default theme:

sudo plymouth-set-default-theme pix

Surpress Console Messages

Hides the display of terminal console messages on top of the splash screen. Open the pix.script file for writing:

sudo nano /usr/share/plymouth/themes/pix/pix.script

And disable the SetUpdateStatusFunction callback at the end of the file:

#Plymouth.SetUpdateStatusFunction(message_callback);

Replace Splash Image

Replace the splash.png image in /usr/share/plymouth/themes/pix, example:

cd /usr/share/plymouth/themes/pix
sudo curl -O https://myplashimg.png
sudo mv myplashimg.png splash.png

Auto Login

Open the tty1 autologin.conf script for for writing:

sudo nano /etc/systemd/system/getty@tty1.service.d/autologin.conf

Replace the line after ExecStart=- with:

-/sbin/agetty --skip-login --noclear --noissue --login-options "-f johndoe" %I $TERM

This ensures johndoe is logged in automatically after system boot. Change johndoe to your username.

To surpress all login messages, create a .hushlogin file:

touch ~/.hushlogin

Application

Install

Browse to the directory where you want to install the application, for example:

cd /usr/local/bin

Download and extract the application:

sudo curl -O https://myapp.tar.bz2
sudo tar -xvf myapp.tar.bz2

Do whatever is required to setup your application.

Launch

Create a .xinitrc file in your home directory. This file is executed by xinit on startup and allows you to run graphical programs that depend on X and set environment variables on X server startup. Create .xinitrc if it doesn't exist yet:

touch ~/.xinitrc

Open .xinitrc for writing:

nano ~/.xinitrc

Add the following content (example):

#!/bin/sh
# Display Rotate
DISPLAY=:0 xrandr --output HDMI-1 --rotate right
xset -dpms
xset s off
xset s noblank
unclutter &
/usr/local/bin/myapp/app

This script tells X Window System server which HDMI output to use and the orientation of the display. The various xset commands disable the blank screen, which occurs after 10/15 minutes if no user input is proved. xset -dpms disables display power management signaling, xset s off disables screen saver blanking, xset s noblank tells the X server to not blank the video device. We then instruct the script to run the app in myapp.

Waveshare 7.9" HDMI LCD

These are the settings associated with the Waveshare 7.9" LCD display. Consult the documentation of your display to acquire the right settings, if required.

HDMI Settings

Add the following lines to /boot/config.txt

hdmi_group:0=2
hdmi_mode:0=87
hdmi_timings=400 0 100 10 140 1280 10 20 20 2 0 0 0 60 0 43000000 3

Rotate Touch

Copy 40-libinput.conf to /etc/X11/xorg.conf.d/:

sudo cp /usr/share/X11/xorg.conf.d/40-libinput.conf /etc/X11/xorg.conf.d/

Open the file for writing:

sudo nano /etc/X11/xorg.conf.d/40-libinput.conf

Rotate the touch interface by 180 degrees by changing the CalibrationMatrix option to:

Option "CalibrationMatrix" "-1 0 1 0 -1 1 0 0 1"

All rotation Matrices:

  • 090 degrees: Option "CalibrationMatrix" "0 1 0 -1 0 1 0 0 1"
  • 180 degrees: Option "CalibrationMatrix" "-1 0 1 0 -1 1 0 0 1"
  • 270 degrees: Option "CalibrationMatrix" "0 -1 1 1 0 0 0 0 1"

NAP Framework is open source software. Suggestions and contributions are welcome.

Coen Klösters | Technical Director | NAP & NAP Labs