MQTT-Integrationen

Erstelle einen externen Dienst, der Presenter folgt, mit ausdrücklicher Berechtigung Folien steuert oder Nachrichten über eigene Topics austauscht. Dauerhafte Zugangsdaten haben ein Passwort, das nur einmal angezeigt wird, und gezielt begrenzte Berechtigungen.

Für Lokal brauchst du eine kostenpflichtige Lizenz für Presenter Own, Flex oder eine berechtigte ältere Version, auch für Presenter über Complete. Die Zugangsdaten bleiben auf diesem Computer und brauchen kein Cloud-Konto. SundayAssist Cloud erfordert ein aktives Complete-Abo, eine Anmeldung, die Mitgliedschaft in der Organisation und die Rolle als Inhaber oder Administrator. Ein unbezahlter Pilotzugang reicht nicht aus. Schlägt die Zahlung zur Verlängerung von Complete fehl, funktionieren vorhandene Cloud-Zugangsdaten noch bis zu 14 Tage weiter. Neue Cloud-Zugangsdaten lassen sich in dieser Zeit nicht erstellen. Endet der Complete-Zeitraum ohne Verlängerung, endet der Cloud-Zugang innerhalb von 3 Tagen.

Zugangsdaten erstellen

  1. Öffne Verbindungen → Integrationen und wähle Lokal oder SundayAssist Cloud.
  2. Wähle Zugangsdaten erstellen und gib dem Dienst einen Namen. Aktiviere Folien von diesem Presenter ansehen, Diesen Presenter steuern oder beides. Jede Option fügt die nötigen reservierten Topics automatisch hinzu. Presenter-Ereignisse lesen ist eine eigene Berechtigung zur Überwachung. Öffne Eigene Topics (optional) nur, wenn du zusätzlich eigene Topics zum Veröffentlichen oder Abonnieren brauchst. Gib ein Topic pro Zeile ein und lass ungenutzte Richtungen leer.
  3. Speichere das Passwort sofort im vertraulichen Speicher deines Dienstes. Verbindungsdaten kopieren enthält auch das Passwort. Es wird nur einmal angezeigt und lässt sich später nicht abrufen.
  4. Verwende eigene Zugangsdaten pro Dienst. In Presenter sind pro Zugang insgesamt bis zu 20 Berechtigungen zum Veröffentlichen oder Abonnieren möglich, einschließlich automatisch hinzugefügter Presenter-Topics. Veröffentlichen und Abonnieren desselben Topics zählen getrennt. Folienansicht und Steuerung belegen zusammen 5 Berechtigungen. Damit bleiben 15 für eigene Topics. Presenter-Ereignisse lesen belegt 1 weitere Berechtigung. Pro lokaler Installation oder pro Konto und Organisation in der Cloud können bis zu 20 Zugänge aktiv sein.

Den richtigen Broker verbinden

Verwalte lokale und Cloud-Zugangsdaten unter Verbindungen → Integrationen. Hier wählst du den Broker für deinen externen Dienst. Die Handy-Verbindung ändert sich dadurch nicht. Lokale Integrationen verwenden den lokalen Broker. Cloud-Clients können über ihre eigenen Topics unabhängig von Presenter Nachrichten austauschen. Um Presenter-Ereignisse zu lesen, Folien anzusehen oder Befehle über die Cloud zu senden, lass Presenter geöffnet und wähle Verbindungen → Handy-Fernsteuerung → Von überall. Wenn ein anderer Modus aktiv ist, verweist der Bereich für Cloud-Zugangsdaten auf Handy-Fernsteuerung, damit du den Modus selbst ändern kannst.

Verwende MQTT 3.1.1 oder 5. Kopiere die tatsächliche lokale Adresse und die Ports, die Presenter anzeigt. Üblicherweise sind das TCP-Port 1883 und WebSocket-Port 9883. Sind sie belegt, verwendet Presenter andere Ports. Die lokale Verbindung ist unverschlüsselt. Nutze sie nur in einem vertrauenswürdigen Netzwerk und leite diese Ports nie ins Internet weiter. TLS in der Cloud verwendet Port 8883, sicheres WebSocket Port 443 und den Pfad /mqtt. Lass die Zertifikatsprüfung eingeschaltet. Jede gleichzeitige Verbindung braucht eine eindeutige Client-ID, die mit dem zugewiesenen Präfix beginnt.

