Raspberry Pi Kiosk

For this Raspberry Pi Kiosk tutorial, we will be showing you how you can set up your Pi as a Kiosk using the popular web browser, Chromium.

We utilize Chromium as it is one of the best-supported web browsers and openly supports the functionality to act in a kiosk mode. It is also easy to control through key presses which we can simulate using the xdotool that we install during this guide.

Ultimate Books of Pi

This guide will give you a good idea on how to use autologin tasks and simple bash scripts to perform numerous tasks.

Please note to do this tutorial you will need to be running the full version of Raspbian as this relies on the GUI that comes with it to properly operate.

Equipment List

The entire list of all the pieces of equipment that we made use of for this Raspberry Pi Kiosk tutorial is listed below.

Recommended:

Raspberry Pi 2 or 3

Micro SD Card

Power Supply

TV or Monitor

HDMI Cord

Ethernet Cord or WiFi dongle

Optional:

Raspberry Pi Case

Setting up the Raspberry Pi Kiosk

1. Before we get started with this tutorial, we will be first removing some packages that we don’t need for our Raspberry Pi kiosk.

Removing these packages will free up some much-needed memory and reduce the number of packages that will be updated every time you update your Raspberry Pi.

To do this just run the following three commands on your Raspberry Pi. We have split these into three different commands to make them easier to copy and write out.

sudo apt-get purge wolfram-engine scratch scratch2 nuscratch sonic-pi idle3 -y
sudo apt-get purge smartsim java-common minecraft-pi libreoffice* -y

2. Now that we have removed these numerous packages from our Raspberry Pi Kiosk we will need to run some cleanup commands.

To remove any unnecessary lingering packages and to clean out the local repository of retrieved packages run the following two commands on your Raspberry Pi.

sudo apt-get clean
sudo apt-get autoremove -y

3. Now that we have removed the bulk of the unnecessary applications, we must now make sure that our installation of Raspbian is up to date. Also, make sure you have SSH enabled as it is very handy if you need to edit any files later on.

We can use the following two commands within the terminal on our Raspberry Pi to update all the packages to their latest versions.

sudo apt-get update
sudo apt-get upgrade

4. We now need also to install xdotool. This tool will allow our bash script to execute key presses without anyone being on the device. We also install the unclutter package, this will enable us to hide the mouse from the display.

Just run the following command on your Raspberry Pi to install the package.

sudo apt-get install xdotool unclutter sed

5. Now that those packages have been installed we can now proceed to the next stage of this tutorial. That is setting up Raspbian to auto login to our user. Having to log in every time for a kiosk would be an annoyance.

Desktop autologin is the default behavior but if for some reason you have changed it follow the next few steps to switch it back. Otherwise, skip to step 6 of this tutorial.

5a. Run the following command on your Raspberry Pi to load up the Raspi-config tool. We will be using this tool to enable auto login.

sudo raspi-config

5b. Now within the tool go to 3 Boot Options -> B1 Desktop / CLI -> B4 Desktop Autologin

5c. Desktop autologin should now be enabled and you can safely quit out of the raspi-config tool.

6. Now that we have enabled desktop autologin we need to go ahead and write our kiosk.sh script.

Writing the Script

The kiosk script will handle the bulk of the work for our Raspberry Pi Kiosk, including launching Chromium itself and also simulating key presses.

Begin writing our kiosk bash script by running the following command on the Raspberry Pi.

nano /home/pi/kiosk.sh

7. Within this file enter the following lines of code, we will explain the important parts of the script so you can better bend it to your needs.

#!/bin/bash

The very first line defines what the command line interpreter (CLI) should use to try and execute this file. This is useful for cases where you don’t want to have to specify the specific application required every time you run the script.

xset s noblank
xset s off
xset -dpms

These three lines are pretty important as they help us stop the Raspberry Pi’s display power management system from kicking in and blanking out the screen.

Basically, these three commands set the current xsession not to blank out the screensaver and then disables the screensaver altogether. The third line disables the entire “display power management system” meaning that the desktop interface should never blank out the screen.

unclutter -idle 0.5 -root &

This line runs the program we installed earlier called unclutter. This application will hide the mouse from the display whenever it has been idle for longer then 0.5 seconds and will remove it even if it is over the root background.

You can adjust the idle timer to the number of seconds you want with each decimal place being a fraction of a second. If you would prefer to remove the mouse instantly, then remove the -idle 0.5 from the  command.

sed -i 's/"exited_cleanly":false/"exited_cleanly":true/' /home/pi/.config/chromium/Default/Preferences
sed -i 's/"exit_type":"Crashed"/"exit_type":"Normal"/' /home/pi/.config/chromium/Default/Preferences

These two lines of the script use sed to search through the Chromium preferences file and clear out any flags that would make the warning bar appear, a behavior you don’t really want happening on your Raspberry Pi Kiosk.

If Chromium ever crashes or is closed suddenly, the lines above will ensure you don’t have to get hold of a mouse and keyboard to clear the warning bar that would typically appear at the top of the browser.

/usr/bin/chromium-browser --noerrdialogs --disable-infobars --kiosk https://pimylifeup.com https://arduinomylifeup.com &

This line launches Chromium with our parameters. We will go through each of these parameters so you know what you can modify, and how you can modify it.

--kiosk

This flag sets Chromium to operate in Kiosk mode, this locks it into a particular set of features and only allows limited access to both the web browser and any other OS functionality.

