Cliente MQTT no CODESYS: Publicando Variáveis do CLP em um Broker

O suporte a CODESYS MQTT transforma qualquer controlador baseado em CODESYS, de um CLP de fabricante a um Raspberry Pi rodando o runtime CODESYS, em um publicador direto de dados da planta, seja uma estação de bombeamento de saneamento ou uma linha de manufatura. Neste tutorial você vai adicionar a biblioteca IIoT MQTT Client do CODESYS a um projeto, publicar variáveis do CLP em JSON com texto estruturado, verificá-las no servidor MQTT público e depois proteger a conexão com credenciais e TLS. Ao longo do caminho, você verá as armadilhas que normalmente custam um dia de comissionamento.

Por que vale a pena fazer CODESYS MQTT

O CODESYS é o runtime por trás de uma grande parcela dos CLPs e controladores industriais do mundo, vendidos sob várias marcas. Isso significa que uma única abordagem de integração cobre muito hardware. Publicar diretamente do controlador tem benefícios claros:

• Nenhum hardware ou software de gateway extra para manter em instalações pequenas.
• Os dados saem do controlador exatamente no formato e no momento que o programador do CLP decidir, prontos para dashboards ou para um gêmeo digital do processo.
• A lógica de report by exception fica junto do processo, onde bandas mortas e estados são mais bem compreendidos.

A contrapartida é que o programador do CLP passa a ser responsável por código de rede. Se você vai conectar muitos controladores de fabricantes diferentes, compare com as arquiteturas baseadas em gateway em conectividade de CLP para a nuvem antes de decidir.

Pré-requisitos

A biblioteca MQTT Client SL faz parte do pacote IIoT Libraries SL, ao lado de bibliotecas de JSON e de cliente web. Os nomes exatos dos pinos dos blocos de função podem variar um pouco entre versões da biblioteca, então mantenha a documentação aberta no Library Manager enquanto trabalha.

Passo 1: adicione a biblioteca MQTT

1. Abra o Library Manager na sua aplicação e escolha Add Library.
2. Procure MQTT Client SL e adicione-a. O namespace da biblioteca é MQTT.
3. Se pretende montar o JSON com funções auxiliares da biblioteca, adicione também a JSON Utilities SL. Este tutorial monta o JSON manualmente para manter as dependências mínimas.
4. Compile o projeto uma vez para confirmar que a biblioteca é resolvida sem erros.

Passo 2: declare as variáveis

Crie um programa, por exemplo PRG_Mqtt, chamado por uma task com ciclo de 20 a 100 ms. Blocos de função de rede precisam ser chamados a cada ciclo para que suas máquinas de estado internas avancem.

PROGRAM PRG_Mqtt
VAR
    // Variáveis de processo (em um projeto real, vêm da sua lógica de controle)
    rTemperature   : REAL := 21.5;
    rPressure      : REAL := 1.82;
    xPumpRunning   : BOOL := TRUE;

    // Cliente e publicador MQTT
    mqttClient     : MQTT.MQTTClient;
    mqttPublish    : MQTT.MQTTPublish;

    sHost          : STRING := 'broker.connectmq.com';
    uiPort         : UINT := 1883;
    sClientId      : STRING := 'codesys-demo-k8q2x7';   // não pode ser vazio e deve ser único
    wsTopic        : WSTRING(255) := "connectmq/demo/k8q2x7/plant1/utilities/pumpstation1/telemetry";

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

Dois detalhes importam aqui. Primeiro, o client ID não pode ser vazio e deve ser único; dois controladores com o mesmo ID vão derrubar um ao outro do broker repetidamente. Segundo, o comprimento padrão de STRING no CODESYS é de 80 caracteres, curto demais para a maioria dos payloads JSON, então declare um comprimento explícito.

Passo 3: conecte e publique com texto estruturado

O programa habilita o cliente, monta um payload JSON e publica a cada 10 segundos ou imediatamente quando a temperatura varia mais de 0,5 grau ou o estado da bomba muda.

// 1. Mantém o cliente rodando a cada ciclo
mqttClient(
    xEnable      := TRUE,
    sHostname    := sHost,
    uiPort       := uiPort,
    eMQTTVersion := MQTT.MQTT_VERSION.V3_1_1,
    sClientId    := sClientId,
    uiKeepAlive  := 30
);

// 2. Decide quando publicar: heartbeat periódico 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. Monta o 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. Publica na borda de subida 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;   // derruba xExecute para que o próximo disparo gere uma nova borda de subida
END_IF

O padrão a lembrar é o handshake execute/done. O MQTTPublish começa em uma borda de subida de xExecute e informa xDone ou xError alguns ciclos depois. Se você nunca derrubar xExecute, nada é publicado uma segunda vez. Se você o ativar a cada ciclo, inunda o broker.

