# pi_kiosk

Turns a Pi with a monitor attached into a full-screen Firefox display: an autologin
console user runs `startx`, whose `.xinitrc` starts Openbox and then Firefox pointed at
`pi_kiosk_url`, relaunching it if it ever exits. If X itself crashes, `.bash_profile`
restarts it.

Vars:

- `pi_kiosk_user` (default `kiosk`) - the account that autologs into tty1.
- `pi_kiosk_url` (default `http://localhost:8080`) - what Firefox shows.
- `pi_kiosk_mode` (default `kiosk`) - `kiosk` or `debug`, see below.

Meant to run alongside `pi_musicmouse` on the same host when it's serving the page
locally (the default `pi_kiosk_url`), gated in `mediapis.yml` by `mediapi_has_monitor`.

## Why there is a window manager

This role used to run no WM at all, on the theory that Firefox is the only X client and
`--kiosk` makes it full-screen by itself. It doesn't. `--kiosk` *asks* to be
full-screen, over EWMH, and with no window manager running there is nobody to answer:
Firefox falls back to its default window size in the top-left corner. On the 1920x1080
monitor on musicdolphin that came out as a 1280x972 window with black bands down the
right edge and along the bottom - looking for all the world like an overscan problem,
which it is not. Openbox answers the request and otherwise stays out of the way.

## Debug mode

`pi_kiosk_mode: debug` turns the device's own screen into something you can work on:

- Firefox runs as an ordinary window with its chrome, so the URL bar and devtools are
  reachable, and it is **not** relaunched when you close it.
- The pointer is visible (no `-nocursor`, no `unclutter`).
- Openbox is the session leader. Right-click the desktop for a menu with a terminal,
  both ways of opening the page again, and "End this X session", which drops back to
  the autologin loop and starts a fresh one.
- `xterm`, `x11-utils` and `mesa-utils` get installed, so `xwininfo`, `xprop`,
  `glxinfo` and `glxgears` are on the device. (The menu's Terminal entry runs
  `x-terminal-emulator`, which on the Pi OS image is `zutty`, not the xterm we
  install - both work; xterm is the fallback if the alternatives link ever points
  somewhere that doesn't.)

Switch a host over in `host_vars`, or for one run:

```sh
just run mediapis.yml musicdolphin -e pi_kiosk_mode=debug
just run mediapis.yml musicdolphin -e pi_kiosk_mode=kiosk
```

Either way the session restarts itself: the templates notify the getty handler, and
restarting `getty@tty1` takes X down with it because Xorg lives in that unit's cgroup.
Going back to `kiosk` does not uninstall the debug packages; they are small and inert.

niri was considered instead of Openbox, but isn't packaged for Debian Bookworm yet (no
official apt package, only third-party `.deb`s or a from-source Rust build) - revisit
once it is.