From ea00e045f995840402c7ebc38cdd0cf7cd6bef0f Mon Sep 17 00:00:00 2001
From: Martin Bauer <martin@bauer.tech>
Date: Sat, 3 Oct 2026 16:13:29 +0200
Subject: [PATCH] Switch musicdolphin's screen from the IR remote's power key

pi_kiosk installs kiosk-screen on|off|toggle|status, which switches the monitor via
DPMS on the kiosk's X display (the Dell P2419H has no HDMI-CEC). Turning it back on
also turns DPMS off again, as .xinitrc does, so the screen never blanks by itself.

musicdolphin's backend config runs `kiosk-screen toggle` for the power key (the new
screen: section, MusicMouse 2d0caeb). config.yml is install-once, so the running host
is changed by hand the same way.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 roles/pi_kiosk/README.md                      |  9 ++++
 roles/pi_kiosk/tasks/main.yml                 |  7 +++
 roles/pi_kiosk/templates/kiosk-screen.j2      | 44 +++++++++++++++++++
 .../files/config-musicdolphin.yml             |  5 +++
 4 files changed, 65 insertions(+)
 create mode 100644 roles/pi_kiosk/templates/kiosk-screen.j2

diff --git a/roles/pi_kiosk/README.md b/roles/pi_kiosk/README.md
index 532671a..60d7b4c 100644
--- a/roles/pi_kiosk/README.md
+++ b/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:
diff --git a/roles/pi_kiosk/tasks/main.yml b/roles/pi_kiosk/tasks/main.yml
index 53ffb11..5f4e0fb 100644
--- a/roles/pi_kiosk/tasks/main.yml
+++ b/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' }}"
diff --git a/roles/pi_kiosk/templates/kiosk-screen.j2 b/roles/pi_kiosk/templates/kiosk-screen.j2
new file mode 100644
index 0000000..49694f8
--- /dev/null
+++ b/roles/pi_kiosk/templates/kiosk-screen.j2
@@ -0,0 +1,44 @@
+#!/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.
+
+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
+}
+
+screen_on() {
+    xset dpms force on
+    xset -dpms
+}
+
+screen_off() {
+    xset +dpms
+    xset dpms force off
+}
+
+case "$1" in
+    on) screen_on ;;
+    off) screen_off ;;
+    toggle) if [ "$(status)" = off ]; then screen_on; else screen_off; fi ;;
+    status) ;;
+    *)
+        echo "usage: $0 on|off|toggle|status" >&2
+        exit 2
+        ;;
+esac
+status
diff --git a/roles/pi_musicmouse/files/config-musicdolphin.yml b/roles/pi_musicmouse/files/config-musicdolphin.yml
index 2775e1f..994db7e 100644
--- a/roles/pi_musicmouse/files/config-musicdolphin.yml
+++ b/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