MQTT_CONTROLLER

Estabelece e mantém a conexão de um cliente MQTT com um broker por um socket Ethernet configurado como CLIENT-MQTT (sem conexão automática), reconectando automaticamente em caso de queda e sinalizando a recepção dos tópicos assinados. É um bloco de função (mantém estado entre scans; requer instância) da biblioteca de comunicação MQTT V1.3.1.

Biblioteca: HI_STD · Namespace: HILS · Tipo: bloco de função

Bloco de função

                MQTT_CONTROLLER
           +------------------------+
  BOOL ----|START          CONNECTED|---- BOOL
           |                        |
 USINT ----|COMM_SRC           ERROR|---- INT
           |                        |
  UINT ----|MQTT_FLAGS        ERR_EV|---- BOOL
           |                        |
  UINT ----|KEEP_ALIVE        TOP_EV|---- BOOL
           |                        |
  UINT ----|BROKER_PORT             |
           |                        |
STRING ----|BROKER_IP ------------- |----
           |                        |
STRING ----|CLIENT_ID ------------- |----
           |                        |
STRING ----|W_TOPIC --------------- |----
           |                        |
STRING ----|W_MSG ----------------- |----
           |                        |
STRING ----|USER ------------------ |----
           |                        |
STRING ----|PASSW ----------------- |----
           |                        |
STRING ----|BROKER_TOPIC ----------- |----
           |                        |
STRING ----|BROKER_MSG ------------ |----
           +------------------------+

O processo é iniciado pela ativação de START, que deve permanecer ativa durante todo o tempo de execução. Ao ser ativado, o bloco inicia a conexão com o broker pelo socket Ethernet indicado em COMM_SRC. Concluído o processo com sucesso, a saída CONNECTED torna-se ativa, indicando que o cliente MQTT está conectado e funcional. A partir daí, tópicos podem ser assinados com o bloco MQTT_SUBSCRIBE e mensagens podem ser publicadas com o bloco MQTT_PUBLISH.

Quando o broker enviar uma mensagem ao cliente, a saída TOP_EV gera um pulso; nesse instante BROKER_TOPIC e BROKER_MSG contêm, respectivamente, o nome do tópico e a mensagem associada. Eventuais quedas de conexão são detectadas e o bloco reconecta automaticamente ao broker.

Para mais informações sobre o protocolo e os blocos disponíveis, consulte protocolo MQTT.

Importante

Para a utilização deste bloco, o socket usado para acesso ao broker deve ser previamente configurado para operação com o protocolo CLIENT-MQTT (sem conexão automática) e o tamanho da cache de dados do socket deve ser de, no mínimo, 500 bytes (1460 max.). A opção de autenticação V1 deve estar desabilitada no socket.

Nota

Na implementação corrente, o tamanho máximo do nome de um tópico é de 80 caracteres. Nomes maiores geram erro no processamento do bloco, retornando o código 28 (RE_FIL_OVF), e não são tratados.

Parâmetros

Nome

Direção

Tipo

Dimensão

Padrão

Faixa / Unidade

Descrição

START

IN

BOOL

—

FALSE

—

Inicia o gerenciamento da conexão MQTT (ativa na transição de subida); deve permanecer ativa durante a execução.

COMM_SRC

IN

USINT

—

0

0 .. 23

Canal de comunicação (socket Ethernet) usado para acesso ao broker (ver Observações).

MQTT_FLAGS

IN

UINT

—

8

—

Flags de conexão com o broker (default = 8 = CLEAN_SECTION; ver Observações).

KEEP_ALIVE

IN

UINT

—

300

s

Keep alive da sessão em segundos (default = 300 = 5 min).

BROKER_PORT

IN

UINT

—

1883

—

Porta de escuta do broker MQTT (default = 1883).

BROKER_IP

IN_OUT

STRING

:*

—

máx. 15 caracteres

IP do servidor que hospeda o broker, no formato a.b.c.d (ex.: '192.168.0.57').

CLIENT_ID

IN_OUT

STRING

:*

—

—

Identificação do cliente MQTT (opcional).

W_TOPIC

IN_OUT

STRING

:*

—

máx. 80 caracteres

Tópico associado à mensagem WILL de desconexão (opcional; exige W_MSG).

W_MSG

IN_OUT

STRING

:*

—

máx. 140 caracteres

Mensagem WILL de desconexão (opcional; exige W_TOPIC).

USER

IN_OUT

STRING

:*

—

máx. 36 caracteres

Usuário para autenticação da conexão (opcional).

