Dokumentation · Version 2.0 · November 2026

1 Was ist zapy?

zapy ist ein eigenständiges Programm, das Smartphones, Geräte, Bildschirme und andere Programme miteinander verbindet. Besucher scannen einen QR-Code und steuern damit eine Installation direkt im Browser ihres Handys, ohne App.

Was bei welchem Eingang passiert, legen Sie im Control Panel mit Regeln fest: wenn ein Eingang eintrifft (ein Knopf auf dem Handy, ein HTTP-Aufruf, ein UDP-Paket, eine Taste, ein Ereignis), dann führt zapy einen Ausgang aus (Relais schalten, Bildschirm ändern, Text ans Handy senden, Gerät per UDP ansteuern …).

 Eingänge                       Regeln                     Ausgänge
 ────────                       ──────                     ────────
 Handy (Knöpfe, Regler)  ─┐                            ┌─  An Handy (Text, Gutschein)
 HTTP  /in/…             │                            │   HTTP-Aufruf (Relais, Webhook)
 UDP                     ├─▶  «wenn X, dann Y»  ─▶   ├─  UDP senden (Player, Licht)
 Taste am Display        │                            │   Display (Meldung, Seite, JS, QR)
 Ereignis                │                            │   Sitzung beenden
 Zeitbefehl             ─┘                            └─  Zeitbefehl, Log

2 Ablauf

  1. Aufmerksamkeit: Das Display (ein Bildschirm im Vollbild) oder ein Kleber an der Scheibe zeigt den QR-Code.
  2. Verbinden: Das Handy scannt den Code und öffnet die Handy-Seite. zapy prüft den Code und startet eine Sitzung mit Zeitlimit. Weitere Besucher warten in einer Warteschlange und sehen ihre Position.
  3. Interaktion: Jeder Knopf schickt einen Befehl. Die passenden Regeln lösen ihre Ausgänge aus.
  4. Call to Action: Läuft die Zeit ab oder ist ein Ziel erreicht, endet die Sitzung. Das Handy zeigt eine Abschlussmeldung oder öffnet eine Seite Ihrer Wahl, zum Beispiel einen Gutschein oder Ihren Onlineshop.
  5. Beim dynamischen Code gilt danach ein neuer QR-Code. Ein abfotografierter Code steuert nichts mehr.

3 Installation

zapy ist ein einzelnes Programm ohne Installation und ohne weitere Software. Es gibt Ausgaben für:

SystemDatei
Mini-Computer mit Linux (ARM, 64 Bit)zapy-linux-arm64
macOS (Apple Silicon / Intel)zapy-macos-arm64 / zapy-macos-intel
Windowszapy-windows.exe
Linux (PC)zapy-linux-amd64

Die Programme erhalten Sie bei der Dissenter GmbH (info@dissenter.ch). Programm in einen Ordner legen und starten:

./zapy-linux-arm64            # bzw. zapy-macos-arm64, zapy-windows.exe

Beim ersten Start legt zapy die Datei zapy.json neben dem Programm an. Die Konsole zeigt die wichtigsten Adressen:

AdresseZweck
http://localhost:8080/Display. Im Browser im Vollbild öffnen (Kiosk-Modus)
http://localhost:8080/admin?key=…Control Panel. Der Schlüssel steht in zapy.json, geben Sie ihn nicht weiter.
https://zapy.ch/r/#…Adresse im QR-Code für die Handys (über Websockets, siehe Kapitel 10)

Optionen beim Start: -config pfad/zapy.json, -port 8090, -quiet (ohne Debug-Meldungen im Log).

Tipp für den Mini-Computer im Fenster: zapy als Systemdienst starten und den Browser im Kiosk-Modus automatisch öffnen. So läuft das Schaufenster nach einem Stromunterbruch von selbst wieder an.

4 Control Panel

Das Control Panel läuft im Browser, auf dem zapy-Rechner selbst oder auf einem anderen Gerät im selben Netz. Änderungen gelten nach Speichern sofort.

Dashboard

Die Übersicht beim Öffnen: Verbindungsstatus (online/offline), verbundene Displays, aktive und wartende Handys, Laufzeit, Besuche, Sitzungen und ausgelöste Aktionen seit dem Start, ein Verlauf der letzten 24 Stunden, Eingänge nach Typ, die eingerichteten Regeln in Kurzform, der aktuelle Verbindungscode und die letzten Log-Einträge. Gezählt wird nur im Speicher, nach einem Neustart beginnen die Zahlen bei null.

I/O-Regeln

