kiosk-screen: toggle by DPMS state, and print the state it set

X wakes the monitor on any key press, so by the time the Del key reaches the backend
the monitor is already on and a toggle going by the monitor would switch it straight
back off. Only `off` ever enables DPMS, so toggle goes by that instead. on/off now
print the state they set, which the backend uses for its blubb's direction.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

host_vars/musicdolphin.yml

@@ -28,9 +28,6 @@ mediapi_install_kidsmusic: true
 # The native Slint front-end is not deployed here; the browser kiosk is the front-end.
 mediapi_install_slint_frontend: false
 mediapi_has_monitor: true
-# Temporarily a debuggable desktop rather than a locked-down kiosk: Openbox root menu,
-# visible pointer, Firefox in a normal window. Set back to "kiosk" when done.
-pi_kiosk_mode: debug
 # ?pi=1 is the front-end's Raspberry Pi profile (web/src/lib/lowPower.ts): the ambient
 # canvas at a quarter of the pixels and 30fps, the progress bar re-rendering ten times
 # a second instead of sixty, and no backdrop blur. Drop the parameter in the address

roles/pi_kiosk/README.md

@@ -15,6 +15,15 @@ Vars:
 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`.
 
+## Switching the screen off
+
+`/usr/local/bin/kiosk-screen on|off|toggle|status` switches the monitor through DPMS:
+X stops the HDMI signal and the monitor goes into standby, while the browser and
+whatever is playing carry on. It is there for the MusicMouse backend, whose `screen:`
+config section runs `kiosk-screen toggle` on the IR remote's power key, and works the
+same as root over ssh. HDMI-CEC would switch a TV off properly, but musicdolphin's Dell
+P2419H does not speak it, and every monitor understands losing its signal.
+
 ## Why Chromium
 
 Firefox was the original choice and lost on measurement. Same page, same machine, idle:

roles/pi_kiosk/tasks/main.yml

@@ -132,6 +132,13 @@
     mode: "0755"
   notify: Reload systemd and restart getty
 
+- name: Install kiosk-screen (switches the monitor on and off)
+  # Run by the MusicMouse backend for the IR remote's power key; see the template.
+  ansible.builtin.template:
+    src: kiosk-screen.j2
+    dest: /usr/local/bin/kiosk-screen
+    mode: "0755"
+
 - name: Ensure the browser policy directory exists
   ansible.builtin.file:
     path: "{{ '/etc/chromium/policies/managed' if pi_kiosk_browser == 'chromium' else '/etc/firefox-esr' }}"

roles/pi_kiosk/templates/kiosk-screen.j2

@@ -0,0 +1,57 @@
+#!/bin/sh
+# Managed by ansible (pi_kiosk role).
+#
+# kiosk-screen on|off|toggle|status - switch the kiosk's monitor on or off.
+#
+# "Off" is DPMS: X stops the HDMI signal and the monitor drops into standby. The
+# session, the browser and everything playing carry on. The MusicMouse backend runs
+# `kiosk-screen toggle` for the IR remote's power key (its config's screen: section);
+# it works over ssh as root too.
+#
+# .xinitrc turns DPMS off so the screen never blanks by itself. Forcing it off has to
+# turn DPMS on, so `on` turns it back off again - otherwise the screen would blank on
+# its own ten minutes after every switch-on.
+#
+# `toggle` therefore goes by whether DPMS is enabled, not by whether the monitor is lit:
+# only `off` ever enables it. That matters for the keyboard. X wakes the monitor on any
+# key press, so by the time the browser hands the Del key to the backend the monitor is
+# already on again - going by that, toggle would switch it straight back off. Going by
+# DPMS, the press reads as "switch on", which is what it was. (Woken by any other key,
+# the screen stays on until the next toggle, which then makes the "on" stick.)
+
+set -e
+export DISPLAY=:0
+export XAUTHORITY=/home/{{ pi_kiosk_user }}/.Xauthority
+
+# With DPMS disabled `xset q` prints no monitor line at all, and the monitor is on.
+status() {
+    if xset q | grep -q "Monitor is Off"; then echo off; else echo on; fi
+}
+
+switched_off() {
+    xset q | grep -q "DPMS is Enabled"
+}
+
+# Each prints the state it set: the backend picks the blubb's direction from that word.
+screen_on() {
+    xset dpms force on
+    xset -dpms
+    echo on
+}
+
+screen_off() {
+    xset +dpms
+    xset dpms force off
+    echo off
+}
+
+case "$1" in
+    on) screen_on ;;
+    off) screen_off ;;
+    toggle) if switched_off; then screen_on; else screen_off; fi ;;
+    status) status ;;
+    *)
+        echo "usage: $0 on|off|toggle|status" >&2
+        exit 2
+        ;;
+esac

roles/pi_musicmouse/files/config-musicdolphin.yml

@@ -78,6 +78,11 @@ general:
     port: 8765
     remote_name: "hauppauge"
 
+  # The remote's power key switches the monitor off and on. kiosk-screen is pi_kiosk's:
+  # it asks X whether the monitor is on and flips it, so nothing here tracks the state.
+  screen:
+    toggle_command: /usr/local/bin/kiosk-screen toggle
+
   # Backlight of the prev/next buttons while a figure is playing, 0..1. Inert here
   # (no mouse), kept so the file reads the same as the other hosts'.
   button_leds_brightness: 0.5