Utilizando o protocolo MQTT no Portal

Conforme definido na Introdução ao protocolo MQTT, este protocolo permite a comunicação entre equipamentos(Cliente MQTT) através de um Broker MQTT.

Este Broker MQTT, entre outras possibilidades, pode ser disponibilizado na nuvem(internet), que é o caso do BROKER MQTT do Portal de Telemetria.

Portanto, do ponto de vista do Portal de Telemetria, a integração de equipamentos que utilizam o protocolo MQTT envolve basicamente dois cenários:

• O principal cenário é a possibilidade de que equipamentos remotos enviem valores aos Dados de um Conector previamente cadastrado no Portal, ou seja, equipamentos remotos podem publicar informações em tópicos associados aos Dados;

• Outro cenário é que os valores informados(escritos) nos Dados de um Conector através do Portal podem ser “enviados” aos equipamentos remotos, ou seja, os equipamentos podem assinar os tópicos associados aos Dados desejados.

Desta maneira, a interface e recursos do Portal de Telemetria podem utilizar os valores “compartilhados” pelos equipamentos, tais como:

• Registro de valores no Histórico de Dados;

• Geração de Alarmes e notificação via Telegram/E-mail;

• Apresentação dos valores de dados em Telas Sinóticas;

• Etc.

Informações de cadastro de um Conector MQTT

Após o cadastro de um Conector MQTT no Portal de Telemetria, tem-se acesso as informações necessárias para que um Cliente MQTT seja configurado para fazer a interface com o mesmo: estabelecer a conexão com o Portal e interagir com os tópicos associados aos Dados do Conector:

Fig. 34 Formulário com informações de cadastro de um Conector MQTT.

Nessa interface, estão presentes todas as informações necessárias para que um Cliente MQTT interaja com um Conector do Portal via MQTT:

Informação	Função
Informações de acesso ao BROKER	Indica o endereço IP/URL e a Porta que o cliente deve utilizar para se conectar ao broker
Chave de Acesso	Indica a informação que o cliente deve utilizar como usuário(username) da conexão com o broker
Identificador de Tópico e ID de Cliente MQTT do Conector	Indica o ID do Cliente(client_id) que o cliente deve utilizar na conexão com o broker

A seguir, vamos explicar em detalhes cada uma das informações.

Atenção

Atualmente, o Portal de Telemetria limita a quantidade de Conectores MQTT que não utilizam Modelos de Hardware de fabricação da HI Tecnologia. Essa limitação é imposta por Contrato e leva em consideração a faixa de dados do Plano contratado:

Faixa de Dados	Quantidade de Conectores MQTT(não HI)
50	5
150	15
300	30
400(white label)	40
500	50
700(white label)	70
1000(white label)	100

BROKER MQTT do Portal de Telemetria

O BROKER MQTT do Portal de Telemetria é o intermediário que permite a integração de equipamentos que utilizam o protocolo MQTT com os Conectores previamente cadastrados no Portal.

Portanto, abaixo serão descritas as informações necessárias para que um equipamento que implemente o protocolo MQTT, no caso, um Cliente MQTT, possa se integrar ao Portal de Telemetria.

Informações de acesso ao BROKER

Para que um Cliente MQTT se conecte ao BROKER MQTT do Portal de Telemetria, primeiramente deve-se utilizar as seguintes informações de acesso ao Broker:

Identificação	IP	URL	Porta	Porta Segura
TCP	107.21.253.4	broker.mqtt.hitecnologia.com.br	1883	8883
Web Socket	107.21.253.4	broker.mqtt.hitecnologia.com.br	1884	8884

Atenção

Para utilização de uma conexão criptografada através de uma porta segura com o Broker, o Cliente MQTT deve utilizar o certificado disponível neste link.

Autenticação de um Cliente MQTT no BROKER do Portal

Além das informações de acesso, é necessário que o Cliente MQTT se autentique no BROKER MQTT do Portal de Telemetria para que a conexão seja estabelecida com sucesso.

Para isso, são necessárias algumas informações a serem utilizadas na conexão:

Chave de Acesso

Para que um Cliente MQTT se autentique no BROKER MQTT do Portal de Telemetria, primeiramente é necessário que o mesmo informe uma Chave de acesso como sendo o usuário da conexão.

Essa Chave de acesso é um recurso “global” do Contrato onde o Conector que se deseja conectar ao Portal esteja cadastrado. A chave possui uma identificação única que autoriza o equipamento remoto a se conectar ao BROKER MQTT do Portal de Telemetria.

Portanto, uma Chave de acesso pode ser utilizada apenas na conexão com os conectores de um mesmo Contrato.

Obtendo as Chaves de Acesso no cadastro do Conector

Inicialmente, as chaves de acesso podem ser obtidas diretamente no cadastro do Conector MQTT que se deseja fazer a interface:

Fig. 35 Chave de Acesso ao Conector.

Nesta opção, são apresentadas as chaves de acesso já configuradas no Contrato e que podem ser utilizadas para acesso ao Conector.

Obtendo as Chaves de Acesso de um Contrato

Para acessar as configurações de Chaves de Acesso do Contrato, realize os seguintes passos:

• Selecione o menu de Configurações de preferências da interface em , ao lado do email do usuário;

• Nas opções de Preferências, clicar em Mais…;

• Neste ponto, será apresentada a Página de configurações da conta do usuário. Então clique em Chaves de Acesso;

Fig. 36 Sequencia para acessar a página de Chaves de Acesso de um contrato.

Para as instruções de como criar e configurar Chaves de Acesso, acesse a seção Configurando Chaves de Acesso.

Atenção

Por padrão, em todo Contrato é disponibilizada uma Chave de Acesso que pode ser utilizada sem a necessidade de se criar uma nova.

Identificador de Tópico e ID de Cliente MQTT do Conector

Além da Chave de Acesso, é necessário que seja informado também o Identificador de Tópico e ID de Cliente MQTT (exclusivo) associado a cada Conector cadastrado no Portal de Telemetria.

Essa informação deve ser utilizada como sendo o ID de Cliente(client_id) da conexão MQTT.

Desse modo, para configurar um Conector com o protocolo MQTT, basta selecionar em Modelos de Hardware qualquer modelo que suporte o protocolo MQTT e escolher este protocolo no Conector.

Abaixo segue um exemplo de configuração de um Conector com o protocolo MQTT:

Fig. 37 Exemplo de configuração de um Conector que utiliza o protocolo MQTT.

Após o cadastro do Conector, é possível obter Identificador MQTT no formulário de cadastro do mesmo:

Fig. 38 Identificador de Tópico e ID de Cliente MQTT de um Conector.

Configurando a conexão MQTT

Com base nas informações acima, a tabela a seguir resume quais são os parâmetros necessários a serem utilizados na conexão MQTT com o BROKER MQTT do Portal de Telemetria:

Credenciais MQTT	Parâmetro
Nome do usuário	Chave de Acesso (obtida no formulário de cadastro do Conector ou na página de configurações do Contrato)
Senha	Qualquer caractere - não utilizado
ID do cliente	Identificador de Tópico e ID de Cliente MQTT do Conector (obtido no formulário de cadastro do Conector)

Formulário de instruções para conexão

No cadastro do Conector MQTT, também é disponibilizado um botão chamado Instruções para conexão, no qual leva o usuário para um formulário interativo onde é possível definir as configurações desejadas para a conexão do Cliente MQTT ao Portal.

Com base nessas informações, é apresentado um JSON consolidando todas as informações, que pode ser facilmente copiado ou baixado para simplificar o processo de configuração:

Fig. 39 Exemplo de configuração para conexão não segura com o broker do Portal.

Por padrão, são apresentadas as configurações mais comuns de acesso ao broker do Portal, considerando a conexão em seu endereço IP(107.21.253.4) e na Porta não segura(1883).

Outro exemplo é selecionar as opções de conexão segura via a URL do broker:

Fig. 40 Exemplo de configuração para conexão segura com o broker do Portal.

Neste caso, o host da conexão é a URL do broker do Portal (broker.mqtt.hitecnologia.com.br) e utiliza-se a Porta Segura(8883). Neste caso, é necessário fazer o download do certificado através do botão Baixar certificado e utilizá-lo no Cliente MQTT para conexão segura com o broker.

