MQTT_GATEWAY

Implementa um gateway de comunicação para o protocolo MQTT, permitindo subscrever e publicar tópicos em um broker qualquer, com publicação automática por critério de tempo ou de alteração de valor; exige um canal Mapeamento de dados associado ao protocolo MQTT e um socket configurado como CLIENT-MQTT. É um bloco de função (mantém estado entre scans; requer instância).

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

Bloco de função

                  MQTT_GATEWAY
           +------------------------+
  BOOL ----|START          CONN_CODE|---- INT
           |                        |
  BOOL ----|EN_SCAN        CONNECTED|---- BOOL
           |                        |
  BOOL ----|EN_SUBS       SUBSCRIBED|---- BOOL
           |                        |
 USINT ----|DMAP_ID            SB_EV|---- BOOL
           |                        |
 USINT ----|COMM_SRC           SB_ID|---- INT
           |                        |
  UINT ----|FLAGS            SB_CODE|---- INT
           |                        |
 USINT ----|DEC_SEP            PB_EV|---- BOOL
           |                        |
  BOOL ----|HI_GATE            PB_ID|---- INT
           |                        |
  UINT ----|KEEP_ALIVE       PB_CODE|---- INT
           |                        |
  UINT ----|BROKER_PORT        RT_EV|---- BOOL
           |                        |
           |                  RT_CHG|---- BOOL
           |                        |
           |                   RT_ID|---- INT
           |                        |
           |                 RT_CODE|---- INT
           |                        |
STRING ----|BROKER_IP ------------- |----
           |                        |
STRING ----|CLIENT_ID ------------- |----
           |                        |
STRING ----|W_TOPIC --------------- |----
           |                        |
STRING ----|W_MSG ----------------- |----
           |                        |
STRING ----|USER ------------------ |----
           |                        |
STRING ----|PASSW ----------------- |----
           |                        |
       ----|T_CACHE --------------- |----
           +------------------------+

Este bloco é parte da biblioteca de comunicação do protocolo MQTT V1.3.1. Tópicos podem ser subscritos (assinados) para recepção e publicados para o broker, sendo a publicação disparada automaticamente por tempo ou por alteração do valor da variável global associada. Para mais informações sobre o protocolo e os blocos disponíveis no HIstudio consulte o protocolo MQTT.

Para utilização deste bloco o usuário deve, com o recurso Mapeamento de dados, criar um canal de mapeamento associado ao protocolo MQTT e, nesse canal, definir os tópicos a subscrever e a publicar. Todos os tópicos criados devem estar associados a variáveis globais exportadas. Enquanto START estiver inativa o bloco permanece desconectado do broker; ao ser ativada, o bloco estabelece a conexão e, conforme EN_SUBS e EN_SCAN, passa a subscrever tópicos e a publicar tópicos por tempo ou por alteração.

Importante

Para a utilização desse bloco, o socket utilizado 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.

Dica

Assista ao vídeo tutorial utilizando o bloco de função para aplicações envolvendo o protocolo MQTT: Tutorial MQTT_GATEWAY

Caso possua dúvidas sobre como configurar o socket assista ao tutorial: Configurando recursos de conectividade do equipamento

Parâmetros

