Building a Perspective Kiosk on Seeed Reterminal-DM (or any RPI-4 based system)

Just thought I would chuck a little guide together to get a working Perspective Kiosk on simple Raspberry Pi 4 Hardware.

Main Features:

  • Webkit Browser Engine: supported by Ignition as part of Safari compatibility.

  • Full Kiosk Mode: No desktop OS on this system, no other apps, no way to exit.

  • Hardware Acceleration: Panel PC hardware supported by linux is able to be utilised.

  • On Screen Keyboard: Critical missing piece of 99% of similar attempts. Auto opens and closes with focus on text entry elements.

  • Auto-Boot: System Boots on power on, no login and ready to go in 25seconds.

  • Auto Network Refresh: The system will refresh the page automatically when a network change is detected.

  • No Menus: No interface items at all besides the rendered webpage.

  • Touchscreen Support: Any touchscreen that works in linux is usable.

I have built and tested this on the Seeed Studios ReTerminal-DM, which is a $700AUD 10.1" Raspberry Pi Compute Module 4 based panel computer.

This guide assumes you are able to work out simple tasks like setting an IP and editing a text file on linux.
Use this at own risk.

Installing Raspbian

Install a copy of the latest version of (6.1.21 or higher) Raspbian Lite OS, follow the manufacturer guide for your device, for me, I followed:

*If you have the ReTerminal-DM, don’t do the touchscreen orientation section.

** Critical steps here - Enable SSH, Set a username and password.

This should get you set up with a Pi that boots to a console login page with the username and password that you chose when uploading the image.

Setting Up the Kiosk

Log in to this console with SSH, this is now your base for all the commands on the unit.

Enter the following into the terminal:

$ sudo apt update

$ sudo apt install snapd

You will also need to reboot your device. This can be accomplished from the terminal (and from the desktop), but make sure you save any open documents first:

$ sudo reboot

After this, install the core snap in order to get the latest snapd.

$ sudo snap install core

core 16-2.45.2 from Canonical✓ installed

Now install Ubuntu Frame with the following command:

$ sudo snap install ubuntu-frame

On Raspbian, Ubuntu Frame does not start by default. To change this default run the following command:

$ sudo snap set ubuntu-frame daemon=true

Now install wpe-webkit-mir-kiosk:

$ sudo snap install wpe-webkit-mir-kiosk

Now we connect it to the display server:

$ sudo snap connect wpe-webkit-mir-kiosk:wayland

As per above, on Raspbian, wpe-webkit-mir-kiosk does not start by default. To change this default run the following command:

$ sudo snap set wpe-webkit-mir-kiosk daemon=true

Now we set the target url for your perspective session, which here is the demo ignition on IA web server.

$ sudo snap set wpe-webkit-mir-kiosk url=

Now start the service:

$ sudo snap start wpe-webkit-mir-kiosk

You should now see on screen the perspective session you linked to.

On Screen Keyboard

Next we configure the On Screen Keyboard:

$ sudo snap install ubuntu-frame-osk

Make sure it’s connected to the display server interface:

$ snap connect ubuntu-frame-osk:wayland

And make it a service:

$ sudo snap **set** ubuntu-frame-osk daemon=true

You can switch between light and dark mode with the theme option:

$ sudo snap set ubuntu-frame-osk theme=dark

$ sudo snap set ubuntu-frame-osk theme=light

Now we have a working system on the screen, and if you have a working touchscreen, it should be able to interact with the session as normal.

Cosmetic Fixes

On my system, the LCD was set up in portrait orientation, which is not the install direction for the unit, so to fix this we open up some settings.

$ sudo nano /boot/cmdline.txt

Use the arrow keys to navigate to the end of the line and add the following:


Then we save and exit the file (+W , Y , )

(1 = Rotate Clockwise 90 degrees, 2 = 180, 3 = 270)

$ sudo reboot

Now your Pi should boot and display the screen in the right orientation.

You may notice that the system will always boot to a browser error saying “dns resolution failed”, This is because the system boots up and starts the browser before the network interface is connected and online.

To fix this, we do a little hack fix (There is likely a nice way to do this, but this works if a little messy).

$sudo nano /lib/dhcpd/hooks/01-Test

Now we add at the bottom of the file the following:

if [ $reason = “BOUND”] || [ $reason = “STATIC”];
    snap set wpe-webkit-mir-kiosk url=

