CODESYS MQTT : publier des variables automate vers un broker

La prise en charge de MQTT dans CODESYS transforme tout contrôleur basé sur CODESYS, de l'automate de marque au Raspberry Pi équipé du runtime CODESYS, en publieur direct des données de l'usine. Dans ce tutoriel, vous ajouterez la bibliothèque IIoT MQTT Client de CODESYS à un projet, publierez des variables d'automate en JSON en texte structuré, les vérifierez sur le serveur MQTT public gratuit, puis sécuriserez la connexion avec des identifiants et TLS. Au passage, vous découvrirez les pièges qui coûtent généralement une journée de mise en service.

Pourquoi CODESYS MQTT en vaut la peine

CODESYS est le runtime qui équipe une grande partie des automates et contrôleurs industriels du monde, vendus sous de nombreuses marques. Une seule approche d'intégration couvre donc beaucoup de matériel. Publier directement depuis le contrôleur présente des avantages clairs :

Pas de matériel ni de logiciel de passerelle supplémentaire à maintenir pour les petites installations.
Les données quittent le contrôleur exactement au format et au moment choisis par l'automaticien.
La logique de report by exception se trouve au plus près du process, là où les bandes mortes et les états sont le mieux compris.

La contrepartie : l'automaticien devient responsable de code réseau. Si vous connectez de nombreux contrôleurs de constructeurs différents, comparez avec les architectures à base de passerelles décrites dans connectivité des automates vers le cloud avant de vous engager.

Prérequis

Élément	Remarques
CODESYS Development System V3.5	Un service pack récent ; installez le paquet IIoT Libraries SL via le CODESYS Installer
Un runtime CODESYS	Un automate de marque, CODESYS Control Win pour les tests, ou CODESYS Control for Raspberry Pi
Licence	IIoT Libraries SL est un module complémentaire sous licence ; sans licence, il fonctionne en mode démo pour une durée limitée
Réseau	TCP 1883 sortant pour les tests, TCP 8883 pour TLS, et DNS configuré sur le contrôleur
Outils de test	mosquitto_sub, ou n'importe quel client MQTT de bureau

La bibliothèque MQTT Client SL fait partie du paquet IIoT Libraries SL, aux côtés de bibliothèques JSON et client web. Les noms exacts des broches des blocs fonctionnels peuvent légèrement varier d'une version de bibliothèque à l'autre : gardez la documentation de la bibliothèque ouverte dans le Library Manager pendant que vous travaillez.

Étape 1 : ajouter la bibliothèque MQTT

Ouvrez le Library Manager de votre application et choisissez Add Library.
Recherchez MQTT Client SL et ajoutez-la. L'espace de noms de la bibliothèque est MQTT.
Si vous comptez construire le JSON avec les fonctions utilitaires de la bibliothèque, ajoutez aussi JSON Utilities SL. Ce tutoriel construit le JSON à la main pour limiter les dépendances.
Compilez le projet une fois pour vérifier que la bibliothèque se résout sans erreur.

Étape 2 : déclarer les variables

Créez un programme, par exemple PRG_Mqtt, appelé depuis une tâche dont le cycle est compris entre 20 et 100 ms. Les blocs fonctionnels réseau doivent être appelés à chaque cycle pour faire progresser leurs machines d'état internes.

PROGRAM PRG_Mqtt
VAR
    // Valeurs process (dans un vrai projet, elles proviennent de votre logique de commande)
    rTemperature   : REAL := 21.5;
    rPressure      : REAL := 1.82;
    xPumpRunning   : BOOL := TRUE;

    // Client et publieur MQTT
    mqttClient     : MQTT.MQTTClient;
    mqttPublish    : MQTT.MQTTPublish;

    sHost          : STRING := 'broker.connectmq.com';
    uiPort         : UINT := 1883;
    sClientId      : STRING := 'codesys-demo-k8q2x7';   // doit être non vide et unique
    wsTopic        : WSTRING(255) := "connectmq/demo/k8q2x7/plant1/utilities/pumpstation1/telemetry";

    sPayload       : STRING(512);
    tonPublish     : TON;
    xTrigger       : BOOL;
    rLastTemp      : REAL;
    xLastRunning   : BOOL;
