MQTT_GATEWAY

Este bloco implementa um gateway de comunicação para o protocolo MQTT, permitindo subscrever e publicar tópicos MQTT para um broker qualquer. Tópicos podem ser automaticamente enviados baseado em critérios de tempo ou de alteração de valores.

Este bloco é parte da biblioteca de comunicação do protocolo MQTT V1.3.1.

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 deverá inicialmente, utilizando o recurso de Mapeamento de dados criar um canal de mapeamento assocido ao protocolo MQTT. Em seguida, no canal de mapeamento criado, definir os tópicos a serem subscritos (assinados) e os tópicos a serem publicados. Note que todos os tópicos criados devem estar associados a variáveis globais exportadas.

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 dever 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

Bloco

                  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 --------------- |----
           +------------------------+

Parâmetros

Nome	Classe	Tipo	Dim.	V. Ini.	Descrição
START	Entrada	BOOL		TRUE	Inicia operação do gateway
EN_SCAN	Entrada	BOOL		TRUE	Habilita o ciclo de notificacoes automaticas ao broker
EN_SUBS	Entrada	BOOL		TRUE	Ativa o processo de registro dos itens
DMAP_ID	Entrada	USINT		0	Id do mapeamento de dados associado ao bloco
COMM_SRC	Entrada	USINT		0	Canal de comunicação utilizado para acesso ou broker (ex: SOCK1_PORT_ID)
FLAGS	Entrada	UINT		8	Flags de conexão com o broker (default: Clean session)
DEC_SEP	Entrada	USINT		46	Separador de casas decimais no processo de conversao dos valores reais para string (default: ponto)
HI_GATE	Entrada	BOOL		FALSE	Se TRUE e conectado ao Portal da HI Tecnologia, notifica que é um equipamento HI e sincroniza o relógio automaticamente.
KEEP_ALIVE	Entrada	UINT		300	Tempo em segundos para o broker validadar a conexão
BROKER_PORT	Entrada	UINT		1883	Porta de escuta do broker
BROKER_IP	Entrada/Saída	STRING	:*		Endereço IP do broker a ser acessado
CLIENT_ID	Entrada/Saída	STRING	:*		Identificador do cliente da conexão com o broker (opc)
W_TOPIC	Entrada/Saída	STRING	:*		Nome do tópico associado a mensagem de desconexão não programada (opc)
W_MSG	Entrada/Saída	STRING	:*		Mensagem de desconexão não programada (opc)
USER	Entrada/Saída	STRING	:*		Nome do usuário (opc)
PASSW	Entrada/Saída	STRING	:*		Senha de acesso (opc)
T_CACHE	Entrada/Saída	ANY			Cache de tópicos a serem enviados ao broker (deve ser fornecido um vetor de tipos INT)
CONN_CODE	Saída	INT		0	Código de retorno do processo de inicializacao e conexão do bloco
CONNECTED	Saída	BOOL		FALSE	Indica que o equipamento esta conectado com o broker
SUBSCRIBED	Saída	BOOL		FALSE	Ativa quando terminado o processo de subscrever os topicos no broker
SB_EV	Saída	BOOL		FALSE	Indica fim do processo de subscribe de um topico
SB_ID	Saída	INT		-1	Id do item da última aquisição do equipamento remoto
SB_CODE	Saída	INT		0	Código de retorno da ultima recepção remota
PB_EV	Saída	BOOL		FALSE	Indica fim do processo de escrita de um item no equipamento remoto
PB_ID	Saída	INT		-1	Id do item da última escrita no equipamento remoto
PB_CODE	Saída	INT		0	Código de retorno da ultima escrita no equipamento remoto
RT_EV	Saída	BOOL		FALSE	Indica fim do processo de recepção de um tópico do broker
RT_CHG	Saída	BOOL		FALSE	Indica que o tópico recebido é diferente do valor anterior presente na base global
RT_ID	Saída	INT		0	Id do item da última recepção de tópico do broker
RT_CODE	Saída	INT		0	Código de retorno da ultima recepção de tópico do broker

START

Entrada de controle do bloco. Quando inativa o bloco se mantém desconectado do broker. Neste cenário os tópicos não serão publicados e nem mantidos em cache. Quando ativada esta entrada, o bloco estabelece conexão com o broker especificado, estando apto e subscrever os tópicos a serem recebidos do broker e aguardando um tópico do broker ou um critério para publicar um tópico para o broker.

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 para esta entrada é TRUE fazendo com que, se não especificada na chamada do bloco o processo de publicação estará automaticamente ativo após a entrada START ser ativada e o processo de conexão como broker realizado com sucesso.

EN_SUBS

Quando ativa, habilita o processo de subscrição dos tópicos a serem recebidos. O valor default para esta entrada é TRUE fazendo com que, se não especificada na chamada do bloco o processo de subscrição (assinatura) estará automaticamente ativo após a entrada START ser ativada e o processo de conexão como broker realizado com sucesso.

