Raspberry Pi Kiosk HOW-TO

2020-09-13

Tested with Raspberry Pi 3 and 4, but should work on some older models too.

For Ethernet connected kiosk machines.

Download and install Raspberry Pi OS

Download img file and image to micro SD card.

  • Raspberry Pi OS (32-bit) with desktop, Image with desktop based on Debian Buster. Warning: This is not the distribution with "recommended software".

All the following, unless otherwise indicated should run in a root shell. Use sudo -i after initial login as user pi.

The default user:pass for Raspbian is pi:raspberry

Initial update and clean up

apt -y update
apt -y dist-upgrade
apt -y install unclutter vim ntpdate at-spi2-core libnotify-bin \
    mate-notification-daemon mate-notification-daemon-common
apt -y remove vlc geany thonny qpdfview xarchiver gpicview galculator mousepad
apt -y autoremove

raspi-config and general config

Things to do:

  • 1. Change User Password
  • 3-B1-B4. Desktop autologin as pi
  • 4-I2 Localisation, change timezone
  • 4-I3 Localisation, change keyboard layout to us
  • 4-I4 Localisation, change wi-fi country to Australia
  • 5-P2 Interfacing Options, enable SSH server

Configure default editor to vim

sudo update-alternatives --config editor

By default, the user pi is part of the sudoers group and requires no password. We want to change this to prompt a user for a password when performing sudo operations for the first time in a session.

Edit /etc/sudoers.d/010_pi-nopasswd and change:

pi ALL=(ALL) NOPASSWD: ALL

To:

pi ALL=(ALL) ALL

Optional: Enable root account

Set password for root user as well, this will enable the root user.

sudo passwd root

Disable wireless and Bluetooth

Disable bluetooth and wireless via GUI in the system tray. The systme should persist this change after reboots. This can also be done via the command line using rfkill.

Enable GPIO shutdown

Allow shutdown via GPIO. Add to /boot/config.txt, at the of the [all] section.

dtoverlay=gpio-shutdown,gpio_pin=26,active_low=1,gpio_pull=up

This will give a physical shutdown button on pin GPIO 26. Shorting GPIO 26 to GND will invoke a shutdown.

J8:
   3V3  (1) (2)  5V
 GPIO2  (3) (4)  5V
 GPIO3  (5) (6)  GND
 GPIO4  (7) (8)  GPIO14
   GND  (9) (10) GPIO15
GPIO17 (11) (12) GPIO18
GPIO27 (13) (14) GND
GPIO22 (15) (16) GPIO23
   3V3 (17) (18) GPIO24
GPIO10 (19) (20) GND
 GPIO9 (21) (22) GPIO25
GPIO11 (23) (24) GPIO8
   GND (25) (26) GPIO7
 GPIO0 (27) (28) GPIO1
 GPIO5 (29) (30) GND
 GPIO6 (31) (32) GPIO12
GPIO13 (33) (34) GND
GPIO19 (35) (36) GPIO16
GPIO26 (37) (38) GPIO20
   GND (39) (40) GPIO21

Fix mouse lag

Add to end of kernel command line file /boot/cmdline.txt to fix laggy mouse behaviour.

usbhid.mousepoll=0

Optional: Configure SSH

Prepare authorized_keys file in ~/.ssh/authorized_keys for both users root and pi. Use your own favourite technique for doing this.

Set permissions for the file

sudo chmod 0600 /home/pi/.ssh/authorized_keys
sudo chmod 0600 /root/.ssh/authorized_keys

Allow only public key authentication, edit /etc/sshd/sshd_config

PermitRootLogin prohibit-password
PasswordAuthentication no

Restart sshd

service sshd restart

Check and confirm you can remotely SSH to the device as both root and pi.

Configure ntpdate

Automatic time sync should already be enabled, however sometimes it is not and I'm not sure why. Enable it with

timedatectl set-ntp True

Disable screensaver and blanking

Disable console screen blanking. This doesn't affect a GUI based kiosk machine but we'll do it anyway for completeness.

Add to /boot/cmdline.txt

consoleblank=0

Disable UI screen blanking by creating ~/.config/lxsession/LXDE-pi/autostart. Note the first 3 lines is from the global /etc/xdg/lxsession/LXDE-pi/autostart. If a local file in ~/.config is found, the global file is ignored. This is why we need to copy the lines from the global file to the local user file.

Run all this as user pi. Create ~/.config/lxsession/LXDE-pi/autostart

mkdir -p ~/.config/lxsession/LXDE-pi && touch ~/.config/lxsession/LXDE-pi/autostart

Make a symbolic link so it's easier to find and edit later on.

ln -s .config/lxsession/LXDE-pi/autostart ~/autostart

Edit autostart and add:

@lxpanel --profile LXDE-pi
@pcmanfm --desktop --profile LXDE-pi
@xscreensaver -no-splash
@xset s off
@xset dpms 0 0 0
@/home/pi/autostart.sh

Configure autostart script

Create a file ~/autostart.sh and make it executable

chmod +x ~/autostart.sh

#!/bin/bash

# URL to open automatically
URL=https://google.com/

while ! ip route | grep -q -e "eth0" -e "wlan0"; do
    notify-send -t 900 "Waiting for network connection..." &> /dev/null
    sleep 1
done

notify-send -t 500 "Connected." &> /dev/null
notify-send -t 3000 "Starting browser..." &> /dev/null
chromium-browser --incognito --app=$URL \
    --start-fullscreen \
    --check-for-update-interval=31536000 \
    --overscroll-history-navigation=0 \
    --disable-pinch

Some command line switches customises the Chromium instance:

  • --overscroll-history-navigation=0 disables behaviour where left and right swiping would trigger the browser's history back and forward behavivour.
  • --disable-pinch disables pinch to zoom.
  • --check-for-update-interval=31536000 disables automatic checks for updates, otherwise would cause "could not be updated" error.

Restarting the unit with sudo reboot and Chromium should automatically start once the network connection is up.

Note this does not automatically refresh the web page at regular intervals, the target web site itself should perform the refreshing.

Overlay FS

It's recommended to use the Overlay FS. After the set up is completed and tested to be working correctly, in raspi-config, enable the Overlay FS with a writable /boot directory.

You will want to clear ~/.config/chromium prior to enabling the overlay. Or alternatively, you can add rm -rf /home/pi/.config/chromium to /boot/start.sh after enabling the Overlay FS.

Prior to enabling OverlayFS

pkill chromium-browser; rm -rf /home/pi/.config/chromium

Using a Overlay FS means it is more resilient to power outages by making the root file system read only. Changes to the filesystem are written to a in memory tmpfs filesystem.

raspi-config implements the scripts based on this article by Mattias Wikstrom.

Update workflow with OverlayFS

To update packages and other files on the flash card (except /boot), you'll need to disable OverlayFS.

  • Disable overlay with raspi-config and reboot
  • Make the changes
  • Clear chromium profile with pkill chromium-browse; rm -rf /home/pi/.config/chromium
  • Enable overlay with raspi-config and reboot