Nome	Direção	Tipo	Dimensão	Padrão	Faixa / Unidade	Descrição
START	IN	BOOL	—	TRUE	—	Inicia a operação do gateway; inativa mantém o bloco desconectado.
EN_SCAN	IN	BOOL	—	TRUE	—	Habilita o ciclo de publicações automáticas (por tempo ou alteração) no broker.
EN_SUBS	IN	BOOL	—	TRUE	—	Habilita o processo de subscrição (assinatura) dos tópicos a receber.
DMAP_ID	IN	USINT	—	0	—	Id do canal Mapeamento de dados (protocolo MQTT) associado ao bloco.
COMM_SRC	IN	USINT	—	0	canal Ethernet	Identificador do socket Ethernet usado para acesso ao broker (ex.: `SOCK1_PORT_ID`).
FLAGS	IN	UINT	—	8	MQTTFLAGS_T	Flags de conexão com o broker (default: `CLEAN_SECTION`).
DEC_SEP	IN	USINT	—	46	código ASCII	Separador decimal na conversão de reais para string (default: 46 = ponto).
HI_GATE	IN	BOOL	—	FALSE	—	Se TRUE e conectado ao Portal HI, identifica o equipamento e sincroniza o relógio.
KEEP_ALIVE	IN	UINT	—	300	s	Tempo, em segundos, para o broker validar a conexão (default: 300 = 5 min).
BROKER_PORT	IN	UINT	—	1883	—	Porta de escuta do broker MQTT.
BROKER_IP	IN_OUT	STRING	:*	—	a.b.c.d	Endereço IP do broker (ex.: `'192.168.0.57'`).
CLIENT_ID	IN_OUT	STRING	:*	—	—	Identificador do cliente da conexão com o broker (opcional).
W_TOPIC	IN_OUT	STRING	:*	—	máx. 80 car.	Nome do tópico associado à mensagem WILL de desconexão (opcional).
W_MSG	IN_OUT	STRING	:*	—	máx. 140 car.	Mensagem WILL de desconexão não programada (opcional).
USER	IN_OUT	STRING	:*	—	máx. 20 car.	Nome do usuário para autenticação (opcional).
PASSW	IN_OUT	STRING	:*	—	máx. 16 car.	Senha de acesso para autenticação (opcional; exige `USER`).
T_CACHE	IN_OUT	ANY	[*]	—	vetor de INT	Cache dos Id’s dos tópicos a publicar no broker (vetor de `INT`).
CONN_CODE	OUT	INT	—	0	código de retorno	Código de retorno do processo de inicialização e conexão do bloco.
CONNECTED	OUT	BOOL	—	FALSE	—	Indica que o equipamento está conectado ao broker.
SUBSCRIBED	OUT	BOOL	—	FALSE	—	Ativa quando concluído o processo de subscrição dos tópicos.
SB_EV	OUT	BOOL	—	FALSE	—	Pulso indicando o fim do subscribe de um tópico.
SB_ID	OUT	INT	—	-1	—	Id do tópico da última subscrição (atualizado com `SB_EV`).
SB_CODE	OUT	INT	—	0	código de retorno	Código de retorno da última subscrição (atualizado com `SB_EV`).
PB_EV	OUT	BOOL	—	FALSE	—	Pulso indicando o fim da publicação de um tópico.
PB_ID	OUT	INT	—	-1	—	Id do tópico da última publicação (atualizado com `PB_EV`).
PB_CODE	OUT	INT	—	0	código de retorno	Código de retorno da última publicação (atualizado com `PB_EV`).
RT_EV	OUT	BOOL	—	FALSE	—	Pulso indicando o fim da recepção de um tópico do broker.
RT_CHG	OUT	BOOL	—	FALSE	—	Pulso indicando que o tópico recebido alterou o valor anterior na base global.
RT_ID	OUT	INT	—	0	—	Id do item da última recepção de tópico (atualizado com `RT_EV`).
RT_CODE	OUT	INT	—	0	código de retorno	Código de retorno da última recepção de tópico (atualizado com `RT_EV`).

Códigos de retorno

As saídas CONN_CODE, SB_CODE, PB_CODE e RT_CODE reportam o resultado das operações de conexão, subscrição, publicação e recepção. Valor 0 indica sucesso; valores diferentes de zero indicam falha. Códigos mais comuns deste bloco:

Código	Identificador	Significado
0	SUCCESS	Operação executada com sucesso.
5	GL_INV_PAR	Parâmetro(s) inválido(s) (ver nota sobre `RT_CODE`).
10	GL_CMD_TMO	Timeout na execução do comando.
23	RE_NOT_FOU	Recurso não encontrado (ex.: canal `DMAP_ID` inexistente ou sem protocolo MQTT).
63	CO_CONEX_FAIL	Falha no processo de conexão com o broker.
64	CO_DEV_UNCONN	Desconexão realizada pelo equipamento remoto (broker).
67	CO_SOCK_ERR	Erro de socket (não foi possível adquirir/usar o socket).

Importante

Em caso de código de retorno 5 (GL_INV_PAR), a falha por parâmetros inválidos pode ocorrer se as seguintes condições não forem atendidas:

Para CLIENT_ID nulo deve existir uma clean session.
Se houver um Will Topic (W_TOPIC) deve existir uma Will Message (W_MSG).
O valor do QOS deve ser válido.

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

Pré-condições

Um canal Mapeamento de dados associado ao protocolo MQTT deve estar criado, com os tópicos a subscrever e a publicar definidos e associados a variáveis globais exportadas.
O socket informado em COMM_SRC deve estar configurado como CLIENT-MQTT (sem conexão automática), com cache de dados de no mínimo 500 bytes e autenticação V1 desabilitada.
T_CACHE deve ser um vetor de INT dimensionado pela aplicação.

Detalhamento das entradas e saídas

START