This effectively reloads the url every time the network either gets a new DHCP address or is configured with a Static IP, which happen every time you reconnect a network.

I have a bunch of other tweaks figured out, but this should get you started pretty well.


One note of warning though, the Raspberry Pi has very limited processing power, and you will need to build any pages you want to display fairly well and follow the optimisation tips in the forum to keep your loading times down to a reasonable time.

I can see a bunch of people on Maker Edition using this for simple projects, and that is probably the best use of limited hardware like this.


i follow this path, but on a full installation of ubuntu. everything seems to be working. Except the dragging of popup. Popup move for a few pixels and then just stop. This was tested on multiple hardware (Capacitive, resistive screen) various compute unit and we still get the same behavior. Dragging popup with a mouse works perfectly. Do you see such behavior at your side ?

I think this is something around the way the touchscreen is handling a click and drag touch event. There may be some modes in either Wayland or the mir-kiosk system that can work on it, they have a pretty active github issue tracker for both.

We went down this same path for a few weeks on our production kiosk HMIs (running Ubuntu Server 22.04) but found the wpe-webkit-mir-kiosk browser to be buggy. Especially, we found that the app would crash every time an operator tried trending - specifically when trying to use the drop-down menu to change the date span (minute, hour, day, etc.). Other drop-downs resulted in similar experiences.

However, I'm a fan of the ubuntu-frame & ubuntu-frame-osk !

We are currently trialing the firefox snap on ubuntu-frame in kiosk mode. While a bit more difficult to set up as a service running wayland, it has certainly improved operability!

A solution using ubuntu-frame & ubuntu-frame-osk together with perspective workstation / jxbrowser is high on the want-list.


You not the only one, I stopped my search due to the same bugs.

I was thinking of doing a comparison to the firefox and chromium waylnad snaps to see what they brought to the table, I definitely don't think that the mir-kiosk is the perfect solution, but it is easy for simple use.

Agreed. The frequent crashes of mir-kiosk made it a non-starter, even though the ease-of-installation/configuration/use was a huge benefit. Firefox has, so far, proven to be more stable, albeit far more complicated to configure. Recent Ignition versions include updates to Java, and recent Perspective Workstation versions include updates to JxBrowser, of which supports Wayland. When time allows...I intend to dabble...

A bash script to migrate from the above mir-kiosk snap to Firefox snap might resemble:

# Store URL used on mir-kiosk:
echo "INFO    | Storing kiosk URL..."
my_Url=$(snap get wpe-webkit-mir-kiosk url)
echo "INFO    | my_Url=${my_Url}"

# Uninstall Mir-Kiosk:
echo "INFO    | Removing webkit-mir-kiosk snap..."
snap remove --purge wpe-webkit-mir-kiosk

# Install Firefox Snap:
echo "INFO    | Installing Firefox snap..."
snap install firefox
snap connect firefox:wayland

# Create Service to run Firefox in Ubuntu-Frame:
echo "INFO    | Creating Service to run Firefox at startup..."
cat > /etc/systemd/system/firefox-frame.service << EOF
Description=Firefox Wayland Kiosk
After=snap.ubuntu-frame.daemon.service snap.ubuntu-frame-osk.daemon.service ignition.service
Requires=snap.ubuntu-frame.daemon.service ignition.service

ExecStartPre=/snap/bin/firefox --CreateProfile "default"
ExecStartPre=-/usr/bin/sleep 10
ExecStart=/snap/bin/firefox -P default --kiosk --private-window "${my_Url}"


echo "INFO    | Reload daemon, start kiosk, enable service at startup..."
systemctl daemon-reload
systemctl start firefox-frame
systemctl enable firefox-frame

Some notes on the above method:

Interestingly I tried this.
Firefox does seem faster and more efficient on slow hardware.
OSK works just fine natively.

Oddly the Systemctl startup doesnt work on mine at boot, shows it starting then immediately stopping the service.
Manually running the systemctl start works just fine.

I experienced a similar issue when the default profile did not exist. I added the line to create a profile as part of the service start up which fixed my issue. Perhaps yours is related?
Try executing the command to --CreateProfile manually, any errors?

I did get this working just fine on another HMI, my only change is I am working on a reliable way to verify Edge is actually starting before launching the browser.
Turns out Edge reports 200OK as a HTTP status well before the "Ignition is starting" splash screen shows.