MQTT_CONTROLLER
Este bloco tem por função implementar a interface com a biblioteca de comunicação do protocolo MQTT para gerenciar a conexão e desconexão com o broker.
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.
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.
Bloco
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 ------------ |----
+------------------------+
Possui as seguintes funções principais:
Estabelece conexão com o broker especificado;
Define o tempo de keep alive da sessão;
Define os flags MQTT de sessão;
Especifica a mensagem WILL (se necessário);
Especifica o usuário e senha da conexão (se necessário);
Gerencia eventuais quedas de conexão reconectando com o broker automaticamente;
Notifica uma conexão com sucesso com o broker permitindo ao usuário assinar;
(SUBSCRIBE) os tópicos que a aplicação necessitar;
Sinaliza a recepção dos tópicos assinados, enviados pelo broker disponiblizando o nome do tópico e a mensagem associada.
O processo é iniciado através da ativação da entrada START que deve permanecer ativa durante todo o tempo de execução.
Ao ser ativado o bloco inicia o processo de conexão com o broker pelo socket ethernet especificado. Concluido o processo com sucesso a saída CONNECTED se torna ativa indicando que o cliente MQTT esta conectado ao broker e funcional.
A partir deste momento, tópicos podem ser assinados utilizando-se o bloco MQTT_SUBSCRIBE e, mensagens podem ser publicadas utilizando-se o bloco MQTT_PUBLISH.
Quando o broker enviar uma mensagem para o cliente, a saída TOP_EV irá gerar um pulso e neste momento as saídas BROKER_TOPIC e BROKER_MSG possuem o nome do tópico e a mensagem associada respectivamente.
Nota
Na implementação corrente, o tamanho máximo do nome de um tópico é de 80 caracteres. Nomes de tópicos maiores que 80 caracteres, irão gerar erro no processamento do bloco retornando do código 28 (RC_RE_FIL_OVF) e não serão tratados.
Parâmetros
Nome |
Classe |
Tipo |
Dim. |
V. Ini. |
Descrição |
START |
Entrada |
BOOL |
FALSE |
Inicia o processo de gerencia de uma conexão MQTT com um broker (ativa na transição de subida) |
|
COMM_SRC |
Entrada |
USINT |
0 |
Canal de comunicação a ser utilizado |
|
MQTT_FLAGS |
Entrada |
UINT |
8 |
Flags de conexão com o broker (default = clean section) |
|
KEEP_ALIVE |
Entrada |
UINT |
300 |
Keep alive time em segundos (default = 5 min) |
|
BROKER_PORT |
Entrada |
UINT |
1883 |
Porta de conexao com o broker (default = 1883) |
|
BROKER_IP |
Entrada/Saída |
STRING |
:* |
IP de conexão com o broker |
|
CLIENT_ID |
Entrada/Saída |
STRING |
:* |
String de identificação do cliente MQTT (opc) |
|
W_TOPIC |
Entrada/Saída |
STRING |
:* |
Nome do tópico associado a mensagem de desconexão (opc) |
|
W_MSG |
Entrada/Saída |
STRING |
:* |
Nome da mensagem de desconexão (opc) |
|
USER |
Entrada/Saída |
STRING |
:* |
Nome do usuário (opc) |
|
PASSW |
Entrada/Saída |
STRING |
:* |
Senha de acesso (opc) |
|
BROKER_TOPIC |
Entrada/Saída |
STRING |
:* |
Nome do topico recebido do broker |
|
BROKER_MSG |
Entrada/Saída |
STRING |
:* |
Mensagem associada ao tópico recebido do broker |
|
CONNECTED |
Saída |
BOOL |
FALSE |
Conexão com o broker estabelecida com sucesso |
|
ERROR |
Saída |
INT |
0 |
Último código de erro detectado no processo |
|
ERR_EV |
Saída |
BOOL |
FALSE |
Gera um pulso ao completar qualquer processo com erro |
|
TOP_EV |
Saída |
BOOL |
FALSE |
Gera um pulso ao receber um tópico do broker |
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. |
MQTT_FLAGS
Define os flags MQTT utilizados no processo de conexão com o Broker. O valores possiveis para este flag são:
Nome |
Ident. |
Descrição |
WILL_QOS0 |
0 |
WILL MESSAGE com QOS0 [3] |
WILL_QOS1 |
1 |
WILL MESSAGE com QOS1 [3] |
WILL_QOS2 |
2 |
WILL MESSAGE com QOS2 [3] |
WILL_RETAIN |
4 |
WILL MESSAGE enviada pelo Broker com flag RETAIN ativo [4] |
CLEAN_SECTION |
8 |
Broker inicia uma sessão limpa |
O valor default deste parametro é 8 = CLEAN_SECTION.
KEEP_ALIVE
Valor em segundos a ser utillzado para notificar ao broker o equipamento esta funcional quando não existirem mensagens sendo trocadas. O valor default deste parametro é 300 = 5 minutos.
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’).
Nota
Esta string deve possuir no máximo 15 caracteres.
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. Quando especificado este parâmetro o parâmentro W_MSG deve ser especificado obrigatoriamente.
Nota
Esta string associada ao tópico de WILL deve possuir no máximo 80 caracteres.
W_MSG
Esta string especifica a mensagem associada WILL a ser utilizada. Esta mensagem é opcional e enviada aos clientes que assinaram o tópico WTOPIC quando o cliente se desconecta do broker. Quando especificado este parâmetro o parâmentro W_TOPIC deve ser especificado obrigatoriamente.
Nota
Esta string associada a mensagem de WILL deve possuir no máximo 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.
Nota
Esta string deve possuir no máximo 36 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.
Nota
Esta string deve possuir no máximo 36 caracteres.
BROKER_TOPIC
Quando o broker enviar um tópico assinado para o cliente, o saída TOP_EV irá gerar um pulso notificando a chegada do tópico. Neste momento, o nome do tópico estará disponível neste parâmetro e deverá ser processado. O tamnaho maximo do nome de um tópico no ambiente é de 80 caracteres. Note que este parâmetro deverá ser processado durante o evento de TOP_EV pois o mesmo poderá ser alterado nos ciclos seguintes.
Nota
Esta string deve possuir no mínimo 80 caracteres.
BROKER_MSG
Quando o broker enviar um tópico assinado para o cliente, o saída TOP_EV irá gerar um pulso notificando a chegada do tópico, e a saída ERROR indicado o resultado do processo de recepção do tópico. Neste momento, o nome do tópico estara disponivél para procesamento bem como e a mensagem associada ao tópico. Note que este parâmetro deverá ser processado durante o evento de TOP_EV pois o mesmo poderá ser alterado nos ciclos seguintes.
Exemplo
Declaração de Variáveis
Nome |
Classe |
Tipo |
Dimensão |
Valor Inicial |
Descrição |
|---|---|---|---|---|---|
BROKER_IP |
Local |
STRING |
‘192.168.0.58’ |
IP do Broker |
|
BROKER_PORT |
Local |
UDINT |
1883 |
porta de escuta do broker |
|
MQTT_CT |
Local |
HILS.MQTT_CONTROLLER |
bloco de controle do protocolo MQTT |
||
START |
Local |
BOOL |
1 |
Habilita protocolo |
|
REC_TOPIC |
Local |
STRING |
Nome do tópico recebido do broker |
||
REC_MSG |
Local |
STRING |
Mensagem associada ao tópico recebido do broker |
||
W_TOPIC |
Local |
STRING |
:80 |
Nome do tópico associado ao processo de desconexão do cliente (opcinal) |
|
W_MSG |
Local |
STRING |
:140 |
Mensagem associada ao processo de desconexão do cliente (opcinal) |
|
USER |
Local |
STRING |
:36 |
‘joao’ |
Nome do usuário (opcinal) |
PASSW |
Local |
STRING |
:36 |
‘1234’ |
Senha de acesso (opcinal) |
MQTT_PUB |
Local |
HILS.MQTT_PUBLISH |
Bloco de publicação do protocolo MQTT |
||
PUB_ITEM |
Local |
BOOL |
FALSE |
Flag para publicar um item |
|
PUB_TOPIC |
Local |
STRING |
‘temp’ |
Nome do tópico a ser publicado |
|
PUB_MSG |
Local |
STRING |
‘123.oC’ |
Valor do tópico a ser publicado |
|
MQTT_SUB |
Local |
HILS.MQTT_SUBSCRIBE |
Bloco de assinatura do protocolo MQTT |
||
SUB_TOPIC |
Local |
STRING |
‘temp’ |
Nome do tópico a ser assinado |
Código ST
// Este código, abre conexão com o broker MQTT, assina o tópico 'temp' e a cada
// ativação da variavel PUB_ITEM, publica o tópico 'temp' com valor '123.oC'.
// Note que, como o tópico é publicado tem o mesmo nome do tópico assinado, após
// a publicação, o topico é recebido do broker.
// Abre uma conexão (Clean section com Keep Alive = 5 min)
MQTT_CT( // MQTT_CONTROLLER
START := START, // [BOOL] Inicia o processo de gerencia de uma conexão MQTT com um broker (ativa na transição de subida)
COMM_SRC := HILS.SOCK1_PORT_ID, // [USINT] Canal de comunicação a ser utilizado
MQTT_FLAGS := HILS.CLEAN_SECTION, // [USINT] 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 conexao com o broker (default = 1883)
BROKER_IP := BROKER_IP, // [STRING] IP de conexão com o broker
CLIENT_ID := , // [STRING] String de identificação do cliente MQTT (opc)
W_TOPIC := W_TOPIC, // [STRING] Nome do tópico associado a 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 topico recebido do broker
BROKER_MSG := REC_MSG // [STRING] Mensagem associada ao tópico recebido do broker
);
// Assim que a conexao com o broker for realizada assina um tópico
MQTT_SUB( // MQTT_SUBSCRIBE
START := MQTT_CT.CONNECTED, // [BOOL] Inicia o processo de publicação de um tópico QTT (ativa na transição de subida)
COMM_SRC := HILS.SOCK1_PORT_ID, // [USINT] Canal de comunicação a ser utilizado
TOPIC := SUB_TOPIC // [STRING] Nome do topico 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 QTT (ativa na 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 topico a ser publicado
MESSAGE := PUB_MSG // [STRING] Mensagem associado ao topico a ser publicado
);
IF MQTT_PUB.DONE_EV THEN
PUB_ITEM := FALSE;
END_IF;
END_IF;