Öffne unter Verbindungen → Integrationen die Verbindungs-URLs, um TCP- und WebSocket-Adressen für den gewählten Broker zu kopieren. Die einmalige Anzeige der Zugangsdaten und Verbindungsdaten kopieren enthalten beide Adressen. Verwende mqtt:// oder ws:// für den lokalen Broker und mqtts:// oder wss:// für SundayAssist Cloud. Der lokale Broker bietet kein TLS.

Local:
  mqtt://<presenter-lan-ip>:1883
  ws://<presenter-lan-ip>:9883/mqtt
Complete cloud:
  mqtts://mqtt.sundayassist.com:8883
  wss://mqtt.sundayassist.com/mqtt
username: <generated-username>
password: <shown-once-password>
clientId: <assigned-client-id-prefix>external-1

Eigene Topics wählen

Berechtigungen zum Veröffentlichen verwenden genaue Topics. Berechtigungen zum Abonnieren erlauben ein genaues Topic oder ein abschließendes /# unter einem ausgeschriebenen Namensraum, etwa church/lyrics/#. Der Platzhalter +, ein alleinstehendes #, leere Ebenen, Leerraum und $ werden abgelehnt. Der erste Namensraum darf unabhängig von Groß- und Kleinschreibung nicht sundayassist lauten. Ausnahmen für reservierte Topics sind die ausdrücklichen Berechtigungen zum Lesen von Ereignissen, zur Folienansicht und zur Presenter-Steuerung.

Lokale Berechtigungen gelten für die jeweilige Presenter-Installation. Cloud-Topics sind auf die Organisation beschränkt. Verwende auf beiden Clients dasselbe Topic ohne Organisationspräfix. Personen derselben Organisation mit überlappenden Topic-Berechtigungen können Nachrichten austauschen. Mit Integrationszugangsdaten kannst du Remote nicht koppeln, sein internes Ablauf- oder Statusprotokoll nicht nutzen und nicht auf KI, Weiterleitung oder Presenter Link zugreifen. Nur die ausdrückliche Steuerungsberechtigung gibt das dokumentierte Befehls-Topic frei. Die Berechtigung zur Folienansicht gibt das Topic für Vorschauanfragen frei. Veröffentlichungen in anderen SundayAssist-eigenen Topics bleiben gesperrt. Musikerfunktionen, Sitzungen, Kataloge, Akkorde und Einladungen von WorshipAssist bleiben getrennt. Diese Berechtigungen geben sie nie frei. Beim Veröffentlichen in eigenen Topics sind QoS 0 oder 1 und Nutzdaten bis 1 MiB zulässig. Das Retain-Flag darf nicht gesetzt sein.

Presenter-Ereignisse lesen

In SundayAssist Cloud sendet Presenter diesen Status einschließlich der Titel von Elementen und Abschnitten nur, solange eine aktuell geprüfte Integration in der gewählten Organisation die Ereignisse dieses Presenters lesen darf. Die Integration kann einem anderen Organisationsmitglied gehören. Die Berechtigung zur Folienansicht oder Steuerung umfasst auch den aktuellen Ereignisstatus des jeweiligen Presenters. Ein reines Ereignis-Basistopic ohne /# abonniert seine untergeordneten Topics nicht. Lokale Ereignisse und der Empfang von Liedtexten funktionieren wie bisher.

