Pular para o conteúdo principal

Estrutura

Este guia descreve os passos necessários para integração através do MQTT, proporcionando uma comunicação eficiente e confiável entre o MHO Cloud e o sistema compatível, disponibilizando para subscrição os dados coletados dos dispositivos integrados ao MHO Cloud.

1 Pré-requisitos​

dica

O broker MHO Cloud utiliza o MQTT v5, com compatibilidade com versões anteriores.

Antes de começar a integração, certifique-se de ter o seguinte:

  • Um sistema compatível com MQTT que possa se conectar em um broker como client;
  • Conhecimento básico sobre tópicos MQTT e QoS (Qualidade de Serviço);
  • Credenciais MQTT de subscrição do broker MHO Cloud (solicite ao fornecedor da solução MHO Cloud).

2 Arquitetura​

Todos os seus dispositivos que já estão conectados ao MHO Cloud permanecerão da mesma forma. A integração será um client do broker MHO Cloud, sendo a integração responsável por solicitar os tópicos de interesse. Quando uma mensagem de interesse chegar o broker irá enviar as informações para a integração.

3 Credenciais​

As credenciais da integração devem ser solicitadas ao fornecedor da solução MHO Cloud. O seu client poderá se subscrever apenas em tópicos dos dispositivos de sua propriedade ou que tenham relação com o seu contexto.

Dados de acesso:

  • broker: mqtt.mhocloud.com
  • porta MQTT: 1883
  • porta MQTTs: 8883
  • credenciais: conforme definido abaixo

3.1 Básica​

Autenticação de um fator, baseado na combinação de clientID, Usuario e/ou Senha. Qualquer combinação de 1 ou mais é possível.

dica

Utilizar uma autenticação de Usuário e Senha costuma ser a melhor forma.

3.2 Certificado X.509​

Conexão segura através de autenticação de dois fatores com certificado X.509. Nesse método o usuário deve solicitar os detalhes de autenticação do certificado a ser utilizado, bem como sua renovação quando necessário.

4 Troca de Dados​

A troca de dados acontece por meio de tópicos MQTT, onde a integração deve se subscrever (subscribe) nos tópicos de interesse para ler os dados dos equipamentos e deve publicar (publish) nos tópicos de interesse para escrever/comandar os equipamentos.

Os tópicos carregam a identificação do dono do equipamento e a identificação do equipamento. Nesta documentação os tópicos serão resumidos pelas seguintes tags: myid e mydevice.

  • myid: ID global dos dispositivos conforme propriedade definida no MHO Cloud;
  • mydevice: ID do dispositivo que está transmitindo telemetria;
Como obter id do cliente (myid)

Dentro do seu contexto MHO Cloud.

  1. Acesse o menu Grupo de Clientes;
  2. Acesse a pasta desejada;
  3. Clique na entidade desejada;
  4. Clique no botão Copiar ID do cliente;

Como obter id do dispositivo (mydevice)

Dentro do seu contexto MHO Cloud.

  1. Acesse o menu Grupo de Dispositivos;
  2. Acesse a pasta desejada;
  3. Clique na entidade desejada;
  4. Clique no botão Copiar ID do dispositivo;

4.1 Tópicos de Subscribe​

dica

A integração client deve se subscrever nos tópicos de interesse para obter dados de telemetria.

Os tópicos da integração são definidos da seguinte forma (esses tópicos definidos neste escopo não dependem de como o MQTT do equipamento funciona).

Todos os tópicos serão disponibilizados da seguinte forma: mho/myid/mydevice/telemetryKey

  • telemetryKey: tag de telemetria, podendo ser uma IO, memórias de protocolo, telemetrias customizadas ou atributos do equipamento;

As mensagems terão payload direta em formatos bool ou float ou int ou string.

  • myid: ID global dos dispositivos conforme propriedade definida no MHO Cloud;
  • mydevice: ID do dispositivo que está transmitindo telemetria;
  • telemetryKey: tag de telemetria;

Status Gerais​

mho/myid/mydevice/status

Resposta: true/false


Entradas Digitais​

mho/myid/mydevice/DI1

...

mho/myid/mydevice/DI16

Resposta: bool


Entradas Analógicas​

mho/myid/mydevice/AI1

...

mho/myid/mydevice/AI8

Resposta: int

Dados interpolados serão interpretados conforme tag de telemetria salva, por exemplo uma tag salva como "Meu dado interpolado":

mho/myid/mydevice/Meu dado interpolado

Resposta: float


Saídas Digitais​

Status atual das saídas digitais. Esse dado também é útil para recebimento de feedback quando um comando for enviado.

mho/myid/mydevice/DO1

...

mho/myid/mydevice/DO16

Resposta: bool


Respostas de RPC​

Receber resposta do equipamento ao comando RPC solicitado.

mho/rpcresponse/myid/mydevice

Resposta: string Erro/Sucesso

4.2 Tópicos de Publish​

dica

A integração client deve publicar valores nos tópicos de interesse para setar valores ou enviar dados para o sistema.

Em processo de documentação...

5 Resumo​

No geral podemos adotar os seguintes passos para realizar a integração. Nos próximos artigos temos exemplos de integração com softwares comerciais.

  • 1: Definir a conexão com o broker:
    • Informe o endereço do broker: mqtt.mhocloud.com
    • Informe a porta a ser utilizada: MQTT 1883 ou MQTTs 8883
    • Informe configurações adicionais: Tempo de timeout, keep alive, ... etc
    • Informe as credenciais de conexão
  • 2: Buscar datasources se inscrevendo nos tópicos de interesse, conforme definições do software a ser integrado
  • 3: Integrar o datasource conforme conforme definições do software a ser integrado