Raspberry Pi 4 Touchscreen Kiosk Setup (64-bit, Bullseye)

mitch

This article covers setting up a Raspberry Pi 4 using Raspberry Pi OS 64-bit Bullseye to run a Web app in kiosk mode on a touchscreen or monitor.

If you need to use an older version of the operating system, see: Raspberry Pi 4 Touchscreen Kiosk Setup (Buster)

Kiosk mode allows you to replace the Raspberry Pi 4 desktop with a stripped down Chromium browser. It will show your Web page or app and nothing more. The user won't even see the address bar. It will look more like an app on a phone or a tablet. If using a touchscreen the user won't even need a mouse.

To test the steps I used a Raspberry Pi 4 with a touchscreen. You can also test these steps using a monitor, keyboard and mouse.

Step 1. Setup a 64-bit Bullseye lite image

The easiest way to start is to setup a headless Raspberry Pi 4 (64-bit) Bullseye Lite image. I will show you how to add the GUI components needed on top of it.

Please note that these instructions only work for Raspberry Pi OS Bullseye (64-bit) Lite. I had issues with the earlier 32-bit version of Bullseye. Only install the 64-bit version.

I also had issues using small MicroSD cards. I would suggest using at least a 64GB card.

To create the base image, follow these instructions then return to this article:

Since I am using a touchscreen, I renamed my host to touchpi64. You can use whatever hostname you would like.

Step 2. Login to the pi over ssh

Because my pi is called touchpi64, I would login over ssh like this:

ssh pi@touchpi64.local

Be sure to adjust the instructions above for the host name that you are using.

Step 3. Configure startup settings

Once you remotely connect to the pi over ssh, run the following command:

sudo raspi-config

From the menu select:

  • System Options
    • Boot / Auto Login
      • Console Autologin
  • Display Options
    • Underscan
      • Yes
         / OK

    • Press the tab key twice to get to the Finish option, then press the enter key.

    When asked to reboot, select Yes.

    If you have a touchscreen or monitor hooked up to the pi, verify that the pi automatically logs in at the command line.

    Don't worry if you don't have a keyboard hooked up. You won't need it. All command line operations will be done through the remote ssh login.

    Step 4. Reconnect after reboot

    On your host computer, you were probably disconnected from the pi when it rebooted.

    Remote login again using ssh using your host name.

    In my case, again I would run:

    ssh pi@touchpi64.local

    Step 5. Install minimum GUI components

    Before you can run the Chromium browser on a lite version of Raspberry Pi OS, you will need a minimum set of GUI (Graphical User Interface) components to support it.

    While remotely logged in to the pi, run the following at the command line:

    sudo apt-get install --no-install-recommends xserver-xorg x11-xserver-utils xinit openbox

    Step 6. Install Chromium Web browser

    Once the minimum GUI components are in place, you can install the Chromium browser to display a Web site or Web app.

    sudo apt-get install --no-install-recommends chromium-browser

    Step 7: Edit Openbox config

    The Openbox window manager will be used to launch the Chromium browser.

    When Openbox launches at startup it will run two scripts in the /etc/xdg/openbox folder. The first, environment will setup any environment variables, etc. The second, autostart will setup and launch whatever app you specify.

    First I will show you how to edit the autostart file and then how to add environment variables to support it.

    • Open up autostart in an editor: 
      sudo nano /etc/xdg/openbox/autostart

    Update the autostart file by adding the text below.

    • First, add commands to turn off power management, screen blanking and screen saving. We don't want those features in a kiosk. 
      xset -dpms            # turn off display power management system
xset s noblank        # turn off screen blanking
xset s off            # turn off screen saver
    • Next if Chromium crashed it may pop up error messages next time it starts. This is another feature that we don't want in a kiosk. 
      # Remove exit errors from the config files that could trigger a warning

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
    • Finally, update autostart to run the Chromium browser in kiosk mode. Pass in an environment variable ($KIOSK_URL) that contains the URL of the Web app to launch. 
      # Run Chromium in kiosk mode
