Agente MQTT do Kepware: Publicando Tags em um Broker MQTT na Nuvem via TLS

Publicar via Kepware MQTT é uma das formas mais rápidas de levar para a nuvem os dados de uma planta cheia de CLPs variados, porque o Kepware já fala os drivers e o recurso IoT Gateway adiciona um cliente MQTT por cima. Neste tutorial você vai configurar o agente MQTT Client do Kepware para publicar tags em um broker na nuvem via TLS, escolher e moldar o payload JSON, adicionar um Last Will, verificar os dados e, opcionalmente, dividir as mensagens em lote do agente em uma árvore de topics limpa, com um topic por tag.

Como funciona o agente MQTT do Kepware

O Kepware (KEPServerEX e seu sucessor, Kepware Server) é um servidor de conectividade industrial com drivers para centenas de protocolos de CLPs e dispositivos. Seu plug-in IoT Gateway adiciona agentes que enviam dados de tags para sistemas externos. O agente MQTT Client é um deles: ele se conecta a um broker como um cliente MQTT comum e publica os valores das tags em JSON.

O modelo é simples:

1. Canais e dispositivos fazem polling dos seus CLPs pelos drivers do Kepware, como já fazem para o SCADA.
2. Um agente MQTT Client mantém a conexão com o broker, as configurações de publicação e o formato do payload.
3. IoT items são as tags que você adiciona a esse agente, cada uma com sua própria taxa de varredura e comportamento de mudança.
4. A cada ciclo de publicação, o agente envia ao seu topic uma mensagem JSON com os valores pendentes.

Como o agente faz uma conexão de saída, você não abre portas de entrada na máquina do Kepware. Isso explica boa parte da popularidade desse padrão para levar dados de OT de uma planta em Joinville ou Manaus a um broker MQTT na nuvem. Os rótulos e valores padrão exatos variam um pouco entre versões do Kepware, então trate os nomes de campos abaixo como referência e consulte a ajuda da sua versão se algo parecer diferente.

Antes de começar

• Kepware com o recurso IoT Gateway licenciado e instalado.
• Pelo menos um canal e um dispositivo já retornando tags com qualidade boa. Confira primeiro no Quick Client.
• Dados de conexão do broker. Para um primeiro teste, use o servidor MQTT público apenas com tags não sensíveis. Para produção, crie um broker privado e anote usuário, senha e client ID.
• Acesso de saída do host do Kepware à porta TCP 8883 (TLS) do broker.

Passo 1: crie o agente MQTT Client

Na ferramenta de configuração do Kepware, expanda IoT Gateway, clique com o botão direito, adicione um novo agente e selecione MQTT Client como tipo. O assistente pede as configurações principais:

Em seguida, abra as configurações de segurança ou de cliente do agente e preencha:

• Client ID: para o servidor MQTT público, qualquer valor único e não vazio, como kepware-k7q2. Para um broker privado, o client ID exato emitido com suas credenciais; os client IDs ficam vinculados a essas credenciais.
• Usuário e senha: em branco para o servidor MQTT público; YOUR_USERNAME e YOUR_PASSWORD para um privado.
• Versão do TLS: TLS 1.2 ou superior.

O broker apresenta um certificado Let's Encrypt publicamente confiável, então normalmente você não precisa importar um certificado de CA. Se sua organização inspeciona o tráfego TLS com um proxy, o host do Kepware precisa confiar no certificado desse proxy.

Passo 2: adicione um Last Will

Configure o Last Will do agente para que os consumidores saibam quando o Kepware desaparece:

• Topic: connectmq/demo/k7q2/plant1/kepware/status
• Mensagem: offline

Quando o agente cai inesperadamente, o broker publica essa mensagem em nome dele. Combine isso com uma regra no dashboard que deixe os valores esmaecidos sempre que o status for offline.

Passo 3: adicione os IoT items

Clique com o botão direito no agente e adicione IoT items, navegando até as tags desejadas. Para cada item, defina:

1. Taxa de varredura (scan rate): com que frequência o Kepware amostra a tag para esse agente. Ajuste à velocidade real de mudança do valor; de um a cinco segundos atende à maioria das variáveis de processo.
2. Publicar a cada varredura ou na mudança de dado: prefira a mudança de dado para estados e valores analógicos lentos. É o report by exception nativo do Kepware, explicado no nosso guia de report by exception.
3. Banda morta (deadband): para valores analógicos ruidosos, a banda morta suprime mudanças menores que um limite.

Comece com poucas tags, confirme o fluxo de ponta a ponta e depois adicione o restante.

Passo 4: verifique os dados

Assine a partir de qualquer máquina com o cliente Mosquitto:

mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -i kepware-viewer-k7q2 -t "connectmq/demo/k7q2/#" -v

Com o formato Standard, cada mensagem no topic do agente fica assim:

{
  "timestamp": 1792137600000,
  "values": [
    { "id": "Line1.Filler.Speed",     "v": 118.4, "q": true, "t": 1792137599950 },
    { "id": "Line1.Filler.Running",   "v": true,  "q": true, "t": 1792137599950 },
    { "id": "Line1.Filler.GoodCount", "v": 48211, "q": true, "t": 1792137599950 }
  ]
}

id é o caminho completo da tag no Kepware, v o valor, q indica se a qualidade é boa e t é o timestamp da tag em milissegundos desde a época Unix. Em um broker privado do ConnectMQ, o cliente MQTT no navegador do portal e o explorador de topics ao vivo mostram as mesmas mensagens sem instalar nada.

