pi-kiosk: a Raspberry Pi browser kiosk in two files

A script, a unit file, and nothing else

pi-kiosk contains what the project calls the simplest form of a persistent Raspberry Pi based browser kiosk, and the repository is small enough to describe exactly: a shell script, a systemd unit file, a licence, and a resources directory with the images.

The use case is narrow and stated in the first paragraph. A kiosk is useful if you want to build a web dashboard for something and have the Pi display it, or if you want a custom web page or an online video to play automatically when the Pi boots and to take over the full screen. The hardware the author uses it with is a Raspberry Pi 5 with 2GB of memory and a Touch Display 2, sitting on a printed stand.

The reason the project is this small is the same reason it exists. The author says the configuration is not meant to be highly secure, and not built to take much abuse, and says he uses it when he wants a page to appear full screen on one of his Pis, for instance as a Home Assistant control panel. That is a person solving his own problem and publishing the two files that solve it, and the reviewer's decision follows from that: it is a starting point to read and copy, not a system to deploy unattended in a public place.

The work the browser does is done by a Chromium in kiosk mode, and Chromium is expected to be present already. The script that runs it is copied into a directory of your own and the unit file is installed into the systemd system directory with your user name substituted into it.

The project was created by Jeff Geerling in 2024, and it says it loosely follows a guide from PiMyLifeUp on a Raspberry Pi kiosk using Chromium. The licence is GPL v3.

Setup: copy two files, enable one service

The first requirement is a Pi OS installation with a graphical interface, the full install, and Chromium installed, which the documentation notes should be the case by default.

With that in place the setup is a handful of commands. You clone the repository into your downloads directory and change into it.

cd /home/$USER/Downloads
git clone https://github.com/geerlingguy/pi-kiosk.git
cd pi-kiosk

Then you create the directory that will hold the script and copy it there.

mkdir -p /home/$USER/kiosk
cp kiosk.sh /home/$USER/kiosk/kiosk.sh

The script is copied into a directory under your own home rather than run from the clone, because the clone is a working copy that you will update, and the running copy is the one the service points at.

The unit file goes into the systemd system directory, and the placeholder in it is replaced with your user name, because a system service runs without your login session and needs to know which account the browser belongs to.

sudo cp kiosk.service /lib/systemd/system/kiosk.service
sudo sed -i "s/USER_HERE/$USER/" /lib/systemd/system/kiosk.service

The last step enables the service so it starts at boot, and the optional one starts it straight away so you do not have to wait for a reboot.

sudo systemctl enable kiosk.service

sudo systemctl start kiosk

The two are separated deliberately, and the order is the point. Enabling does not start a service, so the screen stays dark until you run the second command, and you get to see the browser before it comes back on every boot.

Rotating the screen, before and after the desktop starts

A kiosk on a Pi with a touch display is often mounted in a way that puts the wrong way up, and the project documents two ways to fix it.

The immediate one is a command from the wlr-randr tool, which rotates the named output by 90 degrees.

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

The orientation this produces assumes the Pi is mounted with the USB-C plug pointing towards the bottom of the display, and the documentation is careful about the port: if the display is plugged into the DSI-2 port, the output name in the command has to change to match.

That detail is the kind that costs an afternoon. The command is identical in both cases except for the port name, and the failure mode if you get it wrong is a command that reports no such output rather than a screen that rotates the wrong way.

To make the rotation permanent there are two routes. The first is the display's own Screen Configuration utility. The second is the kanshi configuration file in the user's config directory, which is the file the compositor reads to decide how outputs are arranged.

For a screen that has to be rotated before the graphical environment exists, there is a third route, and it is the one that matters for a kiosk, because the early boot frames are the ones the viewer sees first. You edit the firmware command line file and add a video parameter before the last parameter, then reboot.

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

The comment line above it is part of the file, and it lists the four values the parameter accepts.

The 140x reduction in shutdown power draw

