Für Entwickler
Steuere deine Folien mit eigenen Werkzeugen
Erstelle ein eigenes Bedienfeld, zeige die aktuelle Folie in deiner eigenen Ansicht an oder sende Live-Liedtexte an Presenter. Nutze MQTT mit einer kostenpflichtigen Presenter-Lizenz in einem vertrauenswürdigen lokalen Netzwerk oder verbinde dich mit Complete über SundayAssist Cloud.
Für deine AV-Tools, Dashboards und Automatisierungen im Gottesdienst.
- Berechtigungen einzeln wählen
- Lokal oder über SundayAssist Cloud
- Eigene Zugangsdaten für jeden Dienst
Setze deine eigenen Werkzeuge im Gottesdienst ein
Baue dein eigenes Bedienfeld
Starte und stoppe Presenter mit deinen eigenen Tasten oder über deine AV-Steuerung. Wechsle zwischen Folien und blende die Ausgabe ein oder aus.
Zeige die aktuelle Folie an anderer Stelle
Erstelle eine eigene Ansicht für aktuelle Liedtexte, Bibelverse oder unterstützte Folienvorschauen. Leserechte lassen sich unabhängig von der Steuerung vergeben.
Bringe Live-Liedtexte auf die Leinwand
Sende Text aus einer anderen App an ein Element für Live-Liedtexte in Presenter. Das MQTT-Topic wählst du selbst.
Mit Presenter verbinden
Deine eigene MQTT-Integration erstellen
Wähle „Lokal“ für einen Dienst im Netzwerk deiner Gemeinde oder SundayAssist Cloud für deine Organisation. Presenter zeigt die Verbindungs-URLs an. Du bestimmst, was der Dienst darf.
- Öffne die Zugangsdaten für Integrationen unter „Verbindungen“ und wähle „Lokal“ oder SundayAssist Cloud.
- Erlaube Steuerung, Folienansicht und Metadatenereignisse einzeln. Verwende eigene Topics für deine Nachrichten.
- Speichere das nur einmal angezeigte Passwort in deinem Dienst und vergib für jede Verbindung eine eindeutige Client-ID.
Zugriff, Lizenzvoraussetzungen und Grenzen
Wähle unter „Verbindungen → Integrationen“ „Lokal“ oder SundayAssist Cloud. Lokale Zugangsdaten funktionieren mit einer kostenpflichtigen Own- oder Flex-Lizenz oder einer berechtigten älteren Lizenz, auch mit Presenter über Complete. SundayAssist Cloud erfordert ein aktives Complete-Abo, eine Anmeldung und die Rolle als Inhaber oder Admin der Organisation. Für Cloud-Ereignisse, Folienansicht und Steuerung muss Presenter laufen und die Handy-Fernsteuerung auf „Von überall“ stehen.
Lokale Zugangsdaten bleiben auf der jeweiligen Presenter-Installation. Cloud-Zugangsdaten bleiben in der gewählten Organisation. Ein Zugang erlaubt insgesamt bis zu 20 Themenberechtigungen, einschließlich aktivierter Steuerung und Folienansicht. Bis zu 20 Zugänge können pro Konto und Organisation in der Cloud oder pro lokaler Installation aktiv sein. Steuerung ist standardmäßig aus und erlaubt nur Befehlsthema, Ergebnisse und Status dieses Presenter. Die Option nur für Ereignisse erlaubt keine Befehle. Private Kopplungs- und Ablaufprotokolle für Remote sowie KI, Relay und Presenter-link bleiben gesperrt. Die Folienansicht ist ebenfalls standardmäßig aus. Sie teilt nur die aktuellen unterstützten Folieninhalte des ausgewählten Presenter auf eigenen Anfrage- und Statusthemen. Reine Metadaten-Ereignisse enthalten keine Liedtexte oder Folienvorschauen. Die Musikerfunktionen von WorshipAssist bleiben separat.
Lokales TCP und WebSocket sind unverschlüsselt. Nutze ein vertrauenswürdiges Netzwerk und mache diese Ports nie im Internet erreichbar. Cloud-Verbindungen erfordern TLS mit Zertifikatsprüfung. Das Veröffentlichen auf eigenen Themen unterstützt QoS 0 oder 1 und nicht gespeicherte Nachrichten bis zu 1 MiB. Passwörter laufen nicht planmäßig ab, doch der kostenpflichtige Zugriff und die Berechtigungen werden geprüft. Ersetze oder widerrufe Zugangsdaten, wenn sich ein Dienst ändert.
Alle Einrichtungsschritte
- Erstelle benannte Zugangsdaten für jeden Dienst. Aktiviere unabhängig „Diesen Presenter steuern“, „Folien von diesem Presenter ansehen“ oder „Presenter-Ereignisse lesen“ für reine Metadaten. Nutze „Eigene Themen (optional)“ für andere Dienste.
- Speichere das Passwort, wenn es erscheint. Es wird einmal angezeigt. Gib jeder Verbindung eine eigene Client-ID mit dem zugewiesenen Präfix. Der lokale Zugriff nutzt Computer und Ports, die Presenter anzeigt. Der Cloud-Zugriff nutzt TLS 8883 oder WSS 443 /mqtt.
- Sende ausdrückliche Befehle wie Start, Stopp, nächste oder vorherige Folie oder Element sowie Ausgabe aus- oder einblenden. Nutze die aktuelle runId aus dem Status, eine eindeutige requestId und das Befehlsergebnis, um veraltete oder doppelte Aktionen zu vermeiden. Die Auswahl eines Elements startet die Ausgabe nicht automatisch. Aktiviere für deine eigene Ansicht die separate Berechtigung zur Folienansicht. Sie liefert aktuelle Liedtexte und Bibeltexte sowie unterstützte Vorschauen für PDF, Bild und PowerPoint. Die Musikeransicht von WorshipAssist bleibt separat.
- Erlaube deinem Dienst für Live-Text das Veröffentlichen auf church/lyrics/slide und stelle dieses Thema für Liedtexte in Presenter ein. Complete-Cloud-Integrationen können „Eigener Server“ mit separaten Zugangsdaten nur zum Empfang nutzen. Die Einrichtungsanleitung erklärt beide Wege.
Beispiele für Verbindungen und Topics
mqtt://<presenter-lan-ip>:1883
ws://<presenter-lan-ip>:9883/mqtt
mqtts://mqtt.sundayassist.com:8883
wss://mqtt.sundayassist.com/mqtt
clientId: <assigned-client-id-prefix>external-1
publish: sundayassist/integrations/v1/commands/<presenter-id>/control
subscribe: sundayassist/integrations/v1/commands/<presenter-id>/result
publish: sundayassist/integrations/v1/viewer/<presenter-id>/request
subscribe: sundayassist/integrations/v1/viewer/<presenter-id>/state
subscribe: sundayassist/integrations/v1/events/<presenter-id>/state
QoS: 1Probiere ein funktionsfähiges Beispiel aus
Deine eigene Folienansicht und Steuerung
Diese Node.js-App zeigt aktuelle Folieninhalte und bietet „Zurück“, „Weiter“, „Start“, „Stopp“ sowie „Ausblenden/Einblenden“. Wähle mit getrennten Berechtigungen nur Ansicht, nur Steuerung oder beides. Die MQTT-Zugangsdaten bleiben auf dem Node-Server. Browseraktionen laufen über diesen Server. Die Ansicht unterstützt Lied- und Bibeltexte sowie unterstützte Vorschauen für PDF, Bild und PowerPoint. Probiere die interaktive Vorschau aus und verbinde dann deine Presenter-ID. Die Vorschau steuert nur simulierte Daten.
Interaktives Bedienfeld öffnen
Beispiel auf deinem Computer starten
unzip mqtt-showcase.zip
cd mqtt-showcase
npm ci
npm run demoSuchst du die Protokolldetails?
Der Leitfaden oben dokumentiert dauerhafte Zugangsdaten für Integrationen und erklärt die Schnittstellen für Befehle, Folienansicht und Ereignisse. Die Referenz unten beschreibt das separat gekoppelte Remote-Protokoll. Die Zugangsdaten für Integrationen gewähren keinen Zugriff auf private Remote-Topics.
Warum MQTT?
Presenter nutzt MQTT bereits für QR-Remote, Live-Status und lokale KI-Themen. Derselbe Broker steht deinen eigenen Clients im lokalen Netzwerk der Gemeinde zur Verfügung. Der eingebettete Broker entspricht MQTT v5 und akzeptiert auch Clients mit MQTT v3.1.1 oder v3.0. Du veröffentlichst und abonnierst wie in jeder MQTT-App. Presenter reagiert auf Steuernachrichten und veröffentlicht Ablauf- und Statusänderungen.
Erste Schritte
Verwende einen MQTT-Client für v5 oder v3.x (TCP oder WebSocket). Verbinde ihn mit dem Presenter-Host, solange ein Gottesdienst geöffnet ist oder nachdem Remote den Broker gestartet hat. Die interne Remote-Kommunikation von Presenter nutzt MQTT 3.1.1. Deine Clients können Funktionen verwenden, die nur v5 bietet. Bei Kommunikation mit v3-Clients werden diese entsprechend angepasst.
- Für lokalen Zugriff bleibst du im selben WLAN oder LAN wie der Computer mit Presenter.
- Die Host-IP findest du in den Netzwerk- oder QR-Einstellungen für Remote in Presenter oder in der Geräteliste deines Routers.
- Wenn 1883 oder 9883 nicht funktioniert, probiere den nächsten Port im Ausweichbereich. Presenter protokolliert beim Start die belegten Ports.
- QoS 0 ist für Live-Steuerung üblich. Halte Nutzdaten klein und codiere sie als JSON in UTF-8.
Mit dem eingebetteten Broker verbinden
Wenn Presenter läuft, hört der Broker auf der LAN-Adresse des Computers. Ist der Standardport belegt, versucht Presenter den nächsten Port im Bereich.
| Transport | Endpunkte | Hinweise |
|---|---|---|
| MQTT über TCP | tcp://<presenter-lan-ip>:1883–1887 | Geeignet für Desktop-Skripte, Node, Python und Hardware-Bridges. |
| MQTT über WebSocket | ws://<presenter-lan-ip>:9883–9887/mqtt | Der Pfad ist immer /mqtt. Für Browser oder WebSocket-fähige Clients. |
tcp://192.168.1.40:1883
ws://192.168.1.40:9883/mqttMQTT-Themen für Remote
Verwende das genaue Themenpräfix aus den QR-Verbindungsdaten von Presenter. Ersetze {prefix} durch diesen Wert, normalerweise sundayassist/<machine-scope>/remote, wenn ein Rechnerbereich vorliegt. Andernfalls nur sundayassist/remote.
Diese Referenz beschreibt die Implementierung von sundayassist/. Nutze zueinander passende Builds von Presenter und Remote, aktualisiere alle verknüpften Presenter-Instanzen zusammen und kopple die Handys nach dem Upgrade erneut. Frühere Verbindungsversionen können mit diesem Namensraum nicht kommunizieren.
Präfix aus den QR-Verbindungsdaten von Presenter: sundayassist/<scope>/remote, ohne Rechnerbereich ersatzweise sundayassist/remote. Sitzungs-IDs erhältst du beim Koppeln. Kopple zuerst und veröffentliche dann unter dieser Sitzung.
| Themenmuster | Richtung | Zweck |
|---|---|---|
{prefix}/pair | Client → Presenter | OTP- oder Kopplungsanfrage zum Erstellen einer Sitzung |
{prefix}/<sessionId>/paired | Presenter → Client | Kopplung angenommen oder abgelehnt |
{prefix}/<sessionId>/control | Client → Presenter | Befehle (advance, goto, blank, …) |
{prefix}/<sessionId>/heartbeat | Client → Presenter | Sitzung aktiv halten. Rolle controller oder viewer angeben |
{prefix}/<sessionId>/deck | Presenter → Client | Vollständiger Ablauf als JSON für Steuerung und Bearbeitung |
{prefix}/<sessionId>/state | Presenter → Client | Live-Status von Projektorausgabe und Steuerung |
{prefix}/<sessionId>/viewer/state | Presenter → Client | Umschlag für Folien-Rasterdaten zum Mitlesen (auch segmentierte Varianten) |
{prefix}/ai/* | KI-Engine ↔ Presenter | Lokale KI-Themen |
sundayassist/relay/request | Client → Presenter | Anfrage nach Cloud-Einrichtungscode |
sundayassist/relay/answer/<nonce> | Presenter → Client | Antwort mit den Verbindungsdaten für Remote |
sundayassist/presenter-link/<account-scope>/<sender>/<recipient-or-all> | Presenter ↔ Presenter | Verschlüsselte Erkennung und Synchronisierung zwischen berechtigten Presenter-Instanzen, getrennt von Remote-Sitzungen am Handy |
Aufbau der Steuerdaten
Veröffentliche nach dem Koppeln JSON unter {prefix}/<sessionId>/control. Füge sessionId und token aus der Antwort von /paired sowie cmd und etwaige Navigationsfelder hinzu. Presenter prüft Sitzung, Token, Ablaufzeit und zulässige Rolle, bevor der Befehl ausgeführt wird.
{
"sessionId": "<paired-session-id>",
"token": "<paired-token>",
"cmd": "advance"
}
{
"sessionId": "<paired-session-id>",
"token": "<paired-token>",
"cmd": "goto",
"deckIdx": 2,
"page": 0
}| cmd | Bedeutung |
|---|---|
present | Präsentation starten |
stop | Präsentation stoppen |
advance | Nächstes Element oder nächster Folienschritt |
back | Vorheriges Element oder vorheriger Folienschritt |
goto | Mit deckIdx / page und zugehörigen Feldern springen |
blank | Anzeige leeren oder wiederherstellen |
nextItem | Nächstes Element im Ablauf |
prevItem | Vorheriges Element im Ablauf |
setStanza | Innerhalb des Liedaufbaus springen |
setPage | Seite in PDF oder mehrseitigem Element einstellen |
ping | Erreichbarkeit prüfen |
Sicherheit und Grenzen
- Behandle den Broker als LAN-Dienst. Leite seine Ports nicht ins öffentliche Internet weiter.
- Der LAN-Broker verwendet einen gemeinsamen Backend-Benutzernamen mit einem eigenen Zufallsgeheimnis je Presenter-Installation, das über Neustarts hinweg erhalten bleibt. QR-Clients bekommen separate Zugangsdaten, die auf ihre Sitzung und erlaubte Aktionen begrenzt sind. Das Backend-Geheimnis erhalten sie nie.
- Befehle erfordern ein gültiges Kopplungstoken. Presenter setzt Rolle und Ablaufzeit durch. Schütze Token, Netzwerk und Kopplung.
- Themen unter sundayassist/<scope>/remote/ können bei aktivierter SundayAssist Cloud-Verbindung in Complete auch an SundayAssist Cloud weitergeleitet werden. Teste zuerst im LAN.
- Beobachte /deck und /state aus einer passenden Remote-Sitzung, während du deinen Prototyp erstellst. Felder können mit der Weiterentwicklung ergänzt werden.
- Nicht abwärtskompatible Änderungen an Themennamen sind selten. Wenn du eine öffentliche Integration veröffentlichst, schreib uns an [email protected], damit wir dich vor einer Umbenennung informieren können.