VoxIP Kiosk OS

Lichte, onderhoudbare kioskdistributie voor de Raspberry Pi 3 (Model B/B+) op basis van Raspberry Pi OS Lite 32-bit (Bookworm of Trixie). Na het opstarten toont Chromium fullscreen één HTTPS-pagina. Beheer gaat via de webinterface VoxIP Kiosk Manager op http://kiosk.local:8080.

• Geen desktopomgeving: alleen een minimale X-server plus Chromium.
• Herstelt zichzelf: browsercrashes, een vastgelopen pagina, netwerkuitval en stroomuitval.
• Geen standaardwachtwoorden: de eerste beheerder claimt het apparaat met een setupcode die op het scherm staat.
• Netwerkwijzigingen met automatische rollback.
• Geen klantspecifieke code: alles per klant staat in /etc/voxip-kiosk/config.json en kan bij uitrol via de bootpartitie worden meegegeven.

De architectuur en de veiligheidskeuzes staan in docs/ARCHITECTURE.md. De testprocedure op echte hardware staat in docs/HARDWARE-TEST.md.

Snel aan de slag

Optie A — kant-en-klare image

1. Bouw de image (zie hieronder) of gebruik een uitgebrachte *-voxip-kiosk-os-*.img.xz.
2. Schrijf hem met Raspberry Pi Imager (Eigen image gebruiken) of balenaEtcher naar een microSD-kaart van 16 GB of groter.
3. Optioneel, in Raspberry Pi Imager → OS-aanpassingen: wifi, gebruiker met wachtwoord en/of SSH-sleutel, tijdzone. Zonder aanpassingen heeft de image geen bruikbaar wachtwoord en staat SSH uit.
4. Optioneel: zet een voxip-config.json op de bootpartitie (zie Uitrol bij meerdere klanten).
5. Start de Pi. Bij de eerste boot wordt de rootpartitie automatisch vergroot tot de hele SD-kaart. Daarna verschijnt een setupscherm met de setupcode en het adres van de beheerinterface.
6. Open http://kiosk.local:8080 (of het getoonde IP-adres), voer de setupcode in en kies een uniek beheerderswachtwoord.

Optie B — installeren op een bestaande Raspberry Pi OS Lite

Vereist: Raspberry Pi OS Lite Bookworm of Trixie met NetworkManager (de standaard sinds Bookworm).

sudo apt-get install -y git
git clone <url-van-deze-repository> voxip-kiosk-os
cd voxip-kiosk-os
sudo ./install.sh --url "https://schermen-ijsselflat.voxip.nl" --name "IJsselflat" --hostname ijsselflat

Alle opties zijn optioneel. Het script installeert de benodigde pakketten, maakt de gebruikers kiosk en voxip aan, installeert de services en start de kiosk. Aan het eind toont het de setupcode.

Draaide hier eerder de InfoFlow-kiosk (raspberry-pi/install-kiosk.sh uit de InfoFlow-repository)? Dan neemt install.sh de display-URL (inclusief ?token=) automatisch over en schakelt display-kiosk.service uit.

Updaten

cd voxip-kiosk-os
sudo ./update.sh          # git pull --ff-only + back-up van /etc/voxip-kiosk + install.sh --upgrade

Een update overschrijft nooit bestaande configuratie of het beheerderswachtwoord. Back-ups staan in /var/backups/voxip-kiosk-*.tar.gz (de laatste vijf). Op een apparaat met de image staat de broncode in /usr/src/voxip-kiosk. Clone de repository voor updates naar een eigen map, of pak een release uit en draai daar sudo ./update.sh --no-pull.

Verwijderen

sudo ./uninstall.sh           # programma's en services weg, configuratie blijft
sudo ./uninstall.sh --purge   # ook configuratie, status, logs, netwerkprofielen en gebruikers

Image bouwen

Het image wordt gebouwd met pi-gen, de officiële bouwtool van Raspberry Pi OS. De extra stage image/stage-voxip voert hetzelfde install.sh uit als een handmatige installatie.