chromium-browser  --noerrdialogs --disable-infobars --kiosk $KIOSK_URL

      To prevent checking for updates, you may also want to add this flag to the end of the line above to default the check to once a year (1 year ~= 31536000 seconds):

      --check-for-update-interval=31536000

      In the next step, I will show you how to set $KIOSK_URL.

    • To save the autostart file in nano, press Ctrl-o, hit enter, then press Ctrl-X.

    Step 8. Setup the environment

    • Edit the Openbox environment file: 
      sudo nano /etc/xdg/openbox/environment
    • Add the KIOSK_URL to the file: 
      export KIOSK_URL=https://desertbot.io

    This is so that you can change the URL simply by remote-logging in, editing the environment file and rebooting.

    Step 9. Start the X server on boot

    • See if ~/.bash_profile already exists: 
      ls -la ~/.bash_profile
    • If NOT, then create an empty version: 
      touch ~/.bash_profile
    • Edit ~/.bash_profile: 
      sudo nano ~/.bash_profile
    • Add this line to start the X server on boot. Because I am using a touch screen I'm passing in the flag to remove the cursor. 
      [[ -z $DISPLAY && $XDG_VTNR -eq 1 ]] && startx -- -nocursor
    • Save and exit the file by pressing Ctrl-o, enter, Ctrl-X.
    • From the command line run: 
      source ~/.bash_profile
    • If you had no errors, reboot 
      sudo reboot

    After the server runs through its startup sequence, the browser should be launched and fill the whole screen.

    Step 10. Change the URL

    To change the URL on the Web site or app that launches, all you need to do is remote login to the pi and edit the Openbox environment file following the steps below:

    • Remote login to the pi: 
      ssh pi@touchpi64.local
    • Edit the Openbox environment file:
      sudo nano /etc/xdg/openbox/environment
    • Change the KIOSK_URL to the URL of your Web app or site
    • Then to save the change, press Ctrl-o, enter, Ctrl-X.
    • Reboot the pi:
      sudo reboot

    Troubleshooting

    • If nothing comes up, check the URL that you are using.
    • If you try running the startx command from a remote login it won't work. You will just display a blank screen on the pi.
    • If there is a black border around your browser window, try changing the overscan setting in raspi-config

    Touch screen issues

    Not all apps will work in or as expected on a touch screen if they:
    * have browser dependencies
    * require a keyboard, unless they have an onscreen option
    * require mouse functions beyond what a touch screen can emulate

    Browser crashes

    If the browser crashes often, you can:
    * Try to figure out if you can fix the reason it crashes or get an update
    * Setup a crontab job to reboot the pi at least once a night
    * Use a process manager like pm2 to restart the app when it crashes
    * Look into building a hardware reset button (but hide it from kiosk users!)
    * Remote login and reboot now and then

    Testing a kiosk app on a Mac

    How to test a kiosk app on a Mac is a lengthy topic. But here are a few tips if you are developing your own app:

    Test screen resolution

    On a Mac you can see how a Web app looks on various devices by doing the following:

    1. Launch Chrome
    2. Browse to the Web app URL
    3. Press Option-Command-J to open up the Debug panel (and again to close it)
    4. While in the Debug console, press Shift-Command-M to toggle a panel where you can test the app on various devices and sizes
    5. Create your own custom resolution that matches your touch screen

    Running Chrome in kiosk mode on a Mac

    Just like on a pi, you can run Chrome in kiosk mode on your Mac.

    /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --kiosk --app=https://desertbot.io

    After running that you may find Chrome in full screen always leaves out Toolbar and Bookmarks. If that happens, switch them back on in the View menu.

    Conclusion

    In this article you learned the basics of how to setup a Raspberry Pi 4 to run as a kiosk, either with a monitor or a touch screen.

    You could take it to the next level by building more kiosk-centric Web apps, using tools like ReactJS or Electron.

    By installing a Web or NodeJS server to run things locally, you could remove the dependency on WiFi or external servers.

    To deal with crashes you could add the ability to recover automatically using tools like pm2.

    The kiosk itself could be a standalone touch screen app, or integrated into a device like a robot or home automation. It could access hardware through the GPIO pins, Bluetooth, WiFi or the USB ports.

    Where to buy

    You can buy the touchscreen used in this article by using my affiliate link:

    Part Vendor
    Raspberry Pi Official 7 Inch Touch Screen for Raspberry Pi 4 / Pi 3/ Pi 2 Model B Amazon
    SmartiPi Touch 2 - Case for The Official Raspberry Pi 7" Touchscreen Display - with Cooling Fan Amazon

    More Touchscreen Hardware

    As an alternative you can pick up or order a touchscreen + case bundle from Walmart. It's not the exact hardware that I tested with. But I don't see why it wouldn't work.

    Part Vendor
    Official Raspberry Pi 7" Touchscreen with Pi 4 Compatible Case Walmart

    Related articles

    References

    • openbox.org [1]
    • List of Chromium Command Line Switches [2]
    • Setup a Raspberry Pi to run a Web Browser in Kiosk Mode [3]
    • How to Hide Chrome Warning After Crash [4]
    • Raspberry Pi How To: Periodic reboot via cron [5]
    • SmartiPi Touch 2 setup [6]
    • Chrome/Chromium startup flags [7]