Intégration TCP/UDP

Intégration TCP/UDP

Le protocole TCP/UDP est destiné aux appareils qui communiquent via un jeu de commandes simple directement sur une socket réseau — sans API web ni modèle de registres : lecteurs audio professionnels et matrices (AUDAC XMP44 et modules SourceCon), vidéoprojecteurs (PJLink), écrans et amplificateurs derrière des passerelles RS-232 sur IP, ainsi que cartes à microcontrôleur personnalisées. Vous décrivez les trames de commande que HyperVisu envoie lorsqu'une valeur change, les motifs (patterns) qui extraient les valeurs des trames retournées par l'appareil, et les trames d'interrogation optionnelles pour la scrutation. Toutes les spécificités de l'appareil sont définies dans la configuration, aucune dans le serveur.

Chaque connexion correspond à un appareil, via TCP (une connexion persistante, maintenue ouverte et reconnectée automatiquement) ou UDP (datagrammes). En TCP, tous les objets de l'appareil partagent cette socket unique — ce qu'exigent les équipements qui n'acceptent qu'un seul client (comme le XMP44).

Ce dont vous avez besoin : l'adresse IP et le port de l'appareil, sa documentation de commandes (syntaxe des trames, délimiteur, commandes et retours d'état envoyés), et s'il transmet ses changements d'état spontanément ou sur interrogation.

Connexions. TCP/UDP prend en charge plusieurs connexions : une connexion par appareil (voir « Connexions »). Champs :

La boîte de dialogue Add connection demande le Instance Name, le Device address, le Port, le Poll Interval (seconds), le Transport et le Frame delimiter (valeurs par défaut : 30, TCP · persistent connection et \r\n). Les autres champs se trouvent sous Framing and timing sur la connexion enregistrée : sélectionnez la nouvelle connexion, configurez-les et cliquez sur Save connection.

Le bouton Test dans la boîte de dialogue Add connection ouvre une socket vers l'adresse saisie. Cela confirme que l'appareil est accessible, pas qu'il comprend vos trames. Sur une connexion enregistrée, alors que le service occupe déjà la connexion unique de l'appareil, Test affiche l'état en direct ainsi que le décompte des trames entrantes et sortantes au lieu d'ouvrir une seconde socket.

Liaison d'un objet (voir « Liaison TCP/UDP » ci-dessous). Pour chaque objet, vous définissez une Key — un court texte présent dans chaque réponse contenant cette valeur : seules les trames entrantes contenant la clé sont analysées avec le motif d'extraction de l'objet (pour AUDAC, le nom de la commande de retour : OG1, FREQ2). La comparaison est sensible à la casse et une clé ne peut pas contenir :. Deux objets peuvent partager une clé, par exemple un objet de commande et son objet de retour d'état. L'administration enregistre <connexion>:<clé>. Le reste constitue la chaîne du type de données de l'objet, générée à partir des champs de l'éditeur :

Les modèles (templates) utilisent ${value}, ainsi que ${value:d} pour arrondir une valeur mise à l'échelle à un entier (curseur 0–100 % sur un appareil attendant des arguments entiers), ${value:02d} pour un entier complété par des zéros et ${value:1f} pour un nombre fixe de décimales, et en mode HEX ${value:u8}, ${value:u16be}, ${value:u16le}, ${value:u32be}, ${value:u32le} pour des octets de taille fixe. \r, \n, \t et \xNN sont des caractères d'échappement d'octets. En mode ASCII, si le délimiteur est omis dans un modèle, il est ajouté automatiquement.

Les motifs d'extraction (match patterns) utilisent ces identifiants ; tout le reste est comparé littéralement :

L'éditeur affiche Frame sent avec les caractères de contrôle visibles (# | D001 | hv | SOG1 | 28 | U | <CR><LF>), ainsi que la chaîne enregistrée. Frame sent est un aperçu, pas un journal : chaque ${value…} est remplacé par la valeur d'exemple 28, sans le formatage de la valeur ni la mise à l'échelle, et pour un objet avec des commandes ON et OFF distinctes, seule la commande ON est affichée. Il n'affiche pas le délimiteur ajouté automatiquement par le serveur en mode ASCII. Vérifiez une commande et une réponse réelles avec l'appareil.

Comportements à retenir

• Direction. Les objets In analysent les retours (et scrutent s'ils ont une requête) ; les objets Out transmettent ; les objets In/Out font les deux — l'écho de l'appareil sert de confirmation, comme pour les objets d'état KNX.
• Une trame, plusieurs objets. Chaque trame entrante est testée par rapport à tous les objets entrants de la connexion dont elle contient la clé, ainsi une seule trame d'état peut alimenter plusieurs objets. Les modèles d'interrogation identiques sont envoyés une seule fois par cycle de scrutation.
• TCP. La connexion est rétablie avec des délais croissants après un échec ; lors de la reconnexion, les requêtes sont réexécutées lorsque Read everything on connect est activé. Les trames sortantes passent par une file d'attente espacée par Delay between commands.
• UDP. Un datagramme équivaut à une trame. Les réceptions spontanées nécessitent la configuration du Listen port.
• Les commandes envoyées alors que l'appareil est inaccessible échouent sans bloquer le système ; l'application affiche le dernier état connu.

Exemple pratique — Lecteur multimédia AUDAC XMP44

Le XMP44 écoute sur le port TCP 5001, accepte un seul client et communique via des trames # | D001 | <source> | <command> | <argument> | <checksum> | <CR><LF> — la lettre U est acceptée comme somme de contrôle. La définition du gain de sortie s'effectue via SOG1 | <arg> avec arg = 8 − dB ; l'appareil répond par une trame de mise à jour … | OG1 | <arg> | …, qu'il diffuse également lorsque le gain est modifié en façade. La lecture et l'arrêt correspondent à deux commandes distinctes (SPPLAY1, SPSTOP1).

1. Créez une connexion TCP/UDP (voir « Connexions ») : adresse 192.168.1.60, port 5001, transport TCP, délimiteur \r\n, intervalle de scrutation 30. Cliquez sur Test, puis sur Create connection. Sélectionnez la nouvelle connexion et, sous Framing and timing, laissez Read everything on connect activé et définissez le heartbeat # | D001 | hv | GTPS | 0 | U | \r\n toutes les 120 s. Cliquez sur Save connection.

2. Dans Devices, ajoutez un widget Audio « Lecteur XMP44 » et sélectionnez cette connexion sous Protocol.

3. Sur l'objet volume (In/Out) : clé OG1, modèle de commande # | D001 | hv | SOG1 | ${value:d} | U | \r\n, modèle d'interrogation # | D001 | hv | GOG1 | 0 | U | \r\n, motif d'extraction \i | OG1 | \i\v, échelle -1, décalage 8 — ainsi, −20 dB est envoyé sous la forme 28 et un 28 reçu est lu comme −20 dB.

4. Sur l'objet lecture (Out, booléen) : clé PLAY1, Different commands for ON and OFF : ON # | D001 | hv | SPPLAY1 | 0 | U | \r\n, OFF # | D001 | hv | SPSTOP1 | 0 | U | \r\n.

5. Sur l'objet titre de la piste (In, texte) : clé SON1, interrogation # | D001 | hv | GSON1 | 0 | U | \r\n, motif \i | SON1 | \i\a | .

6. Cliquez sur Save object pour chaque objet, puis sur Apply changes dans la barre latérale et confirmez. Le déplacement du curseur de volume envoie SOG1, le retour OG1 de l'appareil confirme le nouveau niveau, et toute modification effectuée sur la façade de l'appareil apparaît dans l'application.

💡 Conseil : Gardez la documentation des commandes de l'appareil ouverte lors de la liaison — la clé correspond au nom du retour d'état (OG1), qui chez AUDAC diffère du nom de la commande (SOG1).

Liaison TCP/UDP

Les objets TCP/UDP sont configurés dans la boîte de dialogue des paramètres d'objet (voir « Paramètres d'objet, journalisation et notifications »). Les sections sont :

Adressage de trame

Commandes envoyées (objets sortants)

Valeurs relues (objets entrants)

Sous les sections, Frame sent montre la trame sortante résolue pour une valeur d'exemple avec les caractères de contrôle visibles (… | 28 | U | <CR><LF>), et Stored as affiche la chaîne du type de données enregistrée. La syntaxe des motifs, les modèles et un exemple pratique AUDAC sont détaillés dans le chapitre TCP/UDP ci-dessus.