Chromium’s kiosk functionality takes full control of the screen, maximizing Chromium to the full size of your screen and stops user input from being accepted by the OS, effectively trapping the end user within a sandbox.

--noerrdialogs

This option tells Chromium that it should not display any of its error dialogs to the end user.

It is crucial if you don’t want the end user to know if anything has or is going wrong with Chromium, this goes alongside our code to clear the “exited_cleanly” and “exit_type” state earlier in the code.

--disable-infobars

We use this to disable Chromium from displaying its info bar to the end user.

The info bar can be used by Chromium to notify them of certain things such as that Chromium is not their default web browser. Of course, as we are using this as a kiosk, we don’t need the user to know any information that Chromium might want to display.

https://pimylifeup.com https://arduinomylifeup.com

These are the two web pages that the script will open, each will be opened in a new tab. You can add additional web pages/tabs by adding to this list by separating each one with a space.

while true; do
      xdotool keydown ctrl+Tab; xdotool keyup ctrl+Tab;
      sleep 15
done

These lines run a very simple infinite while loop that uses xdotool to mimic pressing Ctrl + Tab. Making Chromium switch to the next tab.

After xdotool has executed its key presses, it then puts the loop to sleep for 15 seconds. To change how long the loop sleeps for before it executes the xdotool command again just change the sleep 15 command.

You can also use this method to add a screen refresh, this may be important when you want to display live scores. The command for this should look something like what we have shown below.

xdotool keydown ctrl+r; xdotool keyup ctrl+r;

8. Once you have entered all the code for our Raspberry Pi kiosk script, it should look somewhat similar to what we have displayed below.

#!/bin/bash
xset s noblank
xset s off
xset -dpms

unclutter -idle 0.5 -root &

sed -i 's/"exited_cleanly":false/"exited_cleanly":true/' /home/pi/.config/chromium/Default/Preferences
sed -i 's/"exit_type":"Crashed"/"exit_type":"Normal"/' /home/pi/.config/chromium/Default/Preferences

/usr/bin/chromium-browser --noerrdialogs --disable-infobars --kiosk https://pimylifeup.com https://arduinomylifeup.com &

while true; do
   xdotool keydown ctrl+Tab; xdotool keyup ctrl+Tab;
   sleep 10
done

9. Once you are sure everything is correct, save the file by pressing CTRL + X then Y and finally ENTER.

Bringing it Altogether

10. Now that we have enforced desktop auto login and written our kiosk script, we need to go ahead and modify the lxsession autostart script by running the following command on the Raspberry Pi.

nano /home/pi/.config/lxsession/LXDE-pi/autostart

11. As we don’t want any screensavers to run, we definitely don’t want the xscreensaver application to be getting launched on our Raspberry Pi Kiosk.

So, the first thing we need to do in this file is to comment out a particular line that launches up the xscreensaver application.

Find

@xscreensaver -no-splash

Replace with

#@xscreensaver -no-splash

12. Now that you have commented out the xscreensaver line you need to enter the following lines to the bottom of the file.

@bash /home/pi/kiosk.sh

This line that we are going to add will trigger a batch script that we wrote earlier in this tutorial.

13. With all the code entered into the autostart file, it should end up looking like what we have shown below. If you are happy with what is there, then you should save the script by pressing Ctrl + X then Y and then finally Enter.

@lxpanel --profile LXDE-pi
@pcmanfm --desktop --profile LXDE-pi
#@xscreensaver -no-splash
@point-rpi
@bash /home/pi/kiosk.sh

14. Finally, let’s restart our Raspberry Pi. Upon reboot, Chromium will be opened up in Kiosk mode, and your chosen websites will be displayed. Hopefully, by this point, everything is working exactly as intended.

Restart the Raspberry Pi by running the following command.

sudo reboot

15. Now with everything up and running correctly, if there is for any reason you want to stop the script from running, you can utilize the following command.

sudo killall kiosk.sh

This command will kill any instances of the kiosk.sh script that is currently running.

Enforcing the resolution on a Raspberry Pi Kiosk

1. One thing you might want to do is to enforce the resolution that the Raspberry Pi is going to use. Setting the resolution can be quite handy as the Raspberry Pi’s built-in detection can sometimes be a bit flakey.

To begin setting the resolution, we must first load up the Raspberry Pi configuration tool by running the following command.

sudo raspi-config

2. Within the configuration tool, you will want to start by going to “7 Advanced Options“.

3. Now that we are in the advanced options section you should see an option labeled “A5 Resolution” select that option.

4. Within here find and select the resolution that best fits your screen and press ENTER.

5. With your resolution now set you will need to restart the Raspberry Pi. Do this by first exiting out of the configuration tool by pressing ESC, then entering the following command into the Raspberry Pi’s terminal.

sudo reboot

6. Your Raspberry Pi should now restart and be running at the specified resolution.

There are so many ways you can extend this tutorial. For example, you can set up a web server on the Raspberry Pi and have it serve local web pages to be displayed on your Kiosk. It’s perfect if you want the results of a competition or basically any other sort of information you want to be displayed.

By now you should have your Raspberry Pi successfully booting into the Kiosk mode of Chromium. If you have any issues with this Raspberry Pi kiosk tutorial or want to leave feedback, then feel free to sign up for our forums.

Ultimate Books of Pi Bottom
Pi My Life Up's Crash Course
to the Raspberry Pi

Pi My Life Up's Crash Course

to the Raspberry Pi

Subscribe to our email list to get the

Crash Course delivered straight to your inbox

Please check your inbox for a confirmation email!