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
- Aufmerksamkeit: Das Display (ein Bildschirm im Vollbild) oder ein Kleber an der Scheibe zeigt den QR-Code.
- 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.
- Interaktion: Jeder Knopf schickt einen Befehl. Die passenden Regeln lösen ihre Ausgänge aus.
- 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.
- 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:
| System | Datei |
|---|---|
| Mini-Computer mit Linux (ARM, 64 Bit) | zapy-linux-arm64 |
| macOS (Apple Silicon / Intel) | zapy-macos-arm64 / zapy-macos-intel |
| Windows | zapy-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:
| Adresse | Zweck |
|---|---|
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).
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
- Display: nur QR-Code oder eigener Webinhalt mit eingeblendetem QR-Code (Kapitel 9)
- Sitzung: maximale Dauer in Sekunden, Anzahl gleichzeitig aktiver Handys, Warteschlange ein/aus
- Remote-App: eigene Handy-Seite, Seite nach Sitzungsende, Texte für Start, Warten, Ende und Fehler
- Verbindung über Websockets: ein/aus, Adresse der Handy-Seite (Kapitel 10)
- Netzwerk: öffentliche Adresse für den Betrieb nur im eigenen Netz, HTTP-Port, UDP-Eingang
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
| Eingang | Feld | Beschreibung |
|---|---|---|
| Handy (WebSocket) | Befehl | Text, den ein Knopf der Handy-Seite sendet, z. B. fahren oder tempo:* |
| HTTP-Aufruf | Pfad | Jeder Aufruf von http://<zapy>:8080/in/<pfad>, z. B. licht/an. Ideal für Sensoren und andere Programme. |
| UDP | Befehl | Inhalt eines UDP-Pakets an den eingestellten Port |
| Taste (Display) | Taste | Taste auf der Tastatur am Display, z. B. a, Enter, ArrowUp; beim Drücken oder Loslassen. Auch für USB-Buzzer, die eine Taste senden. |
| Ereignis | Auswahl | Programmstart, bereit für Nutzer, Sitzung beginnt, Sitzung endet, Display verbunden |
| Zeitbefehl | Name | Wird 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
| Ausgang | Wirkung |
|---|---|
| An Handy | Text an das aktive oder an alle verbundenen Handys. Die Handy-Seite zeigt ihn an oder reagiert darauf (zapy.on("cmd", …)). |
| HTTP-Aufruf | GET, 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 senden | Text an IP und Port, z. B. an einen Digital-Signage-Player oder ein Lichtpult |
| Display | Meldung einblenden, Adresse laden, JavaScript im Webinhalt ausführen, scrollen, QR-Code zeigen oder ausblenden |
| Sitzung beenden | Beendet die Sitzung des auslösenden Handys, z. B. wenn ein Ziel erreicht ist |
| Zeitbefehl | Löst nach n Millisekunden den Eingang «Zeitbefehl» mit diesem Namen aus: Verzögerungen, Abläufe, Wiederholungen |
| Log | Schreibt einen Text ins Log |
7 QR-Code und Sitzungen
- Dynamischer Code: wechselt nach jeder Verbindung. Empfohlen für Bildschirme, weil ein Foto des Codes später nichts mehr steuert.
- Statischer Code: bleibt gleich. Zum Aufkleben an die Scheibe oder für einen NFC-Tag.
- Sitzungsdauer: z. B. 60 Sekunden pro Person. Die Handy-Seite zeigt die Restzeit.
- Mehrere gleichzeitig: Mit «gleichzeitig aktive Nutzer» > 1 steuern mehrere Handys zusammen.
- Warteschlange: Weitere Besucher sehen «Gleich sind Sie dran. Position 2» und kommen automatisch an die Reihe.
- Befehle zählen nur von aktiven Handys. Wartende können nichts auslösen.
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>
data-cmdsendet den Befehl beim Antippen,data-releasezusätzlich beim Loslassen.- Knöpfe mit der Klasse
zapy_ButtonDisabledwerden bei Sitzungsbeginn zuzapy_Button(aktiv) und am Ende wieder deaktiviert. sendcmd("…")funktioniert wie 2014. Bestehende Remote-Apps laufen weiter.- Die Seite nach Sitzungsende (Control Panel → Remote-App) kann ein Gutschein, ein Wettbewerb oder Ihr Onlineshop sein.
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.
- Die ID der Installation entsteht beim ersten Start zufällig und bleibt danach gleich. Gedruckte statische QR-Codes bleiben gültig.
- Das Dashboard zeigt, ob die Verbindung steht. Bricht sie ab, verbindet zapy selbst neu.
- Ein Handy, das 15 Sekunden lang kein Lebenszeichen sendet (Seite geschlossen, Funkloch), gilt als getrennt. Sein Platz wird frei.
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).
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:
| Eingang | Ausgang |
|---|---|
Handy fahren | HTTP http://relais-fahrstrom/relay/0?turn=on |
Handy halt | HTTP http://relais-fahrstrom/relay/0?turn=off |
Handy weiche | HTTP http://relais-weiche/relay/0?turn=toggle |
Handy licht | HTTP http://relais-licht/relay/0?turn=toggle |
Handy pfeife | Display → 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
- Das Control Panel ist nur mit dem Schlüssel aus
zapy.jsonerreichbar. Schreibende Aufrufe sind zusätzlich gegen fremde Seiten geschützt. - Handys steuern nur mit gültigem Code und nur während ihrer Sitzung.
- zapy speichert keine Personendaten. Besucher melden sich nicht an, und die Handy-Seite setzt keine Cookies. Die Statistik zählt nur Ereignisse, ohne Bezug zu Personen, und nur im Arbeitsspeicher.
- Ausgänge wie HTTP und UDP gehen an die Adressen, die Sie im Control Panel eintragen, sonst nirgendwohin.
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:
- Ein einzelnes Programm ohne Installation, auch für Mini-Computer
- Control Panel im Browser mit Dashboard und Live-Log
- Mehrere gleichzeitig aktive Handys, Präfix-Befehle mit
@val, Regler auf der Handy-Seite - Ausgang HTTP mit POST und PUT, Testknopf pro Regel
- Webseiten mit dem Handy steuern (Gamepad, mehrere Spieler)
- Weggefallen: Flash/SWF und die Lizenzsperre. Statistik läuft über HTTP-Webhooks.
Fragen und Projekte: info@dissenter.ch