PASSW

IN_OUT

STRING

:*

—

máx. 36 caracteres

Senha para autenticação da conexão (opcional).

BROKER_TOPIC

IN_OUT

STRING

:*

—

mín. 80 caracteres

Nome do tópico recebido do broker; válido durante o pulso TOP_EV (pode ser alterado nos ciclos seguintes).

BROKER_MSG

IN_OUT

STRING

:*

—

—

Mensagem associada ao tópico recebido; válida durante o pulso TOP_EV (pode ser alterada nos ciclos seguintes).

CONNECTED

OUT

BOOL

—

FALSE

—

Conexão com o broker estabelecida com sucesso.

ERROR

OUT

INT

—

0

RET_CODE

Último código de erro detectado no processo (ver Códigos de retorno).

ERR_EV

OUT

BOOL

—

FALSE

—

Gera um pulso ao concluir qualquer processo com erro.

TOP_EV

OUT

BOOL

—

FALSE

—

Gera um pulso ao receber um tópico assinado do broker.

Códigos de retorno

ERROR carrega o último código de erro do processo. Use os identificadores com o namespace HILS (ex.: HILS.CO_CONEX_FAIL). Códigos mais comuns deste bloco:

Código

Identificador

Significado

0

SUCCESS

Processo executado com sucesso.

1

FAIL

Erro genérico no processamento.

10

GL_CMD_TMO

Timeout na execução do comando.

28

RE_FIL_OVF

Overflow no preenchimento do buffer (ex.: nome de tópico acima de 80 caracteres).

63

CO_CONEX_FAIL

Falha no processo de conexão com o broker.

64

CO_DEV_UNCONN

Desconexão realizada pelo equipamento remoto.

67

CO_SOCK_ERR

Erro de socket (não foi possível adquirir/usar o socket).

68

CO_TRA_BUF_OVL

Overflow no buffer de transmissão.

87

CO_COM_BRO

Comunicação interrompida.

Lista completa dos códigos de retorno: RET_CODE - Códigos de retorno do firmware G5.

Pré-condições

  • O socket indicado em COMM_SRC deve estar configurado com o protocolo CLIENT-MQTT (sem conexão automática), cache de dados de no mínimo 500 bytes (1460 max.) e autenticação V1 desabilitada.

  • Se um tópico/mensagem WILL for usado, W_TOPIC e W_MSG devem ser ambos especificados, junto de um dos flags WILL_QOSx.

Observações

  • BROKER_TOPIC e BROKER_MSG devem ser processados durante o pulso de TOP_EV, pois podem ser sobrescritos nos ciclos seguintes.

  • Valores possíveis de MQTT_FLAGS (default = 8 = CLEAN_SECTION):

    Identificador

    Valor

    Descrição

    WILL_QOS0

    0

    WILL MESSAGE com QOS0 (exige tópico/mensagem WILL).

    WILL_QOS1

    1

    WILL MESSAGE com QOS1 (exige tópico/mensagem WILL).

    WILL_QOS2

    2

    WILL MESSAGE com QOS2 (exige tópico/mensagem WILL).

    WILL_RETAIN

    4

    Broker publica o tópico WILL com o flag RETAIN ativo.

    CLEAN_SECTION

    8

    Broker inicia uma sessão limpa.

  • Identificadores de canal de comunicação (COMM_SRC), namespace HILS:

    Identificador

    Valor

    Meio físico

    COM1_PORT_ID .. COM8_PORT_ID

    0 .. 7

    Portas seriais

    SOCK0_PORT_ID .. SOCK7_PORT_ID

    8 .. 15

    Ethernet 1

    ETH2_SOCK0_PORT_ID .. ETH2_SOCK7_PORT_ID

    16 .. 23

    Ethernet 2

Ver também

MQTT_SUBSCRIBE, MQTT_PUBLISH, protocolo MQTT

Exemplo

Clique aqui para baixar a tabela de variáveis

Código ST

