Beckhoff TwinCAT MQTT : publier des données d'automate structurées vers un broker

La prise en charge de MQTT dans Beckhoff TwinCAT permet à un PC industriel Beckhoff de publier les données machine directement depuis le runtime automate, sans passerelle séparée dans l'armoire. Dans ce tutoriel, vous utiliserez les fonctions IoT de TwinCAT 3 pour vous connecter à un broker MQTT, sérialiser un type de données structuré en JSON, le publier sur changement et sur temporisation, puis sécuriser la connexion avec TLS et des identifiants. Le même principe s'applique d'un simple banc d'essai à une flotte de machines.

Comparatif des options MQTT de TwinCAT

Beckhoff propose plusieurs voies vers MQTT, et bien choisir dès le départ évite de refaire le travail.

Ce tutoriel utilise TF6701, car c'est le choix le plus courant chez les constructeurs de machines qui veulent que le comportement MQTT fasse partie du projet automate versionné. TF6701 et TF6720 sont toutes deux des fonctions TwinCAT sous licence ; une licence d'essai de 7 jours suffit pour suivre ce tutoriel.

Prérequis

• TwinCAT 3.1 XAE (Visual Studio ou TwinCAT XAE Shell) et une cible : un IPC Beckhoff, ou votre PC d'ingénierie en mode run pour les tests.
• La fonction TF6701 installée sur la cible avec une licence d'essai ou complète activée.
• Un accès réseau sortant de la cible vers le broker sur TCP 1883 pour les tests et 8883 pour TLS.
• Les bibliothèques automate Tc3_IotBase et Tc3_JsonXml ajoutées aux références du projet.
• Les clients mosquitto sur un PC pour la vérification.

Étape 1 : définir un type de données structuré

Publier une structure plutôt que des variables isolées garde ensemble les valeurs liées et assure des horodatages cohérents. Ajoutez un DUT :

TYPE ST_PressData :
STRUCT
    rForce_kN       : REAL;
    rTemperature_C  : REAL;
    nCycleCount     : UDINT;
    bRunning        : BOOL;
    sState          : STRING(20);
END_STRUCT
END_TYPE

Étape 2 : se connecter avec FB_IotMqttClient

FB_IotMqttClient de Tc3_IotBase se configure via des propriétés et se pilote en appelant sa méthode Execute à chaque cycle. Appelez-le depuis une tâche de 10 ms ou plus rapide ; le client gère sa propre communication en arrière-plan, mais il ne progresse que lorsque Execute est appelée.

PROGRAM MAIN
VAR
    fbMqttClient   : FB_IotMqttClient;
    bSetParameter  : BOOL := TRUE;
    bConnect       : BOOL := TRUE;

    fbJson         : FB_JsonSaxWriter;
    stPress        : ST_PressData;
    stLastPress    : ST_PressData;

    sTopicData     : STRING(255) := 'connectmq/demo/t3w9p1/plant1/stamping/cell4/press1/telemetry';
    sPayload       : STRING(1023);
    fbHeartbeat    : TON;
    bPublish       : BOOL;
END_VAR

// --- Configuration unique du client ---
IF bSetParameter THEN
    bSetParameter := FALSE;
    fbMqttClient.sHostName  := 'broker.connectmq.com';
    fbMqttClient.nHostPort  := 1883;
    fbMqttClient.sClientId  := 'twincat-demo-t3w9p1';   // non vide et unique
    fbMqttClient.nKeepAlive := 30;
END_IF

// --- Maintenir la connexion à chaque cycle ---
fbMqttClient.Execute(bConnect);

