Repository files navigation

This project contains the simplest form of a persistent Raspberry Pi-based browser kiosk.

Kiosks are useful if you want to build a web dashboard for something and have the Pi display it, or have a custom web page or online video play automatically when your Pi boots up, and take over the full screen.

This configuration is not meant to be highly secure, or extremely robust, I just use it when I want to pop a web page up on one of my Pis full-screen, like for a Home Assistant control panel.

For my own Kiosk, I'm using the following hardware to display a Home Assistant dashboard:

• Raspberry Pi 5 (2GB)
• Raspberry Pi Touch Display 2
• Touch Display 2 3D Printed Stand

Ensure you're running Pi OS with a graphical interface (the 'full install'), and Chromium is installed (it should be, by default).

Then open up Terminal and install a prerequisite:

sudo apt install unclutter

Create the script that will run the Kiosk:

mkdir -p /home/pi/kioskcp kiosk.sh /home/pi/kiosk/kiosk.sh

Copy over the SystemD unit file to run thekiosk service:

sudo cp kiosk.service /lib/systemd/system/kiosk.service

Enable the Systemdkiosk service so it will automatically run at system boot:

sudo systemctl enable kiosk.service

(Optional) Fire up thekiosk service immediately:

sudo systemctl start kiosk

To rotate the Touch Display immediately, you can run:

wlr-randr --output DSI-1 --transform 90

This orientation assumes the Pi is oriented so the USB-C plug is facing towards the bottom of the Touch Display. If you have the display plugged into the DSI-2 port, change the--output accordingly.

To persist the rotation setting, either configure the screen rotation on the display using the "Screen Configuration" utility, or edit thekanshi config file at~/.config/kanshi/config.

You can also set the display to be rotated during boot (either with the Pi Desktop splash screen or console output) by editing/boot/firmware/cmdline.txt. Add the following before the last parameter and reboot:

# Orientation options: normal, upside_down, left_side_up, right_side_upvideo=DSI-1:panel_orientation=left_side_up

Since a Kiosk will likely run quite frequently (or all day), there are a few things you can do to reduce its power consumption:

Following theguide in my blog post, edit your EEPROM file (sudo rpi-eeprom-config -e) and set the following settings:

[all]BOOT_UART=1WAKE_ON_GPIO=0POWER_OFF_ON_HALT=1

(Don't worry about changing any other values.) Save the changes and wait for the EEPROM to be updated. Once it is, the Pi 5's power consumption while shut down will be less than 0.01W (with the Pi's default configuration, the shutdown power consumption could be up to 1-2W!).

Running an always-on display at 100% brightness all day is not that helpful.

Right now I'm looking into the best way to dim the screen after a period of time, or configure the 'Screen Blanking' option in Pi OS.

See issue:Allow for screen to dim after a certain amount of time

You can view thekiosk service logs by running the command:

journalctl -u kiosk

(Follow the logs live by appending-f to that command.)

If you can log in via SSH in the background, you can stop the service with:

sudo systemctl stop kiosk

Otherwise, if you have access to the Pi itself, and can plug in a keyboard, you can pressCtrl +F4, and thatshould quit the browser.

Another alternative is to set up the Pi withPi Connect, and when connected to the Pi remotely, pressCtrl +F4.

Note: On a Mac, you need to pressFn +Ctrl +F4.

If you want to getreally fancy, you canuse something likexdotool and wire up a button to emulate keypresses to quit the browser.

GPL v3

This project was created by Jeff Geerling in 2024, loosely following this guide from PiMyLifeUp:Raspberry Pi Kiosk using Chromium.