Cliente CODESYS MQTT: publica variables del PLC

El soporte de CODESYS MQTT convierte cualquier controlador basado en CODESYS, desde un PLC de fabricante hasta una Raspberry Pi con el runtime de CODESYS, en un publicador directo de datos de planta. En este tutorial añadirás la librería IIoT MQTT Client de CODESYS a un proyecto, publicarás variables del PLC en JSON con texto estructurado, las verificarás en un servidor público y después protegerás la conexión con credenciales y TLS. Por el camino verás los errores que suelen costar un día de puesta en marcha.

Por qué merece la pena CODESYS MQTT

CODESYS es el runtime que hay detrás de una gran parte de los PLC y controladores industriales del mundo, vendidos bajo muchas marcas de fabricantes. Eso significa que un único enfoque de integración cubre mucho hardware. Publicar directamente desde el controlador tiene ventajas claras:

Sin hardware ni software de gateway adicional que mantener en instalaciones pequeñas.
Los datos salen del controlador exactamente en el formato y en el momento que decide el programador del PLC.
La lógica de report by exception vive junto al proceso, donde mejor se entienden las bandas muertas y los estados.

La contrapartida es que el programador del PLC pasa a ser responsable de código de red. Si vas a conectar muchos controladores de distintos fabricantes, compáralo con los diseños basados en gateway de conectividad de PLC a la nube antes de decidirte.

Requisitos previos

Elemento	Notas
CODESYS Development System V3.5	Un service pack reciente; instala el paquete IIoT Libraries SL mediante el CODESYS Installer
Un runtime CODESYS	Un PLC de fabricante, CODESYS Control Win para pruebas o CODESYS Control for Raspberry Pi
Licencia	IIoT Libraries SL es un complemento con licencia; sin ella funciona en modo demo durante un tiempo limitado
Red	Salida por TCP 1883 para pruebas, TCP 8883 para TLS y DNS configurado en el controlador
Herramientas de prueba	mosquitto_sub o cualquier cliente MQTT de escritorio

La librería MQTT Client SL forma parte del paquete IIoT Libraries SL, junto con librerías de JSON y de cliente web. Los nombres exactos de los pines de los bloques de función pueden variar ligeramente entre versiones de la librería, así que ten abierta la documentación de la librería en el Library Manager mientras trabajas.

Paso 1: añadir la librería MQTT

Abre el Library Manager en tu aplicación y elige Add Library.
Busca MQTT Client SL y añádela. El namespace de la librería es MQTT.
Si piensas construir el JSON con funciones auxiliares de librería, añade también JSON Utilities SL. Este tutorial construye el JSON a mano para minimizar dependencias.
Compila el proyecto una vez para confirmar que la librería se resuelve sin errores.

Paso 2: declarar las variables

Crea un programa, por ejemplo PRG_Mqtt, llamado desde una tarea con un ciclo de 20 a 100 ms. Los bloques de función de red deben llamarse en cada ciclo para que avancen sus máquinas de estado internas.

PROGRAM PRG_Mqtt
VAR
    // Process values (in a real project these come from your control logic)
    rTemperature   : REAL := 21.5;
    rPressure      : REAL := 1.82;
    xPumpRunning   : BOOL := TRUE;

    // MQTT client and publisher
    mqttClient     : MQTT.MQTTClient;
    mqttPublish    : MQTT.MQTTPublish;

    sHost          : STRING := 'broker.connectmq.com';
    uiPort         : UINT := 1883;
    sClientId      : STRING := 'codesys-demo-k8q2x7';   // must be non-empty and unique
    wsTopic        : WSTRING(255) := "connectmq/demo/k8q2x7/plant1/utilities/pumpstation1/telemetry";

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

Aquí importan dos detalles. Primero, el client ID no puede estar vacío y debe ser único; dos controladores que compartan un ID se expulsarán mutuamente del broker una y otra vez. Segundo, la longitud por defecto de STRING en CODESYS es de 80 caracteres, demasiado corta para la mayoría de payloads JSON, así que declara una longitud explícita.

Paso 3: conectar y publicar con texto estructurado

El programa habilita el cliente, construye un payload JSON y publica cada 10 segundos o de inmediato cuando la temperatura varía más de 0,5 grados o cambia el estado de la bomba.

// 1. Keep the client running every cycle
mqttClient(
    xEnable      := TRUE,
    sHostname    := sHost,
    uiPort       := uiPort,
    eMQTTVersion := MQTT.MQTT_VERSION.V3_1_1,
    sClientId    := sClientId,
    uiKeepAlive  := 30
);

// 2. Decide when to publish: periodic heartbeat or 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. Build the JSON payload
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. Publish on a rising edge of 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;   // drop xExecute so the next trigger creates a new rising edge
END_IF

El patrón que hay que recordar es el handshake execute/done. MQTTPublish arranca en un flanco de subida de xExecute e informa de xDone o xError algunos ciclos después. Si nunca bajas xExecute, no se vuelve a publicar nada. Si lo subes en cada ciclo, saturas el broker.

Paso 4: verificar en el servidor MQTT público gratuito

