Kiosk-Betriebshandbuch (Android Device Owner)

Für Bediener bestimmte Abläufe zur Bereitstellung, Wiederherstellung, Aktualisierung, WLAN-Einrichtung und Außerbetriebnahme von osd-Kiosk-Tablets. Jedes Teammitglied kann diese ohne den ursprünglichen Entwickler befolgen.

osd läuft als Android-Device-Owner-Kiosk: Das Tablet ist in osd eingesperrt (lock-task), osd ist der Home-Launcher, und Neustarts kehren zu osd zurück. Die einzige Möglichkeit, Device Owner zu entfernen, ist ein Werksreset — eine „Deinstallation" gibt es nicht.

Zielgeräte: Redmi Pad 2 Pro (HyperOS, primär), Lenovo Tab M11 / Samsung Tab A9+ (Ausweichgeräte).

PIN-Referenz (wissen, welche PIN was tut)

PIN Zweck Festgelegt wo Voreinstellung

Shift-PIN

Eingangstür → verbindet das Tablet mit einem bestimmten Dienst

Admin-Panel, pro Einsatz (Story 9.14), auf das Tablet synchronisiert

keine — Admin wählt 6 Ziffern

Firmen-PIN (Firma)

"Neuen Dienst anlegen" offline, wenn kein Dienst synchronisiert ist

Vordertür oder Einstellungen → Firmen-PIN (Story 9.10)

keine — die erste Eingabe legt sie fest (bei erster Verwendung gesetzt), wie die Wartungs-PIN

Wartungs-/Admin-PIN

Wartungs-Notausgang + geschützte Einstellungen (Einschreibung, Geräteeinstellungen, Sperrbildschirmtext, Neustart, Aktualisierungsrichtlinie)

Bei erster Verwendung im Wartungs-Overlay gesetzt

keine — die erste Eingabe legt sie fest

Der Wartungs-Notausgang: 10 schnelle Tipps auf die Versionsbezeichnung in den Einstellungen (nur auf einem bereitgestellten Device-Owner-Tablet) öffnen den Wartungs-PIN-Dialog → einen kleinen Launcher (Einstellungen / Dateien / Kamera / Notizen / Karten) — die einzige Möglichkeit, aus dem gesperrten Kiosk heraus die Android-Einstellungen oder Dateien zu erreichen. Er sperrt nach ~5 Min, beim Verlassen oder bei einem Neustart automatisch wieder. (Dies ersetzt die frühere versteckte Langdruck-Geste oben rechts.)

Ablauf 1 — Ein neues Tablet bereitstellen

Voraussetzungen (zuerst erledigen):

  • Stellen Sie die Android-Systemsprache des Tablets vor dem Werksreset auf Deutsch (Deutschland) — der Text des Einrichtungsassistenten und die erwartete Ausgabe unten sind deutsch, und eine abweichende Sprache verursacht unnötige Fehlersuche. (osds Bereitstellung setzt außerdem PROVISIONING_LOCALE/TIME_ZONE, aber der Assistent läuft davor.)

  • Halten Sie die neueste provision.png aus dem GitLab-Release auf einem zweiten Gerät (Handy-/Laptop-Bildschirm) bereit, um sie der Tablet-Kamera zu zeigen. Laden Sie sie von der Paket-URL des Releases herunter (API-Form, anonym erreichbar): https://gitlab.com/api/v4/projects/70262263/packages/generic/releases/<version>/provision.png

  • Ein WLAN vor Ort oder ein Handy-Hotspot, dem das Tablet beitreten kann (der Assistent lädt darüber die ~143 MB große APK herunter).

Schritte (QR-Pfad — bevorzugt):

  1. Werksreset des Tablets (Einstellungen → System → Zurücksetzen, oder Recovery). Bei HyperOS ist das Recovery-Menü möglicherweise chinesisch — verwenden Sie eine Übersetzungs-Kamera-App.

  2. Auf dem Willkommensbildschirm NICHT anmelden. Tippen Sie 6× auf dieselbe Stelle → der QR-Bereitstellungsablauf öffnet sich.

  3. Mit dem WLAN verbinden, wenn Sie dazu aufgefordert werden.

  4. Aktivieren Sie die Kamera, falls gefragt, und scannen Sie provision.png.

  5. Der Assistent zeigt „Dieses Gerät gehört Ihrer Organisation" („owned by business"), lädt osd herunter und installiert es, führt den Bereitstellungs-Handshake aus und startet in den osd-Kiosk. Rechnen Sie mit ≤ 5 Min bei 50 Mbps.

    • Erwarteter Endzustand: der osd-Logo-Bildschirm mit „Einsatzbereitschaft herstellen" + einem Zahnrad für die Einstellungen. Kein Android-Home, kein App-Drawer.

  6. Gerät einschreiben: Einstellungen (Zahnrad → Wartungs-PIN, jetzt bei erster Verwendung festlegen) → Geräte-Einschreibung → Einschreibungs-Token + Gerätenamen eingeben → den GPG-Fingerabdruck gegen den Inhaber des Org-Schlüssels bestätigen (Epic-4-Vertrauensanker). Dies bindet das Gerät + das GPG-Vertrauen.