Presenter prüft diese Berechtigung beim Start und üblicherweise alle 30 Sekunden, auch wenn Verbindungen geschlossen ist. Nach einer Änderung auf einem anderen Gerät kann es bis zu 60 Sekunden dauern, bis keine neuen Statusmeldungen mehr gesendet werden. Eine fehlgeschlagene Prüfung verlängert diese Frist nicht. Wenn die Berechtigung wieder gilt, sendet Presenter den aktuellen Zustand erneut, auch wenn sich die Folie nicht geändert hat. Bei einem Entzug versucht Presenter, die gespeicherte MQTT-Statusmeldung zu löschen, solange dieselbe Verbindung und Cloud-Berechtigung noch gültig sind. Offline, nach der Abmeldung oder nach Verlust dieser Berechtigung ist die Bereinigung nicht garantiert. Die Meldung verschwindet also nicht unbedingt sofort von jedem Broker oder verbundenen Client.

Aktiviere Presenter-Ereignisse lesen und abonniere sundayassist/integrations/v1/events/# oder nur sundayassist/integrations/v1/events/<presenterId>/state. Presenter veröffentlicht einen beim Broker gespeicherten JSON-Status mit QoS 1 in folgendem Format. Er enthält Titel, aber keine Liedtexte, Notizen, Dateipfade, Bildschirmfotos oder Kontodaten. Element oder Abschnitt können null sein.

{
  "schemaVersion": 1,
  "eventId": "boot-id:42",
  "presenterId": "opaque-installation-id",
  "runId": "boot-id",
  "sequence": 42,
  "occurredAt": "2026-10-27T12:00:00Z",
  "type": "presenter.state",
  "state": {
    "presenting": true,
    "blanked": false,
    "phase": "active",
    "cue": {"id": "opaque-occurrence", "type": "lyrics", "title": "Welcome", "index": 0},
    "section": {"id": "opaque-section", "title": "Gathering", "index": 0},
    "position": {"subIndex": 0, "page": 0}
  }
}

Verwende eventId, um Duplikate zu erkennen, und sortiere Nachrichten mit derselben runId nach sequence. Beim Neustart von Presenter beginnt ein neuer Lauf. Beim erneuten Verbinden kann dasselbe Ereignis noch einmal eintreffen. IDs für Elemente und Abschnitte bezeichnen einzelne Vorkommen ohne lesbare Bedeutung. Wenn du den Ablauf bearbeitest oder umsortierst, können sie sich ändern. Indizes beginnen bei null. subIndex kann für eine Standardfolie -1 sein.

Änderungen werden bis zu 1 Sekunde gebündelt. Auch ohne Änderung erscheint normalerweise alle 15 Sekunden eine frische Statusmeldung. Prüfe vor einer Aktion occurredAt und die Retain-Kennzeichnung von MQTT. Eine beim Broker gespeicherte Statusmeldung kann erhalten bleiben, wenn Presenter nicht mehr läuft, und belegt nicht, dass die App online ist. Sie zeigt den letzten bekannten Zustand, kein vollständiges Ereignisprotokoll und keinen kommenden Ablauf.

Eine eigene Folienansicht bauen

Aktiviere Folien von diesem Presenter ansehen für eine externe App zur Folienansicht. Die Berechtigung gilt für eine Installation und erlaubt, sundayassist/integrations/v1/viewer/<presenterId>/state und das genaue Ereignis-Status-Topic dieser Installation zu abonnieren. Sie erlaubt Veröffentlichungen ausschließlich auf sundayassist/integrations/v1/viewer/<presenterId>/request. Die Folienansicht erlaubt keine Präsentationsbefehle. Wähle beide Berechtigungen, wenn dieselbe App auch steuern soll.

Lies eine aktuelle Ereignis-Statusmeldung und fordere mit ihrer runId den aktuellen Inhalt an. Sende folgende Anfrage alle 10 Sekunden, solange die Ansicht gebraucht wird. Eine Anfrage schaltet die Ansicht für 30 Sekunden frei, und zwar nur auf dem Verbindungsweg, auf dem sie einging. Ohne Anfragen werden Inhalte nicht laufend in die Cloud geladen. Wie Befehle müssen Anfragen aktuell sein und dürfen nicht beim Broker gespeichert werden. Beende die Anfragen, wenn die Folienansicht geschlossen wird.