Descarga la aplicación, iníciala y suscríbete desde un PC:

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

Deberías ver un mensaje cada 10 segundos, además de mensajes adicionales cuando escribas una nueva temperatura o cambies xPumpRunning desde la vista online:

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

El servidor MQTT público gratuito es ideal para esta fase de puesta en marcha: anónimo, sin configuración y con respuesta rápida. Cualquiera puede leerlo y está pensado solo para pruebas y prototipos, así que usa un prefijo de topic aleatorio y ningún dato de proceso real. Además limita cada cliente a 10 mensajes por segundo y 64 KB por mensaje, una protección útil mientras ajustas tus disparadores.

Paso 5: pasar a un broker privado con TLS

Para producción, conéctate a tu propio broker con credenciales y cifrado:

Crea un broker en el portal de ConnectMQ y anota el usuario, la contraseña y el client ID generados.
En el controlador, abre la Security Screen de CODESYS e importa la CA raíz del certificado del broker en el almacén de certificados de confianza. Los brokers con certificados de Let's Encrypt se encadenan a ISRG Root X1.
Fija uiPort := 8883, habilita TLS en el bloque de función del cliente y referencia el contexto TLS como se describe en la documentación de la librería.
Fija sClientId := 'YOUR_CLIENT_ID' y pasa YOUR_USERNAME y YOUR_PASSWORD a las entradas de credenciales del cliente.
Cambia el topic a tu jerarquía de producción, como plant1/utilities/pumpstation1/telemetry.

En ConnectMQ, los client ID están vinculados a las credenciales emitidas, así que un proyecto copiado en un segundo controlador con el mismo ID será rechazado en lugar de robar la sesión en silencio. Da a cada controlador sus propias credenciales. El explorador de topics en vivo del broker muestra tus mensajes en cuanto el handshake TLS tiene éxito.

Si gestionar y parchear un broker por tu cuenta no es en lo que quieres invertir tu tiempo, un broker MQTT gestionado se encarga de certificados, actualizaciones y monitorización.

Solución de problemas de CODESYS MQTT

El cliente nunca conecta. Revisa el DNS y la puerta de enlace predeterminada del controlador. Prueba con una IP literal para aislar problemas de resolución de nombres.
Falla el handshake TLS. Falta el certificado de la CA en el almacén de confianza del controlador, o el reloj del controlador está mal y el certificado parece aún no válido. Configura NTP.
Solo publica una vez. xExecute nunca se resetea; consulta el handshake del paso 3.
Payload truncado. El STRING es demasiado corto, o udiPayloadSize se calculó a partir de otra variable.
La conexión se cae cada pocos segundos. Otro dispositivo usa el mismo client ID, o el ciclo de la tarea es tan lento que los paquetes de keep alive llegan tarde.
El modo demo se detiene al cabo de un rato. La licencia de IIoT Libraries SL no está activada en el destino.

Lista de comprobación para producción

Client ID y credenciales únicos por controlador.
TLS en el puerto 8883 con una CA de confianza y sincronización horaria NTP.
Constructor de payloads protegido contra desbordamiento de strings.
Report by exception más un latido (heartbeat) periódico.
Un topic de estado con Last Will para que los consumidores distingan desconectado de inactivo.
Los topics siguen la convención de nombres ISA-95 de la planta.

Con una jerarquía ISA-95 limpia, los mismos topics del PLC pueden alimentar tanto un dashboard como un gemelo digital 3D de la línea, sea en una planta de Monterrey o de Valencia.

Los controladores Beckhoff usan otra librería para la misma tarea; consulta Beckhoff TwinCAT MQTT para la comparación, o el tutorial Siemens S7 MQTT para TIA Portal. Para el panorama de arquitectura general, empieza por la guía de IoT industrial con MQTT.

Publica tus datos de CODESYS en ConnectMQ

Cuando tu controlador esté listo para dejar el broker de pruebas, dale un broker MQTT en la nube seguro. Crea un broker Serverless gratuito en app.connectmq.com, sin tarjeta de crédito, y pega las credenciales generadas en tu proyecto CODESYS.

Preguntas frecuentes

¿Es gratuita la librería MQTT de CODESYS?

La librería MQTT Client SL forma parte del paquete IIoT Libraries SL, que requiere licencia. Puede probarse en modo demo, que se detiene tras un tiempo de ejecución limitado hasta que se activa una licencia.

¿Admite CODESYS MQTT el uso de TLS?

Sí. Importa la CA raíz del broker en el almacén de certificados del controlador mediante la Security Screen, habilita TLS en el cliente y conéctate al puerto 8883.

¿Puede CODESYS suscribirse también a topics MQTT?

Sí, la librería incluye un bloque de función de suscripción. Valida con cuidado cada valor recibido antes de que influya en la lógica de control.

¿Qué versión de MQTT usa el cliente de CODESYS?

La librería admite MQTT 3.1.1, y las versiones recientes añaden MQTT 5; consulta la documentación de la versión que tengas instalada. Empieza con 3.1.1 para obtener la máxima compatibilidad.

Cliente CODESYS MQTT: publicar variables del PLC en un broker