A kiosk that runs all day is rarely plugged in and switched off, so the power it draws while shut down is the number that matters over a year. The project points at a blog post of its own about reducing the Raspberry Pi 5 power consumption by a factor of 140 and then gives the exact EEPROM settings to use.

You edit the EEPROM configuration with the tool that manages it, and set three values in the all section.

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

BOOT_UART enables boot output over the UART, WAKE_ON_GPIO stops the chip waking on a GPIO signal, and POWER_OFF_ON_HALT is the one that matters, since it lets the system cut power when it halts instead of leaving the processor in a state that keeps drawing current.

The documentation says not to worry about the other values, and to save the changes and wait for the EEPROM to be updated. The result it quotes is a shutdown power consumption below 0.01W, against a default configuration where it could be one to two watts.

That is a real saving on a device that is plugged in for years, and it is also the kind of change that has consequences beyond the number. A wake on GPIO that is disabled is a wake source you will have to re-enable. The documentation does not spell those out, so they are worth knowing before you apply the settings to a Pi you depend on for remote access.

The blog post is the reference for the measurement, and the EEPROM settings here are the subset that the project recommends.

Dimming the screen is still an open issue

The power section ends with a problem the author has not solved, and the project is honest about it.

The argument is that an always-on display at full brightness all day is not that helpful, so there are two things a user can do: dim the screen after a period of time, or configure the screen blanking option in Pi OS. The text says the author is looking into the best way to dim the screen after a period of time, and links an issue for it.

That issue is titled to allow for the screen to dim after a certain amount of time, and it is the only part of the project that is an open question rather than a recipe. The section on the display blanking option points at a setting that exists in the operating system rather than at anything in this repository.

That is worth knowing before you build the whole project around a screen that will burn itself out. A display left at full brightness for a year is a display replaced in a year, and the project has a working answer for the power the Pi draws while shut down and no answer yet for the light the panel emits while the Pi is on.

If you need dimming now, the two paths are the screen blanking option in the operating system and a panel that handles it in hardware, and the linked issue is where the project intends to record what works.

Stopping the kiosk when you need the screen back

Every kiosk eventually has to be stopped, and the project covers the ways in order of how much access they require.

The first is the log. The service's output is read with the journal, and the documentation notes that adding the follow flag to that command tails the logs live.

journalctl -u kiosk

The second is the service itself, and it needs a shell on the machine. If you can log in over SSH in the background you can stop the unit directly.

sudo systemctl stop kiosk

The third is the physical one, and it is the case the project cares about most, because a kiosk on a wall has no keyboard attached. If you have the Pi in your hands and can plug in a keyboard, the combination of the control key and the function four key should quit the browser.

There is a remote version of the same thing, using Pi Connect to reach the machine without being at it, and then pressing the same key combination. On a Mac the documentation adds a note that the function key is combined with the others, so the shortcut is the function key, the control key, and function four.

And for anyone who wants to go further, the project points at using something like xdotool and wiring a physical button to emulate the key press, which turns the escape hatch into a dedicated one.

The order of these options is a good summary of the project's character. The supported path is the service, the recovery path is the keyboard, and the convenience path is a script. There is no administration interface, and that is deliberate for a configuration the author describes as simple rather than robust.

Editorial conclusion

pi-kiosk fits a Raspberry Pi owner who wants a wall panel, a dashboard, or a video page on a small screen without configuring a display manager or a browser extension. It does not fit a kiosk that has to survive a power cut unattended, because the configuration is explicitly not built to survive much or to be secure, and it does not fit a screen that has to dim itself, since that part is still an open issue. Verify first that your Pi OS installation includes the graphical environment, since the browser needs it, that the display is on the DSI port your rotation command names, and that the unit file is edited for your own user name before it is enabled, because the setup writes a placeholder into it.

Frequently asked questions

Official sources

1. geerlingguy/pi-kiosk on GitHub
2. Issues
3. License: GPL-3.0
4. README