Já abaixo, segue um outro exemplo com uma chamada de conexão utilizando um cliente Javascript MQTT:

var client = mqtt.connect(
    'broker.mqtt.hitecnologia.com.br', {
        clientId: '9a3547bc',
        username: '6f27b6700ede4a0db47560db0cf7d3de',
        password: ''
    }
)

Atenção

O BROKER MQTT do Portal de Telemetria permite a utilização de apenas uma conexão MQTT simultânea por ID de Cliente, ou seja, somente uma conexão por Conector. Caso seja identificada uma nova conexão utilizando o mesmo ID de Cliente(Conector) e a mesma seja autenticada com sucesso, a conexão anterior será fechada.

Devido a diversos fatores que envolvem o acesso a um servidor na nuvem, como instabilidade da internet, manutenções, etc, é fundamental que o Cliente MQTT implemente uma rotina consistente e temporizada de reconexão com o BROKER MQTT do Portal de Telemetria em caso de perda de conexão.

Publicando(enviando) valores em Tópicos(dados) de um Conector

No contexto do Portal de Telemetria, publicar valores em um tópico de um Conector significa que o equipamento remoto publicará valores no BROKER MQTT do Portal de Telemetria para que o Dado associado ao tópico “assuma” os valores enviados.

Desta maneira, todos os recursos do Portal que envolvem Dados podem ser utilizados, como por exemplo, a apresentação desses valores em uma tela sinótica.

Atenção

O BROKER MQTT do Portal de Telemetria restringe as publicações em tópicos de um determinado Conector apenas para a Conexão MQTT que utilize o seu ID de Cliente(client_id) com o valor do Identificador de Tópico e ID de Cliente MQTT do Conector diretamente associado ao Conector. Caso seja utilizado um outro ID de Cliente(e o mesmo seja autenticado com sucesso), as publicações serão recusadas.

Dados de um Conector MQTT

Os Dados de um Conector configurado com o protocolo MQTT representam na verdade os Tópicos MQTT do Conector.

Abaixo seguem as configurações de um Dado que envolvem o protocolo MQTT:

Fig. 41 Exemplo de configuração de um Dado para o protocolo MQTT.

Portanto, as configurações pertinentes ao protocolo MQTT em um Dado são as seguintes:

Definição do Tópico MQTT

Para publicar valores em Dados de um Conector cadastrado no Portal de Telemetria, deve-se primeiramente definir um rótulo(label) de acesso aos Dados.

O rótulo definido para um Dado formará em conjunto com o Identificador de Tópico e ID de Cliente MQTT do Conector (o identificador se encontra na página de configuração do Conector) e/ou com rótulo MQTT de seu Dispositivo(caso definido na página de configuração do Dispositivo) o tópico MQTT de acesso ao Dado.

Tópico MQTT de um Dado sem utilizar um rótulo no Dispositivo

Abaixo, segue um exemplo de definição de um tópico de um Dado sem a utilização de um rótulo para o seu Dispositivo:

Fig. 42 Exemplo de configuração de um tópico MQTT associado a um Dado.

Desse modo, conforme a imagem acima, o tópico MQTT de acesso ao Dado é definido da seguinte forma:

IDENTIFICADOR-MQTT-CONECTOR/ROTULO-DADO -> 9a3547bc/temperatura-forno

Inicialmente, o Portal permitia apenas este formato de definição de tópicos associados aos seus Dados, já que não havia uma configuração de rótulo no Dispositivo.

Tópico MQTT de um Dado utilizando um rótulo no Dispositivo

Já no seguinte exemplo, segue um exemplo de definição de um tópico de um Dado com a utilização de um rótulo para o seu Dispositivo:

Fig. 43 Exemplo de configuração de um tópico MQTT associado a um Dado de um Dispositivo Virtual.

Desse modo, conforme a imagem acima, o tópico MQTT de acesso ao Dado é definido da seguinte forma:

IDENTIFICADOR-MQTT-CONECTOR/ROTULO-DISPOSITIVO/ROTULO-DADO -> 9a3547bc/cozinha/temperatura-forno

Com este conceito, é possível agrupar tópicos de um Conector MQTT de acordo com os Dados que o Dispositivo possui e que faz interface no campo.

Atenção

O Portal de Telemetria pré-define o rótulo a ser utilizado como tópico de acesso ao Dado de acordo com o nome definido para mesmo.

Por questões de melhores práticas na identificação de tópicos MQTT, o Portal restringe a utilização de letras maiúsculas, espaços, acentos e caracteres especiais na definição do tópico.

Caso se utilize um Dispositivo Virtual(veja mais sobre este conceito em Dispositivos Virtuais) em um Conector MQTT, é obrigatório a utilização de um rótulo MQTT neste Dispositivo para formação dos tópicos de acesso aos seus Dados deste Dispositivo.

Tipos de Memórias

Atualmente, o Portal de Telemetria disponibiliza dois tipos de memória para publicação em tópicos MQTT: Número e String.

Número

Para o tipo Número, são aceitos valores inteiros ou reais. Exemplos:

• Inteiros: 0, 10, 200, 3000, 40000, etc;

• Reais: 5.75, 13.9, 150.25, etc.

String

Para o tipo String, são aceitos valores textos de até 246 caracteres definidos pela codificação ASCII.

Exemplos:

• TEMPERATURA ALTA, desligado, acionado, etc.

Modos de armazenamento do Histórico de Dados

Confira na seção de Tipos de Histórico para um Dado as diferentes opções disponíveis em relação à forma como os valores publicados para um Dado podem ser registrados no Histórico de Dados de um Conector.

Atenção

Conforme orientado na documentação citada acima, é crucial tomar precauções ao configurar o tipo de histórico para um Dado de um Conector, especialmente ao usar o protocolo MQTT.

Considerando que, neste protocolo, o equipamento remoto é responsável por publicar os valores nos tópicos associados aos Dados, há um RISCO SIGNIFICATIVO de ULTRAPASSAR a cota mensal de registros no histórico se o tipo de configuração não for o Periódico.

Portanto, recomendamos fortemente o uso deste tipo de configuração. Caso deseje utilizar os outros tipos, será responsabilidade da aplicação do equipamento remoto gerenciar as publicações ou utilizar outros recursos para controlar os registros no histórico e garantir que a cota mensal não seja ultrapassada, o que resultaria no DESCARTE DE NOVOS REGISTROS.

Para verificar os limites impostos pelo Portal de Telemetria para o Histórico de Dados, acesse Uso do Histórico.

Parâmetros de Escrita em Dados através do Portal

O Portal de Telemetria trata a escrita em Dados de um Conector MQTT como uma publicação no tópico associado ao Dado.

Por exemplo, as escritas realizadas em Dados MQTT do Portal, seja utilizando o painel de dados ou controles de um sinótico, realizam uma publicação no BROKER MQTT do Portal de Telemetria com o valor da escrita no tópico associado ao dado.

Portanto, quando habilitada a escrita em um Dado associado a um Conector MQTT, serão apresentadas algumas configurações para que sejam definidos os critérios de publicação que o Portal utilizará na operação de escrita:

• MQTT QoS: define a QoS(Qualidade de Serviço) que será utilizada na publicação. Para mais informações, acesse Qualidade de serviço - QoS;

• MQTT Retain: define se a mensagem de escrita no Dado será publicada como retentiva no Broker. Para mais informações, acesse Mensagens Retidas(Retained Messages).

Um detalhe importante a ser observado aqui é que Conector MQTT além de realizar publicações, pode também assinar determinados tópicos associados a Dados que permitem escrita pelo Portal.

Dessa maneira, o equipamento poderá obter os valores escritos através do Portal nesses tópicos e tratar a informação conforme desejado.

Um exemplo de utilização seria a parametrização de um set point de temperatura, sendo este definido através do Portal.

Para mais informações sobre assinatura de tópicos, acesse: Assinando(recebendo) valores de Tópicos(dados) de um Conector.

Conteúdo de uma publicação