DMAP_ID

Esta entrada define qual o canal de mapeamento de dados esta associado ao bloco. Note que este canal deve ser configurado com o protocolo MQTT ou o bloco irá gerar 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. Este canal de comunicação utilizado é especificado por um identificador (valor númerico) conforme indicado na tabela a seguir:

Nome	Ident.	Descrição
HILS.COM1_PORT_ID	0	Canal serial COM1
HILS.COM2_PORT_ID	1	Canal serial COM2
HILS.COM3_PORT_ID	2	Canal serial COM3
HILS.COM4_PORT_ID	3	Canal serial COM4
HILS.COM5_PORT_ID	4	Canal serial COM5
HILS.COM6_PORT_ID	5	Canal serial COM6
HILS.COM7_PORT_ID	6	Canal serial COM7
HILS.COM8_PORT_ID	7	Canal serial COM8
HILS.SOCK0_PORT_ID	8	Controlador Ethernet 1: Socket 0
HILS.SOCK1_PORT_ID	9	Controlador Ethernet 1: Socket 1
HILS.SOCK2_PORT_ID	10	Controlador Ethernet 1: Socket 2
HILS.SOCK3_PORT_ID	11	Controlador Ethernet 1: Socket 3
HILS.SOCK4_PORT_ID	12	Controlador Ethernet 1: Socket 4
HILS.SOCK5_PORT_ID	13	Controlador Ethernet 1: Socket 5
HILS.SOCK6_PORT_ID	14	Controlador Ethernet 1: Socket 6
HILS.SOCK7_PORT_ID	15	Controlador Ethernet 1: Socket 7
HILS.ETH2_SOCK0_PORT_ID	16	Controlador Ethernet 2: Socket 0
HILS.ETH2_SOCK1_PORT_ID	17	Controlador Ethernet 2: Socket 1
HILS.ETH2_SOCK2_PORT_ID	18	Controlador Ethernet 2: Socket 2
HILS.ETH2_SOCK3_PORT_ID	19	Controlador Ethernet 2: Socket 3
HILS.ETH2_SOCK4_PORT_ID	20	Controlador Ethernet 2: Socket 4
HILS.ETH2_SOCK5_PORT_ID	21	Controlador Ethernet 2: Socket 5
HILS.ETH2_SOCK6_PORT_ID	22	Controlador Ethernet 2: Socket 6
HILS.ETH2_SOCK7_PORT_ID	23	Controlador Ethernet 2: Socket 7

	Este texto pode ser utilizado como parâmetro pois esta definido no tipo COMM_CHAN_ID disponível na biblioteca HI_STD.
	Cada equipamento possui um sub-conjunto dos recursos de comunicação indicados na tabela acima. Para identificar quais recursos estão disponíveis em um dado equipamento, consulte o manual do mesmo.

KEEP_ALIVE

Valor em segundos a ser utilizado para notificar ao broker que o equipamento esta funcional quando não existirem mensagens sendo trocadas. O valor default deste parametro é 300 = 5 minutos.

MQTT_FLAGS

Define os flags MQTT utilizados no processo de conexão com o broker. O valores possíveis para este flag 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 [3]
HILS.WILL_QOS1	1	WILL MESSAGE com QOS1 [3]
HILS.WILL_QOS2	2	WILL MESSAGE com QOS2 [3]
HILS.WILL_RETAIN	4	WILL MESSAGE enviada pelo Broker com flag RETAIN ativo [4]
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

	[3] (1,2,3) Caso o usuário especifique um tópico e mensagem WILL, deve ser especificado um dos WILL_QOSx para ser associado ao tópico
	[4] 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 parametro é 8 = CLEAN_SECTION.

DEC_SEP

Esta entrada é utilizada caso seja necessário alterar o separador de casas decimais no processo de conversão de variáveis reais. O valor default utilizado na conversão é o ponto (ex: 2.45). Caso necessário modificar esta valor especifique nesta entrada o código ASCII do caracter a ser utilizado como separador de casas decimais.

Por exemplo, para gerar valores separados com vírgula (Ex: 2,45) especifique o valor 44 (código ASCII do caracter vírgula) nesta entrada.

HI_GATE

Esta entrada é utilizada para indicar quando igual a TRUE que o equipameno irá se conectar ao portal de telemetria da HI Tecnologia. Neste caso, logo após o processo de conexão com o broker é automaticamente ativado 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.

Fig. 119 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

Esta string especifica o nome do tópico associado a 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

Esta string 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

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

PASSW

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

T_CACHE

