MQTT_SUBSCRIBE

Este bloco permite que tópicos sejam registrados (SUBSCRIBE) em um broker MQTT para posteriormente serem notificados para o cliente.

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 como cliente TCP-IP (sem conexão automática) com protocolo MQTT e o tamanho da cache de dados do socket dever ser de no mínimo 500 bytes (1460 max.)

Bloco

              MQTT_SUBSCRIBE
           +-------------------+
  BOOL ----|START       DONE_EV|---- BOOL
           |                   |
 USINT ----|COMM_SRC     RESULT|---- INT
           |                   |
  BOOL ----|SUBSCRIBE          |
           |                   |
 USINT ----|QOS                |
           |                   |
STRING ----|TOPIC ------------ |----
           +-------------------+

Este bloco opera em conjunto com o bloco MQTT_CONTROLLER e só deve ser ativado após a saída CONNECTED do bloco MQTT_CONTROLLER se tornar ativa, indicando que a conexão com o broker foi executada com sucesso.

Nesta condição o processo é iniciado através da ativação da entrada START que deve permanecer ativa durante todo o tempo de assinatura do tópico.

São especificados os seguintes parâmetros:

identificador do socket ethernet associado ao broker;

nome do tópico a ser publicado;

Maxima QOS (Quality of service) associado ao tópico a ser publicado;

Ao final do processo de assinatura, a saída DONE_EV gera um pulso de conclusão especifica em RESULT o código de retorno do processo.

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 código de retorno 28 (RC_RE_FIL_OVF).

Parâmetros

Nome	Classe	Tipo	Dim.	V. Ini.	Descrição
START	Entrada	BOOL		FALSE	Inicia o processo de publicação de um tópico QTT (ativa na transição de subida)
COMM_SRC	Entrada	USINT		0	Canal de comunicação a ser utilizado
SUBSCRIBE	Entrada	BOOL		TRUE	Se TRUE registra (Subscribe) o tópico especificado. Se FALSE Remove o registro (Unsubscribe) do tópico
QOS	Entrada	USINT		0	Maximo QOS que o broker pode notificar esta mensagem (0..2)
TOPIC	Entrada/Saída	STRING	:*		Nome do topico a ser assinado
DONE_EV	Saída	BOOL		FALSE	Gera um pulso no final do processo ou se detectada falha no processo
RESULT	Saída	INT		0	Resultado do processo de publicação

COMM_SRC

Identificador do socket ethernet a ser utilizado para acesso ao broker. Este do canal de comunicação utilizado é especificado por um identificador (valor númerico) conforme indicado na tabela a seguir:

ID	LABEL [4]	Tipo de canal de comunicação [5]
8	HILS.SOCK0_PORT_ID	Identificador do socket 0
9	HILS.SOCK1_PORT_ID	Identificador do socket 1
10	HILS.SOCK2_PORT_ID	Identificador do socket 2
11	HILS.SOCK3_PORT_ID	Identificador do socket 3
12	HILS.SOCK4_PORT_ID	Identificador do socket 4
13	HILS.SOCK5_PORT_ID	Identificador do socket 5
14	HILS.SOCK6_PORT_ID	Identificador do socket 6
15	HILS.SOCK7_PORT_ID	Identificador do socket 7

	[4] Este texto pode ser utilizado como parâmetro pois esta definido no tipo COMM_SRC disponível na biblioteca HI_STD
	[5] 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.

TOPIC

Esta string especifica o nome do tópico a ser assinado no broker. 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.

RESULT

Tipo Dado

Descrição

INT

Código de retorno na execução da função, do tipo RET_CODE, onde:

Se for igual a 0: Função executada com sucesso - código HILS.SUCCESS

Se for diferente de 0: Falha na execução da função indica o respectivo código de erro. [6]

Exemplo

Declaração de Variáveis

Nome	Classe	Tipo	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 assocada ao tópico recebido do broker
WILL	Local	STRING		WILL message de conexão
USER	Local	STRING		Usuario e senha de conexao
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

Clique aqui para baixar a tabela de variáveis

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_ENGINE
  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
  BROKER_IP    := BROKER_IP,    // [STRING] IP de conexão com o broker 192.168.0.80
  BROKER_PORT  := BROKER_PORT,  // [UINT] Porta de conexao com o broker
  WILL_P       := WILL,         // [STRING] Topico e mensagem de WILL (separados por |)
  USER_P       := USER,         // [STRING] Nome e senha do usuário (separados por |)
  BROKER_TOPIC := REC_TOPIC,    // [STRING] Nome do topico recebido
  BROKER_MSG   := REC_MSG       // [STRING] Mensagem associada ao tópico recebido
  );

// 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;