Create a webapp kiosk with a Raspberry Pi 3

RPI3_kiosk.md

Raspberry Pi 3 B Kiosk

This guide utilizes Raspbian Jessie Lite as a base to create a kiosk that loads a single-page web app in the Chromium browser.

Prepare Micro SD Card

1. Download and unzip Raspbian Jessie Lite.
2. Copy the img file to the micro SD card. For platform-specific instructions, you can look here. If using Linux or MacOS, my preference is to use dd as described below.

Using dd

1. Run lsblk -p before and after inserting your card to find the correct path to your card. Be absolutely sure to get this right because dd will DESTROY everying it writes over, and there are no limits to where it can write.
2. Copy img file to card: sudo dd if=PATHTODOWNLOADEDIMG of=PATHTOCARD bs=1M status=progress

Your card should now be ready to boot and configre as a kiosk.

Configure Kiosk

1. Insert the card into the RPI and boot it up.

2. Log in with default username pi and password raspberry.

3. Raspbian now disables SSH by default (preventing RPI botnets), so you will need to run sudo raspi-config directly on the machine.

   • Change User Password (Give it a good password: this is root access!)
   • Interfacing Options --> SSH (enable SSH)
   • Localisation Options --> Change Timezone (set to your timezone)
   • Expand Filesystem
   • Finish (and sudo reboot)

4. Note IP address of device, then SSH into it (this will allow copy & pasting from this file): ssh pi@IPADDRESS

5. Update OS and install needed packages (this will take a LONG time): sudo apt-get update && sudo apt-get --yes --force-yes dist-upgrade && sudo apt-get --yes --force-yes install xorg nodm chromium-browser xautolock numlockx

6. If you want WiFi, edit the config file: sudo nano /etc/network/interfaces

   • Comment out the existing wlan0 and wlan1 and add a new config for wlan0:

     auto wlan0
     iface wlan0 inet dhcp
     wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf
     wpa-ssid YOURSSID
     wpa-psk YOURKEY
     

   • Save the file by pressing ctrl-x , then y and enter.

7. Create the kiosk user: sudo useradd -G www-data -m kiosk && sudo passwd kiosk

8. Create an .xsession file for the kiosk user: sudo nano /home/kiosk/.xsession

   Paste this into the editor (usually shift-ctrl-v or shift-insert, or use the right-click context menu):

   #!/usr/bin/env bash
   
   # Set your app's URL below:
   SPA_URL="APP_URL_HERE"
   
   xset s off
   xset -dpms
   xset s noblank
   sed -i 's/"exited_cleanly": false/"exited_cleanly": true/' ~/.config/chromium/Default/Preferences
   numlockx on
   
   #Lock out right-click and menu button on keyboard
   xmodmap -e "pointer = 1 2 32 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31"
   xmodmap -e "keycode 135 ="
   
   #Lock out other special keys
   xmodmap -e "keycode 64 ="       #L-alt
   xmodmap -e "keycode 108 ="      #R-alt
   xmodmap -e "keycode 37 ="       #L-ctrl
   xmodmap -e "keycode 105 ="      #R-ctrl
   xmodmap -e "keycode 133 ="      #L-windows (meta key)
   xmodmap -e "keycode 134 ="      #R-windows (meta key)
   xmodmap -e "keycode 107 ="      #print-screen
   xmodmap -e "keycode 127 ="      #page-break
   xmodmap -e "keycode 77 ="       #num-lock
   xmodmap -e "keycode 78 ="       #scroll-lock
   xmodmap -e "keycode 118 ="      #insert
   xmodmap -e "keycode 9 ="        #esc
   xmodmap -e "keycode 67 ="       #F1
   xmodmap -e "keycode 68 ="       #F2
   xmodmap -e "keycode 69 ="       #F3
   xmodmap -e "keycode 70 ="       #F4
   #xmodmap -e "keycode 71 ="       #F5
   xmodmap -e "keycode 72 ="       #F6
   xmodmap -e "keycode 73 ="       #F7
   xmodmap -e "keycode 74 ="       #F8
   xmodmap -e "keycode 75 ="       #F9
   xmodmap -e "keycode 76 ="       #F10
   xmodmap -e "keycode 95 ="       #F11
   xmodmap -e "keycode 96 ="       #F12
   
   # Restart chromium after 10 minutes of inactivity (this helps with page reloads, etc.)
   xautolock -secure -time 10 -locker /home/kiosk/kill_chromium.sh &
   
   # Auto-detect resolution and store in variables
   res=$(xdpyinfo -d :0 | grep dimensions | sed -r 's/^[^0-9]*([0-9]+x[0-9]+).*$/\1/')
   resx=$(echo $res | awk '{split($0,array,"x")} END{print array[1]}')
   resy=$(echo $res | awk '{split($0,array,"x")} END{print array[2]}')
   
   while true; do
     chromium-browser --incognito --noerrdialogs --window-size=$resx,$resy --window-position=0,0 --kiosk $SPA_URL;
     sleep 1s;
   done
   

   Make any changes to the config as needed, at least setting the SPA_URL.

   Save the file by pressing ctrl-x , then y and enter.

9. Create a simple script to kill Chromium: echo "pkill chromium" | sudo tee /home/kiosk/kill_chromium.sh

10. Make the script executable: sudo chmod +x /home/kiosk/kill_chromium.sh

11. Edit the nodm config file: sudo nano /etc/default/nodm

• Change as needed to match the following two settings: NODM_ENABLED=true and NODM_USER=kiosk
• If you wish to disable the mouse pointer entirely, you can use this option: NODM_X_OPTIONS='-nolisten tcp -nocursor'
• Save the file by pressing ctrl-x , then y and enter.

12. Optional Stuff

• You can use xbindkeys to attach scripts to keys if you want to add custom functionality.

• You can add a cron job to reboot the kiosk regularly: sudo crontab -e

  Choose nano and edit the cron file by adding the following to the bottom of the file:

  0 4 * * * /sbin/shutdown -r now
  

  Save the file by pressing ctrl-x , then y and enter.

13. You are done! Reboot the kiosk and it should boot into your app: sudo reboot