Atualmente e independente do protocolo dos equipamentos remotos, o Portal de Telemetria trabalha apenas com valores numéricos associados aos seus Dados(sejam valores Inteiros ou Reais) ou textos(strings).

Portanto, em relação a carga útil(payload) de uma mensagem MQTT, ou seja, a definição das informações que deseja-se enviar ao Portal, o BROKER MQTT do Portal de Telemetria suporta os seguintes formatos:

Formato “bruto”

Neste tipo de formato, é possível informar apenas o valor numérico “bruto” a ser atribuído ao Dado do Portal (inteiro ou real). Exemplos:

• Inteiro: 0, 10, 200, 3000, 40000, etc;

• Real: 5.75, 13.9, 150.25, etc;

• Texto: “LIGADO”, “desligado”, “ok”, etc.

Um exemplo de publicação, pode ser observado abaixo:

mosquitto_pub -h "broker.mqtt.hitecnologia.com.br " -p 1883 -u "6f27b6700ede4a0db47560db0cf7d3de" -i "9a3547bc" -t "9a3547bc/temperatura-forno" -q 0 -m 10.75

Nota

Todos os exemplos de comandos desta seção fazem uso da biblioteca Eclipse Mosquitto. Caso deseje testar os comandos, instale o biblioteca seguindo as instruções oficiais.

Parâmetro	Identificação	Valor	Observações
-h	Endereço do BROKER MQTT	broker.mqtt.hitecnologia.com.br	URL do BROKER MQTT do Portal de Telemetria
-p	Porta de comunicação do BROKER MQTT	1883	Porta do BROKER MQTT do Portal de Telemetria
-u	Usuário da conexão MQTT	6f27b6700ede4a0db47560db0cf7d3de	Chave de Acesso obtida no cadastro do Conector ou nas configurações do Contrato
-i	ID de cliente da conexão MQTT	9a3547bc	Identificador de Tópico e ID de Cliente MQTT do Conector em que se deseja realizar a publicação
-t	Tópico a ser publicado o valor	9a3547bc/temperatura-forno	Tópico associado ao Dado cadastrado no Conector e que receberá o valor publicado
-q	Qualidade de Serviço(QoS) da publicação	0	Define a confiabilidade da entrega da mensagem de publicação. O portal aceita os níveis 0(no máximo uma vez) ou 1(pelo menos uma vez)
-m	Conteúdo a ser publicado	10.75	Carga útil(payload) com a informação do valor do Dado a ser publicado(formato aceito pelo Portal)

Formato JSON(Java Script Object Notation)

Já o formato JSON é uma coleção de pares de nome/valor comum em várias linguagens de programação, sendo tratada como um objeto, registro, estrutura, dicionário, tabela de hash, lista com chave ou matriz associativa.

Também é legível por humanos e independente da linguagem.

Os exemplos de formatos de carga útil(payload) em JSON que o BROKER MQTT do Portal de Telemetria suporta podem ser verificados abaixo:

JSON apenas com o valor a ser atribuído para o Dado

{"value": 10.75} ou {"value": "10.75"}

JSON com o valor a ser atribuído para o Dado e seu timestamp(data/hora)

{"value": 10.75, "timestamp": 1634213376506}

Atenção

Todos os carimbos de data/hora(timestamp) devem ser informados com o número de milissegundos a partir de 1 de Janeiro de 1970 e considerando o fuso horário de referencia UTC (Coordinated Universal Time ou Tempo Universal Coordenado).

Caso seja informado um carimbo de data/hora para o valor do tópico, o mesmo será armazenado com a data/hora representada por ele desde que a data/hora informada não seja anterior a 7 dias em relação a data atual e nem superior a data/hora atual.

É possível converter facilmente carimbos de data/hora(timestamp) em data/hora aqui.

Recomendamos fortemente que dentro do possível, evite-se informar o timestamp do valor associado a um tópico publicado no BROKER do Portal. Isso se deve ao fato de que, caso se informe este timestamp, o BROKER irá consistir esta informação e caso identificada alguma inconsistência, como por exemplo, o timestamp informado seja igual ou mais antigo em relação ao último valores registrado para o tópico, anterior, a nova publicação será descartada.

Caso não seja possível evitar, é fundamental garantir que a fonte que se utiliza para obter o timestamp seja confiável e que não se utilize dois clientes MQTT diferentes publicando no mesmo tópico.

Exemplo de publicação em um Dado de um Conector do Portal de Telemetria:

mosquitto_pub -h "broker.mqtt.hitecnologia.com.br" -p 1883 -u "6f27b6700ede4a0db47560db0cf7d3de" -i "9a3547bc" -t "9a3547bc/temperatura-forno" -q 0 -m '{"value": 25.5}'

Após qualquer publicação em um tópico no BROKER MQTT do Portal de Telemetria, independentemente do formato ou conteúdo utilizado, o valor do tópico no Broker será padronizado para incluir o valor informado e o seu carimbo de data/hora(timestamp em epoch/unix):

{"value": 25.5, "timestamp": 1634213376506}

Informando o valor de mais um Tópico(Dado) em uma única publicação

Utilizando o formato JSON explicado na seção anterior, é possível definir no payload(conteúdo) de uma única publicação, o valor de demais de um Tópico a ser enviado para o Portal.

Neste caso, a publicação deve ser realizada diretamente no tópico associado apenas ao nível do Conector, ou seja, o tópico será o Identificador de Tópico e ID de Cliente MQTT do Conector.

Considerando os exemplos anteriores, este tópico seria 9a3547bc.

Abaixo, seguem os exemplos de conteúdo JSON para que seja informado o valor de mais de um tópico:

JSON com a lista de valores a serem atribuídos para os Dados

{"temperatura": 10.75, "umidade": 20} ou {"temperatura": "10.75", "umidade": "20"}

JSON com um timestamp global para os Dados informados

{"timestamp": 1633040701720, "temperatura": 10.75, "umidade": 20}

JSON com a lista de valores a serem atribuídos para os Dados e seus timestamps(data/hora)

{"temperatura": {"value": 10.75, "timestamp": 1633040701718}, "umidade": {"value": 20, "timestamp": 1633040701719}}

Exemplo de publicação em dois Dados de um Conector do Portal de Telemetria:

mosquitto_pub -h "broker.mqtt.hitecnologia.com.br" -p 1883 -u "6f27b6700ede4a0db47560db0cf7d3de" -i "9a3547bc" -t "9a3547bc" -q 0 -m '{"temperatura": 10.75, "umidade": 20}'

Cuidados ao informar um timestamp no conteúdo de uma publicação

Como vimos acima, o Portal de Telemetria permite que sejam enviados no conteúdo de uma publicação nos tópicos associados aos Dados, apenas o valor a ser atribuído ao Dado, como também a informação de timestamp(data/hora) a ser associado ao valor deste Dado.

Apesar da possibilidade de se informar o timestamp, recomendamos fortemente que dentro do possível, evite-se informa-lo no conteúdo das publicações no BROKER do Portal de Telemetria e tente-se utilize a publicação desta forma apenas nos cenários em que realmente for necessário.

Isso se deve ao fato de que, caso se informe este timestamp, o BROKER irá consistir esta informação e caso seja identificada alguma inconsistência, como por exemplo, o timestamp informado seja igual ou mais antigo em relação ao último valor registrado para o tópico, a nova publicação será descartada.

Caso não seja possível evitar, é fundamental garantir que a fonte que se utiliza para obter o timestamp seja confiável e que não se utilize dois clientes MQTT diferentes publicando no mesmo tópico(pois a fonte da informação do timestamp será diferente).

A grande vantagem de não informar um timestamp no conteúdo da publicação é que neste caso, o próprio BROKER define o timestamp da publicação na ordem em que as mesmas chegam ao mesmo. Dessa forma, não se corre o risco de identificação de alguma inconsistência em relação a data/hora das publicações.

Interface de auxilio na montagem de payloads

No formulário de cadastro de um Conector é disponibilizado um botão chamado Instruções para conexão, no qual acessa um formulário com algumas orientações.

Na aba chamada Mensagem(payload), são disponibilizadas as instruções de montagem de payload considerando os tópicos associados aos Dados do Conector:

Fig. 44 Exemplo de payload considerando os Dados “Temperatura e Umidade”.

Neste exemplo, considera-se a publicação no tópico do nível do Conector 9a3547bc e um payload no formato JSON onde é informado o label MQTT dos Dados “Temperatura” e “Umidade” com os respetivos valores que devem ser publicados para cada um.

As opções de configuração neste formulário são as seguintes:

• Tabela de seleção de Dados: permite a seleção dos Dados do Conector para que sejam considerados na montagem do payload de exemplo;

• Modelo: define o formato do payload da publicação a ser considerado na montagem do exemplo conforme os padrões vistos acima;

• Tópico do Conector: Caso marcada essa opção, o exemplo de payload considera a publicação no tópico do nível do Conector. Caso desmarcada, o exemplo de payload e o tópico de publicação será específico para cada Dado selecionado;

• Tópico: define o tópico que a publicação deve ser realizada. Caso marcada a opção Tópico do Conector, este será definido com o tópico do mesmo ou caso desmarcado, será apresentado o tópico específico de cada Dado selecionado;

• Payload: apresenta o exemplo de payload conforme as configurações das opções anteriores.

Já no seguinte exemplo, a opção de Tópico do Conector foi desmarcada, indicando o exemplo de publicação no tópico específico de cada Dado. Além disso, foi selecionado o modelo de payload onde é informado o timestamp associado ao valor de publicação para cada Dado:

Fig. 45 Exemplo de payload considerando a publicação no tópico especifico de cada Dado.

Assinando(recebendo) valores de Tópicos(Dados) de um Conector

Para receber os valores publicados em tópicos de um Conector MQTT cadastrado no Portal, como por exemplo, publicações de escritas em um Dado do Conector através de um controle de um painel Sinótico, deve-se assinar(subscrever) os tópicos associados aos Dados desejados.

Exemplo de assinatura de tópico associado a um Dado de um Conector do Portal de Telemetria:

mosquitto_sub -h "broker.mqtt.hitecnologia.com.br" -p 1883 -u "6f27b6700ede4a0db47560db0cf7d3de" -i "9a3547bc" -t "9a3547bc/temperatura-forno" -q 0'

Parâmetro	Identificação	Valor	Observações
-h	Endereço do BROKER MQTT	broker.mqtt.hitecnologia.com.br	URL do BROKER MQTT do Portal de Telemetria
-p	Porta de comunicação do BROKER MQTT	1883	Porta do BROKER MQTT do Portal de Telemetria
-u	Usuário da conexão MQTT	6f27b6700ede4a0db47560db0cf7d3de	Chave de Acesso obtida no cadastro do Conector ou nas configurações do Contrato
-i	ID de cliente da conexão MQTT	9a3547bc	Identificador de Tópico e ID de Cliente MQTT do Conector em que se deseja realizar a publicação
-t	Tópico a ser assinado	9a3547bc/temperatura-forno	Tópico associado ao Dado cadastrado no Conector e que receberá os valores publicados no mesmo
-q	Qualidade de Serviço(QoS) da publicação	0	Define a confiabilidade da entrega da mensagem de assinatura. O portal aceita os níveis 0(no máximo uma vez) ou 1(pelo menos uma vez)

Conforme explicado na seção de publicação de tópicos, após qualquer publicação em um tópico no BROKER MQTT do Portal de Telemetria, independentemente do formato ou conteúdo utilizado, o valor do tópico no Broker será padronizado para incluir o valor informado e o seu carimbo de data/hora(timestamp em epoch/unix):

{"value": 25.5, "timestamp": 1634213376506}

Ou seja, o cliente MQTT que assinar um determinado tópico associado a um Dado no Portal, deve lidar com o conteúdo neste padrão informado.

Atenção

O equipamento(cliente MQTT) deve enviar um PINGREQ sempre que implemente uma rotina de assinatura ao BROKER MQTT do Portal de Telemetria para evitar que a conexão seja fechada por inatividade.

O tempo máximo permitido para enviá-lo é de até 1 hora, portanto, certifique-se de configurar o parâmetro Keep Alive em seu cliente MQTT para até 60 minutos(3600 segundos).

Para obter mais informações sobre a informação de “Keep Alive” do MQTT, consulte MQTT Keep Alive.

Mensagem de Última Vontade e Testamento

A implementação MQTT do Portal de Telemetria permite que o Cliente MQTT que se autentique no BROKER MQTT do Portal de Telemetria especifique uma mensagem de Última Vontade e Testamento.

Porém, é obrigatório que esta mensagem seja definida no tópico IDENTIFICADOR-MQTT-CONECTOR/lwt.

Exemplo:

9a3547bc/lwt

A seção sobre uma Mensagem de Última Vontade e Testamento explica com mais detalhes a utilização deste tipo de mensagem.

Atenção

Caso se utilize uma definição de tópico diferente, a mensagem não será enviada pelo BROKER MQTT do Portal de Telemetria.

Configurando Chaves de Acesso

Para acessar as configurações de Chaves de Acesso, os passos de seção Obtendo as Chaves de Acesso de um Contrato.

As configurações de uma Chave de Acesso são as seguintes:

Configuração	Descrição
Descrição	Descrição da Chave de Acesso
Restrições	Configuração do privilégio de operações permitidas para a Chave de Acesso. As opções disponíveis são as seguintes: Assinaturas(leituras) e Publicações(escritas): permite ao Cliente MQTT que utilize a Chave possa assinar e publicar em tópicos; Somente Assinaturas(leituras): permite ao Cliente MQTT que utilize a Chave possa apenas assinar tópicos; Somente Publicações(escritas): permite ao Cliente MQTT que utilize a Chave apenas publicar em tópicos.
Token	Identificação da Chave de Acesso a ser utilizada como o usuário da conexão MQTT
Habilitado	Habilita ou Desabilita a utilização da Chave de Acesso(não será possível se autenticar no Broker MQTT através de uma chave desabilitada)
Conectores	Indica os conectores que a Chave possui acesso. Caso não seja selecionado nenhum conector, a Chave terá acesso a todos os conectores do Contrato

Exemplo das configurações de uma chave de acesso:

Fig. 46 Configurações de uma Chave de Acesso de um contrato.

Já para cadastrar uma nova Chave de Acesso, basta seguir os seguintes passos:

• No formulário acessado anteriormente, clique na opção Novo;

• Configure uma Descrição, as Restrições e eventuais Conectores que a Chave terá acesso;

• Salve o cadastro clicando no botão Confirmar.

Fig. 47 Sequencia para o cadastro de uma nova Chave de Acesso de um contrato.

Atenção

Por padrão, em todo Contrato é disponibilizada uma Chave de Acesso que pode ser utilizada sem a necessidade de se criar uma nova.

Versões suportadas do protocolo MQTT

O BROKER MQTT do Portal de Telemetria suporta as versões v3.1.1 e 5.0.0 do protocolo MQTT. Porém, existem algumas restrições e limitações descritas nas próximas seções.

Restrições e Limitações

Número de mensagens MQTT

O número de mensagens MQTT enviadas ao BROKER MQTT do Portal de Telemetria por cada conexão(Cliente MQTT) são limitadas em dois recursos: no Conector (equipamento) como um todo e em cada Tópico.

Tópico

Para cada Tópico, as mensagens MQTT são limitadas ao envio de 15 mensagens em uma janela de 15 segundos, ou seja, em média 1 mensagem por segundo.

Isso significa que o Cliente MQTT pode publicar em um mesmo Tópico até 15 mensagens MQTT dentro de uma janela de tempo de 15 segundos.

Atenção

Se o equipamento em questão exceder esses limites, o mesmo será automaticamente desconectado do BROKER MQTT do Portal de Telemetria e não terá permissão para se conectar novamente por 30 segundos (inicialmente).

Caso o equipamento exceda repetidamente esses limites, o período de tempo que não terá permissão para se conectar aumentará progressivamente em até no máximo 1 hora. Após atingir o tempo máximo, o ciclo recomeçará em 30 segundos.

Conector

