[Update 2022]
Ubuntu Frame is the replacement for mir-kiosk, it all the same things and more and it is much easier to configure. The corresponding configuration notes for Frame are here:
https://github.com/MirServer/ubuntu-frame/blob/master/REFERENCE.md
Configuring mir-kiosk: a masterclass
Several posts have recently sparked discussions about the configuration of mir-kiosk based solutions. I decided to pull this together in a more organized post.
- What I propose to cover: all the configuration options for mir-kiosk.
- What I propose to omit: all the configuration options for snaps that rely on mir-kiosk.
Prerequisite
I’m going to assume you have a device (or VM) with mir-kiosk and, presumably, a client snap that interests you. For the sake of specificity I’ll use mir-kiosk-scummvm but you could use one of these snaps from the store:
- mir-kiosk-scummvm: A program which allows you to run certain classic graphical point-and-click adventure games
- wpe-webkit-mir-kiosk allows embedders to create simple and performant systems based on Web platform technologies
- xdmcp-client: An XDMCP client to be used with mir-kiosk
- wmx-kiosk-session: The superior wmx window manager in a busybox session for mir-kiosk
Or one you built yourself from one of these tutorials:
- Embedding IoT GUI with Ubuntu Frame — Developer Guide
- Make a Wayland-native Kiosk snap
- Make a X11-based Kiosk Snap
- Make a HTML5/Electron-based Kiosk Snap
I also assume you have a terminal session open to your device. (This is reasonable as you needed this to set the device up!)
snap install mir-kiosk
snap install mir-kiosk-scummvm
/snap/mir-kiosk-scummvm/current/bin/setup.sh
Depending upon the system you’re running on you may see some benign “errors” from this (e.g. error: snap “snapd” has no “wayland” interface slots
). This doesn’t matter as if you have mir-kiosk installed it should be connected:
$ snap connections mir-kiosk-scummvm
Interface Plug Slot Notes
alsa mir-kiosk-scummvm:alsa - -
opengl mir-kiosk-scummvm:opengl :opengl -
pulseaudio mir-kiosk-scummvm:pulseaudio pulseaudio:service -
wayland mir-kiosk-scummvm:wayland mir-kiosk:wayland -
If necessary, start mir-kiosk-scummvm
:
snap start mir-kiosk-scummvm
The basics
In your terminal type:
snap get mir-kiosk
You should see something like the following:
$ snap get mir-kiosk
Key Value
cursor software
daemon true
display-layout default
vt 4
Let’s summarise each of these:
Key | Comment |
---|---|
cursor | The way the cursor is displayed. Can be “auto”, “software” or “none” |
vt | 4 |
daemon | Whether to run as a “daemon” (as root on startup). Defaults to “true” on core and “false” on Classic |
display-layout | Explained below |
These can be set using the snap set <key>=<value>
command, for example:
$ snap set mir-kiosk vt=3
With mir-kiosk-scummvm I find the screen goes black and I need to restart the app:
$ snap start mir-kiosk-scummvm
Started.
If you try setting display-layout, you’ll not have much success (yet).
snap set mir-kiosk display-layout=inverted
But that only gets you:
$ snap set mir-kiosk display-layout=inverted
error: cannot perform the following tasks:
- Run configure hook of "mir-kiosk" snap (run hook "configure": ERROR: 'inverted' is not a layout in /var/snap/mir-kiosk/562/miral-kiosk.display)
The configuration files
There are two configuration files used by Mir:
$ ls /var/snap/mir-kiosk/current/
miral-kiosk.config miral-kiosk.display
Let us take them in turn:
miral-kiosk.config
This is the basic server configuration file and the basic options here are controlled from the snap set
command. Here’s what we have in it:
$ cat /var/snap/mir-kiosk/current/miral-kiosk.config
arw-file=
file=/run/mir_socket
console-provider=vt
env-hacks=MIR_MESA_KMS_DISABLE_MODESET_PROBE
display-layout=default
vt=0
cursor=software
Do not touch the first four lines! These are necessary configuration for the mir-kiosk to work. The next two you will recognise. You can set any of the standard Mir configuration options in this file. (I’ll provide a complete listing at the end of this post.)
miral-kiosk.display
This is the server configuration file containing display layouts. Here’s what we have in it:
$ cat /var/snap/mir-kiosk/current/miral-kiosk.display
layouts:
# keys here are layout labels (used for atomically switching between them)
# when enabling displays, surfaces should be matched in reverse recency order
default: # the default layout
cards:
# a list of cards (currently matched by card-id)
- card-id: 0
HDMI-A-1:
# This output supports the following modes: 1024x600@43.1
#
# Uncomment the following to enforce the selected configuration.
# Or amend as desired.
#
# state: enabled # {enabled, disabled}, defaults to enabled
# mode: 1024x600@43.1 # Defaults to preferred mode
# position: [0, 0] # Defaults to [0, 0]
# orientation: normal # {normal, left, right, inverted}, defaults to normal
# group: 0 # Outputs with the same non-zero value are treated as a single display
This is what it looks like on the board I’m using for testing, the file on your device will reflect the output(s) available there. For a simple example, edit the file…
sudo vi /var/snap/mir-kiosk/current/miral-kiosk.display
… and add the following:
inverted:
cards:
- card-id: 0
HDMI-A-1:
orientation: inverted
And, now we can select an “inverted” as the display layout:
snap set mir-kiosk display-layout=inverted && snap start mir-kiosk-scummvm
This time it works! Mir restarts and the display is inverted.
The display-config snap configuration option
It is also possible to configure the .display
configuration file using the snap set
command option. For example:
$ snap set mir-kiosk display-config="layouts:
> default:
> cards:
> - card-id: 0
> HDMI-A-1:
> orientation: inverted"
This is particularly useful when used to configure mir-kiosk from a gadget snap. The gadget.yaml
corresponding to the above is:
defaults:
rW4inp7UbJb1YBxWr6SVebxa3Yv7K1Vm:
display-config: |
layouts:
default:
cards:
- card-id: 0
HDMI-A-1:
orientation: inverted
(Thanks to @knitzsche for contributing that snippet.)
Good luck!
I hope this provides you with a good starting point for configuring your own kiosk!
If you really mess things up
If you really mess things up, you can just delete the file(s) and reset the default settings:
sudo rm /var/snap/mir-kiosk/current/*
snap set mir-kiosk display-layout=default vt=4
snap start mir-kiosk-scummvm
This gets you right back to the starting point.
miral-kiosk.config Reference
Many of the following will be irrelevant to use as a kiosk. They are included for completeness only.
The full list of configuration options recognised by miral-kiosk:
$ miral-kiosk --help
usage: miral-kiosk [options]
Command-line options (e.g. "--host-socket=/tmp/mir_socket").
Environment variables capitalise long form with prefix "MIR_SERVER_" and "_" in place of "-".
(E.g. "MIR_SERVER_HOST_SOCKET=/tmp/mir_socket")
Config file entries are long form (e.g. "host-socket=/tmp/mir_socket").
The config file (miral-kiosk.config) is located via the XDG Base Directory Specification.
($XDG_CONFIG_HOME or $HOME/.config followed by $XDG_CONFIG_DIRS)
user options:
--wayland-socket-name arg Overrides the default socket name used
for communicating with clients
--host-socket arg Host socket filename
-f [ --file ] arg (=/run/user/1000/mir_socket)
Socket filename [string:default=$XDG_RU
NTIME_DIR/mir_socket or
/tmp/mir_socket]
--no-file Do not provide a socket filename for
client connections
--arw-file Make socket filename globally rw
(equivalent to chmod a=rw)
-p [ --prompt-file ] Provide a "..._trusted" filename for
prompt helper connections
--platform-graphics-lib arg Library to use for platform graphics
support (default: autodetect)
--platform-input-lib arg Library to use for platform input
support (default: input-stub.so)
--platform-path arg (=/usr/lib/x86_64-linux-gnu/mir/server-platform)
Directory to look for platform
libraries (default: /usr/lib/x86_64-lin
ux-gnu/mir/server-platform)
-i [ --enable-input ] arg (=1) Enable input.
--compositor-report arg (=off) Compositor reporting [{log,lttng,off}]
--connector-report arg (=off) How to handle the Connector report.
[{log,lttng,off}]
--display-report arg (=off) How to handle the Display report.
[{log,lttng,off}]
--input-report arg (=off) How to handle to Input report.
[{log,lttng,off}]
--legacy-input-report arg (=off) How to handle the Legacy Input report.
[{log,off}]
--seat-report arg (=off) How to handle to Seat report.
[{log,off}]
--session-mediator-report arg (=off) How to handle the SessionMediator
report. [{log,lttng,off}]
--msg-processor-report arg (=off) How to handle the MessageProcessor
report. [{log,lttng,off}]
--scene-report arg (=off) How to handle the scene report.
[{log,lttng,off}]
--shared-library-prober-report arg (=log)
How to handle the SharedLibraryProber
report. [{log,lttng,off}]
--shell-report arg (=off) How to handle the Shell report.
[{log,off}]
--composite-delay arg (=0) Compositor frame delay in milliseconds
(how long to wait for new frames from
clients before compositing). Higher
values result in lower latency but risk
causing frame skipping. Default: A
negative value means decide
automatically.
--name arg When nested, the name Mir uses when
registering with the host.
--nested-passthrough arg (=1) When nested, attempt to pass a client's
graphics content directly to the host
to avoid a composition pass
--offscreen Render to offscreen buffers instead of
the real outputs.
--enable-touchspots Display visualization of touchspots
(e.g. for screencasting).
--cursor arg (=auto) Cursor (mouse pointer) to use
[{auto,null,software}]
--enable-key-repeat arg (=1) Enable server generated key repeat
--on-fatal-error-except On "fatal error" conditions [e.g.
drivers behaving in unexpected ways]
throw an exception (instead of a core
dump)
--debug Enable extra development debugging.
This is only interesting for people
doing Mir server or client development.
--console-provider arg (=auto) Console device handling
How Mir handles console-related tasks
(device handling, VT switching, etc)
Options:
logind: use logind
vt: use the Linux VT subsystem.
Requires root.
none: support no console-related tasks.
Useful for nested platforms which do
not need raw device access and which
don't have a VT concept
auto: detect the appropriate provider.
--vt arg (=0) [requires --console-provider=vt] VT to
run on or 0 to use current.
--bypass arg (=1) [platform-specific] utilize the bypass
optimization for fullscreen surfaces.
--x11-output arg (=1280x1024) [mir-on-X specific] WIDTHxHEIGHT of
"output" window.
--startup-apps arg Colon separated list of startup apps
--env-hacks arg Colon separated list of environment
variable settings
--display-layout arg (=default) Display configuration layout from
`miral-kiosk.display'
(Found in $XDG_CONFIG_HOME or
$HOME/.config, followed by
$XDG_CONFIG_DIRS)
--window-management-trace log trace message
--keymap arg (=gb) keymap <layout>[+<variant>[+<options>]]
, e,g, "gb" or "cz+qwerty" or
"de++compose:caps"
--kiosk-startup-apps-only arg (=0) Only allow applications to connect
during startup
-h [ --help ] this help text