From c862e5dd78d9af64b4d9ad2ab822560727636774 Mon Sep 17 00:00:00 2001 From: Johannes Rest Date: Wed, 23 Sep 2026 15:50:55 +0200 Subject: [PATCH] Document successful HDMI hardware validation for 0.2.1 --- CHANGELOG.md | 7 +++++ README.md | 14 +++++++--- docs/code-review.md | 22 +++++++++++++++- docs/hardware-validation.md | 51 +++++++++++++++++++++++++++++++++++++ docs/troubleshooting.md | 9 +++++++ 5 files changed, 99 insertions(+), 4 deletions(-) create mode 100644 docs/hardware-validation.md diff --git a/CHANGELOG.md b/CHANGELOG.md index ef9390a..d02913e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,13 @@ All notable changes to this project will be documented here. - Add regression coverage for Lua, older Hyprland without `status`, and refresh failures before and after the VT switch. Document the Lua startup hook. +### Validated + +- 30 behavioral tests, Bash syntax checks and ShellCheck 0.11.0 passed. +- Full manual recovery completed on the desktop; the operator then confirmed + physical HDMI input switching and recovery on Hyprland 0.56.2 with Lua and + an iiyama PL3288UH on `HDMI-A-2`. See [validation details](docs/hardware-validation.md). + ## 0.2.0 - 2026-09-23 ### Fixed diff --git a/README.md b/README.md index 44f77ce..783beb6 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,10 @@ DPMS toggle or polling timer. **Version 0.2.1.** The initial implementation and the review fixes are separate commits. See [the code review](docs/code-review.md) and [changelog](CHANGELOG.md). +Physical HDMI input switching and recovery were confirmed working on +2026-09-23 with Hyprland 0.56.2 (Lua configuration) and an iiyama PL3288UH on +`HDMI-A-2`. See [validation results and remaining checks](docs/hardware-validation.md). + ## Requirements A systemd-based Linux desktop with Hyprland, a local `seat0` Wayland session, @@ -24,8 +28,10 @@ recovery. Hyprland must still expose the configured monitor over its IPC socket. ## Install from the package -Download `hyprland-hdmi-revive-0.2.1.tar.gz` and `SHA256SUMS` from the -[Gitea release](https://gitea.jr-it-services.de/johannes/hyprland-hdmi-revive/releases). +Use `hyprland-hdmi-revive-0.2.1.tar.gz` and `SHA256SUMS` from a published +[Gitea release](https://gitea.jr-it-services.de/johannes/hyprland-hdmi-revive/releases) +or [build the bundle from source](#build-and-validate). A Git push alone does not +publish installer bundles. Run as your desktop user, **without sudo**: ```bash @@ -181,7 +187,9 @@ It creates a `.tar.gz` installer bundle, source ZIP, Base64 ZIP and `SHA256SUMS` be decoded on Windows with `certutil -decode `. Tests mock loginctl, Hyprland IPC, udev, sudo and systemd. They never switch the -real display. A hardware input-switch test after installation remains necessary. +real display. Version 0.2.1 passed 30 behavioral tests and a physical input-switch +test on the [documented setup](docs/hardware-validation.md). Test input switching +after installation on other hardware as well. CI runs the shell checks and behavioral tests on a configured Gitea Actions runner. See [architecture](docs/architecture.md), [troubleshooting](docs/troubleshooting.md) diff --git a/docs/code-review.md b/docs/code-review.md index e7df607..2f0f32b 100644 --- a/docs/code-review.md +++ b/docs/code-review.md @@ -41,4 +41,24 @@ kann einen echten schnellen Rückwechsel unterdrücken. Das bleibt eine bewusste Einschränkung dieses hardwareabhängigen Workarounds und ist in README beschrieben. Ein realer Test von HDMI-Eingangswechsel, Ab-/Anmeldung und Boot-Verhalten wurde -in diesem Review nicht ausgeführt. Er bleibt nach Installation erforderlich. +im ursprünglichen Review für 0.2.0 nicht ausgeführt. Der anschließende Praxistest +für 0.2.1 ist im folgenden Nachtrag dokumentiert. + +## Nachtrag: Lua-Korrektur und Praxistest für 0.2.1 + +Die Prüfung am Desktop zeigte, dass Hyprland 0.56.2 mit Lua-Konfiguration die +alten `dispatch dpms on`-/`dispatch focusmonitor`-Befehle ablehnt. Version 0.2.0 +brach dadurch vor dem VT-Wechsel ab. Die bisherigen Mocks hatten beliebige +Dispatch-Aufrufe akzeptiert und diesen Fehler nicht erkannt. + +Version 0.2.1 erkennt den aktiven Konfigurationsanbieter über `hyprctl -j status` +und verwendet die passenden Lua- oder hyprlang-Befehle. Die Mocks prüfen nun die +Befehlssyntax; fehlgeschlagene Refresh-Aufrufe protokollieren Operation, +Exitstatus und Fehlerantwort. Alle 30 Verhaltenstests sowie Bash-Syntaxprüfung +und ShellCheck 0.11.0 waren erfolgreich. + +Der vollständige manuelle Recovery-Lauf am Desktop kehrte auf die grafische VT1 +zurück und meldete `Recovery completed for HDMI-A-2`. Anschließend bestätigte +der Betreiber am 23.09.2026 den erfolgreichen physischen HDMI-Eingangswechsel. +Testumgebung und noch nicht separat bestätigte Prüfungen sind unter +[Hardware validation](hardware-validation.md) festgehalten. diff --git a/docs/hardware-validation.md b/docs/hardware-validation.md new file mode 100644 index 0000000..1bb6318 --- /dev/null +++ b/docs/hardware-validation.md @@ -0,0 +1,51 @@ +# Hardware validation + +## Confirmed on 2026-09-23 + +Version 0.2.1 was installed and the systemd user watcher restarted on the +following setup: + +| Component | Tested configuration | +| --- | --- | +| Desktop | Arch Linux, Hyprland 0.56.2 | +| Configuration provider | Lua (`hyprctl -j status`) | +| Session | Local Wayland session on seat0, graphical VT1 | +| Display | iiyama PL3288UH, 3840 × 2160 at 60 Hz | +| Output | `HDMI-A-2` | +| Timing | 5 s HDMI settle, 1 s temporary VT, 2 s return settle, 30 s cooldown | + +The original failure was reproduced: legacy DPMS/focus commands returned Lua +syntax errors and stopped recovery before the VT switch. Both corrected Lua +commands returned `ok` on the running compositor. + +After installation, a complete manual recovery returned to graphical VT1 and +reported: + +```text +revive-monitor-fix: Recovery started for HDMI-A-2 on VT 1 +revive-monitor-fix: Using lua dispatch syntax +revive-monitor-fix: VT refresh: 2 -> 1 +revive-monitor-fix: Recovery completed for HDMI-A-2 +``` + +The watcher remained active. The operator then tested physical HDMI input +switching and confirmed that recovery worked successfully. + +## Automated validation + +- All 30 behavioral tests passed, including Lua and legacy dispatch syntax, + refresh failures, session guards, VT return handling and installer behavior. +- Bash syntax checks and ShellCheck 0.11.0 passed. +- Installer archive and ZIP contents matched; ZIP integrity, Base64 round-trip + and release checksums were verified. + +## Scope and remaining checks + +This confirms the normal HDMI input-switch path on the setup above. It does +not establish compatibility with every monitor or GPU. + +The operator had reported that the earlier unwanted tty switching was gone. +A dedicated cold-boot/pre-login check and logout/login cycle after the 0.2.1 +update have not been separately confirmed. Rapid away/back switching inside +the cooldown also remains a separate test; such events can be suppressed by +design. See [the hardware acceptance procedure](troubleshooting.md#hardware-acceptance). diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index e5c4dbf..f912cf3 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -100,6 +100,15 @@ hook manually as documented in README. ## Hardware acceptance +The operator confirmed successful physical HDMI input switching and recovery +with version 0.2.1 on 2026-09-23. The tested setup and the scope of that result +are recorded in [hardware validation](hardware-validation.md). + After installation, check a normal input change, a rapid away/back change and a logout/login cycle. Before Hyprland login there must be no chvt invocation from this service. Automated tests use mocks and do not replace this hardware check. + +For a first normal input-switch test with the default timing, stay on the other +input for about 40 seconds before returning. This allows the initial attempt +and its 30-second cooldown to finish. Then test rapid switching separately; +returns inside the cooldown can still be suppressed.