// --- Décider quand publier : sur changement ou toutes les 10 s ---
fbHeartbeat(IN := NOT fbHeartbeat.Q, PT := T#10S);
bPublish := fbHeartbeat.Q
            OR ABS(stPress.rForce_kN - stLastPress.rForce_kN) > 1.0
            OR stPress.bRunning <> stLastPress.bRunning
            OR stPress.sState <> stLastPress.sState;

// --- Sérialiser et publier ---
IF bPublish AND fbMqttClient.bConnected THEN
    fbJson.ResetDocument();
    fbJson.StartObject();
    fbJson.AddKey('force_kN');       fbJson.AddReal(stPress.rForce_kN);
    fbJson.AddKey('temperature_C');  fbJson.AddReal(stPress.rTemperature_C);
    fbJson.AddKey('cycle_count');    fbJson.AddUdint(stPress.nCycleCount);
    fbJson.AddKey('running');        fbJson.AddBool(stPress.bRunning);
    fbJson.AddKey('state');          fbJson.AddString(stPress.sState);
    fbJson.EndObject();
    fbJson.CopyDocument(sPayload, SIZEOF(sPayload));

    fbMqttClient.Publish(
        sTopic       := sTopicData,
        pPayload     := ADR(sPayload),
        nPayloadSize := LEN(sPayload),
        eQoS         := TcIotMqttQos.AtLeastOnceDelivery,
        bRetain      := FALSE,
        bQueue       := FALSE);

    stLastPress := stPress;
END_IF

Quelques remarques sur ces choix :

• CopyDocument plutôt que GetDocument. GetDocument renvoie une chaîne standard de 255 caractères, qui tronque silencieusement les payloads plus longs. La copie dans un buffer dimensionné évite ce problème.
• Report by exception. La bande morte sur la force et les comparaisons d'état publient immédiatement les vrais changements, tandis que le heartbeat de 10 secondes prouve que la machine est vivante même quand rien ne change.
• Gestion des erreurs. Surveillez fbMqttClient.hrErrorCode et fbMqttClient.eConnectionState dans la vue en ligne pendant la mise en service. La plupart des défaillances s'y manifestent en premier.

Pour les structures plus grandes, Tc3_JsonXml propose aussi une fonction utilitaire qui sérialise un type de données entier, y compris des attributs comme les unités, en un seul appel. Une sortie SAX écrite à la main comme ci-dessus vous donne un contrôle exact sur les noms de clés, ce qui compte quand d'autres équipes consomment les données.

Étape 3 : vérifier sur le serveur MQTT public gratuit

Activez la configuration, démarrez l'automate et abonnez-vous depuis un PC :

mosquitto_sub -h broker.connectmq.com -p 1883 -i twincat-watch-t3w9p1 \
  -t 'connectmq/demo/t3w9p1/#' -v

Résultat attendu :

connectmq/demo/t3w9p1/plant1/stamping/cell4/press1/telemetry {"force_kN":412.5,"temperature_C":38.2,"cycle_count":10233,"running":true,"state":"AUTO"}

Forcez une valeur dans la vue en ligne : le changement apparaît instantanément. Le serveur MQTT public gratuit broker.connectmq.com, anonyme, est parfait pour ce type de mise au point, mais il est public et réservé aux tests : utilisez un préfixe de topic aléatoire et rien de confidentiel.

Étape 4 : sécuriser la connexion Beckhoff TwinCAT MQTT

Des machines de production ne doivent jamais publier en TCP en clair vers Internet. Créez un broker privé dans le portail ConnectMQ, notez le nom d'utilisateur, le mot de passe et le client ID générés, puis :

1. Téléchargez le certificat ISRG Root X1 (la racine de Let's Encrypt, utilisée par le broker ConnectMQ) et copiez-le sur la cible, par exemple dans un dossier Certificates sous le répertoire boot ou config de TwinCAT.
2. Complétez la configuration initiale :

fbMqttClient.sHostName     := 'YOUR_BROKER_HOST';
fbMqttClient.nHostPort     := 8883;
fbMqttClient.sClientId     := 'YOUR_CLIENT_ID';
fbMqttClient.sUserName     := 'YOUR_USERNAME';
fbMqttClient.sUserPassword := 'YOUR_PASSWORD';
fbMqttClient.stTLS.sCA     := 'C:\TwinCAT\3.1\Config\Certificates\isrgrootx1.pem';

3. Configurez un Last Will via la structure will du client, par exemple un message offline retenu sur plant1/stamping/cell4/press1/status, et publiez un online retenu sur le même topic après la connexion. Les consommateurs peuvent alors distinguer une machine arrêtée d'une connexion perdue.
4. Supprimez le préfixe de démonstration et utilisez la hiérarchie de topics ISA-95 de votre usine.

Gardez les identifiants hors du contrôle de version : chargez-les depuis un fichier sur la cible ou depuis une variable persistante renseignée lors de la mise en service, plutôt que de les coder en dur dans un projet partagé.

Concevoir les topics pour une flotte de machines

Les constructeurs de machines livrent souvent le même projet TwinCAT à des dizaines de clients : des topics codés en dur deviennent vite un casse-tête de maintenance. Quelques habitudes aident :

• Faites du préfixe de topic un paramètre. Stockez les noms d'entreprise, de site, de zone, de ligne et de machine dans des variables persistantes renseignées à la mise en service, et construisez la chaîne de topic au démarrage.
• Séparez données, statut et événements. Utilisez .../telemetry pour les valeurs périodiques, .../status pour les informations d'état et de présence retenues, et .../events pour les alarmes ou les fins de lot. Les consommateurs s'abonnent uniquement à ce dont ils ont besoin.
• Versionnez votre payload. Une clé "schema": 1 coûte quelques octets et permet au code en aval de gérer une mise à jour du firmware qui ajoute ou renomme des champs.
• Gardez des payloads compacts. Publiez les valeurs réellement utilisées. Les vidages de diagnostic peuvent aller sur un topic séparé, à la demande.

Ces conventions rendent aussi les données faciles à parcourir : un broker qui reconnaît les chemins de style ISA-95 peut présenter chaque machine dans une arborescence de sites et de lignes sans configuration supplémentaire.

Checklist de mise en service

Dépannage

• hrErrorCode indique un refus de connexion. Identifiants ou client ID erronés ; sur les brokers qui lient les client IDs aux identifiants, les deux doivent correspondre à ce qui a été fourni.
• Erreurs TLS après un redémarrage. Le chemin du certificat est erroné sur la cible, ou le fichier d'AC n'a pas été copié avec le projet de boot.
• Rien n'est publié malgré bConnected. bPublish n'est jamais vrai, ou Publish est appelée avant la construction du payload.
• Les messages arrivent par rafales. bQueue := TRUE avec une fréquence d'appel de Execute trop lente ; appelez Execute à chaque cycle depuis une tâche rapide.

La place de cette approche

Publier depuis l'IPC n'est qu'une des architectures possibles pour sortir les données machine ; comparez-la aux architectures à base de passerelles et de SCADA dans connectivité des automates vers le cloud. Si vous travaillez avec des contrôleurs de marques différentes, le tutoriel CODESYS MQTT utilise un principe execute-and-publish très similaire. Et lorsque de nombreuses machines publient dans une même hiérarchie, le guide de l'IoT industriel avec MQTT explique comment la modéliser en Unified Namespace que chaque application peut consommer via le broker MQTT.

Connectez vos machines Beckhoff à ConnectMQ

Exploiter votre propre broker à côté de chaque machine implique certificats, mises à jour et supervision sur chaque site. Un broker MQTT managé supprime ce travail. Créez un broker Serverless gratuit sur app.connectmq.com, sans carte bancaire, et regardez vos données TwinCAT arriver dans l'explorateur de topics en direct en quelques minutes.

Questions fréquentes

Quelle licence TwinCAT faut-il pour MQTT ?

L'approche par bibliothèque automate nécessite TF6701 TwinCAT 3 IoT Communication. L'alternative par configuration est TF6720 IoT Data Agent. Toutes deux proposent une licence d'essai de 7 jours.

TwinCAT MQTT prend-il en charge TLS ?

Oui. Indiquez le chemin du certificat d'AC dans la structure TLS du client, connectez-vous au port 8883 et ajoutez les identifiants. Les certificats clients sont également pris en charge si votre broker les exige.

TwinCAT peut-il s'abonner à des topics MQTT ?

Oui. FB_IotMqttClient prend en charge les abonnements avec une file de messages que vous lisez dans l'automate. Validez chaque valeur reçue avant qu'elle n'atteigne la logique de commande.

Pourquoi mon payload JSON est-il coupé à 255 caractères ?

GetDocument renvoie une chaîne de longueur standard. Utilisez CopyDocument vers un buffer plus grand, comme montré ci-dessus.