Passo 4: verifique no servidor MQTT público

Faça o download da aplicação, inicie-a e assine a partir de um PC:

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

Você deve ver uma mensagem a cada 10 segundos, além de mensagens extras quando escrever uma nova temperatura ou alternar xPumpRunning pela visão online:

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

O servidor MQTT público (gratuito) é ideal para esta fase de colocação em operação: anônimo, sem configuração e com retorno rápido. Ele pode ser lido por qualquer pessoa, então use um prefixo de topic aleatório e nenhum dado real de processo. Ele também limita cada cliente a 10 mensagens por segundo e 64 KB por mensagem, uma proteção útil enquanto você ajusta os disparos.

Passo 5: migre para um broker privado com TLS

Para produção, conecte-se ao seu próprio broker com credenciais e criptografia:

1. Crie um broker no portal do ConnectMQ e anote o usuário, a senha e o client ID gerados.
2. No controlador, abra a Security Screen do CODESYS e importe a CA raiz do certificado do broker para o repositório de certificados confiáveis. Brokers com certificados Let's Encrypt encadeiam até a ISRG Root X1.
3. Defina uiPort := 8883, habilite o TLS no bloco de função do cliente e referencie o contexto TLS conforme a documentação da biblioteca.
4. Defina sClientId := 'YOUR_CLIENT_ID' e passe YOUR_USERNAME e YOUR_PASSWORD para as entradas de credenciais do cliente.
5. Altere o topic para a sua hierarquia de produção, como plant1/utilities/pumpstation1/telemetry.

No ConnectMQ, os client IDs são vinculados às credenciais emitidas, então um projeto copiado para um segundo controlador com o mesmo ID será recusado em vez de roubar a sessão silenciosamente. Dê a cada controlador suas próprias credenciais. O explorador de topics ao vivo do broker mostra suas mensagens assim que o handshake TLS é concluído.

Se operar e atualizar um broker por conta própria não é onde você quer gastar tempo, um broker MQTT gerenciado tira certificados, atualizações e monitoramento das suas mãos.

Solução de problemas do CODESYS MQTT

1. O cliente nunca conecta. Verifique o DNS e o gateway padrão no controlador. Teste com um IP literal para isolar problemas de resolução de nomes.
2. O handshake TLS falha. O certificado da CA não está no repositório confiável do controlador, ou o relógio do controlador está errado e o certificado parece ainda não válido. Configure o NTP.
3. Publica apenas uma vez. xExecute nunca é resetado; veja o handshake no passo 3.
4. Payload truncado. A STRING é curta demais ou udiPayloadSize foi calculado a partir de outra variável.
5. A conexão cai a cada poucos segundos. Outro dispositivo usa o mesmo client ID, ou o ciclo da task é tão lento que os pacotes de keep alive atrasam.
6. O modo demo para depois de um tempo. A licença do IIoT Libraries SL não está ativada no dispositivo.

Checklist de produção

• Client ID e credenciais únicos por controlador.
• TLS na porta 8883 com CA confiável e sincronização de horário por NTP.
• Montagem do payload protegida contra estouro de string.
• Report by exception mais um heartbeat periódico.
• Um topic de status com Last Will para que os consumidores distingam offline de ocioso.
• Topics seguindo a convenção de nomes ISA-95 da planta.

Controladores Beckhoff usam outra biblioteca para a mesma tarefa; veja Beckhoff TwinCAT MQTT para a comparação, ou o tutorial Siemens S7 MQTT para o TIA Portal. Para a visão arquitetural mais ampla, comece pelo guia de IoT industrial com MQTT.

Publique seus dados CODESYS no ConnectMQ

Quando seu controlador estiver pronto para deixar o servidor MQTT público, dê a ele um broker MQTT na nuvem seguro. Crie um broker Serverless gratuito em app.connectmq.com, sem cartão de crédito, e cole as credenciais geradas no seu projeto CODESYS.

Perguntas frequentes

A biblioteca MQTT do CODESYS é gratuita?

A biblioteca MQTT Client SL faz parte do pacote IIoT Libraries SL, que é licenciado. Ela pode ser testada em modo demo, que para após um tempo de execução limitado até que uma licença seja ativada.

O CODESYS MQTT suporta TLS?

Sim. Importe a CA raiz do broker para o repositório de certificados do controlador pela Security Screen, habilite o TLS no cliente e conecte-se à porta 8883.

O CODESYS também pode assinar topics MQTT?

Sim, a biblioteca inclui um bloco de função de assinatura. Valide cuidadosamente cada valor recebido antes que ele influencie a lógica de controle.

Qual versão do MQTT o cliente CODESYS usa?

A biblioteca suporta MQTT 3.1.1, e versões recentes adicionam MQTT 5; consulte a documentação da versão instalada. Comece com 3.1.1 para máxima compatibilidade.