Entrada de controle do bloco. Quando inativa o bloco se mantém desconectado do broker; nesse cenário os tópicos não são publicados nem mantidos em cache. Quando ativada, o bloco estabelece conexão com o broker especificado, ficando apto a subscrever os tópicos a receber e aguardando um tópico do broker ou um critério para publicar um tópico.

EN_SCAN

Quando ativa, habilita o ciclo de publicações automáticas no broker. Estas publicações podem ser por tempo ou por alteração de valor da variável associada. O valor default é TRUE, fazendo com que, se não especificada na chamada do bloco, a publicação fique automaticamente ativa após a entrada START ser ativada e a conexão com o broker ser realizada com sucesso.

EN_SUBS

Quando ativa, habilita o processo de subscrição dos tópicos a receber. O valor default é TRUE, fazendo com que, se não especificada na chamada do bloco, a subscrição (assinatura) fique automaticamente ativa após a entrada START ser ativada e a conexão com o broker ser realizada com sucesso.

DMAP_ID

Define qual canal de mapeamento de dados está associado ao bloco. Este canal deve ser configurado com o protocolo MQTT, caso contrário o bloco gera um código de erro indicando que o recurso não foi encontrado.

COMM_SRC

Identificador do socket Ethernet a ser utilizado para acesso ao broker. O canal de comunicação é especificado por um identificador numérico (namespace HILS), conforme a tabela a seguir:

Identificador	Valor	Canal
`HILS.COM1_PORT_ID` .. `HILS.COM8_PORT_ID`	0 .. 7	Canais seriais
`HILS.SOCK0_PORT_ID` .. `HILS.SOCK7_PORT_ID`	8 .. 15	Sockets da interface Ethernet 1
`HILS.ETH2_SOCK0_PORT_ID` .. `HILS.ETH2_SOCK7_PORT_ID`	16 .. 23	Sockets da interface Ethernet 2

KEEP_ALIVE

Valor em segundos usado para notificar ao broker que o equipamento está funcional quando não existirem mensagens sendo trocadas. O valor default é 300 (= 5 minutos).

MQTT_FLAGS

Define os flags MQTT utilizados no processo de conexão com o broker. Os valores possíveis estão definidos no tipo de dados MQTTFLAGS_T, disponível na biblioteca HI_STD. São eles:

Nome	Ident.	Descrição
`HILS.WILL_QOS0`	0	WILL MESSAGE com QOS0 [nota 1]
`HILS.WILL_QOS1`	1	WILL MESSAGE com QOS1 [nota 1]
`HILS.WILL_QOS2`	2	WILL MESSAGE com QOS2 [nota 1]
`HILS.WILL_RETAIN`	4	WILL MESSAGE enviada pelo Broker com flag RETAIN ativo [nota 2]
`HILS.CLEAN_SECTION`	8	Broker inicia uma sessão limpa
`HILS.SUB_FMT_JS1`	256	Decodifica um pacote de dados recebido do broker no formato JS1
`HILS.PUB_FMT_JS1`	1024	Codifica o pacote de dados a ser publicado no formato JS1

Nota

[nota 1] Caso o usuário especifique um tópico e mensagem WILL, deve ser especificado um dos WILL_QOSx para ser associado ao tópico.
[nota 2] Este flag, quando especificado, faz com que o broker, ao publicar o tópico WILL, o faça com o flag RETAIN ativo.

O valor default deste parâmetro é 8 (= CLEAN_SECTION).

DEC_SEP

Utilizada caso seja necessário alterar o separador de casas decimais na conversão de variáveis reais. O valor default é o ponto (ex.: 2.45). Para modificar, especifique o código ASCII do caractere a usar como separador. Por exemplo, para gerar valores separados com vírgula (ex.: 2,45) especifique o valor 44 (código ASCII da vírgula).

HI_GATE

Quando igual a TRUE, indica que o equipamento irá se conectar ao portal de telemetria da HI Tecnologia. Nesse caso, logo após a conexão com o broker é ativado automaticamente um processo para identificar o equipamento e sincronizar o relógio/calendário do portal com o equipamento remoto.

Importante

Para utilizar esta funcionalidade é necessário que o usuário especifique o prefixo dos tópicos subscritos e publicados com o Identificador do conector (ClientID), conforme ilustrado na figura seguinte.

../../../_images/mqtt_gat_hi_gate.png — Fig. 116 Fig.1 - Definição do prefixo dos tópicos

BROKER_PORT

Especifica a porta de escuta do broker MQTT a ser utilizada para conexão. O valor default é 1883.

BROKER_IP