client.publish(
  `sundayassist/integrations/v1/viewer/${presenterId}/request`,
  JSON.stringify({
    schemaVersion: 1,
    requestId: crypto.randomUUID(),
    runId: latestState.runId,
    issuedAtUnixMs: Date.now()
  }),
  { qos: 0, retain: false }
);

Presenter sendet nicht gespeicherte Statusmeldungen vom Typ presenter.viewer höchstens einmal pro Sekunde. Normalerweise werden sie nach 15 Sekunden erneuert und laufen nach 45 Sekunden ab. Verwirf abgelaufene Daten und ältere Werte von sequence bei derselben runId. Leere die Vorschau nach Ablauf oder Neustart. Die gesamte Nachricht ist höchstens 512 KiB groß und wird nicht in Teile zerlegt. Bei unterstützten Bildvorschauen ist die längste Kante höchstens 960 Pixel lang.

{
  "schemaVersion": 1,
  "presenterId": "opaque-installation-id",
  "runId": "boot-id",
  "sequence": 7,
  "occurredAt": "2026-10-27T12:00:00Z",
  "expiresAt": "2026-10-27T12:00:45Z",
  "type": "presenter.viewer",
  "view": {"kind": "text", "text": "Current slide text"}
}

view.kind ist black, blank, text, image oder unsupported. Text enthält nur die gerade projizierte Liedstrophe, Bibelstelle oder den Live-Text, optional mit secondaryText und reference. Akkorde sind ausgeschlossen. Für das aktuelle Bild, die PDF-Seite oder die unterstützte PowerPoint-Vorschau werden imageMime (image/jpeg) und imageBase64 verwendet. reason ist ein Code dafür, warum ein Inhaltstyp nicht unterstützt wird. Die Vorschau zeigt den aktuellen Inhalt, keine pixelgenaue Gestaltung, Bildschirmaufnahme, Live-Video oder Audio. Video-, Audio-, Website-, Publikums-, QR-/Einladungs- und WorshipAssist-Elemente werden nicht unterstützt. Abläufe, Notizen, Pfade, URLs, Kopplungstokens und WorshipAssist-Daten sind ausgeschlossen.

Diesen Presenter steuern

Aktiviere Diesen Presenter steuern nur für einen Dienst, dem du die Bedienung der laufenden Präsentation anvertraust. Die Option ist standardmäßig aus und gilt für die presenterId dieser Installation. Presenter erlaubt automatisch Veröffentlichungen auf sundayassist/integrations/v1/commands/<presenterId>/control und Abos für sundayassist/integrations/v1/commands/<presenterId>/result sowie das genaue Status-Topic. Private Remote-Befehle sind nicht freigegeben. Um Ziel oder Berechtigungen zu ändern, widerrufe die Zugangsdaten und erstelle neue.

Lies zuerst eine frische Statusmeldung und verwende ihre aktuelle runId. Veröffentliche einen JSON-Befehl mit einer neuen UUID als requestId, der aktuellen Unix-Zeit in Millisekunden als issuedAtUnixMs und schemaVersion: 1. Die Nutzdaten dürfen höchstens 4 KiB groß sein und nur die dokumentierten Felder enthalten. Verwende QoS 0 oder 1 mit retain: false. Presenter lehnt Befehle ab, die älter als 10 Sekunden sind, mehr als 2 Sekunden in der Zukunft liegen, zu einem früheren Lauf gehören oder die Grenzwerte für Häufigkeit oder Warteschlange überschreiten. Eine doppelte requestId führt Presenter innerhalb von 30 Sekunden nicht erneut aus. Er kann das bisherige Ergebnis erneut senden. Halte die Uhren synchron und wiederhole einen Befehl mit ungewissem Ausgang nie automatisch.

const message = {
  schemaVersion: 1,
  requestId: crypto.randomUUID(),
  runId: latestState.runId,
  issuedAtUnixMs: Date.now(),
  cmd: "advance"
};
client.publish(
  `sundayassist/integrations/v1/commands/${presenterId}/control`,
  JSON.stringify(message),
  { qos: 1, retain: false }
);

