TCP/UDP-Integration

TCP/UDP-Integration

Das TCP/UDP-Protokoll ist für Geräte gedacht, die eine einfache Befehlssprache direkt über einen Netzwerk-Socket sprechen – ohne Web-API, ohne Registermodell: professionelle Audioplayer und -matrizen (AUDAC XMP44 und SourceCon-Module), Projektoren (PJLink), Displays und Verstärker hinter RS-232-over-IP-Bridges sowie eigene Mikrocontroller-Boards. Sie beschreiben die Befehls-Frames, die HyperVisu bei einer Wertänderung sendet, die Muster, die Werte aus den Antwort-Frames des Geräts extrahieren, und optionale Abfrage-Frames für das Polling. Das gesamte gerätespezifische Wissen liegt in der Konfiguration, nichts davon im Server.

Jede Verbindung entspricht einem Gerät, über TCP (eine dauerhafte Verbindung, die offen gehalten und automatisch wiederhergestellt wird) oder UDP (Datagramme). Über TCP teilen sich alle Objekte des Geräts diesen einzelnen Socket – was für Geräte erforderlich ist, die nur einen einzigen Client akzeptieren (wie der XMP44).

Was Sie benötigen: die IP-Adresse und den Port des Geräts, dessen Befehlsreferenz (Frame-Syntax, Trennzeichen, die Befehle und die Rückmeldungen) und die Information, ob es Statusänderungen selbstständig sendet (Push) oder abgefragt werden muss (Pull).

Verbindungen. TCP/UDP ist mandantenfähig: eine Verbindung pro Gerät (siehe „Verbindungen“). Felder:

Der Dialog Verbindung hinzufügen fordert den Instanznamen, die Geräteadresse, den Port, das Abfrageintervall (Sekunden), den Transport und das Frame-Trennzeichen an (Standardwerte 30, TCP · dauerhafte Verbindung und \r\n). Die weiteren Felder befinden sich unter Framing und Timing der gespeicherten Verbindung: Wählen Sie die neue Verbindung aus, tragen Sie die Werte ein und klicken Sie auf Verbindung speichern.

Testen im Dialog Verbindung hinzufügen öffnet einen Socket zur eingegebenen Adresse. Dies bestätigt nur die Erreichbarkeit des Geräts, nicht das Verständnis der Befehls-Frames. Bei einer bereits bestehenden Verbindung, während der Dienst den Socket bereits belegt, gibt Testen den aktuellen Live-Status sowie die ein- und ausgehenden Frames aus, anstatt einen zweiten Socket zu öffnen.

Binden eines Objekts (siehe „TCP/UDP-Bindung“ unten). Pro Objekt vergeben Sie einen Schlüssel – ein kurzer Text, der in jeder Rückmeldung enthalten ist, die diesen Wert überträgt: Nur eingehende Frames, die diesen Schlüssel enthalten, werden mit dem Match-Muster des Objekts abgeglichen (bei AUDAC der Name des Rückmeldebefehls: OG1, FREQ2). Der Abgleich berücksichtigt Groß-/Kleinschreibung, und der Schlüssel darf kein : enthalten. Zwei Objekte können denselben Schlüssel nutzen, beispielsweise ein Befehlsobjekt und dessen Rückmeldeobjekt. Die Administration speichert <Verbindung>:<Schlüssel>. Der Rest ist der Datentyptyp-String des Objekts, der aus den Feldern des Editors generiert wird:

Templates nutzen ${value}, ergänzt durch ${value:d} zum Runden eines skalierten Werts auf eine Ganzzahl (z. B. ein 0–100 % Schieberegler an einem Gerät mit Integer-Parametern), ${value:02d} für Ganzzahlen mit führenden Nullen, ${value:1f} für feste Dezimalstellen sowie im HEX-Modus ${value:u8}, ${value:u16be}, ${value:u16le}, ${value:u32be}, ${value:u32le} für feste Bytebreiten. \r, \n, \t und \xNN dienen als Byte-Escapes. Im ASCII-Modus wird das Trennzeichen automatisch angehängt, falls es im Template fehlt.

Match-Muster verwenden folgende Tokens; alle anderen Zeichen werden exakt abgeglichen:

