This guide provides a lightweight kiosk configuration for a Raspberry Pi. We will start with a fresh install of Raspbian Lite and add a minimum X Server environment to run the Chromium browser in Kiosk mode.
The hardware I am using is to create this guide is a Microsoft Surface 4 Pro with Windows 10 and a Raspberry Pi Zero W. I will be operating as a standard user on the Windows machine, and as such, I will need to run most of the software “as an administrator.”
I wasn’t able to connect the PI a television and external keyboard during the configuration; therefore, these instructions are written on assumption that you will be connecting to your Raspberry Pi through SSH via data port.
The software I will be using on Windows in this guide are:
- SD Card Formatter
- Win32 Disk Imager
- PSPad Portable
- Bonjour Print Services for Windows
- PuTTY Portable
Install Raspbian Lite on an Mirco SD Card
The Microsoft Surface has a built in Micro SD Reader hidden underneath the kickstand near the power plug. First, we need to prep our Micro SD Card by formatting it with SD Card Formatter running as an administrator.
After downloading the latest version of Raspbian Lite, extract the 2018-10-09-raspbian-stretch-lite.img from the zip file to folder on your computer. In my case, I stored the file in c:\export so the file would be accessible to applications running as an administrator.
Finally, write the Raspbian Lite image using the Win32 Disk Imager, running as the administrator. After this step, we our card is loaded with the Raspbian Lite OS. We need to modify the config.txt and the cmdline.txt files and create a new before inserting the card into our Raspberry Pi.
IMPORTANT: DO NOT EDIT THESE FILES IN NOTEPAD, because notepad will destroy the formatting of these files causing your PI not to boot.
- Edit the file: <SDCARD>/boot/config.txt and add the following line at the bottom: dtoverlay=dwc2
- Save and close the file.
- Edit the file <SDCARD>/boot/cmdline.txt and find the word, “rootwait” and the follow line after: “ modules-load=dwc2,g_ether ”.
- Save and Exit.
- Finally, in the <SDCARD>/boot/ directory, create a new file titled, “ssh”.
You can eject your SD card and insert it your Raspberry PI and connect your computer to Raspberry Pi via the PI’s data USB port.
Connecting to your Raspberry Pi
I mentioned above that I wasn’t connecting my pi to external monitor and keyboard during the setup phase. The main reason was that I didn’t have these resources available at the time. As such, this gave me a great learning opportunity. In the last section, we enabled SSH when we edited the cmdnline.txt and config.txt files and added the “ssh” file.
You should have “Bonjour Print Services for Windows” installed on your system at this point, and you should be connected to your PI via a USB cord. Using Putty, we can SSH into the PI with the hostname of “Pi@RaspberryPi.local”. If you get the error, “Unable to open connection to raspberrypi.local. Host does not exist.” Very you have “Bonjour Print Services for Windows” installed.
If everything goes correctly, you are presented with an SSH screen asking for a password for the pi user. The default password is “raspberry”.
Configuring your Raspberry Pi
Let apply some initial customizations.
sudo raspi-config
- Localisation Options: Select your preferred locale.
- I used en_us.UTF-8,
- timezone
- keyboard layout.
- Change User Password:
- Keeping the default password means your Pi will get hacked faster than you can say “botnet” as soon as you connect it to the internet.
- Boot Options:
- Select “Desktop / CLI” and then “Console Autologin”.
Now reboot the PI, and reconnect via SSH. To conclude the initial setup, update all preinstalled packages by running the following commands:
sudo apt-get update
sudo apt-get upgrade
Configuring Wifi Settings
Edit the wpa_supplicant file.
nano /etc/wpa_supplicant/wpa_supplicant.conf
Go to the bottom of the file and add the following:
network={
ssid="MySSID"
psk="SSIDPASSWORD"
}
Note: The password can be configured either as the ASCII representation in quotes as in the example above. You may, also, enter it as a pre-encrypted 32 byte hexadecimal number by using the wpa_passphrase
utility to generate an encrypted PSK.
$ wpa_passphrase "MySSID"
# reading passphrase from stdin
SSIDPASSWORD
network={
ssid="MySSID"
#psk="SSIDPASSWORD"
psk=009309e5f77b45a357eff78831f47f216fa8a6864b3241e421d14516d71e9838
}
Creating a Minimum X Server Environment for the Chromium Browser
We only want to run the Chromium web browser in kiosk mode; therefore, we don’t need a desktop environment or login manger.
sudo apt-get install --no-install-recommends xserver-xorg x11-xserver-utils xinit openbox
Install Chromium
sudo apt-get install --no-install-recommends chromium-browser
We can configure Openbox. Edit /etc/xdg/openbox/autostart and replace its content with the following:
# Disable any form of screen saver / screen blanking / power management
xset s off
xset s noblank
xset -dpms
# Allow quitting the X server with CTRL-ATL-Backspace
setxkbmap -option terminate:ctrl_alt_bksp
# Start Chromium in kiosk mode
sed -i 's/"exited_cleanly":false/"exited_cleanly":true/' ~/.config/chromium/'Local State'
sed -i 's/"exited_cleanly":false/"exited_cleanly":true/; s/"exit_type":"[^"]\+"/"exit_type":"Normal"/' ~/.config/chromium/Default/Preferences
chromium-browser --disable-infobars --kiosk 'http://your-url-here'
Note: I configured my kiosk to scroll through a series of Google Slides which were configured to run in Portrait mode.
Start X automatically on boot
Because we already configured the Pi to autologin the pi user, we can use its .bash_profile for starting X. Simply append the following line:
[[ -z $DISPLAY && $XDG_VTNR -eq 1 ]] && startx -- -nocursor
The condition makes sure that X is only started on the first console (and if it isn’t already running). Because autologin uses the first console, this has the desired effect of automatically starting the X server (and thus the window manager and thus Chromium) on boot. And you can still use any of the other consoles for logging in manually.
Reboot your pi to test if everything works as expected.
Since I, configured my slides to be displayed in a portrait mode, I needed to modify the /boot/config.txt file and add the line:
display_rotate=1
in order to have the screen rotated to match Google Slides.
Special Hat tip:
- Stefan at TechBlog for the article titled: Setup a Raspberry Pi to run a Web Browser in Kiosk Mode
- Youtuber TechWizTime for the instructions on connecting to Raspberry Pi Zero W via USB.
Cool! I was wondering if I need a full blown Raspi for this and am pleased to learn that a Zero will do. How can I get the kiosk to refresh a webpage automatically in a specified interval?
Hans,
I won’t lie, but you will see a performance drop with the Raspberry Pi Zero. In some applications, that isn’t a problem.
Where is the demo video?
Hi Krishna,
I apologize, but I am not really setup to do demo videos. Thanks for the comment.
~bk
I’m a producer and created a Raspberry Pi kiosk which is step-by-step and start to finish. I used it to display my Grafana dashboards with my account stats for a couple of my video channels.
You can watch the video here: https://www.youtube.com/watch?v=ocV7Y1EsBqI&ab_channel=AidenValentine