How to use a Raspberry Pi in kiosk mode

For the initial SD card setup, you will need:

To begin, follow the 'Getting started' documentation to set up your Raspberry Pi. For your operating system, choose Raspberry Pi OS (64-bit).

In this tutorial, we’re going to run the Raspberry Pi without a mouse or keyboard, so during Raspberry Pi Imager’s OS customisation stage, edit the settings as follows:

SSH allows you to wirelessly connect to your Raspberry Pi, eliminating the need for a keyboard or mouse. It’s perfect if your Raspberry Pi is located in a hard-to-reach location, like the back of your television.

$ ssh <username>@pi-kiosk.local
The authenticity of host 'pi-kiosk.local (fd81:b8a1:261d:1:acd4:610c:b069:ac16)' can't be established.
ED25519 key fingerprint is SHA256:s6aWAEe8xrbPmJzhctei7/gEQitO9mj2ilXigelBm04.
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added 'pi-kiosk.local' (ED25519) to the list of known hosts.

<username>@pi-kiosk.local's password:
Linux pi-kiosk 6.1.21-v8+ #1642 SMP PREEMPT Mon Apr  3 17:24:16 BST 2023 aarch64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Tue Oct 24 09:41:00 2023
<username>@pi-kiosk:~ $

$ sudo apt update

$ sudo apt -y full-upgrade

This tutorial requires one additional piece of software, wtype, which simulates keyboard activity. To install it, run the following command:

$ sudo apt -y install wtype

Next, we’ll tell your Raspberry Pi what to present in kiosk mode and how to present it. In this tutorial, we’ll display the Raspberry Pi home page and a page showing the time in London, switching between the two every few seconds.

To achieve this, we will edit .config/labwc/autostart, which is a configuration file used to automatically run programs when the Raspberry Pi OS desktop has loaded.

Edit the .config/labwc/autostart file in nano, a text editor, by running the following command:

$ nano .config/labwc/autostart

Add the following two lines:

chromium https://raspberrypi.com https://time.is/London --kiosk --noerrdialogs --disable-infobars --no-first-run --enable-features=OverlayScrollbar --start-maximized &
~/switchtab.sh

The first line opens the Chromium web browser in kiosk mode, with two tabs open: raspberrypi.com and time.is. The extra options alter kiosk mode in the following ways:

The second line executes a bash script (which we’ll create soon!) that automatically switches between the two tabs every ten seconds.

The ampersand (&) at the end of the first line is very important, as it ensures that both lines in the autostart file are run in parallel. If it were omitted, chromium would run, but the switchtab.sh script wouldn’t. (Technically, if the ampersand were missing, the switchtab.sh script would run after chromium has finished running — but since we’re running Chromium in kiosk mode, there’s no way to quit it!)

Press Ctrl+X, then Y, and finally Enter to save the edited file with nano. Next, we’ll write the bash script that switches between the two tabs. Usually, the keyboard shortcut Ctrl+Tab cycles through open browser tabs. The script will use the program we installed, wtype, to simulate and automate these keystrokes. To create the script with nano, type:

$ nano ~/switchtab.sh

Add the following to the file:

#!/bin/bash

# Find Chromium browser process ID
chromium_pid=$(pgrep chromium | head -1)

# Check if Chromium is running
while [[ -z $chromium_pid ]]; do
  echo "Chromium browser is not running yet."
  sleep 5
  chromium_pid=$(pgrep chromium | head -1)
done

echo "Chromium browser process ID: $chromium_pid"

# Loop to send keyboard events
while true; do
  # Send Ctrl+Tab using `wtype` command
  wtype -M ctrl -P Tab -p Tab
  sleep 10
done

This script first checks that the Chromium browser is running. If not, it waits five seconds before trying again (this gives Chromium enough time to launch before moving on). To toggle between the two tabs, the script uses wtype to simulate Ctrl+Tab every ten seconds.

Press Ctrl+X, then Y, and finally Enter to save the new file with nano. Mark the file as executable so that it can be run as a script:

$ chmod +x ~/switchtab.sh

Finally, reboot your Raspberry Pi:

$ sudo reboot

Once your Raspberry Pi has rebooted, your display should be showing Chromium in kiosk mode, toggling between raspberrypi.com and time.is every ten seconds.

Depending on which websites your Raspberry Pi kiosk is displaying, you may want to temporarily plug a USB mouse into your Raspberry Pi so that you can dismiss any cookie pop-ups; the mouse can be unplugged again afterwards.

Kiosk-mode devices run unattended for long periods of time and frequently restart. They are usually left unattended in public places, making them vulnerable to unwanted attention or interference. Kiosks can also be a potential target for hackers. None of this is conducive to a reliable, long-term kiosk-mode installation. Although it’s not realistic to make them 100% secure, there are a number of things we can do to protect devices running in kiosk mode.

$ ssh-keygen -t ed25519

$ ssh-keygen
Generating public/private ed25519 key pair.
Enter file in which to save the key (/Users/<username>/.ssh/id_ed25519):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /Users/<username>/.ssh/id_ed25519
Your public key has been saved in /Users/<username>/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:u3Ry3y8g3tEo4TChzzjmebihkWqonbhVj7qiq3BsjMk <username>@<hostname>.local
The key's randomart image is:
+--[ED25519 256]--+
|                 |
|        .        |
|       . .       |
|      . o .      |
|    .  +S+ . o   |
|.= . ++ o.+ + .  |
|+E* +oo++.o+ o   |
|+*.+ o+o.=.....  |
|@=*.. .o.   . .o.|
+----[SHA256]-----+
$

$ cat ~/.ssh/id_ed25519.pub

$ ssh <username>@pi-kiosk.local

$ mkdir ~/.ssh

$ nano ~/.ssh/authorized_keys

$ exit

$ ssh <username>@pi-kiosk.local

$ sudo nano /etc/ssh/sshd_config

# To disable tunneled clear text passwords, change to no here!
PasswordAuthentication no
#PermitEmptyPasswords no

$ sudo reboot

$ sudo raspi-config

This guide covers the basics of setting up a simple web page viewer in kiosk mode. From here, you can explore more complex kiosk projects, such as a CCTV viewing station, a home automation system, or perhaps the ultimate kiosk-mode project: a magic mirror. Our tutorial is based on Magic Mirror², the winner of The MagPi (now Raspberry Pi Official Magazine)'s 50th-issue celebration feature, as voted by the Raspberry Pi community.