MQTT_Q4GA1

Conecta-se a um broker MQTT através do módulo de modem celular 4GA1 (4G CAT-M) instalado na ITF-B do equipamento e realiza o publishing/subscribing das variáveis catalogadas no canal de Mapeamento de dados do projeto. É um bloco de função (mantém estado entre scans; requer instância) e opera apenas com o módulo 4GA1 na ITF-B.

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

Faz 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.

Bloco de função

                   MQTT_Q4GA1
           +-------------------------+
  BOOL ----|START        MODEM_STATUS|---- USINT
           |                         |
  BOOL ----|EN_SCAN            RESULT|---- INT
           |                         |
  BOOL ----|EN_SUBS         CONNECTED|---- BOOL
           |                         |
  BOOL ----|USE_FLED            SB_EV|---- BOOL
           |                         |
 USINT ----|DMAP_ID             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
           |                         |
           |                    RT_EV|---- BOOL
           |                         |
           |                   RT_CHG|---- BOOL
           |                         |
           |                    RT_ID|---- INT
           |                         |
           |                  RT_CODE|---- INT
           |                         |
STRING ----|CLIENT_ID -------------- |----
           |                         |
STRING ----|W_TOPIC ---------------- |----
           |                         |
STRING ----|W_MSG ------------------ |----
           |                         |
STRING ----|USER ------------------- |----
           |                         |
STRING ----|PASSW ------------------ |----
           |                         |
   INT ----|T_CACHE ---------------- |----
           +-------------------------+

Antes de utilizar o bloco, configure no módulo de modem os parâmetros de acesso à rede celular (APN, PIN, User, Password) e o IP (ou URL) e a porta de conexão com o broker MQTT. Essa configuração é feita pelo script “Configura módulo 4GA1”, disponível no HIstudio em Ferramentas ‣ Ferramentas avançadas ‣ Scripts.

Ao ser inserido na aplicação, o bloco mantém o modem inativo aguardando uma transição de subida na entrada START. Nessa transição o módulo 4GA1 é habilitado e executa todo o registro na rede celular e a abertura da conexão TCP com o broker; estabelecida a conexão TCP, inicia-se a conexão do protocolo MQTT e, concluída com êxito, o bloco entra na rotina padrão de publishing e subscribing. A entrada START deve permanecer em nível alto durante toda a execução do bloco.

Se habilitado (USE_FLED), o bloco usa o LED vermelho do equipamento para sinalizar os estados:

LED vermelho aceso: configurando a rede celular ou bloco desabilitado.
LED vermelho piscando: em processo de abertura da conexão TCP.
LED vermelho apagado: operando, trocando dados com sucesso.

Importante

Este bloco opera apenas com o módulo de modem 4GA1 na ITF-B do equipamento. Quando o equipamento possuir o módulo de modem 4G (EG915), utilize o bloco MQTT_QC1. Quando possuir o módulo U3G (3G-SARA-U201), utilize o bloco MQTT_RNB_U3G.

Dica

Para conhecer melhor o recurso e suas funcionalidades acesse o vídeo tutorial: Trabalhando com MQTT utilizando modem integrado 4G.

Nota

Para as variáveis DMAP_ID, DEC_SEP, HI_GATE, KEEP_ALIVE, USER, PASSW, T_CACHE, W_TOPIC e W_MSG consulte também a documentação do bloco MQTT_GATEWAY.

Parâmetros

Nome	Direção	Tipo	Dimensão	Padrão	Faixa / Unidade	Descrição
START	IN	BOOL	—	FALSE	—	Habilita a operação do bloco (deve permanecer em nível alto).
EN_SCAN	IN	BOOL	—	TRUE	—	Habilita o ciclo de notificações automáticas ao broker.
EN_SUBS	IN	BOOL	—	TRUE	—	Ativa o processo de registro (subscribe) dos itens.
USE_FLED	IN	BOOL	—	FALSE	—	Usa o LED de falha do equipamento para indicar o status de conexão com a rede celular e o broker.
DMAP_ID	IN	USINT	—	0	—	Id do mapeamento de dados associado ao bloco MQTT.
FLAGS	IN	UINT	—	8	—	Flags de conexão com o broker (default: clean session).
DEC_SEP	IN	USINT	—	46	—	Separador de casas decimais na conversão de reais para string (46 = ponto).
HI_GATE	IN	BOOL	—	FALSE	—	Se TRUE e conectado ao Portal da HI Tecnologia, notifica que é um equipamento HI e sincroniza o relógio automaticamente.
KEEP_ALIVE	IN	UINT	—	300	s	Tempo, em segundos, para o broker validar a conexão.
CLIENT_ID	IN_OUT	STRING	:*	—	—	Nome do cliente na conexão com o broker (opcional).
W_TOPIC	IN_OUT	STRING	:*	—	—	Tópico associado à mensagem de desconexão (last will).
W_MSG	IN_OUT	STRING	:*	—	—	Mensagem de desconexão (last will).
USER	IN_OUT	STRING	:*	—	—	Usuário/login de autenticação no broker MQTT (opcional).
PASSW	IN_OUT	STRING	:*	—	—	Senha de autenticação no broker MQTT (opcional).
T_CACHE	IN_OUT	INT	[*]	0	—	Cache de tópicos a serem enviados ao broker (fornecer um vetor de INT).
MODEM_STATUS	OUT	USINT	—	0	—	Status de conexão do modem (ver Observações).
RESULT	OUT	INT	—	0	RET_CODE	Resultado da operação do bloco (ver Códigos de retorno).
CONNECTED	OUT	BOOL	—	FALSE	—	Indica que o equipamento está conectado ao broker.
SB_EV	OUT	BOOL	—	FALSE	—	Indica o fim do processo de subscribe de um tópico.
SB_ID	OUT	INT	—	0	—	Id do item da última aquisição do equipamento remoto.
SB_CODE	OUT	INT	—	0	—	Código de retorno da última recepção remota.
PB_EV	OUT	BOOL	—	FALSE	—	Indica o fim do processo de escrita (publish) de um item no equipamento remoto.
PB_ID	OUT	INT	—	0	—	Id do item da última escrita no equipamento remoto.
PB_CODE	OUT	INT	—	0	—	Código de retorno da última escrita no equipamento remoto.
RT_EV	OUT	BOOL	—	FALSE	—	Indica o fim do processo de recepção de um tópico do broker.
RT_CHG	OUT	BOOL	—	FALSE	—	Indica que o tópico recebido é diferente do valor anterior na base global.
RT_ID	OUT	INT	—	0	—	Id do item da última recepção de tópico do broker.
RT_CODE	OUT	INT	—	0	—	Código de retorno da última recepção de tópico do broker.