Especifica o IP do servidor que hospeda o broker MQTT. Este valor é uma string no formato a.b.c.d (ex.: '192.168.0.57').

W_TOPIC

Especifica o nome do tópico associado à mensagem WILL. Esta mensagem é opcional e enviada aos clientes que assinaram este tópico quando o cliente se desconecta do broker. O tamanho máximo para o nome do tópico é de 80 caracteres.

W_MSG

Especifica a mensagem (WILL) associada a ser utilizada. Esta mensagem é opcional e enviada aos clientes que assinaram o tópico W_TOPIC quando o cliente se desconecta do broker. O tamanho máximo para esta mensagem é de 140 caracteres.

USER

Especifica o nome do usuário utilizado no processo de autenticação na conexão com o broker. É opcional e, quando utilizada, permite que o broker autentique a conexão com os parâmetros enviados. O tamanho máximo para o nome do usuário é de 20 caracteres.

PASSW

Especifica a senha utilizada no processo de autenticação na conexão com o broker. É opcional e, quando utilizada, permite que o broker autentique a conexão com os parâmetros enviados. Se for especificada uma senha, o nome do usuário deve obrigatoriamente existir. O tamanho máximo para a senha de autenticação é de 16 caracteres.

T_CACHE

Fornece ao bloco uma cache onde são inseridos os Id’s dos itens a serem publicados no broker. Um Id representa o valor numérico associado à linha do canal de mapeamento; cada Id mapeia uma variável global da aplicação a um nome de tópico MQTT. Esta cache deve ser um vetor de INT com o tamanho definido pela aplicação. Os itens a publicar são inseridos nesta cache através da função COMM_NOTIFY_ITEM. Uma vez inserido um item, o bloco é responsável por removê-lo e publicá-lo no broker assim que possível.

CONNECTED

Saída lógica que indica, quando ativa, que a conexão com o broker foi estabelecida.

CONN_CODE

Código de retorno do processo de conexão com o broker. Permanece igual a zero enquanto a entrada START estiver inativa. Uma vez ativada START, esta saída, junto com CONNECTED, indica o resultado da conexão: um valor diferente de zero indica o código de falha; caso contrário mantém-se em zero e CONNECTED ativa indica conexão estabelecida com sucesso. Para a lista completa dos códigos de falha consulte RET_CODE - Códigos de retorno do firmware G5.

SUBSCRIBED

Saída lógica que indica, quando ativa, que o processo de subscrição dos tópicos a receber do broker foi concluído. As saídas SB_EV, SB_CODE e SB_ID podem ser usadas para rastrear condições de erro neste processo.

SB_EV

Saída lógica que gera um pulso (ativa por um ciclo de scan) indicando o fim da subscrição de um tópico MQTT no broker.

SB_ID

Id do tópico associado ao último processo de subscrição no broker. É atualizada com a saída SB_EV.

SB_CODE

Código de retorno do último processo de subscrição de tópico no broker. É atualizada com a saída SB_EV. Para a lista completa dos códigos de falha consulte RET_CODE - Códigos de retorno do firmware G5.

PB_EV

Saída lógica que gera um pulso (ativa por um ciclo de scan) indicando o fim do processo de publicação de um tópico no broker.

PB_ID

Id do tópico associado ao último processo de publicação no broker. É atualizada com a saída PB_EV.

PB_CODE

Código de retorno do último processo de publicação de tópico no broker. É atualizada com a saída PB_EV. Para a lista completa dos códigos de falha consulte RET_CODE - Códigos de retorno do firmware G5.

RT_EV

Saída lógica que gera um pulso (ativa por um ciclo de scan) indicando o fim do processo de recepção de um tópico do broker.

RT_ID

Id do item associado ao último processo de recepção de um tópico do broker. É atualizada com a saída RT_EV.

RT_CODE

Código de retorno do último processo de recepção de um tópico do broker. É atualizada com a saída RT_EV. Para a lista completa dos códigos de falha consulte RET_CODE - Códigos de retorno do firmware G5.

RT_CHG

Saída lógica que gera um pulso (ativa por um ciclo de scan) indicando que o processo de recepção de um tópico do broker, finalizado com sucesso, modificou o valor anterior da variável global associada. Este sinal, quando ocorre, é sincronizado com a saída RT_EV.

Observações

As saídas SB_EV, PB_EV, RT_EV e RT_CHG são pulsos de um ciclo de scan; amostre-as no mesmo scan em que ficam ativas.
Os contadores/tratamentos associados a cada evento devem usar os pares SB_EV/SB_ID/SB_CODE, PB_EV/PB_ID/PB_CODE e RT_EV/RT_ID/RT_CODE.

