Step-by-Step: Set up a Kiosk Web Display using the Raspberry Pi

Tested on the Raspberry Pi 2B and higher, as well as the Pi Zero W. This configuration will also work for touch screens.

These instructions will work for HDMI and on-board display connections.

Prerequisites

1. Some basic Linux terminal knowledge
2. Flash Raspberry Pi OS Lite
3. Wifi/network and SSH access.
4. A connection to the internet

Step-by-Step

Configure the raspberry pi

Enter the command below, and use the configuration that follows. raspi-config may have different menu structures, but the options should still be there.

sudo raspi-config

1. Change the password
2. Set Timezone (ie. America/Vancouver)
3. Set Keyboard (optional, only if not using SSH)
   1. Choose “Generic 104-key PC” for US/Canada, 105-key PC (intl.) for the rest of the world
   2. Choose “Other Language -> English (US)”
4. Update hostname
5. Display Options -> Underscan -> No Compensation
6. System Options -> Boot/Autologin -> Console Autologin -> Yes
7. Set gpu memory to 128mb or more
8. Set GL graphics driver the FakeKMS. Others may not display properly, or audio may not work
9. Finish and Reboot

Update package (apt) data.

IMPORTANT! Do this before installing other packages.

sudo apt update

Install x server and tools

sudo apt install -y --no-install-recommends xserver-xorg xinit x11-xserver-utils xdotool

Install openbox and chromium

sudo apt install -y --no-install-recommends openbox chromium-browser

Install mesa drivers for hw acceleration

sudo apt install -y libgles2-mesa mesa-utils libsdl2-dev

Edit /etc/xdg/openbox/autostart as root, and add the following content

xset -dpms      # turn off display power management system
xset s noblank  # turn off screen blanking
xset s off      # turn off the screen saver

# Set manual resolution for X
# xrandr --output HDMI-1 --mode 1280x720 --rate 30

# Prevent chromium crash error popups
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

# Run chromium with the KIOSK_URL env variable
chromium-browser --noerrdialogs \
  --disable-infobars \
  --kiosk $KIOSK_URL \
  --check-for-update-interval=31536000 \
  --ignore-gpu-blacklist \
  --use-gl=egl \
  --enable-native-gpu-memory-buffers \
  --enable-accelerated-2d-canvas \
  --force-gpu-rasterization \
  --cast-app-background-color=000000ff \
  --default-background-color=000000ff
  # --disable-gpu-compositing \  # Do not disable gpu compositing. Canvas effects are smoother this way

Hint: Shift-Insert to paste into putty+vim in insert mode

Hint: Use the command :set paste and :set nopaste within vim, if auto-formatting is a problem when pasting.

Edit /etc/xdg/openbox/environment as root, and add the following

export KIOSK_URL=http://localhost:3530

This will be the URL that will be opened when the RPi boots up.

Edit/append to ~/.bash_profile

# Start X server on boot
[[ -z $DISPLAY && $XDG_VTNR -eq 1 ]] && startx -- -nocursor

Reboot

sudo reboot

If X server gives an error and chromium doesn’t start, try setting a screen resolution in sudo raspi-config or changing the GL driver. FakeKMS is preferred.

Bonus

In addition to serving up a webpage online, you can always host your own webserver right on the Pi! My preferred flavor is to run NodeJS+Express+ReactJS. This will allow for an offline- or unstable internet-capable device.

Git and docker can also be easily installed for automation and updates. (For earlier versions of RPi such as the Zero W, you will have to download and install Node.js specifically for ARMv6.)

References

• https://reelyactive.github.io/diy/pi-kiosk/
• https://desertbot.io/blog/raspberry-pi-4-touchscreen-kiosk-setup
• https://pimylifeup.com/raspberry-pi-screen-resolution/
• https://peter.sh/experiments/chromium-command-line-switches/