Der Editor zeigt unter Gesendeter Frame die Steuerzeichen sichtbar an (# | D001 | hv | SOG1 | 28 | U | <CR><LF>) sowie den gespeicherten String. Gesendeter Frame ist eine Vorschau, kein Protokoll: Jedes ${value…} wird durch den Beispielwert 28 ersetzt, ohne Wertformatierung oder Skalierung, und bei Objekten mit getrennten EIN-/AUS-Befehlen wird nur der EIN-Befehl dargestellt. Das im ASCII-Modus vom Server automatisch angehängte Trennzeichen ist hier nicht sichtbar. Prüfen Sie reale Befehle und Rückmeldungen direkt am Gerät.

Wichtiges Betriebsverhalten

• Richtung. In-Objekte werten Rückmeldungen aus (und pollen bei hinterlegter Abfrage); Out-Objekte senden; In/Out-Objekte führen beides aus – das Echo des Geräts dient als Bestätigung, analog zu KNX-Statusobjekten.
• Ein Frame, mehrere Objekte. Jeder eingehende Frame wird gegen alle In-Objekte der Verbindung geprüft, deren Schlüssel im Frame vorkommt; somit kann ein einzelner Status-Frame mehrere Objekte speisen. Identische Abfrage-Templates werden pro Abfragezyklus nur einmal gesendet.
• TCP. Nach einem Verbindungsabbruch erfolgt die Wiederverbindung mit gestaffelter Verzögerung; bei erfolgreichem Neuaufbau werden die Abfragen erneut ausgeführt, wenn Alles beim Verbinden lesen aktiv ist. Ausgehende Frames durchlaufen eine Warteschlange gemäß der Verzögerung zwischen Befehlen.
• UDP. Ein Datagramm entspricht einem Frame. Unaufgeforderte Pushes erfordern den Listen-Port.
• Befehle, die gesendet werden, während das Gerät offline ist, schlagen fehl, ohne das System zu blockieren; die App behält den zuletzt bekannten Status bei.

Praxisbeispiel – AUDAC XMP44 Mediaplayer

Der XMP44 lauscht auf TCP-Port 5001, unterstützt nur einen Client und arbeitet mit Frames im Format # | D001 | <Quelle> | <Befehl> | <Parameter> | <Prüfsumme> | <CR><LF> – das Literal U wird als Prüfsumme akzeptiert. Das Setzen des Ausgangspegels erfolgt über SOG1 | <arg> mit arg = 8 − dB; das Gerät antwortet mit dem Update-Frame … | OG1 | <arg> | …, der auch bei manueller Pegeländerung am Frontpanel gesendet wird. Play und Stop sind zwei separate Befehle (SPPLAY1, SPSTOP1).

1. Erstellen Sie eine TCP/UDP-Verbindung (siehe „Verbindungen“): Adresse 192.168.1.60, Port 5001, Transport TCP, Trennzeichen \r\n, Abfrageintervall 30. Klicken Sie auf Testen, dann auf Verbindung erstellen. Wählen Sie die Verbindung aus, belassen Sie unter Framing und Timing die Option Alles beim Verbinden lesen aktiviert und hinterlegen Sie den Heartbeat # | D001 | hv | GTPS | 0 | U | \r\n alle 120 s. Klicken Sie auf Verbindung speichern.

2. Fügen Sie unter Geräte ein Audio-Widget "XMP44 Player" hinzu und wählen Sie unter Protokoll diese Verbindung aus.

3. Am Lautstärke-Objekt (In/Out): Schlüssel OG1, Befehls-Template # | D001 | hv | SOG1 | ${value:d} | U | \r\n, Abfrage-Template # | D001 | hv | GOG1 | 0 | U | \r\n, Match-Muster \i | OG1 | \i\v, Skalierung -1, Offset 8 – damit wird −20 dB als 28 gesendet und ein empfangener Wert von 28 als −20 dB interpretiert.

4. Am Wiedergabe-Objekt (Out, boolesch): Schlüssel PLAY1, Unterschiedliche Befehle für EIN und AUS: EIN # | D001 | hv | SPPLAY1 | 0 | U | \r\n, AUS # | D001 | hv | SPSTOP1 | 0 | U | \r\n.

5. Am Titel-Objekt (In, Text): Schlüssel SON1, Abfrage # | D001 | hv | GSON1 | 0 | U | \r\n, Match \i | SON1 | \i\a | .

6. Klicken Sie bei jedem Objekt auf Objekt speichern, danach in der Seitenleiste auf Änderungen übernehmen und bestätigen Sie. Das Bewegen des Lautstärkereglers sendet SOG1, das Echo OG1 des Geräts bestätigt den neuen Pegel, und manuelle Änderungen am Gerät erscheinen direkt in der App.

💡 Tipp: Halten Sie die Befehlsreferenz des Herstellers beim Verknüpfen bereit – der Schlüssel entspricht dem Rückmelde-Namen (OG1), der sich bei AUDAC vom Sendebefehl (SOG1) unterscheidet.

TCP/UDP-Bindung

TCP/UDP-Objekte werden im Dialog der Objekteinstellungen konfiguriert (siehe „Objekteinstellungen, Logging & Benachrichtigungen“). Die Bereiche umfassen:

Frame-Adressierung

Gesendete Befehle (ausgehende Objekte)

Zurückgelesene Werte (eingehende Objekte)

Unterhalb der Bereiche zeigt Gesendeter Frame den aufgelösten Sende-Frame für einen Beispielwert mit sichtbaren Steuerzeichen an (… | 28 | U | <CR><LF>), und Gespeichert als zeigt den finalen Datentyp-String. Die Mustersyntax, Templates und ein AUDAC-Praxisbeispiel finden Sie im obigen Abschnitt zu TCP/UDP.