Vereist: een Linux-buildmachine (x86_64 of arm64) met Docker en git. Op x86_64 is ook binfmt/qemu nodig voor ARM-emulatie:

sudo apt-get install -y qemu-user-static binfmt-support   # alleen op x86_64
./image/build.sh                                           # bouwt in Docker
# of zonder Docker, op Debian/Ubuntu met de pi-gen-afhankelijkheden:
sudo ./image/build.sh --native

Resultaat: image/deploy/<datum>-voxip-kiosk-os-<versie>.img.xz plus een .sha256 en BUILD-INFO-<versie>.txt.

Instelbaar via omgevingsvariabelen:

Variabele	Standaard	Betekenis
PI_GEN_REF	2024-11-19-raspios-bookworm-armhf	pi-gen-tag (32-bit)
RELEASE	bookworm	bookworm of trixie (moet bij PI_GEN_REF passen)
VOXIP_DEFAULT_URL	https://schermen-ijsselflat.voxip.nl	standaard kiosk-URL
VOXIP_DEVICE_NAME	VoxIP Kiosk	standaard apparaatnaam
TARGET_HOSTNAME	kiosk	hostname (http://<hostname>.local:8080)
ALLOW_DIRTY	0	1 = bouw de werkmap in plaats van de laatste commit

Reproduceerbaarheid. pi-gen staat vast op een tag en de broncode gaat via git archive van één commit mee. Beide staan in BUILD-INFO (ook in de image: /usr/share/voxip-kiosk/BUILD-INFO). De Debian- en Raspberry Pi-pakketten komen uit de archieven zoals die op het moment van bouwen zijn. Er bestaat geen snapshot-archief voor Raspberry Pi OS, dus twee builds op verschillende dagen kunnen nieuwere pakketversies bevatten. Bewaar voor een uitrol daarom de gebouwde .img.xz zelf.

Beheer

Webinterface — http://<hostname>.local:8080

Pagina	Functies
Dashboard	Chromium-status, kiosk-URL, uptime, CPU, temperatuur, voeding (onderspanning), RAM, SD-kaart, IP-adressen, verbinding, versie. Grote knoppen voor Pagina herladen, Chromium herstarten en Raspberry Pi herstarten.
Kiosk	URL (alleen HTTPS), apparaatnaam, automatisch verversen, browserprofiel, herstart na crash, screenshot van het scherm, laatste meldingen.
Systeem	Herstarten, veilig uitschakelen, hostname, rotatie, resolutie, zoom, screensaver/DPMS, poort/HTTPS van de beheerinterface.
Netwerk	Status van ethernet en wifi, wifi scannen, wifi instellen, DHCP of statisch IP, DNS, wifi-land. Iedere wijziging moet binnen 3 minuten bevestigd worden, anders volgt een rollback.
Logboek	Logs per onderdeel (kiosk, Chromium, agent, healthcheck, beheer, netwerk, systeem).

Pagina herladen gebruikt het Chrome DevTools Protocol op localhost: de browser blijft draaien. Chromium herstarten herstart alleen de browser. Raspberry Pi herstarten herstart het hele systeem.

Commandoregel (via SSH)

sudo voxip-kiosk-ctl status              # overzicht
sudo voxip-kiosk-ctl setup-code          # setupcode voor de eerste configuratie
sudo voxip-kiosk-ctl reset-password      # wachtwoord vergeten: nieuwe setupcode
sudo voxip-kiosk-ctl set-url https://…   # URL wijzigen
sudo voxip-kiosk-ctl reload              # pagina herladen
sudo voxip-kiosk-ctl restart-browser     # Chromium herstarten
sudo voxip-kiosk-ctl health              # healthcheck-rapport
sudo voxip-kiosk-ctl maintenance on|off  # healthcheck tijdelijk niets laten herstellen
journalctl -u voxip-kiosk-browser -u voxip-kiosk-agent -f

Configuratie — /etc/voxip-kiosk/config.json

Sleutel	Standaard	Betekenis
device_name	VoxIP Kiosk	naam in beheer en op de offlinepagina
url	https://schermen-ijsselflat.voxip.nl	kiosk-URL, alleen HTTPS
refresh_interval	0	0 = uit, anders 30–86400 seconden
screen_always_on	true	geen screensaver/DPMS
screen_off_minutes	10	scherm uit na N minuten (als screen_always_on uit staat)
rotation	0	0, 90, 180, 270
resolution	auto	auto of bijv. 1920x1080 / 1280x720@60
zoom	1.0	0,25–4, schaalt de pagina (grote tv's)
browser_restart	true	Chromium automatisch herstarten na een crash
browser_profile	persistent	persistent = cookies en offline-cache blijven bewaard, ephemeral = alleen in RAM
admin_port	8080	poort van de beheerinterface
admin_https	false	HTTPS met zelfondertekend certificaat
admin_allow_public	false	ook toegang vanaf publieke IP-adressen (afgeraden)

Wijzigingen via de webinterface of voxip-kiosk-ctl worden atomair opgeslagen, met een .bak van de vorige versie. Een URL-wijziging gaat in zonder dat Chromium herstart. Scherminstellingen gelden na een herstart van Chromium (een vinkje in de webinterface doet dat direct).

Uitrol bij meerdere klanten

Eén image voor alle klanten. Per apparaat zet je na het flashen op de bootpartitie (bootfs, zichtbaar op Windows en macOS):

• voxip-config.json: instellingen voor deze kiosk, plus optioneel hostname en wifi_country. Een voorbeeld staat als voxip-config.example.json op de bootpartitie.
• voxip-authorized_keys: openbare SSH-sleutels. SSH gaat dan aan, alleen met sleutel-login.
• Wifi en een eigen gebruiker stel je in via Raspberry Pi Imager.

De bestanden worden bij het opstarten verwerkt en hernoemd naar *.applied, of naar *.rejected met de reden in voxip-config.error.txt.

InfoFlow-schermen

Voor een InfoFlow-display gebruik je als url de kiosk-URL van het scherm uit InfoFlow (Schermen → scherm → kiosk-URL, inclusief ?token=). Het token wordt in de webinterface, de CLI en de logs afgeschermd (?token=…ab12). De kiosk laat een lopende pagina staan als het netwerk wegvalt. InfoFlow toont dan zijn eigen laatst bekende inhoud, en automatisch verversen wordt overgeslagen zolang de server niet bereikbaar is.

Ontwikkelen en testen

python3 -m venv .venv && .venv/bin/pip install -r requirements-dev.txt
.venv/bin/python -m pytest          # unit- en webtests
make lint                           # shellcheck (indien geïnstalleerd)
make test-bookworm                  # dezelfde tests in Debian Bookworm met de apt-pakketten van de Pi (Docker)

Lokaal draaien van de webinterface (zonder Pi; systeemacties falen netjes):

make dev    # http://127.0.0.1:8080 met tijdelijke mappen in .dev/

Probleemoplossing

Symptoom	Oplossing
Zwart scherm na opstarten	sudo voxip-kiosk-ctl status. Kijk in de journal van voxip-kiosk-x/voxip-kiosk-browser. Staat de monitor aan vóór de Pi?
Beheerinterface onbereikbaar na netwerkwijziging	Wacht 3 minuten (automatische rollback) of zet voxip-network-reset op de bootpartitie en herstart.
Wachtwoord vergeten	sudo voxip-kiosk-ctl reset-password via SSH, of verwijder /etc/voxip-kiosk/admin.json met de SD-kaart in een Linux-pc.
kiosk.local werkt niet	Gebruik het IP-adres (staat op het setupscherm en in je router). Windows heeft soms Bonjour/mDNS nodig. Geef iedere kiosk een unieke hostname.
Onderspanning in het dashboard	Gebruik de officiële 5,1 V/2,5 A-voeding. Onderspanning veroorzaakt crashes en SD-kaartcorruptie.