VoxIP Kiosk OS 1.0.0: Raspberry Pi kiosk with web management

Chromium kiosk without a desktop for the Raspberry Pi 3, a Flask web
interface on port 8080 (kiosk, system and network management), a
restricted root helper, network changes with automatic rollback, a
healthcheck timer, install/update/uninstall scripts and a pi-gen image
build.

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

docs/HARDWARE-TEST.md

@@ -0,0 +1,125 @@
+# Testprocedure op Raspberry Pi 3-hardware
+
+De geautomatiseerde tests (`make test`, `make test-bookworm`) dekken de
+configuratie, validatie, de webinterface, de helper (inclusief
+netwerk-rollback), de agent en de healthcheck. Wat alleen op echte hardware
+te controleren is, staat hieronder. Voer dit uit voor iedere nieuwe release
+en voor elk nieuw type scherm.
+
+**Benodigd:** Raspberry Pi 3 Model B of B+, officiële voeding (5,1 V/2,5 A),
+nieuwe microSD-kaart van 16 GB of groter, HDMI-monitor, ethernetkabel,
+een wifi-netwerk, een laptop op hetzelfde netwerk.
+
+Noteer per stap: ✅ / ❌ + opmerking, de imageversie en het schermtype.
+
+## 1. Flashen en eerste boot
+
+- [ ] Schrijf de `.img.xz` met Raspberry Pi Imager **zonder** OS-aanpassingen.
+- [ ] Eerste boot: de rootpartitie wordt vergroot (`df -h /` toont later
+      ongeveer de kaartgrootte). De Pi herstart zichzelf eenmaal.
+- [ ] Binnen 90 s na stroom aan verschijnt het setupscherm met de setupcode,
+      `http://kiosk.local:8080` en het IP-adres. Er is geen muiscursor en
+      er zijn geen dialoogvensters.
+- [ ] SSH is uit (`ssh voxipadmin@kiosk.local` wordt geweigerd), en er is
+      geen bruikbaar standaardwachtwoord.
+
+## 2. Initiële configuratie
+
+- [ ] `http://kiosk.local:8080` en `http://<ip>:8080` tonen de setuppagina.
+- [ ] Een verkeerde setupcode wordt geweigerd. Na 5 pogingen volgt een wachttijd.
+- [ ] Een zwak wachtwoord (`admin12345`) wordt geweigerd.
+- [ ] Met de juiste code en een sterk wachtwoord: dashboard. Het scherm
+      schakelt binnen 10 s naar de kiosk-URL.
+- [ ] De setupcode werkt daarna niet meer (`/setup` stuurt door).
+
+## 3. Kiosk
+
+- [ ] De pagina is fullscreen, zonder adresbalk, scrollbalk-pop-ups,
+      vertaalbalk of "Chromium is niet correct afgesloten".
+- [ ] Na 30 minuten is het scherm niet gedimd of zwart geworden.
+- [ ] **Pagina herladen** (dashboard): de pagina herlaadt binnen 2 s, zonder
+      zwart scherm (Chromium herstart niet).
+- [ ] **Chromium herstarten**: kort zwart scherm, binnen 15 s weer de pagina.
+- [ ] Een andere URL instellen (Kiosk → Instellingen): binnen 10 s getoond,
+      zonder herstart van Chromium (de teller *Herstarts* blijft gelijk).
+- [ ] Een `http://`-URL wordt geweigerd.
+- [ ] Verversinterval op *Elke minuut*: de pagina herlaadt ongeveer elke minuut
+      (zie Logboek → Kiosk-agent).
+- [ ] Screenshot op de Kiosk-pagina toont wat er op het scherm staat.
+- [ ] InfoFlow-URL met `?token=`: het token is overal gemaskeerd
+      (dashboard, `voxip-kiosk-ctl status`, `journalctl -u voxip-kiosk-agent`).
+
+## 4. Herstel
+
+- [ ] `sudo pkill -9 chromium`: binnen 15 s is de pagina terug. Het logboek
+      toont de herstart.
+- [ ] `sudo pkill -9 Xorg`: X en Chromium komen binnen 20 s terug.
+- [ ] Crashloop: `sudo voxip-kiosk-ctl set-url https://localhost:1/` en
+      daarna 7× `sudo pkill -9 chromium` binnen 2 minuten. De service komt
+      in de fouttoestand (start-limit). De healthcheck logt een fout en start
+      hem na ongeveer 5 minuten opnieuw. Er is geen eindeloze stille lus.
+      Zet de URL daarna terug.
+- [ ] Vastgelopen pagina: open via SSH-tunnel DevTools of zet een testpagina met
+      `while(true){}` in. Na ±15 s herlaadt de agent, na ±30 s herstart Chromium.
+- [ ] `sudo systemctl stop voxip-kiosk-agent`: de healthcheck start hem binnen 2 minuten.
+- [ ] De webinterface blijft werken terwijl Chromium gestopt is
+      (`sudo systemctl stop voxip-kiosk-browser`).
+
+## 5. Netwerk
+
+- [ ] Netwerkkabel eruit terwijl de pagina draait: de pagina **blijft
+      staan** (een InfoFlow-display toont zijn laatste inhoud). Het
+      dashboard toont *Offline*.
+- [ ] Kabel weer erin: het dashboard toont binnen 1 minuut *Online*.
+- [ ] Opstarten zonder netwerk: offlinepagina met klok. Kabel erin:
+      automatisch naar de kiosk-URL.
+- [ ] Wifi scannen toont netwerken. Wifi instellen (met kabel nog erin):
+      wlan0 krijgt een adres. Bevestigen werkt.
+- [ ] Statisch IP op eth0 in een ander adres van hetzelfde subnet:
+      beheer bereikbaar op het nieuwe adres, bevestigen daar.
+- [ ] **Rollback:** stel een statisch IP in een verkeerd subnet in en bevestig
+      niet. Na 3 minuten is het oude adres weer bereikbaar.
+- [ ] **Rollback na stroomuitval:** herhaal, trek binnen 3 minuten de stroom
+      eruit. Na het opstarten zijn de oude instellingen actief.
+- [ ] **Noodreset:** stel iets onbereikbaars in en bevestig het. Zet
+      `voxip-network-reset` op de bootpartitie en start: weer DHCP.
+
+## 6. Systeem
+
+- [ ] Rotatie 90° en 270° (met *direct toepassen*): beeld gedraaid, pagina
+      vult het scherm.
+- [ ] Resolutie 1280x720: het scherm schakelt om. Een niet-ondersteunde resolutie
+      valt terug op automatisch.
+- [ ] *Scherm altijd aan* uit, 1 minuut: na een minuut gaat het scherm uit
+      (DPMS). Zet het weer aan.
+- [ ] Hostname wijzigen naar `test-kiosk`: `http://test-kiosk.local:8080` werkt.
+- [ ] HTTPS aan: doorgestuurd naar `https://…:8080`. Na bevestiging van het
+      certificaat werkt inloggen.
+- [ ] **Veilig uitschakelen**: de groene LED stopt met knipperen. De Pi komt pas terug na stroom eruit/erin.
+- [ ] **Raspberry Pi herstarten**: na ±60 s weer kiosk + beheer.
+
+## 7. Betrouwbaarheid (24/7)
+
+- [ ] 10× stroom eruit tijdens normaal bedrijf (willekeurige momenten): steeds
+      zonder ingrijpen terug in de kiosk, zonder "herstellen"-melding.
+- [ ] 72 uur continu draaien met verversinterval 5 min. Daarna: geheugen
+      < 80% (dashboard), geen onderspanning, `journalctl -p err -b` zonder
+      terugkerende fouten, `voxip-kiosk-ctl status` alles *Actief*.
+- [ ] SD-kaartschrijfacties: `cat /proc/diskstats | grep mmcblk0` op t=0 en
+      na 1 uur stationair. Het verschil in geschreven sectoren (kolom 10) is
+      minder dan 50 MB per uur.
+- [ ] Hardware-watchdog actief: `systemctl show -p RuntimeWatchdogUSec` toont `15s`.
+
+## 8. Uitrol en updates
+
+- [ ] Nieuwe kaart met `voxip-config.json` (url, device_name, hostname,
+      rotation) en `voxip-authorized_keys` op de bootpartitie: bij de eerste
+      boot toegepast, hernoemd naar `.applied`, SSH alleen met sleutel.
+- [ ] Ongeldige `voxip-config.json` (http-URL): `.rejected` en
+      `voxip-config.error.txt` met de reden. De kiosk start met de standaardconfiguratie.
+- [ ] `sudo ./update.sh` vanuit een nieuwere checkout: versie in het dashboard
+      verhoogd, configuratie en wachtwoord ongewijzigd, back-up in `/var/backups`.
+- [ ] `sudo ./uninstall.sh --purge` op een testkaart: geen VoxIP-services of
+      -bestanden meer (`systemctl list-unit-files | grep voxip` is leeg).
+- [ ] Installatie op een bestaande Raspberry Pi OS Lite (Bookworm) met de
+      InfoFlow-kiosk erop: URL overgenomen, `display-kiosk.service` uitgeschakeld.