Já para um Conector(equipamento), as mensagens MQTT são limitadas a 60 mensagens em uma janela de 15 segundos, ou seja, em média 4 mensagens por segundo (ou 1 mensagem a cada 250ms).

Isso significa que o Cliente MQTT pode publicar até 60 mensagens MQTT(considerando as publicações em qualquer tópico) dentro de uma janela de tempo de 15 segundos.

Neste caso, é importante observar não apenas a taxa de publicação em cada tópico, mas também no somatório de todos os tópicos do equipamento.

Atenção

Se o equipamento em questão exceder esses limites, o mesmo será automaticamente desconectado do BROKER MQTT do Portal de Telemetria e não terá permissão para se conectar novamente por 30 segundos (inicialmente).

Caso o equipamento exceda repetidamente esses limites, o período de tempo que não terá permissão para se conectar aumentará progressivamente em até no máximo 1 hora. Após atingir o tempo máximo, o ciclo recomeçará em 30 segundos.

Qualidade de Serviço(Qos)

A Qualidade de Serviço(Qos) 2(exatamente um vez) não é suportada para publicações ou assinaturas, apenas QoS 0(no máximo uma vez) e QoS 1(pelo menos uma vez) são suportados.

Para mais informações sobre o conceito de Qualidade de Serviço(Qos), acesse: Qualidade de serviço - QoS.

Tamanho da Carga Útil(payload)

O tamanho máximo da carga útil das mensagens é de 20 KB. Caso o Cliente MQTT envie uma mensagem como uma carga útil superior a este limite, o mesmo será desconectado do BROKER MQTT do Portal de Telemetria.

Limites de registros no Histórico de Dados

Para o Histórico de Dados(que registra os valores publicados nos tópicos), acesse Uso do Histórico para obter as informações dos limites impostos e as instruções de como lidar com o Histórico de Dados.

Atenção

Conforme orientado na documentação citada acima, é crucial tomar precauções ao configurar o tipo de histórico para um Dado de um Conector, especialmente ao usar o protocolo MQTT.

Considerando que, neste protocolo, o equipamento remoto é responsável por publicar os valores nos tópicos associados aos Dados, há um RISCO SIGNIFICATIVO DE ULTRAPASSAR a cota mensal de registros no histórico se o tipo de configuração não for o Periódico.

Portanto, recomendamos fortemente o uso deste tipo de histórico. Caso deseje utilizar os outros tipos, será de responsabilidade da aplicação do equipamento remoto gerenciar as publicações ou utilizar outros recursos para controlar os registros no histórico e garantir que a cota mensal não seja ultrapassada, o que resultaria no DESCARTE DE NOVOS REGISTROS.

Limites de registros no Histórico de Alarmes

Para o Histórico de Alarmes(de maneira semelhante ao histórico de dados), o número de registros que serão armazenados na base de dados são limitados em três janelas de tempo conforme descrito na tabela a seguir:

Janela de Tempo	Quantidade	Descrição
5 minutos(curta)	10 registros	Em uma janela de tempo de 5 minutos, serão armazenados no máximo 10 registros por alarme, ou em média, 1 registro a cada 30 segundos
1 hora(média)	30 registros	Em uma janela de tempo de 1 hora, serão armazenados no máximo 30 registros por alarme, ou em média, 1 registro a cada 2 minutos
24 horas(longa)	300 registros	Em uma janela de tempo de 24 horas(1 dia), serão armazenados no máximo 300 registros por alarme, ou em média, 1 registro a cada 5 minutos(aproximadamente)

Atenção

Caso o número de registros seja atingido na janela de tempo, o Portal de Telemetria deixará de armazenar novos registros no histórico dentro da janela de tempo informada.

Por este motivo, é recomendado que se habilite o histórico apenas nos Alarmes(associados aos Dados) em que realmente seja necessário o armazenamento.

Além disso, é sempre importante considerar a condição configurada para a geração de um alarme, de forma a evitar e reentrância desse evento de maneira desnecessária.

Notificações de Alarmes

Acesse a seguinte página de Limites para notificações de Alarme para verificar os limites impostos pelo Portal neste cenário.

Notificações de Desconexão

Acesse a seguinte página de Limites para notificações de Desconexão para verificar os limites impostos pelo Portal neste cenário.

Depurando eventos MQTT em um Conector

No cadastro de um Conector configurado com o protocolo MQTT, é disponibilizada uma opção chamada Visualizador de eventos:

Fig. 48 Visualizador de eventos de um Conector MQTT.

Ao selecionar esta opção, é disponibilizado um painel lateral na página que apresentará a depuração em tempo real de alguns eventos MQTT a medida que ocorram no Conector, tais como:

• Conexão e desconexão do Conector do Broker;

• Publicações realizadas no Conector e seus conteúdos;

• Eventos de Autenticação e Controle de Acesso.

No Visualizador de eventos, os eventos são listados do mais recente(no topo da lista) para os mais antigos, ou seja, um novo evento sempre será inserido no topo da lista.

Além disso, são disponibilizadas as seguintes opções:

Opção	Descrição
Pesquisar()	Filtra por eventos cujo o conteúdo contenha o texto informado
Filtros de Eventos	Filtra por eventos de acordo com os seguintes tipos: Todos: filtra por eventos de todos os tipos informados pelo Broker; Debug: filtra por eventos de “depuração” informados pelo Broker; Info: filtra por eventos de “informação” informados pelo Broker; Erro: filtra por eventos de “erro” informados pelo Broker.
Pause()	Pause o monitoramento de eventos
Play()	Continua com o monitoramento de eventos
Exportar()	Exporta os eventos registrados para um arquivo
Restaurar()	Limpa os eventos registrados até o momento no painel

Para mais informações sobre eventos de um Conector, acesse Eventos de um Conector(connector_events).

Simulador MQTT

Ao cadastrar um Conector com o protocolo MQTT, você também tem acesso ao Simulador MQTT.

O Simulador MQTT funciona como um Cliente MQTT, permitindo que você envie valores para todos os tópicos (Dados) do Conector e visualize seus valores em tempo real.

Esse simulador é útil especialmente na fase de desenvolvimento de telas sinóticas, ajudando a testar como os controles e animações se comportam com os dados simulados.

Para acessar o Simulador, clique no botão Simulador na página de edição de um Conector MQTT:

Ao clicar em Simulador, uma nova janela será aberta com todas as configurações e informações do Simulador:

Fig. 49 Simulador de um Cliente MQTT do Portal de Telemetria.

Configurações do Simulador

Identificação	Descrição
Conexão	Botão para conectar e desconectar o Simulador do BROKER MQTT do Portal de Telemetria
Broker Endereço	URL de acesso ao BROKER MQTT do Portal de Telemetria
Modo	Alterna entre Simulação ativada (apenas visualização) e Simulação desativada (impacta a base de dados). Para mais detalhes, veja a seção: Modos de simulação
Randomizar	Ao ativar esta opção, o simulador irá iniciar um processo automático de envio de valores aleatórios ao(s) Dado(s) baseado no limite mínimo e máximo definidos nos campos individuais de cada tópico
Taxa de envio	Taxa de envio das publicações através do simulador(a taxa mínima é de 1000ms ou 1 segundo)
Enviar campos	Adiciona a informação de timestamp no payload, associando a Data/hora aos valores publicados
Conector	Exibe o Conector selecionado para simulação e permite alterar para outros Conectores do Contrato

Modos de simulação

Através do campo “Modo”, podemos definir duas opções de simulação:

• Simulação ativada: As informações de conexão e publicações não impactam a base de dados. Os valores são exibidos na interface, mas o status real e os valores não são salvos, e não há registros no histórico;

• Simulação desativada : O Simulador atua como um Cliente MQTT real. Todas as informações enviadas impactam a base de dados, incluindo status de conexão, valores de Dados, Alarmes e registros no histórico.

Atenção

Use a simulação desativada com cuidado, pois todas as ações afetarão as informações reais do Conector e seus recursos(valores dos Dados, status de Alarmes e registros no histórico).

Características

Cada publicação é feita de acordo com a Taxa de envio configurada, o que ajuda a gerenciar a quantidade de publicações pendentes, exibida no canto inferior direito após cada envio.

