Using Raspberry Pis (bookworm) as a web-based display kiosk

12 July, 2025 at 16:01 -0500

Using Raspberry Pis as a simple kiosk display is quite neat. There’s plenty of instructions, including one from Raspberry Pi themselves.

As such, I decided to use them for some displays used at a music festival for which I am an IT team member. Yes, I could use ready-made options (both free and paid) such as Anthias, PiSignage, or OpenSplash, but then I’d lose out on the "hacker" spirit which makes tech fun. However I’ve discovered that I needed a couple of extra things to get the displays to work properly.

Setting up the Pi

Once the Pi is initially running, I had to use raspi-config to switch from the X.org display server to the wayfire display server. Following a reboot, the ~/.config/wayfire.ini will now be present if it wasn’t already there.

I needed to add the [autostart] section.

[autostart]
autostart0 = false
kiosk = /usr/local/bin/start-kiosk
screensaver = false
dpms = false

The format for the entries in the autostart is to have a unique name as the key and the command to run as the value. Overwriting the commands simply requires redefining a key with the new value.

The first line autostart0, disables the lxde panel, which was showing up in the full-screen browser. The last two lines disable the screensaver and screen blanking. Finally, the kiosk line runs a script which, in our case, checks the date and determines which page to load.

Removing the cursor

To remove the cursor, there exists a set of plugins for Wayfire, wayfire-plugins-extra, which include a plugin to disable the cursor. Unfortunately, that plugin isn’t available in the 0.7.5 version, which is the one shipped by bookworm. Luckily, you can easily backport the plugin from 0.8.0 and compile it on the device itself. Note, make sure to install wayfire-dev as it’ll complain if it’s not installed.

sudo apt build-dep wayfire -y
sudo apt-get install wayfire-dev libglibmm-2.4-dev meson cmake -y

# download and backport the hide-cursor plugin

meson build --prefix=/usr --buildtype=release
ninja -C build && sudo ninja -C build install

Then, you’ll have to enable the plugin in the ~/.config/wayfire.ini by adding a [core] section:

[core]
plugins = autostart hide-cursor

Special stuff

For the special stuff, we wanted to have the kiosk automatically switch to a different URL on specific days. On initial testing, we saw it working perfectly: The script would grad the current date (with timezone), compare it to a list of days with special URLs, and if it found no match, it would use a default URL.

Unfortunately, once deloyed, the devices were never using the the special URLs.

After much debugging, I realized that the script would run before the time was synced, which meant that I had no idea what date the script would think "today" was.

Luckily, systemd has a unit that can be enabled, systemd-time-wait-sync.service that will delay the time-sync.target target until after systemd-timesyncd reports that the time has been synchronised from whichever sources are configured.

Once the unit is enabled, lightdm can be delayed by adding a Wants to it’s service unit that ensures that the display manager doesn’t start until the pi has acquired the time, which means the autostart script will always have the correct day.

[Unit]
Wants=time-sync.target