EARS Kiosk Mode

Runs the EARS application fullscreen on tty3 at boot, with no desktop environment around it. The normal Xubuntu desktop remains available on tty7 for development and troubleshooting.

Status: semi-permanent. Nothing here replaces the Xubuntu desktop. lightdm still runs, the default systemd target is unchanged, and GRUB is untouched. Removing two files returns the machine to stock.

Quick reference

Layout

~/kiosk/
├── kiosk-start.sh        launches the X server on the current VT
├── kiosk-session.sh      the session: hardware setup, WM, app loop
├── display-setup.sh      symlink to the rotation/touch script
├── enabled               presence of this file enables boot autostart
├── README.md             this file
└── logs/
    ├── current.log       symlink to the newest session log
    ├── session-*.log     one per session, 20 kept
    └── startx.log        X server output (appended, never rotated)

Application: /home/ears/Desktop/Kazi/v3/linux/program.exe

How it boots

power on
  → GRUB → systemd → graphical.target
      ├── lightdm on vt7          (normal Xubuntu, untouched)
      └── getty@tty3 autologin as `ears`
            → ~/.bash_profile sees tty3 + ~/kiosk/enabled
              → exec kiosk-start.sh
                → startx on vt3
                  → kiosk-session.sh
                    → display-setup.sh, matchbox, unclutter
                    → loop: mono program.exe

kiosk-start.sh calls fgconsole to find the VT it was launched from, so it works whether started at boot on tty3 or by hand from any console.

Exit codes

Dependencies

sudo apt install --no-install-recommends \
     xinit matchbox-window-manager unclutter xterm x11-xserver-utils

Plus mono-complete for the application itself.

Installation from scratch

1. Scripts

Place kiosk-start.sh and kiosk-session.sh in ~/kiosk/, then:

chmod +x ~/kiosk/kiosk-start.sh ~/kiosk/kiosk-session.sh
mkdir -p ~/kiosk/logs

Confirm the app path at the top of kiosk-session.sh:

APP_DIR="/home/ears/Desktop/Kazi/v3/linux"
APP_CMD="mono program.exe"

No $ before the path, no trailing slash.

2. Display and touch

The rotation script is shared with the Xubuntu session (~/.config/autostart/Rotate Display.desktop). Symlink it:

ln -s /path/to/rotate-display.sh ~/kiosk/display-setup.sh

It handles: 90° right rotation, the matching touch coordinate matrix for SIS0457:00 0457:11ED, and disabling blanking/DPMS.

3. Autologin on tty3

sudo systemctl edit getty@tty3

[Service]
ExecStart=
ExecStart=-/sbin/agetty --autologin ears --noclear %I $TERM

sudo systemctl enable getty@tty3.service

4. Boot hook

Append to ~/.bash_profile (or ~/.profile if that's the one bash reads):

# --- kiosk autostart on tty3 only ---
if [[ -z $DISPLAY && $(tty) == /dev/tty3 && -f $HOME/kiosk/enabled ]]; then
    sleep 3                      # let lightdm claim vt7 first
    exec "$HOME/kiosk/kiosk-start.sh"
fi

5. Enable and reboot

touch ~/kiosk/enabled
sudo reboot

Troubleshooting

Always start here:

tail -60 ~/kiosk/logs/current.log     # app + session errors
tail -40 ~/kiosk/logs/startx.log      # X server failed to start
grep -E '\(EE\)' ~/.local/share/xorg/Xorg.1.log

xf86EnableIO: failed to enable I/O ports in the Xorg log is normal and can be ignored — rootless X doesn't need legacy port access.

Getting a shell inside the kiosk

Add temporarily to kiosk-session.sh, before the while true loop:

xterm -fa Monospace -fs 14 -geometry 100x30 &

Audio

The kiosk session does not start an audio server; on the desktop that's done by Xfce's autostart. Check from inside the kiosk:

pactl info                    # "Connection refused" = no server
aplay /usr/share/sounds/alsa/Front_Center.wav

If a server is needed, add to kiosk-session.sh before matchbox:

if command -v pipewire >/dev/null && ! pactl info &>/dev/null; then
    pipewire & pipewire-pulse & wireplumber &
    sleep 2
elif command -v pulseaudio >/dev/null && ! pactl info &>/dev/null; then
    pulseaudio --start
    sleep 2
fi

Test with the Xfce session logged out, not merely switched away. Both sessions run as ears, so an audio server started by the desktop will serve the kiosk too — giving a false pass that breaks later when lightdm is removed.

Updating the application

Replace files in /home/ears/Desktop/Kazi/v3/linux/, then from a shell:

pkill -f program.exe

The session loop treats this as a crash and relaunches within 2 seconds with the new build. No reboot needed.

Removal

Temporary (next boot only):

rm ~/kiosk/enabled

Complete:

sudo systemctl disable getty@tty3.service
sudo rm -rf /etc/systemd/system/getty@tty3.service.d/
# remove the kiosk block from ~/.bash_profile
rm -rf ~/kiosk

Nothing else was modified. lightdm, the default target, GRUB, and ~/.config/xfce4/ are all untouched.

Known limitations

• Both lightdm and the kiosk X server run simultaneously — roughly 200MB of RAM that will be freed when lightdm is eventually dropped.
• No lockdown yet: VT switching, GRUB editing, and USB boot are all open.
• No in-app power control; shutdown is done from the desktop or a shell.
• startx.log grows without bound; truncate occasionally.

Next steps toward a permanent kiosk

In this order, testing each before moving on:

1. systemctl set-default multi-user.target, disable lightdm
2. Move autologin from tty3 to tty1
3. In-app power menu (sleep/shutdown/restart) with a polkit rule
4. Developer unlock: PIN pad, exit 42 → Xfce session
5. Lockdown: GRUB password, DontVTSwitch, mask tty4–6, BIOS password
6. Move the app out of Desktop/ to /opt/ears/

Keep a transcript (script -a ~/kiosk/setup-transcript.txt) through each stage — it becomes the provisioning script for the remaining tablets.