As publicações podem ser feitas de duas formas:

• Individual: Publica o valor da simulação apenas para o Dado escolhido através do botão “” localizado em cada um dos tópicos exclusivos para os Dados”;

• Coletiva: Publica todos os valores das simulações contidas nos tópicos através do botão “ Publicar”. Também é possível visualizar ao lado do botão, a quantidade de tópicos(Dados) que receberão seus valores simulados em conjunto.

Recursos

Após conectar-se a um Conector MQTT, você poderá simular valores nos tópicos associados aos Dados.

Com isso, você poderá:

• Digitar um valor que será publicado para um Dado;

• Publicar valores pré-definidos para um Dado arrastando o seletor para direita ou para a esquerda;

• Definir os valores mínimos, máximos e de incremento para cada simulação dos valores;

• Visualizar o limite de cada Alarme cadastrado para seu respectivo Dado e seus estados atuais(alarmados ou não alarmados).

Tipos de simulação

Utilizando o simulador MQTT, podemos ter 2 opções para as simulações dos Dados:

Padrão

Serão individualmente exibidas janelas com informações e campos para cada um dos Dados, estas informações são:

• Nome do Dado;

• Nome do Tópico MQTT;

• Campo para preencher um valor simulado específico para o Dado;

• Opções para o campo de valor:

  • “”: para limpar o valor do campo;

  • “”: para realizar uma requisição de envio de valor individualmente ao Dado.

• Barra informativa e ajustável para visualizar/selecionar um valor pré-definido ao Dado;

• Opções de pré-definição para a simulação:

  • Mínimo: define um valor mínimo para o valor que será simulado;

  • Incremento: define um incremento fixo que será acrescentado ao Dado;

  • Máximo: define um valor máximo para o valor que será simulado.

• Informações dos Alarmes cadastrados no Dado:

  • Informa se o(s) Alarme(s) encontra(m)-se ativo(s) ou normalizado(s);

  • Condição de disparo e limite do(s) Alarme(s).

• Botão “ Publicar” que permite realizar o envio dos valores das simulações em conjunto.

Em lote

O tipo de simulação “Em lote” permite importar um arquivo (CSV) com valores pré-definidos para o(s) Dado(s). Ao realizar a importação com um arquivo válido, o simulador exibirá uma tabela contendo os Dados e os respectivos valores simulados via planilha.

O arquivo que será importado, deve seguir o padrão de definir o(s) ID(s) para o(s) Dado(s) que será(ão) simulado(s) na parte superior do arquivo, representando as colunas da tabela. Caso a simulação possua mais de 1 Dado, será necessário separar os Dados e os valores de simulação por ponto e vírgula(;).

Os valores que serão simulados devem seguir na coluna representada pelo Dado e separados por linha, como mostra o exemplo abaixo:

Neste exemplo, estamos simulando os Dados “Pressão” e “Temperatura” (separados por coluna e sendo representados pelos seus ID’s) e abaixo, definindo os valores 1,2,3 e 4 para o Dado “Pressão”, e os valores 10,20,30 e 40 para o Dado “Temperatura”.

Ao importar este arquivo para o simulador, teremos uma reapresentação da tabela como mostra o exemplo abaixo:

O Portal automaticamente reconhecerá os ID’s dos Dados (caso corretos) e apresentará os nomes dos mesmos. Em seguida, teremos os valores definidos no arquivo já reapresentados na tabela e para concluir a simulação, após conectar o simulador ao Conector, será exibido o botão “ Publicar” que permite realizar os envios das simulações seguindo a sequência da tabela, e o botão “ Remover” para deletar o arquivo importado.

Após o processo de importação ter sido finalizado, teremos a possibilidade de simular os valores de acordo com o conteúdo do arquivo, como mostra o exemplo abaixo:

Tópicos de Sistema de um Conector

Para cada Conector MQTT cadastrado no Portal e para seus Dados(tópicos), o BROKER MQTT do Portal de Telemetria realiza publicações em tópicos específicos de sistema com algumas informações úteis sobre os recursos.

Atualmente, os seguintes tópicos de sistema são disponibilizados:

Estado de um conector(connector_state)

No tópico connector_state de um conector, o BROKER MQTT do Portal de Telemetria publica as alterações de alguns estados associados ao conector, tais como:

• Estado de conexão/desconexão;

• Estado de alarmes ativos(ou não);

• Estado de habilitação no sistema.

Um exemplo do conteúdo de um tópico de connector_state pode ser observado abaixo:

{"connected": true, "has_active_alarms": false, "enabled": true}

Onde:

• connected: Indica se o Conector está online no Portal de Telemetria ou desconectado;

• has_active_alarms: Indica se o Conector possui algum alarme ativo ou não;

• enabled: Indica se o Conector está habilitado no sistema ou não.

Estado de alarme de um tópico(alarm_state)

No tópico alarm_state associado a um Dado de um Conector, o BROKER MQTT do Portal de Telemetria publica as alterações do estado de qualquer alarme associado ao Dado(tópico).

Um exemplo do conteúdo de um tópico de alarm_state pode ser observado abaixo:

{"id": 7346, "is_active": true, "alarm_state_id": 2, "data_value": 230, "last_transition_at": 1634213375648}

Onde:

• id: Identificação única do Alarme no Portal de Telemetria;

• is_active: Indica se o Alarme está ativo(alarmado);

• alarm_state_id: Indica o estado do Alarme;

• data_value: Informa o valor do Dado que gerou a condição de alarme;

• last_transition_at: Data/hora da última transição do Alarme em UTC(normal para alarmado ou alarmado para normal).

Eventos de um Conector(connector_events)

No tópico connector_events de um Conector, o BROKER MQTT do Portal de Telemetria publica alguns eventos identificados para o Conector para as seguintes categorias:

Autenticação

Nessa categoria de eventos, o BROKER MQTT do Portal de Telemetria realiza publicações informando eventuais falhas ou sucesso na autenticação de clientes MQTT.

Os eventos possíveis são listados a seguir:

Mensagem do Evento	Significado	Sugestões
Authentication failure: User/access key not informed	O BROKER do Portal negou a conexão pois não foi informada a chave de acesso(user) na conexão	Verificar se a chave de acesso está sendo definida como o usuário da conexão
Authentication failure: User/access key (chave_de_acesso) not registered	O BROKER do Portal negou a conexão pois a chave de acesso informada na conexão não está registrada(cadastrada) no portal	Verificar se a chave de acesso foi informada de maneira correta na conexão e se a mesma está cadastrada de fato no Portal
Authentication failure: User/access key (chave_de_acesso) disabled	O BROKER do Portal negou a conexão pois a chave de acesso informada na conexão não está habilitada no portal	Verificar se a chave de acesso está desabilitada em seu cadastro no Portal
Authentication failure: Client without associated connector	O BROKER do Portal negou a conexão pois o ID de cliente informado na conexão não possui acesso ao conector	Verificar se o ID de cliente informado na conexão está associado à algum Conector do Portal(Identificador de Tópico e ID de Cliente MQTT do Conector)
Authentication failure: User/access key (chave_de_acesso) without connector access	O BROKER do Portal negou a conexão pois a chave de acesso informada na conexão não possui acesso ao conector	Verificar no cadastro da chave de acesso no Portal, se a mesma possui acesso ao Conector informado na conexão(através do ID de cliente)
Authentication failure: Client (id_do_cliente) can only connect to: 202Y-MM-AAAA HH:MM:SSZ	O BROKER do Portal negou a conexão pois o cliente MQTT só poderá se conectar ao broker a partir da data/hora informada	Verificar a frequência de publicações do cliente MQTT. Possivelmente deve estar ultrapassando os limites de mensagens
Authentication failure. Connector (identificador_mqtt_conector) without registration in the Portal	O BROKER do Portal negou a conexão pois o ID de cliente informado na conexão não está associado a nenhum conector do Portal	Verificar o ID de cliente informado na conexão está correto(o mesmo deve estar associado à algum Conector cadastrado no Portal)
Authentication failure: Disabled connector (identificador_mqtt_conector) on the Portal	O BROKER do Portal negou a conexão pois o ID de cliente informado na conexão está associado a um conector que está desabilitado no Portal	Verificar se o Conector informado na conexão(através do ID de cliente) está habilitado em seu cadastro no Portal
Authentication failure: Keep alive not invalid or not provided	O BROKER do Portal negou a conexão pois o parâmetro de “keep alive” é inválido ou não foi fornecido na conexão	Verificar se o parâmetro de “keepalive” está sendo definido na conexão
Authentication failure: Keep alive value (valor_fornecido_keepalive) less than allowed (5 seconds)	O BROKER do Portal negou a conexão pois o valor do “keep alive” fornecido está abaixo do valor mínimo permitido	Verificar se o valor do parâmetro de “keepalive” é igual ou superior ao valor mínimo informado na mensagem de erro
Authentication failure: Keep alive value (valor_fornecido_keepalive) greater than allowed (3600 seconds)	O BROKER do Portal negou a conexão pois o valor do “keep alive” fornecido está acima do valor máximo permitido	Verificar se o valor do parâmetro de “keepalive” é igual ou superior ao valor máximo informado na mensagem de erro
Authentication failure: Will message QoS(valor_qos_fornecido) not supported on broker, try a lower QoS	O BROKER do Portal negou a conexão pois o valor do QoS da Will Message(quando definida) na conexão possui um valor inválido	Verificar se o valor de QoS definido para a Will Message da conexão é 0 ou 1(caso seja definida uma Will Message)
Authentication failure: Connector (identificador_mqtt_conector) contract expired	O BROKER do Portal negou a conexão pois o contrato associado ao Conector da conexão está vencido	Verificar o status do Contrato no Portal
Authentication success: User/access key: (chave_de_acesso)	Sucesso na autenticação do cliente MQTT com o BROKER do Portal de Telemetria

