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 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 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 (Client ID) 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. 23 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. 24 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. 25 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 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 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 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, 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. 26 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. 27 Exemplo de payload considerando a publicação no tópico especifico de cada Dado.