Unterstützte Werte für cmd sind present, stop, advance, back, nextItem, prevItem, setBlank, goto, setPage und setStanza. setBlank braucht blanked: true oder blanked: false und schaltet nicht zwischen den Zuständen um. goto erfordert deckIndex und kann subIndex enthalten. Beide beginnen bei null. setPage erfordert page, beginnend bei eins. setStanza erfordert stanzaIndex, beginnend bei null. Andere Befehle nehmen keine zusätzlichen Felder an.

Ordne Ergebnisse anhand von requestId, runId und cmd zu. Ein Ergebnis enthält type: "presenter.command.result", schemaVersion, presenterId, requestId, runId, occurredAt, cmd, status und code. status: "executed" mit code: "ok" bedeutet, dass die Verarbeitung des Befehls abgeschlossen wurde. Was tatsächlich angezeigt wird, steht in der darauffolgenden Statusmeldung. status: "rejected" enthält einen Grund als Code. Die PUBACK-Bestätigung des Brokers ist keine Bestätigung durch Presenter. Ergebnisse werden nicht beim Broker gespeichert. Andere berechtigte Steuerungen für dasselbe Ziel können sie ebenfalls empfangen. Bei einer Zeitüberschreitung ist der Ausgang unbekannt. Prüfe Presenter, bevor du es erneut versuchst.

Die Foliensteuerung mit Node.js ausprobieren

Lade das lauffähige Beispiel herunter oder öffne die interaktive Vorschau. Mit Node.js 22 oder neuer kannst du Zurück, Weiter, Start, Stopp und Ausgabe ausblenden bzw. anzeigen mit simulierten Folien testen, ohne Broker oder Lizenz:

unzip mqtt-showcase.zip
cd mqtt-showcase
npm ci
npm run demo

Für die echte Steuerung erstelle Zugangsdaten mit Diesen Presenter steuern. Kopiere .env.example nach .env und trage die erzeugte Broker-URL, den Benutzernamen, das Passwort, das Client-ID-Präfix und die erforderliche Installations-UUID PRESENTER_ID ein. Führe npm start aus und öffne http://127.0.0.1:4188. Das Beispiel wählt nie automatisch einen Presenter. Die Zugangsdaten bleiben in Node. Der Browser empfängt den dargestellten Zustand über Server-Sent Events und sendet Tastenanfragen an den lokalen Node-Server. Ohne frischen Zustand deaktiviert der Server die Steuerung. Er wartet bis zu 8 Sekunden auf ein passendes Ergebnis von Presenter und wiederholt Befehle nie automatisch. Die Karte wird nur anhand des empfangenen Zustands aktualisiert. Halte .env geheim. Das Beispiel bindet sich an die Loopback-Adresse und ist ein lokaler Entwicklungsserver, kein gemeinsam gehosteter Dienst.

Verbinde in Node-RED einen MQTT in-Knoten mit der kopierten Broker-Adresse. Trage den erzeugten Benutzernamen, das Passwort und eine eindeutige Client-ID mit dem zugewiesenen Präfix ein. Aktiviere für die Cloud TLS mit Zertifikatsprüfung. Stelle das oben genannte Ereignis-Topic und QoS 1 ein und verbinde dann JSON → debug. Lies msg.payload.state.cue.title, prüfe msg.payload.occurredAt und verwende msg.payload.eventId, um doppelte Ereignisse vor einer Aktion auszusortieren. Siehe offizielle MQTT.js-Referenz und MQTT-Anleitungen für Node-RED.

Wähle in .env nur die Berechtigungen, die du vergeben hast. Der Node-Server fügt nie stillschweigend ein Topic für Folienansicht oder Steuerung hinzu:

ModusENABLE_CONTROLENABLE_VIEWER
Nur Folienansichtfalsetrue
Nur Steuerungtruefalse
Beidestruetrue