Jede Zeile verbindet einen Eingang (links) mit einem Ausgang (rechts). Mehrere Regeln dürfen auf denselben Eingang reagieren. Regeln lassen sich ausschalten, mit Notiz versehen und mit dem Knopf Testen sofort auslösen.

Allgemein

QR-Code

Dynamischer oder statischer Code, Position und Grösse über dem Webinhalt, Text unter dem Code. Der statische Code lässt sich als Bild speichern (/qr.png?static=1&size=1024), zum Drucken oder für einen NFC-Tag.

Nutzer und Log

Alle verbundenen Handys mit Status (aktiv, wartet), Startzeit und Restzeit. Sitzungen lassen sich einzeln oder alle beenden. Das Log zeigt jedes Ereignis live. Wenn etwas nicht wie erwartet läuft, lohnt sich zuerst ein Blick dorthin.

5 Eingänge im Detail

EingangFeldBeschreibung
Handy (WebSocket)BefehlText, den ein Knopf der Handy-Seite sendet, z. B. fahren oder tempo:*
HTTP-AufrufPfadJeder Aufruf von http://<zapy>:8080/in/<pfad>, z. B. licht/an. Ideal für Sensoren und andere Programme.
UDPBefehlInhalt eines UDP-Pakets an den eingestellten Port
Taste (Display)TasteTaste auf der Tastatur am Display, z. B. a, Enter, ArrowUp; beim Drücken oder Loslassen. Auch für USB-Buzzer, die eine Taste senden.
EreignisAuswahlProgrammstart, bereit für Nutzer, Sitzung beginnt, Sitzung endet, Display verbunden
ZeitbefehlNameWird von einem Ausgang «Zeitbefehl» nach einer Verzögerung ausgelöst

Präfix und Wert: Endet ein Befehl auf *, gilt er als Anfang. Der Rest steht im Ausgang als @val bereit. Die Regel tempo:* mit dem Befehl tempo:70 ergibt @val = 70. Weitere Platzhalter: @code (aktueller Code) und @user (Kennung des Handys).

6 Ausgänge im Detail