Schritte (adb-Pfad — Ausweichlösung, wenn der QR-Ablauf nicht greift): Funktioniert nur auf einem nicht bereitgestellten Tablet (nach der Bereitstellung bleibt USB-adb unauthorized und Wireless debugging kann sich nicht koppeln — siehe Ablauf 2 / die adb-auf-Kiosk-Einschränkung). Auf einem frisch werksreseteten Tablet:

  1. Überspringen Sie im Assistenten alle Konten.

  2. Einstellungen → Entwickleroptionen aktivieren → USB-Debugging.

  3. adb install -r app-universal-release.apk

  4. adb shell dpm set-device-owner de.eventsanitaeter.es_dashboard/.OsdDeviceAdminReceiver

  5. Neustart → osd-Kiosk. Dann einschreiben wie in Schritt 6 oben.

Fehlerbild — „startet in den Kiosk, aber die Einschreibung schlägt fehl" (bricked-but-locked): Server nicht erreichbar, Einschreibungs-Token aufgebraucht oder der GPG-Fingerabdruck-Dialog wurde weggetippt → das Tablet ist nun ohne Einschreibung in osd eingesperrt und kann für einen echten Dienst nicht synchronisieren oder dokumentieren. **Einzige Wiederherstellung ist Ablauf 2 (Werksreset

  • neu bereitstellen).** Beheben Sie zuerst die Ursache (Server erreichbar? frisches Token? richtiger Fingerabdruck?), bevor Sie neu bereitstellen.

Ablauf 2 — Ein hängendes Tablet wiederherstellen

Symptom → Behebung zuordnen:

Symptom Behebung

Schwarzer Bildschirm / eingefroren

Physischer Power-Knopf-Langdruck 8—​12 s → Neustart erzwingen → Neustart lädt osd.

Android-Startbildschirm statt osd

Device Owner ging verloren → Werksreset + neu bereitstellen (Ablauf 1).