Das Beispiel verwendet standardmäßig nur die Steuerung. Aktiviere die Folienansicht in Presenter und setze ENABLE_VIEWER=true für eine Vorschau des aktuellen Inhalts. Setze ENABLE_CONTROL=false für eine Folienansicht ohne Steuerung. Show slide preview demonstriert das mit simuliertem Inhalt in der statischen Vorschau. Node verarbeitet Anfragen für die Folienansicht, die ausgegebenen Felder und den Ablauf der Gültigkeit. Vertrauliche MQTT-Daten bleiben auf dem Server.

Live-Text empfangen

Für lokalen Live-Text erlaube dem externen Dienst, auf church/lyrics/slide zu veröffentlichen. Lege unter Verbindungen → Handy-Fernsteuerung → Gleiches WLAN als Topic für Liedtexte den Wert church/lyrics/slide fest. Füge Live-MQTT aus der Bibliothek zum Ablauf hinzu und präsentiere das Element. Sende reinen UTF-8-Text ohne JSON-Hülle vom Dienst an den lokalen Broker.

Für Live-Text über die Complete-Cloud erstelle in derselben Organisation eigene Zugangsdaten, die nur das Abonnieren von church/lyrics/slide erlauben. Wähle in Presenter Eigener Server, gib wss://mqtt.sundayassist.com/mqtt, diese Zugangsdaten und dasselbe Topic für Liedtexte ein. Speichere und teste die Verbindung. Die lokale Handy-Verbindung bleibt verfügbar. Eigener Server nutzt diese manuelle Verbindung anstelle des automatischen Modus Von überall. Zugangsdaten für Integrationen gewähren Remote keinen Cloud-Zugriff.

Passwörter ersetzen, Zugänge widerrufen und Unterbrechungen behandeln

Lokale und Cloud-Zugangsdaten samt Steuerungsberechtigung behalten nach Neustarts und Updates von Presenter denselben Benutzernamen und dasselbe Passwort. Presenter speichert zur Passwortprüfung einen Hash. Bewahre das einmal angezeigte Passwort in deinem Dienst auf. Ein Neustart ändert runId, nicht die Zugangsdaten. Verbinde dich erneut, lies eine frische Statusmeldung und verwende die neue runId für Befehle. Diese MQTT-Zugangsdaten sind getrennt von einer Sitzung oder einem JWT deines SundayAssist-Kontos.

Passwort ersetzen macht die alten Verbindungsdaten ungültig und zeigt die neuen einmal an. Aktualisiere jeden Client, der diese Daten nutzt. Widerrufen deaktiviert die Zugangsdaten dauerhaft. Lokale Zugangsdaten bleiben bei Neustarts erhalten. Passwörter haben kein festes Ablaufdatum. Kostenpflichtiger Zugang und Berechtigungen werden weiterhin geprüft. Auch nach Ende des kostenpflichtigen Zugangs kannst du die Zugangsdaten anzeigen und widerrufen.

Die Cloud-Berechtigung und aktive Verbindungen werden etwa alle 30 Sekunden geprüft. Ein Widerruf greift nicht sofort. Eine Störung des Berechtigungsdienstes kann die Trennung um einige Minuten verzögern. Cloud-Clients müssen sich mindestens stündlich mit demselben aktuellen Passwort neu verbinden. Aktiviere automatisches Neuverbinden und erneutes Abonnieren. Bei QoS 1 können Nachrichten mehrfach eintreffen. Netzwerkausfälle, Wartung und Ausweichbetrieb können die Zustellung unterbrechen. Gestalte Aktionen so, dass eine Wiederholung keine unbeabsichtigten Folgen hat, und halte vorbereitete lokale Inhalte bereit. TLS schützt die Netzwerkverbindung, verschlüsselt Nachrichten aber nicht Ende zu Ende.

Um Ziel oder Berechtigungen zu ändern, widerrufe die Zugangsdaten und erstelle neue. Wenn du nur das Passwort ersetzt, bleiben diese Einstellungen erhalten.

Ab Presenter 1.2.6: Ab dieser Version stehen der eigene Bereich Verbindungen → Integrationen und die in dieser Anleitung beschriebenen Verbindungs-URLs zur Verfügung. Protokoll, Berechtigungen und Lizenzanforderungen gelten unverändert.