Códigos de retorno

O erro gerado no processo é reportado por RESULT, obtido da saída CONN_CODE do bloco MQTT_GATEWAY chamado internamente. Use os identificadores com o namespace HILS (ex.: HILS.CO_EQP_TMO). Códigos mais relevantes deste bloco:

Código	Identificador	Significado
0	SUCCESS	Processo executado com sucesso.
63	CO_CONEX_FAIL	Falha no processo de conexão.
64	CO_DEV_UNCONN	Desconexão realizada pelo equipamento remoto.
80	CO_EQP_TMO	Timeout na resposta do equipamento externo (modem).
180	CN_PIN_ERR	PIN inválido ou bloqueado.
181	CN_SIM_CARD_ERR	SIM card inválido ou não encontrado.
182	CN_NO_NET	Não detectou rede celular.
185	CN_AUTH_DENIED	Autenticação na rede celular negada.

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

Pré-condições

O módulo de modem 4GA1 deve estar instalado na ITF-B do equipamento.
O modem deve estar configurado (APN, PIN, User, Password, IP/URL e porta do broker) pelo script “Configura módulo 4GA1” do HIstudio.
A entrada START deve permanecer em nível alto durante toda a operação.

Observações

A saída MODEM_STATUS reflete o estado de conexão do modem:

Valor	Descrição
-1	Hardware incompatível.
0	Falha de hardware.
1	Configuração do modem inválida.
2	Sem SIM card.
10	Sem rede celular.
11	Falha de autenticação na rede celular.
12	Modem em modo de configuração.
15	Erro no acesso ao servidor (ex.: IP/porta inválidos).
19	Modem com conexão estabelecida.

Ver também

MQTT_QC1, MQTT_RNB_U3G, MQTT_GATEWAY, protocolo MQTT

Exemplo

Clique aqui para baixar a tabela de variáveis

Código ST

VAR
    START           : BOOL := FALSE;      (* Habilita operação do bloco *)
    MQTT_CLI_ID     : STRING := 'DEV_ID'; (* Nome do cliente na conexão com o broker (opcional) *)
    MQTT_USER       : STRING;             (* Usuário/login de autenticação do broker MQTT (opcional) *)
    MQTT_PASSW      : STRING;             (* Senha de acesso do login de autenticação do broker MQTT (opcional) *)
    MQTT_W_TOPIC    : STRING;             (* Tópico associado à mensagem de desconexão *)
    MQTT_W_MSG      : STRING;             (* Mensagem de desconexão *)
    MQTT_CACHE      : INT := 0;           (* Cache de tópicos a serem enviados ao broker (vetor de INT) *)
    MQTT_DMAP_ID    : USINT := 0;         (* Id do mapeamento de dados associado ao bloco *)
    MQTT_DEC_SEP    : USINT := 46;        (* Separador decimal na conversão de reais para string (46 = ponto) *)
    MQTT_KEEP_ALIVE : UINT := 300;        (* Tempo em segundos para o broker validar a conexão *)
    MQTT_CEL_RESULT : INT := 0;           (* Resultado da operação do bloco de conexão MQTT via rede celular *)
    MODEM_MQTT      : HILS.MQTT_Q4GA1;    (* Instância do bloco MQTT_Q4GA1 *)
END_VAR

MODEM_MQTT(
  START      := START,           (* [BOOL] Habilita operação do bloco *)
  DMAP_ID    := MQTT_DMAP_ID,    (* [USINT] Id do mapeamento de dados associado ao bloco MQTT *)
  CLIENT_ID  := MQTT_CLI_ID,     (* [STRING] Nome do cliente na conexão com o broker (opcional) *)
  USER       := MQTT_USER,       (* [STRING] Usuário/login de autenticação do broker MQTT (opcional) *)
  PASSW      := MQTT_PASSW,      (* [STRING] Senha de acesso do login de autenticação do broker MQTT (opcional) *)
  T_CACHE    := MQTT_CACHE,      (* [INT] Cache de tópicos a serem enviados ao broker (vetor de INT) *)
  DEC_SEP    := MQTT_DEC_SEP,    (* [USINT] Separador decimal na conversão de reais para string *)
  KEEP_ALIVE := MQTT_KEEP_ALIVE, (* [UINT] Tempo em segundos para o broker validar a conexão *)
  W_TOPIC    := MQTT_W_TOPIC,    (* [STRING] Tópico associado à mensagem de desconexão *)
  W_MSG      := MQTT_W_MSG       (* [STRING] Mensagem de desconexão *)
  );

MQTT_CEL_RESULT := MODEM_MQTT.RESULT;