VAR
    BROKER_IP   : STRING := '192.168.0.58'; (* IP do Broker *)
    BROKER_PORT : UDINT := 1883;            (* porta de escuta do broker *)
    MQTT_CT     : HILS.MQTT_CONTROLLER;     (* bloco de controle do protocolo MQTT *)
    START       : BOOL := 1;                (* Habilita protocolo *)
    REC_TOPIC   : STRING;                   (* Nome do tópico recebido do broker *)
    REC_MSG     : STRING;                   (* Mensagem associada ao tópico recebido do broker *)
    W_TOPIC     : STRING[80];               (* Nome do tópico associado ao processo de desconexão do cliente (opcional) *)
    W_MSG       : STRING[140];              (* Mensagem associada ao processo de desconexão do cliente (opcional) *)
    USER        : STRING[36] := 'joao';     (* Nome do usuário (opcional) *)
    PASSW       : STRING[36] := '1234';     (* Senha de acesso (opcional) *)
    MQTT_PUB    : HILS.MQTT_PUBLISH;        (* Bloco de publicação do protocolo MQTT *)
    PUB_ITEM    : BOOL := FALSE;            (* Flag para publicar um item *)
    PUB_TOPIC   : STRING := 'temp';         (* Nome do tópico a ser publicado *)
    PUB_MSG     : STRING := '123.oC';       (* Valor do tópico a ser publicado *)
    MQTT_SUB    : HILS.MQTT_SUBSCRIBE;      (* Bloco de assinatura do protocolo MQTT *)
    SUB_TOPIC   : STRING := 'temp';         (* Nome do tópico a ser assinado *)
END_VAR

(* Este código abre conexão com o broker MQTT, assina o tópico 'temp' e, a cada
   ativação da variável PUB_ITEM, publica o tópico 'temp' com valor '123.oC'.
   Como o tópico publicado tem o mesmo nome do tópico assinado, após a
   publicação o tópico é recebido de volta do broker. *)

(* Abre uma conexão (Clean section com Keep Alive = 5 min) *)
MQTT_CT(  (* MQTT_CONTROLLER *)
  START        := START,               (* [BOOL] Inicia o gerenciamento da conexão MQTT (transição de subida) *)
  COMM_SRC     := HILS.SOCK1_PORT_ID,  (* [USINT] Canal de comunicação a ser utilizado *)
  MQTT_FLAGS   := HILS.CLEAN_SECTION,  (* [UINT] Flags de conexão com o broker (default = clean section) *)
  (* KEEP_ALIVE   := ,                 [UINT] Keep alive time em segundos (default = 5 min) *)
  BROKER_PORT  := BROKER_PORT,         (* [UINT] Porta de conexão com o broker (default = 1883) *)
  BROKER_IP    := BROKER_IP,           (* [STRING] IP de conexão com o broker *)
  W_TOPIC      := W_TOPIC,             (* [STRING] Nome do tópico associado à mensagem de desconexão (opc) *)
  W_MSG        := W_MSG,               (* [STRING] Nome da mensagem de desconexão (opc) *)
  USER         := USER,                (* [STRING] Nome do usuário (opc) *)
  PASSW        := PASSW,               (* [STRING] Senha de acesso (opc) *)
  BROKER_TOPIC := REC_TOPIC,           (* [STRING] Nome do tópico recebido do broker *)
  BROKER_MSG   := REC_MSG              (* [STRING] Mensagem associada ao tópico recebido do broker *)
  );

(* Assim que a conexão com o broker for realizada, assina um tópico *)
MQTT_SUB(  (* MQTT_SUBSCRIBE *)
  START    := MQTT_CT.CONNECTED,  (* [BOOL] Inicia o processo de assinatura de um tópico MQTT (transição de subida) *)
  COMM_SRC := HILS.SOCK1_PORT_ID, (* [USINT] Canal de comunicação a ser utilizado *)
  TOPIC    := SUB_TOPIC           (* [STRING] Nome do tópico a ser assinado *)
  );

IF MQTT_CT.TOP_EV THEN
  (* Tratar aqui o tópico recebido do broker *)
  ;
END_IF;

IF PUB_ITEM THEN
  MQTT_PUB(  (* MQTT_PUBLISH *)
    START    := PUB_ITEM,           (* [BOOL] Inicia o processo de publicação de um tópico MQTT (transição de subida) *)
    COMM_SRC := HILS.SOCK1_PORT_ID, (* [USINT] Canal de comunicação a ser utilizado *)
    RETAIN   := FALSE,              (* [BOOL] Notifica o broker para manter a mensagem enviada *)
    QOS      := 0,                  (* [USINT] QOS (Quality of service) (0, 1 ou 2) *)
    TOPIC    := PUB_TOPIC,          (* [STRING] Nome do tópico a ser publicado *)
    MESSAGE  := PUB_MSG             (* [STRING] Mensagem associada ao tópico a ser publicado *)
    );
  IF MQTT_PUB.DONE_EV THEN
    PUB_ITEM := FALSE;
  END_IF;
END_IF;