Este parâmetro fornece para o bloco uma cache onde serão inseridos os ID’s dos items a serem publicados ao broker. Um ID representa o valor númerico associado a linha do canal de mapeamento. Cada ID consequentemente mapeia uma variável global da aplicação com um nome de tópico MQTT. Esta cache portanto deve ser uma vetor de tipos INT com o tamanho definido pela aplicação. Os items a serem publicados para o broker são inseridos nesta cache através da função COMM_NOTIFY_ITEM. Uma vez inserido um item, o bloco é responsavél por remover este item e publica-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. Esta saída permanece igual a zero enquanto a entrada START estiver inativa. Uma vez ativada a entrada START esta saída juntamente com a saída CONNECTED irão indicar o resultado do processo de conexão com o broker. Se a saída CONN_CODE assumir um valor diferente de zero indica o código de falha do processo de conexão. Caso contrário esta saidá se manterá em zero e a saída CONNECTED quando ativa indicará que a conexão com o broker foi estabelecida com sucesso.

Para acesso a lista completa dos códigos de falha que podem ser reportados pelo firmware G5 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 serem recebidos do broker foi concluido. As saida SB_EV, SB_CODE e SB_ID podem ser utilizadas para rastrar condições de erro neste processo.

SB_EV

Saída lógica que gera um pulso (se mantém ativa por em um ciclo de scan da aplicação) para indicar fim do subscrição de um tópico MQTT no broker.

SB_ID

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

SB_CODE

Saída que especifica código de retorno do último processo de subscrição de tópico no broker. É atualizada com a saída SB_EV.

Para acesso a lista completa dos códigos de falha que podem ser reportados pelo firmware G5 consulte RET_CODE - Códigos de retorno do firmware G5.

PB_EV

Saída lógica que gera um pulso (se mantém ativa por em um ciclo de scan da aplicação) para indicar fim do processo de publicação de um tópico no broker.

PB_ID

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

PB_CODE

Saída que especifica código de retorno do processo de publicação de um tópico no broker. É atualizada com a saída PB_EV.

Para acesso a lista completa dos códigos de falha que podem ser reportados pelo firmware G5 consulte RET_CODE - Códigos de retorno do firmware G5

RT_EV

Saída lógica que gera um pulso (se mantém ativa por em um ciclo de scan da aplicação) para indicar fim do processo de recepção de um tópico do broker.

RT_ID

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

RT_CODE

Saída que especifica código de retorno do último processo de recepção de um tópico do broker. É atualizada com a saída RD_EV.

Para acesso a lista completa dos códigos de falha que podem ser reportados pelo firmware G5 consulte RET_CODE - Códigos de retorno do firmware G5.

Importante

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

• Para ClientID nulo deve existir uma Clear session.

• Se houver um Will Topic deve existir uma Will message.

• O valor do QOS deve ser válido.

RT_CHG

Saída lógica que gera um pulso (se mantém ativa por em um ciclo de scan da aplicação) para indicar 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 ocorrer é sincronizado com a saída RT_EV.

Ver também

Bloco de função COMM_NOTIFY_ITEM para inserir um tópico a ser enviado pelo gateway para o broker.

Bloco de função MQTT_MDB_BRIDGE para criar uma bridge de comunicação para os protocolos MQTT e MODBUS.

Bloco de função MDB_GATEWAY para disponibilizar um gateway de comuncação para o protocolo MODBUS.

Exemplo

Declaração de Variáveis

Nome	Classe	Tipo	Dimensão	Valor Inicial	Descrição
START	Local	BOOL		FALSE	Ativa operação do gateway
SCAN	Local	BOOL			Habilita publicação automatica de tópicos
SUBS	Local	BOOL			Habilita subscrição de tópicos
NOTIFY	Local	BOOL		FALSE	Publica um tópico no broker (exemplo)
BROKER_IP	Local	STRING	:15	‘192.168.0.58’	IP do broker
BROKER_PORT	Local	UDINT		1883	Porta do broker
WILL_T	Local	STRING	:80	‘W_TOPIC’	Topico de desconexão
WILL_M	Local	STRING	:140	‘W_MSG’	Mensagem de desconexão
USER	Local	STRING	:36	‘JOAO’	Usuário
PASSW	Local	STRING	:36	‘123’	Senha
T_CACHE	Local	INT	[0..99]	0	Cache para publicação de tópicos
CONNECTED	Local	BOOL		FALSE	Broker conectado
SUBSCRIBED	Local	BOOL		FALSE	Tópicos subscritos
PB_COUNT	Local	INT		0	Contador de topicos publicados
SB_COUNT	Local	INT		0	Contador de topicos subscritos
RT_COUNT	Local	INT		0	Contador de topicos recebidos
MQTT_GAT	Local	MQTT_GATEWAY			Instancia do gateway

Clique aqui para baixar a tabela de variáveis

Código ST

// 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 utilizado para acesso equipamento Modbus  (ex: COM1_PORT_ID)
  FLAGS       := HILS.CLIENT_ID + HILS.CLEAN_SECTION,  // [USINT] Flags de conexão com o broker
  //DEC_SEP     := ,          // [USINT] Separador de casas decimais no processo de conversao dos valores reais para string (default = ponto)
  //KEEP_ALIVE  := ,          // [UINT] Tempo em segundos para o broker validadar 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;