Configure a Raspberry Pi as a kiosk display

Our step-by-step guide to configure a Raspberry Pi as a kiosk display that runs automatically on boot.

Configure a Raspberry Pi as a kiosk display

The TL;DR (Too Long; Didn't Read)

Learn how we at reelyActive configure a Raspberry Pi as a kiosk display.

The Raspberry Pi can act as a digital display driver thanks to its HDMI port.

What will this accomplish?
The Pi will automatically display a specific web page in full screen mode on any HDMI-connected screen via the Chromium browser.
Why use a Pi?
A Pi is a cost-effective and easily sourceable device for driving kiosk displays.
Does this apply only to the Pi?
The process should apply equally well to other Debian Linux-based platforms.

Prerequisites

A Raspberry Pi (or equivalent) with Raspberry Pi OS Lite installed.

Installing X11 and Chromium   Step 1 of 2

Install the X Window System (X11), the Chromium browser and kiosk-mode dependencies.

Do I need to SSH into the Pi?
Yes. If you forgot how, recall Step 4 from the Pi Prep tutorial.
Why X11?
Raspberry Pi OS Lite is headless, it does not include a display system by default, so the the X Window System must be installed manually.
X11 and Chromium for Pi kiosk display

Prerequisites

Both the Pi and the computer used for its configuration must be on the same network, with which they can access the Internet.

Boot the Pi and connect via SSH Part 1

With the prepared micro SD card inserted into the Pi, complete the following:

  1. Apply power to the Raspberry Pi
  2. Open a terminal on the computer and SSH into the Pi with the command ssh pi@xxx.xxx.xxx.xxx replacing the x values with the Pi's IP address
  3. When prompted enter the password (berryinsecure is the default)

If you're still using the default password, this is as good a time as any to change it. Simply run sudo raspi-config

Install the X Window System (X11) Part 2

From the same terminal connected to the Pi via SSH:

  1. Install xserver-xorg with the command sudo apt-get install --no-install-recommends xserver-xorg
  2. Install xinit with the command sudo apt-get install --no-install-recommends xinit
  3. Install x11-xserver-utils with the command sudo apt-get install --no-install-recommends x11-xserver-utils

Install Chromium and kiosk dependencies Part 3

From the same terminal connected to the Pi via SSH:

  1. Install chromium-browser with the command sudo apt-get install chromium-browser
  2. Install the kiosk dependencies with the command sudo apt-get install matchbox-window-manager xautomation unclutter
  3. Optionally, install colour emojis 🤓 with the command sudo apt-get install fonts-noto-color-emoji

Configure boot and display options   Step 2 of 2

Auto-login on boot and start kiosk mode from a script.

Why auto-login?
The pi user will launch X and Chromium, and therefore must be logged in.
Why call a script from .bashrc?
It is difficult to get Chromium to run (as the pi user) from the rc.local file.
Pi autologin and kiosk script

From the same terminal connected to the Pi via SSH:

Create the kiosk startup script Part 1

Create a new file called kiosk in the pi user's home folder with the command nano ~/kiosk and paste in the following template, updating the URL on the last line as required (unless you like this tutorial so much that you plan to display it on a big screen!): 

#!/bin/sh
xset -dpms     # disable DPMS (Energy Star) features.
xset s off     # disable screen saver
xset s noblank # don't blank the video device
matchbox-window-manager -use_titlebar no &
unclutter &    # hide X mouse cursor unless mouse activated
chromium-browser --display=:0 --kiosk --incognito --window-position=0,0 https://reelyactive.github.io/diy/pi-kiosk/

Make the kiosk script file executable with the command chmod 755 ~/kiosk

Add the kiosk script to .bashrc Part 2

Initiation of the X Windows System and the kiosk script will be added to the pi user's .bashrc file which runs each time the Pi boots.

Edit the ~/.bashrc file with the command nano ~/.bashrc to include the following as the last line: 

xinit /home/pi/kiosk -- vt$(fgconsole)

Configure boot and display with the raspi-config tool Part 3

From the command prompt on the Pi , enter the command sudo raspi-config which will open a text-based menu. Update the configuration as per the following table where the settings are indicated in [ ].

# Option Action(s)
2 Display Options D2 Underscan
  • Enable compensation? [No]
1 System Options S5 Boot / Auto Login
  • [B2 Console Autologin]

Upon completing the above, select <Finish> and select <Yes> when prompted to reboot. If a display is connected via HDMI, following the boot sequence, the Chromium browser should open in kiosk mode and display the specified webpage.

Configure custom settings (OPTIONAL) Part 4

Depending on your display and Pi configuration, it may be necessary to configure additional settings to achieve the desired functionality. Many of these settings can be found in The config.txt file, which is well documented—and the place to look first!

An increasing number of web pages & applications (like this one!) support light/dark themes. To prioritise dark themes, add the --enable-features=WebUIDarkMode and --force-dark-mode flags to the chromium-browser startup script command, like this: 

chromium-browser --display=:0 --kiosk --incognito --window-position=0,0 --enable-features=WebUIDarkMode --force-dark-mode https://reelyactive.github.io/diy/pi-kiosk/

This should update the prefers-color-theme media feature which triggers compatible web pages & applications (ex: Bootstrap 5.3 and our own web-style-guide) to automatically render the desired theme.

Edit the display_rotate_hdmi property and disable the DRM VC4 V3D driver for portrait displays: 

# /boot/config.txt

# 0 = 0°, 1 = 90°, 2 = 180°, 3 = 270°
display_hdmi_rotate=1

# Comment out DRM VC4 V3D driver for portrait mode
#dtoverlay=vc4-kms-v3d
#max_framebuffers=2

Thanks to Mike for validating this configuration on a Pi 3B!

Again, check The config.txt file first! And if you complete a non-obvious kiosk configuration that you think would benefit the community, contact us and we'll be happy to document it here.

For additional settings, see also:

Display Pareto Anywhere Apps (OPTIONAL) Part 5

If Pareto Anywhere is running on the Pi, any of the Pareto Anywhere Apps can be displayed in kiosk mode, such as the following, simply by updating the URL in the kiosk file (see Part 1):

Contributor
reelyActive half-barnowl

Tutorial prepared with ♥ by jeffyactive.

You can reelyActive's open source efforts directly by contributing code & docs, collectively by sharing across your network, and commercially through our packages.

Where to next?

Continue exploring our open architecture and all its applications.