Controle de Acesso

O BROKER MQTT do Portal de Telemetria monitora as mensagens de publicações/assinaturas de clientes MQTT e caso detecte alguma anormalidade em relação ao controle de acesso aos tópicos associados as mensagens, publica os seguintes eventos:

Mensagem do Evento	Significado	Sugestões
Topic(definição_do_topico) access denied. Invalid topic structure	Estrutura inválida informada para um tópico na publicação/assinatura	Verificar a estrutura de tópico utilizada na operação de publicação/assinatura
Topic (definição_do_topico) access denied. Unprivileged user/access key (chave_de_acesso) for operation	Chave de acesso informada na conexão MQTT não tem privilégio para realizar a operação(publicação ou assinatura) solicitada no tópico	Verificar no cadastro do Token informado na conexão MQTT se o mesmo possui o privilégio necessário para operação desejada
Topic (definição_do_topico) access denied. Client (id_do_cliente) not authorized to publish on this connector (identificador_mqtt_conector)	O ID de cliente informado na conexão MQTT não está autorizado a publicar no conector	Verificar se na conexão MQTT foi informado o ID de cliente diretamente associado ao Conector do tópico
Topic (definição_do_topico) access denied. User/access key (chave_de_acesso) not registered. The connection will be closed by the Portal	A chave de acesso informada na conexão não está mais registrada(cadastrada) no portal. A conexão será fechada pelo BROKER	Verificar se a chave de acesso foi informada de maneira correta na conexão e se a mesma está cadastrada de fato no Portal
Topic (definição_do_topico) access denied. User/access key (chave_de_acesso) disabled. The connection will be closed by the Portal	a chave de acesso informada na conexão não está habilitada no portal. A conexão será fechada pelo BROKER	Verificar se a chave de acesso está desabilitada em seu cadastro no Portal
Topic (definição_do_topico) access denied. Connector (connector_identifier) contract expired. The connection will be closed by the Portal	Contrato associado ao Conector associado ao tópico da publicação/assinatura está vencido. A conexão será fechada pelo BROKER	Verificar o status do Contrato no Portal
Topic (definição_do_topico) access denied. Disabled connector (identificador_mqtt_conector) on the Portal. The connection will be closed by the Portal	O Conector associado ao tópico da publicação/assinatura está desabilitado no Portal. A conexão será fechada pelo BROKER	Verificar se o Conector informado na conexão(através do ID de cliente) está habilitado em seu cadastro no Portal
Topic (definição_do_topico) access denied. Connector (identificador_mqtt_conector) not registered in the Portal	O Conector associado ao tópico da publicação/assinatura não está cadastrado no Portal	Verificar o ID de cliente informado na conexão está correto(o mesmo deve estar associado à algum Conector cadastrado no Portal)
Topic (definição_do_topico) access denied. Topic or Connector (identificador_mqtt_conector) not registered or user/access key (chave_de_acesso) without connector access	O tópico ou conector associados a publicação/assinatura não estão cadastrados no Portal ou a chave de acesso não possui acesso ao Conector	Verificar a definição do tópico informado na publicação/assinatura assim como se a chave de acesso utilizada como usuário da conexão possui acesso ao conector informado
Topic (definição_do_topico) access denied. Topic not registered on the Portal	O tópico associado a publicação/assinatura não está cadastrado no Portal	Verificar se o Dado associado ao tópico utilizado na publicação/assinatura está de fato cadastrado no Portal
Topic (definição_do_topico) access denied. Disabled topic on the Portal	O tópico associado a publicação/assinatura não está habilitado no Portal	Verificar se o Dado associado ao tópico utilizado na publicação/assinatura está de fato habilitado no Portal
Invalid QoS(qos) on topic: (definição_do_topico). The connection will be closed by the Portal	Valor de QoS informado na publicação/assinatura inválido	Verificar o valor de QoS utilizado para publicar/assinar o tópico(que deve ser 0 ou 1)

Publicações

O BROKER MQTT do Portal de Telemetria monitora as mensagens de publicações de clientes MQTT e caso detecte alguma anormalidade, publica os seguintes eventos:

Mensagem do Evento	Significado	Sugestões
Publish failed: Invalid timestamp (carga_util_mensagem) informed in payload for topic (definição_do_topico)	Valor do carimbo de data/hora(timestamp) inválido informado no conteúdo da carga útil da mensagem MQTT publicada	Verificar o valor informado no carimbo de data/hora(timestamp) da mensagem
Publish failed: Invalid payload (carga_util_mensagem) format for topic (definição_do_topico)	Formato inválido utilizado no conteúdo da carga útil(payload) da publicação no tópico informado	Avaliar se o formato utilizado na carga útil da mensagem está de acordo com os formatos suportados pelo BROKER
Publish failed: Invalid payload (carga_util_mensagem) type for topic (definição_do_topico)	Tipo de carga útil(payload) na mensagem MQTT publicada	Avaliar se o conteúdo informado na carga útil da mensagem está de acordo com os conteúdos suportados pelo BROKER
Publish failed: Non-numeric value(valor) for topic (definição_do_topico)	Valor não numérico(NaN) informado para o tópico no conteúdo da carga útil da mensagem MQTT publicada	Verificar o valor numérico informado para o tópico na carga útil da mensagem
Publish failed: Invalid type value for topic (definição_do_topico)	Tipo de valor inválido informado para o tópico no conteúdo da carga útil da mensagem MQTT publicada	Verificar o valor numérico informado para o tópico na carga útil da mensagem
Publish failed: Invalid numeric value (valor) for topic (definição_do_topico)	Valor numérico informado para o tópico não é válido	Verificar o valor numérico informado para o tópico na carga útil da mensagem
Publish failed: Error in the execution of the calculation registered for the topic (definição_do_topico)	Falha ao aplicar o cálculo configurado para o dado associado ao tópico da publicação	Verificar parâmetros informados para o cálculo no cadastro do Dado associado ao tópico
Publish failed: Value(valor) below the minimum (data_hora_minima) for the topic (definição_do_topico)	Valor informado para o tópico inferior ao valor mínimo aceitável para o dado associado ao tópico	Alterar valor mínimo cadastrado para o Dado associado ao tópico ou avaliar o valor que está sendo publicado
Publish failed: Value(valor) above the maximum (data_hora_maxima) for the topic (definição_do_topico)	Valor informado para o tópico superior ao valor máximo aceitável para o dado associado ao tópico	Alterar valor máximo cadastrado para o Dado associado ao tópico ou avaliar o valor que está sendo publicado
Publish failed: Timestamp(data_hora) informed the topic(definição_do_topico) greater than the server datetime (data_hora_servidor)	Valor do carimbo de data/hora(timestamp) informado no conteúdo da carga útil da mensagem MQTT publicada é superior a data/hora do BROKER	Informar o valor do carimbo de data/hora(timestamp) com um valor igual ou inferior a data/hora atual do BROKER
Publish failed: Timestamp(data_hora) informed the topic(definição_do_topico) less than the minimum acceptable datetime (data_hora_minima_aceitavel_pelo_broker)	Valor do carimbo de data/hora(timestamp) informado no conteúdo da carga útil da mensagem MQTT publicada é anterior a 7 dias em relação a data/hora atual	Informar o valor do carimbo de data/hora(timestamp) não anterior a 7 dias atrás em relação a data/hora atual do BROKER
Publish failed: Timestamp(data_hora) informed the topic(definição_do_topico) equal to or less than the last record (data_hora_minima_ultimo_registro)	Valor do carimbo de data/hora(timestamp) informado no conteúdo da carga útil da mensagem MQTT publicada é igual a data/hora já registrada para o dado	Informar o valor do carimbo de data/hora(timestamp) com um valor superior ao que já foi utilizado para o tópico
Publish failed: Messages limit (numero_de_publicações) in time window(janela_de_tempo seconds) exceeded for (topico_ou_conector). Client (id_do_cliente) can only connect to: 202Y-MM-AAAA HH:MM:SSZ	O cliente MQTT da conexão ultrapassou o limite de mensagens para o Conector ou Tópico conforme os limites informados	Avaliar a frequência de publicações do cliente MQTT. Possivelmente deve estar ultrapassando os limites de mensagens
Publish failed: Invalid payload content (carga_util_mensagem) for topic (definição_do_topico)	Definição da carga útil da mensagem utilizada na publicação não pode ser tratada pelo BROKER	Verificar os tipos de formato e conteúdos válidos para a carga útil(payload) de uma mensagem suportados pelo BROKER
Publish failed: Invalid type of element (elemento_da_lista) in list informed in payload (carga_util_mensagem) for topic (definição_do_topico)	Tipo do elemento utilizado na carga útil para publicação em múltiplos tópicos inválido	Verificar o tipo de cada elemento informado no conteúdo da carga útil(payload) da publicação(em múltiplos tópicos)

Assinaturas

O BROKER MQTT do Portal de Telemetria monitora as requisições de assinaturas de clientes MQTT e caso detecte alguma anormalidade, publica os seguintes eventos:

Mensagem do Evento	Significado	Sugestões
Subscribe failed: Requests limit (numero_de_requisições_de_assinatura) in time window (janela_de_tempo seconds) exceeded for client. Client (id_do_cliente) can only connect to: 202Y-MM-AAAA HH:MM:SSZ	O cliente MQTT da conexão ultrapassou o limite de requisições de assinaturas para o Conector ou Tópico conforme os limites informados	Avaliar a frequência de assinaturas do cliente MQTT. Possivelmente deve estar ultrapassando o limite de requisições informados na mensagem de erro

Guia de conexão MQTT com o Portal utilizando o MQTTBox

Neste guia, vamos demonstrar como realizar a conexão de um cliente MQTT, chamado MQTTBox, com o Portal de Telemetria, além de realizar a publicação e assinatura de um tópico.

Cadastrando um Conector MQTT

Primeiramente, vamos cadastrar um Conector no Portal de Telemetria com o protocolo MQTT.

Para isso, basta que, no cadastro de um Conector, seja selecionado o Modelo do Hardware como DEVICE MQTT e seja preenchida as demais informações obrigatórias, conforme apresentado a seguir:

Atenção

Após salvar o cadastro do Conector, o formulário apresentará a informação do Identificador de Tópico e ID de Cliente MQTT do Conector (que deverá ser utilizado nos passos seguintes).

Cadastrando um Dado para o Conector MQTT

Neste passo, vamos criar um Dado para o Conector MQTT no qual definirá o Tópico que iremos publicar e assinar posteriormente.

Para isso, basta configurá-lo conforme indicado a seguir:

Neste exemplo, o tópico foi definido como temperatura-forno e em conjunto com o Identificador de Tópico e ID de Cliente MQTT do Conector é formado o tópico completo: “15324323/temperatura-forno”.

Atenção

Para mais informações sobre Dados/Tópicos em Conectores, acesse Dados de um Conector MQTT.

Baixando e instalando o aplicativo MQTTBox

Baixe o aplicativo MQTTBox diretamente do site da Microsoft e realize a instalação padrão do aplicativo.

Configurando o MQTTBox para se conectar ao Portal

Neste passo, vamos configurar o MQTTBox para abrir uma conexão MQTT com Broker do Portal de Telemetria.

Para iniciarmos, clique no botão Create MQTT Client:

Após criada a conexão MQTT, vamos configurá-la.

Para isso, clique nas configurações da conexão através do botão .

No formulário que será apresentado, preencha as configurações conforme as instruções a seguir e mantenha as demais como padrão:

Nome do campo	Descrição	Valor a ser configurado
MQTT Client Name	Nome da conexão MQTT	Conector MQTT
Protocol	Protocolo da conexão	mqtt / tcp
Username	Chave de Acesso obtida no cadastro do Conector ou nas configurações do Contrato	d83c09b14704a9ea9ddc9047730edda
MQTT Client id	Identificador de Tópico e ID de Cliente MQTT do Conector em que se deseja realizar a publicação	15324323
Host	URL do Broker MQTT do Portal de Telemetria	broker.mqtt.hitecnologia.com.br

Após realizadas as configurações, o formulário deverá estar preenchido conforme a seguir:

Para realizar a conexão com o Broker do Portal de Telemetria, basta clicar no botão azul Not Connected para realizar a conexão.

Caso a conexão seja estabelecida com sucesso, a cor do botão mudará para verde e o seu título indicará Connected:

Configurando a publicação no Tópico do Conector

Neste passo, vamos configurar no MQTTBox um publicador para que possamos enviar alguns valores para o Tópico associado ao Dado do Conector.

Para isso, clique no botão Add a publisher e no formulário que será apresentado, preencha as configurações conforme as instruções a seguir:

Nome do campo	Descrição	Valor a ser configurado
Topic to publish	Definição do Tópico MQTT associado ao Dado do Conector que receberá as publicações	15324323/temperatura-forno
QoS	Qualidade de Serviço da Publicação	0 - Almost Once
Payload Type	Formato da carga útil(payload)	Strings/ JSON/ XML/ Characters
Payload	Este campo será utilizado para receber o valor a ser publicado no tópico	20

Após a configuração, teremos a publicação definida de forma semelhante com o exemplo abaixo:

Configurando a assinatura do Tópico do Conector

Agora, vamos criar um assinante para o mesmo Tópico que iremos publicar.

Então, clique no botão Add a subscriber e no formulário que será apresentado, preencha as configurações conforme as instruções a seguir:

Nome do campo	Descrição	Valor a ser configurado
Topic to subscribe	Definição do Tópico MQTT associado ao Dado do Conector que receberá as publicações	15324323/temperatura-forno
QoS	Qualidade de Serviço da Assinatura	0 - Almost Once

Exemplo de funcionamento

Após realizar as configurações acima, basta realizar os seguintes passos:

• Clique no botão azul Not Connected para realizar a conexão com o Broker do Portal(caso ainda não realizado). O botão deve ser alterado para a cor Verde e indicar o título Connected;

• Realize a assinatura do tópico no formulário do subscriber clicando no botão Subscribe;

• Realize a publicação no tópico no formulário do publisher especificando um valor qualquer(20 por exemplo) na seção Payload e clicando no botão Publish.

O resultado esperado pode ser observado abaixo:

Podemos verificar que tanto a interface do Portal de Telemetria é atualizada com o valor publicado no tópico associado ao Dado, como o assinante do cliente MQTT do MQTTBox recebe o valor publicado também.