Passo 5: molde o payload com um template Advanced

O formato Advanced permite escrever um template com placeholders que o Kepware preenche. Um template que renomeia os campos para algo mais amigável ao código consumidor fica assim:

{
  "source": "kepware-plant1",
  "sent": |SERVERTIMESTAMP|,
  "tags": [
    |#each VALUES|
    { "name": "|TAGNAME|", "value": |VALUE|, "good": |QUALITY|, "ts": |TIMESTAMP| }|#unless @last|,|/unless|
    |/each|
  ]
}

Mantenha o template como JSON válido para todas as combinações de valores, inclusive quando apenas uma tag mudou. Teste observando as mensagens enquanto alterna tags no simulador de CLP ou no Quick Client.

Passo 6: distribua em uma árvore com um topic por tag

O agente publica lotes em um único topic. Isso é eficiente, mas muitos consumidores preferem um topic por valor em uma hierarquia ISA-95, que é também o que torna um Unified Namespace navegável. Um pequeno republicador pode fazer a divisão. Ele roda em qualquer lugar, conecta-se ao broker como um cliente normal e mapeia os caminhos de tags do Kepware para topics:

# kepware_fanout.py - divide lotes no formato Standard do Kepware em topics por tag
import json, uuid
import paho.mqtt.client as mqtt

ROOT = "connectmq/demo/k7q2/plant1"
SOURCE = f"{ROOT}/kepware"

def to_topic(tag_id: str) -> str:
    # "Line1.Filler.Speed" -> "connectmq/demo/k7q2/plant1/line1/filler/speed"
    return f"{ROOT}/" + "/".join(part.lower() for part in tag_id.split("."))

def on_connect(client, userdata, flags, reason_code, properties):
    client.subscribe(SOURCE, qos=1)

def on_message(client, userdata, message):
    batch = json.loads(message.payload)
    for item in batch.get("values", []):
        payload = {"value": item["v"], "quality": "good" if item["q"] else "bad", "ts": item["t"]}
        client.publish(to_topic(item["id"]), json.dumps(payload), qos=1, retain=True)

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id=f"kep-fanout-{uuid.uuid4().hex[:8]}")
client.on_connect = on_connect
client.on_message = on_message
client.tls_set()
# client.username_pw_set("YOUR_USERNAME", "YOUR_PASSWORD")  # broker privado
client.connect("broker.connectmq.com", 8883, keepalive=30)
client.loop_forever()

Cada lote do Kepware vira várias mensagens retidas por tag, então o limite do servidor MQTT público de dez mensagens por segundo por cliente se aplica ao cliente de distribuição; mantenha pequena a lista de tags de teste. Em um broker privado, os limites seguem o seu plano. Nosso artigo sobre topics MQTT ISA-95 ajuda a projetar a hierarquia de destino, e o ConnectMQ detecta automaticamente topics estruturados em ISA-95 na visualização de dispositivos.

Solução de problemas do agente MQTT do Kepware

Checklist de produção

1. Broker privado com TLS na 8883 e credenciais do portal.
2. Client ID único por agente, nunca compartilhado com ferramentas de teste.
3. Last Will configurado e monitorado.
4. Publicação na mudança de dado e bandas mortas nas tags analógicas.
5. Tamanho de mensagem dentro do limite do seu plano: 256 KB no plano gratuito Serverless, 1 MB no Serverless pago.
6. Firewall do host do Kepware: apenas saída na 8883.
7. Um runbook para rotação de certificados ou credenciais.

Para a visão geral de onde o Kepware se situa entre CLPs, gateways e consumidores, veja o guia de MQTT para IoT industrial. Se você está comparando o Kepware com um gateway próprio, nosso tutorial de gateway OPC UA para MQTT mostra a alternativa open source.

Comece a usar o ConnectMQ

Dê ao seu servidor Kepware um destino na nuvem em minutos. Cadastre-se em app.connectmq.com, escolha o plano gratuito Serverless sem cartão de crédito, crie um broker e copie o usuário, a senha e o client ID gerados para o agente MQTT Client. O ConnectMQ é um broker MQTT gerenciado, então não há servidor para atualizar, e as regras de alerta por limite do portal podem monitorar suas tags assim que elas chegam.

Perguntas frequentes

O Kepware suporta MQTT sobre TLS?

Sim. Use uma URL ssl:// com a porta 8883 no agente MQTT Client e selecione uma versão atual do TLS. Brokers com certificados publicamente confiáveis normalmente não exigem importação extra de certificados.

O Kepware pode publicar cada tag em seu próprio topic MQTT?

O agente MQTT Client publica lotes no topic do agente, e as opções de topics por tag dependem da versão do Kepware. Um pequeno cliente de distribuição que divide os lotes em topics por tag funciona com qualquer versão.

Qual QoS o agente MQTT do Kepware deve usar?

QoS 1 é um bom padrão para dados de tags: a entrega é garantida pelo menos uma vez com pouca sobrecarga. QoS 2 raramente é necessário para telemetria.

Uma aplicação na nuvem pode escrever tags de volta pelo Kepware MQTT?

O agente pode ser configurado para aceitar requisições de escrita em um topic assinado, mas habilite isso apenas com controle de acesso rigoroso e uma necessidade clara. A maioria das implantações mantém o caminho da nuvem somente leitura.