AusgangWirkung
An HandyText an das aktive oder an alle verbundenen Handys. Die Handy-Seite zeigt ihn an oder reagiert darauf (zapy.on("cmd", …)).
HTTP-AufrufGET, POST oder PUT an eine Adresse, z. B. ein netzwerkfähiges Relais (http://192.168.1.50/relay/0?turn=on), eine Hausautomation oder ein Webhook für Statistik.
UDP sendenText an IP und Port, z. B. an einen Digital-Signage-Player oder ein Lichtpult
DisplayMeldung einblenden, Adresse laden, JavaScript im Webinhalt ausführen, scrollen, QR-Code zeigen oder ausblenden
Sitzung beendenBeendet die Sitzung des auslösenden Handys, z. B. wenn ein Ziel erreicht ist
ZeitbefehlLöst nach n Millisekunden den Eingang «Zeitbefehl» mit diesem Namen aus: Verzögerungen, Abläufe, Wiederholungen
LogSchreibt einen Text ins Log

7 QR-Code und Sitzungen

8 Handy-Seite (Remote-App)

Ohne weitere Einstellung erhalten Besucher eine einfache Bedienung mit drei Knöpfen und einem Regler. Für ein Projekt gestalten Sie eine eigene Seite. Sie ist eine gewöhnliche Webseite (HTML, CSS, etwas JavaScript) und kann auf einem beliebigen Webserver liegen.

<p id="msg"></p>                                   <!-- Meldungen von zapy -->
<span id="time"></span>                             <!-- Restzeit -->

<button class="zapy_ButtonDisabled" data-cmd="fahren">Losfahren</button>
<button class="zapy_ButtonDisabled" data-cmd="pfeife" data-release="pfeife_aus">Pfeifen</button>
<input type="range" min="0" max="100" data-cmd="tempo:">    <!-- sendet tempo:<Wert> -->

<script src="https://zapy.ch/r/zapy.js"></script>
<script>
  zapy.on("cmd", text => console.log("von zapy:", text));
  zapy.on("state", (state, msg) => {});           // active | waiting | ended | refused
  // eigener Knopf: sendcmd("weiche_links");
</script>

Die Adresse Ihrer Seite tragen Sie im Control Panel unter Verbindung über Websockets → Handy-Seite ein. zapy hängt die Verbindungsdaten automatisch an (…#ID/CODE).

9 Display-Inhalte

Das Display ist eine Webseite im Vollbild. Neben dem reinen QR-Code kann es eigene Inhalte zeigen: Legen Sie Ihre Dateien in den Ordner content neben dem Programm und wählen Sie unter Allgemein → Display «Webinhalt mit QR-Code». Der Inhalt erhält jede Display-Aktion als Ereignis:

window.addEventListener("zapy", e => {
  // e.detail = { action: "message" | "load" | "js" | "qr" | …, value: "…" }
});

Mit dem Ausgang «Display → JavaScript ausführen» läuft Code direkt im Inhalt, z. B. spiel.springe() oder zeigeLevel(@val). So lassen sich Spiele, Animationen und Videos mit dem Handy steuern.

10 Verbindung: Websockets übers Internet oder WLAN

Übers Internet (Standard): zapy meldet sich bei einem Websocket-Vermittlungsserver an. Der QR-Code zeigt auf die öffentliche Handy-Seite https://zapy.ch/r/#<ID>/<CODE>. Handy und zapy treffen sich dort. Damit können Besucher aus dem Mobilnetz mitspielen, und der zapy-Rechner braucht keinen offenen Port, keine feste IP-Adresse und keinen eigenen Server. Ein gewöhnlicher Internetanschluss oder ein Mobilfunk-Router genügt.

Nur im WLAN: Ist die Verbindung übers Internet ausgeschaltet, zeigt der QR-Code die Adresse im lokalen Netz (http://<IP>:8080/r/CODE). Die Handys müssen dann im selben WLAN sein. Sinnvoll für Messen oder Räume mit Gäste-WLAN. Alternativ lässt sich eine eigene öffentliche HTTPS-Adresse eintragen (Tunnel oder Portweiterleitung).

Der Vermittlungsserver leitet Nachrichten nur weiter. zapy verwendet lange Zufalls-IDs, überträgt keine Personendaten, und gesteuert wird nur mit gültigem Code. Für vertrauliche Daten ist dieser Weg nicht gedacht.

11 Beispiel: Die Eisenbahn im Schaufenster

Eine Modelleisenbahn im Fenster, drei netzwerkfähige Relais (Fahrstrom, Weiche, Licht), ein kleiner Bildschirm mit dem Display und ein Lautsprecher für den Pfiff. Sitzungsdauer 60 Sekunden, Warteschlange ein, dynamischer Code. Die Regeln:

EingangAusgang
Handy fahrenHTTP http://relais-fahrstrom/relay/0?turn=on
Handy haltHTTP http://relais-fahrstrom/relay/0?turn=off
Handy weicheHTTP http://relais-weiche/relay/0?turn=toggle
Handy lichtHTTP http://relais-licht/relay/0?turn=toggle
Handy pfeifeDisplay → JavaScript pfiff.play()
Ereignis «Sitzung beginnt»Display → Meldung «Lokführer am Werk»
Ereignis «Sitzung endet»HTTP Fahrstrom aus
Ereignis «Sitzung endet»Display → Meldung «Danke! Die nächste Fahrt startet gleich.»

Als Seite nach Sitzungsende ist eine Gutschein-Seite eingetragen, z. B. https://ihr-laden.ch/gutschein. Dort steht der Rabattcode und ein Link zum Onlineshop. Das Dashboard zeigt am nächsten Morgen, wie viele Fahrten es gab.

12 Webseiten mit dem Handy steuern

Neben Installationen lassen sich auch Webseiten wie mit einer Spielkonsole steuern. Jeder Besucher erhält einen eigenen QR-Code und auf dem Handy ein Gamepad, dessen Tasten die Webseite festlegt (bis 8 Spieler pro Seite).

<script src="https://zapy.ch/fun/zapy/zapy-web.js"></script>
<script>
  var pad = Zapy.connect({ app: "Mein Spiel", players: 2,
    layout: { dpad: true, buttons: [{ id: "a", label: "Springen" }] } });
  pad.on("input", e => { /* e.player, e.id, e.state = "down" | "up" */ });
  pad.send("Punkte: 42");
</script>

Beispiele zum Ausprobieren gibt es in der Spielhalle.

13 Sicherheit und Datenschutz

14 Neu in 2.0

zapy 1.0 erschien im September 2014 und arbeitete bereits nach demselben Prinzip: QR-Code, Handy-Seite im Browser, Verbindung über Websockets, Regeln aus Eingang und Ausgang. Damals lief zapy als Desktop-Applikation. Version 2.0 übernimmt dieses Prinzip und bestehende Handy-Seiten laufen weiter. Neu bzw. anders sind vor allem:

Fragen und Projekte: info@dissenter.ch