Ver também

COMM_NOTIFY_ITEM, MQTT_MDB_BRIDGE, MDB_GATEWAY

Exemplo

Clique aqui para baixar a tabela de variáveis

Código ST

VAR
    START       : BOOL := FALSE;                (* Ativa operação do gateway *)
    SCAN        : BOOL;                         (* Habilita publicação automatica de tópicos *)
    SUBS        : BOOL;                         (* Habilita subscrição de tópicos *)
    NOTIFY      : BOOL := FALSE;                (* Publica um tópico no broker (exemplo) *)
    BROKER_IP   : STRING[15] := '192.168.0.58'; (* IP do broker *)
    BROKER_PORT : UDINT := 1883;                (* Porta do broker *)
    WILL_T      : STRING[80] := 'W_TOPIC';      (* Topico de desconexão *)
    WILL_M      : STRING[140] := 'W_MSG';       (* Mensagem de desconexão *)
    USER        : STRING[36] := 'JOAO';         (* Usuário *)
    PASSW       : STRING[36] := '123';          (* Senha *)
    T_CACHE     : ARRAY [0..99] OF INT;         (* Cache para publicação de tópicos *)
    CONNECTED   : BOOL := FALSE;                (* Broker conectado *)
    SUBSCRIBED  : BOOL := FALSE;                (* Tópicos subscritos *)
    PB_COUNT    : INT := 0;                     (* Contador de topicos publicados *)
    SB_COUNT    : INT := 0;                     (* Contador de topicos subscritos *)
    RT_COUNT    : INT := 0;                     (* Contador de topicos recebidos *)
    GTW_MQTT    : HILS.MQTT_GATEWAY;            (* Instancia do gateway *)
END_VAR

// Este código, após a ativação da entrada START, publica ciclicamente os
// tópicos definidos no canal de mapeamento 2.
// Ao ser ativada a variavel NOTIFY a variavel de escrita com ID 1 do canal de mapeamento será
// publicada no broker. Todas os tópicos subscritos são automaticamente atualizados nas
// variveis associadas quando recebidos do broker.

// Gateway MQTT

GTW_MQTT(  // MQTT_GATEWAY
  START       := START,       // [BOOL] Inicia operação do gateway
  //EN_SUBS     := ,          // [BOOL] Habilita subscricao de topicos
  //EN_SCAN     := ,          // [BOOL] Habilita o polling de dados do equipamento remoto
  DMAP_ID     := 2,            // [USINT] Id do mapeamento de dados associado ao bloco
  COMM_SRC    := HILS.SOCK2_PORT_ID,  // [USINT] Canal de comunicação (socket Ethernet) usado para acesso ao broker
  FLAGS       := HILS.CLEAN_SECTION,  // [UINT] Flags de conexão com o broker
  //DEC_SEP     := ,          // [USINT] Separador de casas decimais na conversao dos valores reais (default = ponto)
  //KEEP_ALIVE  := ,          // [UINT] Tempo em segundos para o broker validar a conexão
  BROKER_PORT := BROKER_PORT, // [UINT] Porta de escuta do broker
  BROKER_IP   := BROKER_IP,   // [STRING] Endereço IP do broker a ser acessado (string:15)
  W_TOPIC     := WILL_T,      // [STRING] Nome do tópico associado a mensagem de desconexão (string:80)
  W_MSG       := WILL_M,      // [STRING] Mensagem de desconexão (string:140)
  USER        := USER,        // [STRING] Nome do usuário (string:20)
  PASSW       := PASSW,       // [STRING] Senha de acesso (string:16)
  T_CACHE     := T_CACHE      // [ANY] Cache de tópicos a serem enviados para o broker
  );

CONNECTED := GTW_MQTT.CONNECTED;
SUBSCRIBED := GTW_MQTT.SUBSCRIBED;

// Mantem um contador de tópicos subscritos no broker
IF GTW_MQTT.SB_EV THEN
  SB_COUNT := SB_COUNT + 1;
END_IF;

// Mantem um contador de tópicos publicados no broker
IF GTW_MQTT.PB_EV THEN
  PB_COUNT := PB_COUNT + 1;
END_IF;

// Mantem um contador de tópicos recebidos do broker
IF GTW_MQTT.RT_EV THEN
  RT_COUNT := RT_COUNT + 1;
END_IF;

// Publica a variavel associada ao ID = 1 no broker
IF NOTIFY THEN
  HILS.COMM_NOTIFY_ITEM(1, T_CACHE);
  NOTIFY := FALSE;
END_IF;