osd stürzt in Endlosschleife ab („ES Dashboard keeps stopping")

Global Actions (Power-Langdruck) → ausschalten → einschalten. Wenn es nach 2 Neustarts immer noch schleift → Werksreset + neu bereitstellen. Bekannte Ursache: ein aus v0.10.17/v0.10.18 bereitgestelltes Gerät hat einen fehlerhaften OTA-Watcher (Selbst-Neuinstallations-Schleife) — nicht aus diesen Tags bereitstellen; verwenden Sie v0.10.19 oder neuer. Falls erreichbar, entfernt das Leeren des osd-Cache (nicht der Daten) die zwischengespeicherte APK und durchbricht die Schleife, während die Einschreibung erhalten bleibt.

Banner „Kiosk degraded" in den Einstellungen (Story 9.2 kiosk:degraded)

Device Owner verloren (z. B. HyperOS-OS-Aktualisierung). Lesen Sie das Crash-Log in den Einstellungen zur Diagnose → Werksreset + neu bereitstellen.

Synchronisationsanzeige zeigt ausstehende Vorgänge UND das Tablet muss zurückgesetzt werden

Entscheidung des Bedieners: Datenverlust akzeptieren und zurücksetzen (der Werksreset löscht die Vorgangs-Warteschlange) oder auf das Leerlaufen der Synchronisation warten, wenn das Tablet noch teilweise nutzbar ist. Ist das Gerät zu defekt, um überhaupt die Synchronisationsanzeige zu erreichen, akzeptieren Sie den Verlust und fahren Sie fort.

Vergessene Firmen-/Wartungs-PIN, ausgesperrt

Die Wartungs-PIN schützt den Notausgang; wenn vergessen, kann die Wartungsgeste zwar weiterhin ausgelöst, aber nicht erfüllt werden → Wiederherstellung ist Werksreset + neu bereitstellen.

adb-auf-Kiosk-Einschränkung: Auf einem bereitgestellten HyperOS-Tablet bleibt USB-adb unauthorized (der Autorisierungsdialog wird unter lock-task unterdrückt) und die Wireless-debugging-Kopplung schlägt fehl. Somit ist adb kein Wiederherstellungswerkzeug auf einem laufenden Kiosk — der app-interne ADB-Aktivierungsbefehl (Einstellungen, Story 9.7) ist die einzige Möglichkeit, adb einzuschalten, und OTA ist die einzige zuverlässige Möglichkeit, einen neuen Build aufzuspielen. Planen Sie die Wiederherstellung um Werksreset + Neubereitstellung herum, nicht um adb.

Werksreset-Datenverlust: Ein Werksreset vernichtet alle lokalen osd-Daten — offene Protokolle, lokal (offline) angelegte Dienste und in der Warteschlange stehende op_log-Einträge. Wenn das Tablet erreichbar ist, prüfen Sie vor dem Zurücksetzen, dass die Synchronisationsanzeige „keine ausstehenden Vorgänge" zeigt. Wenn es nicht erreichbar ist, akzeptieren Sie den Verlust und fahren Sie fort.

Zielwert Wiederherstellungszeit: ≤ 20 Min bis zurück im Feld bei repräsentativem Einsatz-WLAN (50 Mbps). Dies ist ein Zielwert, keine Zusage (die frühere 15-Min-Angabe war optimistisch).

Ablauf 3 — osd über die Flotte aktualisieren

Primärer Pfad — app-internes OTA (kein Werksreset):

  1. Einstellungen → „Nach Updates suchen". osd prüft die stabile latest.json, lädt die neue APK herunter und installiert sie stillschweigend per Device-Owner-Selbstinstallation (kiosk_install_apk) — funktioniert innerhalb des Kiosks, kein Bediener-Tipp über das Starten hinaus nötig. Das Gerät startet einmal in die neue Version neu.

  2. Schneiden Sie ein Release, indem Sie vX.Y.Z taggen (CI veröffentlicht die APK + aktualisiert die stabile latest.json); Geräte holen es sich bei der nächsten Prüfung.

OTA-Bootstrap-Realität: Der OTA-Endpunkt-Fix steckt im Binary, daher kann ein Gerät auf einem Build vor dem Fix nicht per OTA zum Fix gelangen — das erste Gerät mit dem Fix muss einmal per Sideload aufgespielt werden, danach kann es OTA weitergeben. Geräte niemals auf v0.10.17/v0.10.18 bereitstellen/belassen (fehlerhafter OTA-Watcher); v0.10.19+ ist sicher.

Ausweichpfad — wenn OTA fehlschlägt (Signatur-Abweichung, Downgrade-Versuch, Datenträger voll): erneut aus den Einstellungen auslösen; schlägt es weiterhin fehl, die APK per adb-Pfad auf einem zurückgesetzten Gerät sideloaden (Ablauf 1) oder zu Ablauf 5 eskalieren. Im Normalpfad gibt es keine Werksreset-als-Aktualisierung-Kosten.

System-(Android-OS-)Aktualisierungen sind separat: Einstellungen → Gerät → System-Updates (Story 9.11) legt die Richtlinie fest (Aufschieben / Zeitfenster / Automatisch). Ein frisch bereitgestellter Kiosk verwendet standardmäßig Aufschieben (verschieben, ≤ 30 Tage), damit eine OS-Aktualisierung ein Tablet niemals mitten im Dienst neu startet. (Ob HyperOS die Richtlinie beachtet, wird noch auf dem Gerät verifiziert.)

Ablauf 4 — WLAN mitten im Einsatz wechseln

Ein Sani öffnet osd Einstellungen → WLAN (Story 9.5), scannt verfügbare Netzwerke und tritt bei — keine Begleitung durch einen Bediener, kein Verlassen des Kiosks. Ist der WLAN-Bereich nicht verfügbar (Device Owner verloren), gilt Ablauf 2.

Status: Der app-interne WLAN-Bereich ist Story 9.5 (noch nicht ausgeliefert). Bis er kommt, richten Sie das WLAN während der Bereitstellung ein (Ablauf 1, Schritt 3) oder erreichen Sie die Android-WLAN-Einstellungen über den Wartungs-Notausgang (10 Tipps auf die Versionsbezeichnung in den Einstellungen → Wartungs-PIN → Einstellungen).

Ablauf 5 — Außerbetriebnahme / flottenweite QR-Neuausgabe

Ein Tablet außer Betrieb nehmen:

  1. Admin-Seite: Gerät im Admin-Panel widerrufen (Epic 5 — Geräte-Off-Boarding).

  2. Tablet-Seite: Werksreset — die einzige Möglichkeit, Device Owner zu entfernen (die DPC kann im bereitgestellten Zustand nicht deinstalliert werden).

Flottenweite Neuausgabe (Keystore-Rotation): Wenn der produktive Signierungs-Keystore rotiert wird (Story 7.1 oder jede künftige Rotation), wird jeder zuvor gedruckte QR ungültig — der QR kodiert die Prüfsumme des Signierungszertifikats. Alle Tablets müssen mit der neuen provision.png neu bereitgestellt werden. Flottenweite Auswirkung; in einem Wartungsfenster einplanen.

Siehe auch

  • Release-/Branch-Status + Entscheidungen: docs/superpowers/plans/RELEASE-PLAN.md (im Repo; nicht im Portal veröffentlicht)

  • Architektur: _bmad-output/planning-artifacts/architecture.md (Nachtrag: Android Kiosk Deployment)

  • Onboarding (erste Anmeldung + Einschreibung): docs/ONBOARDING.md — Story 7.4, noch nicht geschrieben; sie wird für die Bereitstellungs-Voraussetzung auf dieses Betriebshandbuch verweisen.