END_VAR

Deux détails comptent ici. D'abord, le client ID doit être non vide et unique ; deux contrôleurs partageant le même ID s'éjecteront mutuellement du broker en boucle. Ensuite, la longueur par défaut d'un STRING dans CODESYS est de 80 caractères, trop courte pour la plupart des payloads JSON : déclarez une longueur explicite.

Étape 3 : se connecter et publier en texte structuré

Le programme active le client, construit un payload JSON et publie soit toutes les 10 secondes, soit immédiatement lorsque la température varie de plus de 0,5 degré ou que l'état de la pompe change.

// 1. Maintenir le client actif à chaque cycle
mqttClient(
    xEnable      := TRUE,
    sHostname    := sHost,
    uiPort       := uiPort,
    eMQTTVersion := MQTT.MQTT_VERSION.V3_1_1,
    sClientId    := sClientId,
    uiKeepAlive  := 30
);

// 2. Décider quand publier : heartbeat périodique ou report by exception
tonPublish(IN := NOT tonPublish.Q, PT := T#10S);
IF tonPublish.Q
   OR ABS(rTemperature - rLastTemp) > 0.5
   OR xPumpRunning <> xLastRunning THEN
    xTrigger := TRUE;
END_IF

// 3. Construire le payload JSON
IF xTrigger AND NOT mqttPublish.xBusy THEN
    sPayload := CONCAT('{"temperature":', REAL_TO_STRING(rTemperature));
    sPayload := CONCAT(sPayload, ',"pressure":');
    sPayload := CONCAT(sPayload, REAL_TO_STRING(rPressure));
    sPayload := CONCAT(sPayload, ',"pump_running":');
    IF xPumpRunning THEN
        sPayload := CONCAT(sPayload, 'true}');
    ELSE
        sPayload := CONCAT(sPayload, 'false}');
    END_IF
    rLastTemp := rTemperature;
    xLastRunning := xPumpRunning;
END_IF

// 4. Publier sur front montant de xExecute
mqttPublish(
    xExecute       := xTrigger AND mqttClient.xConnectedToBroker,
    mqttClient     := mqttClient,
    wsTopicName    := wsTopic,
    pbPayload      := ADR(sPayload),
    udiPayloadSize := TO_UDINT(LEN(sPayload)),
    eQoS           := MQTT.QoS.AtLeastOnce,
    xRetain        := FALSE
);

IF mqttPublish.xDone OR mqttPublish.xError THEN
    xTrigger := FALSE;   // retomber xExecute pour que le prochain déclenchement crée un nouveau front montant
END_IF

Le principe à retenir est la poignée de main execute/done. MQTTPublish démarre sur un front montant de xExecute et signale xDone ou xError quelques cycles plus tard. Si vous ne faites jamais retomber xExecute, rien n'est publié une seconde fois. Si vous l'activez à chaque cycle, vous saturez le broker.

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

Chargez l'application, démarrez-la et abonnez-vous depuis un PC :

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

Vous devriez voir un message toutes les 10 secondes, plus des messages supplémentaires lorsque vous écrivez une nouvelle température ou basculez xPumpRunning depuis la vue en ligne :

{"temperature":21.5,"pressure":1.82,"pump_running":true}

Le serveur MQTT public gratuit est idéal pour cette phase de mise au point : anonyme, sans configuration et avec un retour immédiat. Il est lisible par tout le monde : utilisez donc un préfixe de topic aléatoire et aucune vraie donnée process : il sert aux tests et aux prototypes, pas à la production. Il limite aussi chaque client à 10 messages par seconde et à 64 Ko par message, un garde-fou utile pendant que vous ajustez vos déclencheurs.

Étape 5 : passer à un broker privé avec TLS

Pour la production, connectez-vous à votre propre broker avec identifiants et chiffrement :

Créez un broker dans le portail ConnectMQ et notez le nom d'utilisateur, le mot de passe et le client ID générés.
Sur le contrôleur, ouvrez le Security Screen dans CODESYS et importez l'AC racine du certificat du broker dans le magasin de certificats de confiance. Les brokers dotés de certificats Let's Encrypt remontent à ISRG Root X1.
Définissez uiPort := 8883, activez TLS sur le bloc fonctionnel client et référencez le contexte TLS comme indiqué dans la documentation de la bibliothèque.
Définissez sClientId := 'YOUR_CLIENT_ID' et passez YOUR_USERNAME et YOUR_PASSWORD aux entrées d'identifiants du client.
Remplacez le topic par votre hiérarchie de production, par exemple plant1/utilities/pumpstation1/telemetry.

Avec ConnectMQ, les client IDs sont liés aux identifiants fournis : un projet copié sur un second contrôleur avec le même ID sera refusé au lieu de voler silencieusement la session. Attribuez à chaque contrôleur ses propres identifiants. L'explorateur de topics en direct du broker affiche vos messages dès que le handshake TLS réussit.

Si exploiter et mettre à jour un broker vous-même n'est pas là où vous voulez investir votre temps, un broker MQTT managé vous décharge des certificats, des mises à niveau et de la supervision.

Dépannage de CODESYS MQTT

Le client ne se connecte jamais. Vérifiez le DNS et la passerelle par défaut du contrôleur. Testez avec une adresse IP littérale pour isoler les problèmes de résolution de noms.
Le handshake TLS échoue. Le certificat d'AC manque dans le magasin de confiance du contrôleur, ou l'horloge du contrôleur est fausse et le certificat paraît pas encore valide. Configurez NTP.
Une seule publication. xExecute n'est jamais réinitialisé ; reportez-vous à la poignée de main de l'étape 3.
Payload tronqué. Le STRING est trop court, ou udiPayloadSize a été calculé à partir d'une autre variable.
La connexion tombe toutes les quelques secondes. Un autre équipement utilise le même client ID, ou le cycle de la tâche est si lent que les paquets keep alive arrivent en retard.
Le mode démo s'arrête au bout d'un moment. La licence IIoT Libraries SL n'est pas activée sur la cible.

Checklist de mise en production

Client ID et identifiants uniques par contrôleur.
TLS sur le port 8883 avec une AC de confiance et synchronisation horaire NTP.
Construction du payload protégée contre les débordements de chaîne.
Report by exception plus un heartbeat périodique.
Un topic de statut avec Last Will pour que les consommateurs distinguent hors ligne et inactif.
Des topics conformes à la convention de nommage ISA-95 de l'usine.

Les contrôleurs Beckhoff utilisent une autre bibliothèque pour la même tâche ; consultez Beckhoff TwinCAT MQTT pour la comparaison, ou le tutoriel Siemens S7 MQTT pour TIA Portal. Pour la vue d'ensemble de l'architecture, commencez par le guide de l'IoT industriel avec MQTT.

Publiez vos données CODESYS vers ConnectMQ

Quand votre contrôleur est prêt à quitter le serveur MQTT public gratuit, donnez-lui un broker MQTT dans le cloud sécurisé. Créez un broker Serverless (Free) sur app.connectmq.com, sans carte bancaire, et collez les identifiants générés dans votre projet CODESYS.

Questions fréquentes

La bibliothèque MQTT de CODESYS est-elle gratuite ?

La bibliothèque MQTT Client SL fait partie du paquet IIoT Libraries SL, qui est sous licence. Elle peut être testée en mode démo, qui s'arrête après une durée d'exécution limitée tant qu'aucune licence n'est activée.

CODESYS MQTT prend-il en charge TLS ?

Oui. Importez l'AC racine du broker dans le magasin de certificats du contrôleur via le Security Screen, activez TLS sur le client et connectez-vous au port 8883.

CODESYS peut-il aussi s'abonner à des topics MQTT ?

Oui, la bibliothèque comprend un bloc fonctionnel d'abonnement. Validez soigneusement chaque valeur reçue avant qu'elle n'influence la logique de commande.

Quelle version de MQTT le client CODESYS utilise-t-il ?

La bibliothèque prend en charge MQTT 3.1.1, et les versions récentes ajoutent MQTT 5 ; vérifiez la documentation de la version installée. Commencez par la 3.1.1 pour une compatibilité maximale.

Client MQTT CODESYS : publier des variables d'automate vers un broker