Pular para o conteúdo principal

cloud (servidor)

cloud​

Função global utilizada para realizar comunicação com o servidor IoT.


TAGs de Telemetria

As tags de telemetria são definidas de forma numérica, temos 4096 endereços para enviar telemetria personalizadas via mhoJS. Essa quantidade não inclui outras tags de telemetria padronizadas no equipamento, por exemplo: DIs, DOs, AIs, MBs, MIs, pulsos, etc. Essa quantidade abrange apenas as tags de telemetria definidas no mhoJS.

Como o dado chega ao servidor​

Dentro da função deve ser definida qual a memória de telemetria a ser utilizada, sendo esse valor de 1 a 4096. O equipamento enviará para o servidor a tag CTX, onde X é o número da memória de telemetria utilizada e CT é a categoria de telemetria utilizada que significa Custom Telemetry.

Exemplo: Enviando uma telemetria utilizando a memória 1, o servidor irá receber uma tag de telemetria CT1.

Formas de Envio​

Existem duas maneiras de enviar dados, uma associando a um uma 'tag' binária para controle de envios e outra disparando imediatamente a telemetria quando a função for chamada.

A tag binária de controle não está disponível para as funções cloud.send_srt e ìnsight. O disparo imediato não está disponível para a função insight.

Tag binária de controle
Quando o envio acontecer utilizando a tag binária de controle, para o envio acontecer novamente o usuário deve chamar a função que limpa a tag binária de controle cloud.clear(key);. Dessa forma, a telemetria pode ser chamada repetidamente no loop sem problemas, já que o valor será enviado novamente somente quando acontecer a limpeza da tag binária. *Durante a documentação a seguir a tag binária de controle será indicada nos argumentos das funções como controlBin e por padrão tem seu valor como false (quando não inserido).

Disparo imediato
Quando o envio acontecer utilizando o disparo automático, o programa deve ser feito de forma que envios repetidos não aconteçam, seja por estratégias de lógica ou temporizadores. Caso a função seja chamada repetidamente no loop a telemetria será enviada repetidamente, ocasionando em um alto consumo de banco de dados e dados trafegados.


Status​

cloud.connected​

Retorna se o equipamento está conectado ao servidor IoT.

cloud.connected();

Resposta: true se o equipamento estiver conectado e false se o equipamento estiver desconectado.


cloud.remotecontrol​

Retorna se o equipamento está com o modo remoto ativo (variável padrão).

cloud.remotecontrol();

Resposta: true se o equipamento estiver no modo remoto e false se o equipamento estiver no modo local.


cloud.setremotecontrol​

Seta valor da variável de controle remoto/local.

cloud.setremotecontrol(status);

true para ativar modo remoto e false para ativar modo local.


Telemetria​

cloud.send_int​

Envia um valor inteiro (de 32 bits: de −2147483648 até 2147483647) como telemetria para o servidor IoT.

cloud.send_int(key, value, ts=now, controlBin=false);

Resposta: true se o dado foi enviado/armazenado com sucesso ou false se o envio falhou.

Exemplo​

Enviar uma telemetria de um numero inteiro na memória 1 CT1 para identificar a etapa de um processo utilizado na lógica de programação. O timestamp deve ser o momento atual.


cloud.send_int(1, 5);

Resposta: true se o dado foi enviado com sucesso ou false se o envio falhou.

Agora nessa mesma situação deve ser enviado um timestamp antigo salvo na memoria...

cloud.send_int(1, 5, 1673032387);

Resposta: true se o dado foi enviado/armazenado com sucesso ou false se o envio falhou.


cloud.send_uint​

Envia um valor inteiro positivo (de 32 bits: de 0 a 4294967295) como telemetria para o servidor IoT.

cloud.send_uint(key, value, ts=now, controlBin=false);

Resposta: true se o dado foi enviado/armazenado com sucesso ou false se o envio falhou.

Exemplo​

Enviar uma telemetria de um numero inteiro na memória 2 CT2 para identificar a etapa de um processo utilizado na lógica de programação. O timestamp deve ser o momento atual.

cloud.send_uint(2, 5);

Resposta: true se o dado foi enviado/armazenado com sucesso ou false se o envio falhou.

Agora nessa mesma situação deve ser enviado um timestamp antigo salvo na memoria...

cloud.send_uint(2, 5, 1673032387);

Resposta: true se o dado foi enviado/armazenado com sucesso ou false se o envio falhou.


cloud.send_double​

Envia um valor de precisão (de 64 bits: de -7.2E+75 a 7.2E+75) como telemetria para o servidor IoT.

Memória Retentiva

Por padrão a memória retentiva do JS vem configurada para valores de até 32 bits, caso precise salvar esse valor na memória retentiva em eventos de desconexão é necessário definir a memória JS para 64 bits, veja a função setTelemetrySize.

cloud.send_double(key, value, ts=now, controlBin=false);

Resposta: true se o dado foi enviado/armazenado com sucesso ou false se o envio falhou.

Exemplo​

Enviar uma telemetria de um numero double na memória 3 CT3 para identificar a etapa de um processo utilizado na lógica de programação. O timestamp deve ser o momento atual.

cloud.send_double(3, 5.21);

Resposta: true se o dado foi enviado/armazenado com sucesso ou false se o envio falhou.

Agora nessa mesma situação deve ser enviado um timestamp antigo salvo na memoria...

cloud.send_double(3, 5.21, 1673032387);

Resposta: true se o dado foi enviado/armazenado com sucesso ou false se o envio falhou.


cloud.send_bin​

Envia um valor binário (true ou false) como telemetria para o servidor IoT.

cloud.send_bin(key, value, ts=now, controlBin=false);

Resposta: true se o dado foi enviado com sucesso ou false se o envio falhou.

Exemplo​

Enviar uma telemetria booleana na memória 4 CT4 para identificar a etapa de um processo utilizado na lógica de programação está ativo. O timestamp deve ser o momento atual.

cloud.send_bin(4, true);

Resposta: true se o dado foi enviado/armazenado com sucesso ou false se o envio falhou.

Agora nessa mesma situação deve ser enviado um timestamp antigo salvo na memoria...

cloud.send_bin(4, true , 1673032387);

Resposta: true se o dado foi enviado/armazenado com sucesso ou false se o envio falhou.


cloud.send_att​

Envia um objeto com atributos para o servidor IoT.

cloud.send_att(objeto);

Resposta: true se o dado foi enviado com sucesso ou false se o envio falhou.

Exemplo 1​

let objeto = {atributoTeste: true, OutroAtributo: 'Carga 1'};
cloud.send_att(objeto);

Resposta: true se o dado foi enviado com sucesso ou false se o envio falhou.

Exemplo 2​

Para o MHO Cloud podemos utilizar a tag up_sa para atualizar os atributos do servidor. Útil para configurar alarmes e parâmetros de equipamentos padronizados utilizados em grande escala.

let objeto = {up_sa: true, DI1name: 'Carga 1', DI1notify: true, DI1true: 'Falha', DI1false: 'Ok'};
cloud.send_att(objeto);

Resposta: true se o dado foi enviado com sucesso ou false se o envio falhou.


cloud.clear​

Limpa tag binária auxiliar de controle, permitindo envio novamente da telemetria. Serve para send_int, send_uint, send_double e send_bin. Dessa forma controlamos o envio de telemetria conforme os eventos do código e não a cada vez que a função for chamada.

cloud.clear(key);

Resposta: true.

Exemplo​

Enviar uma telemetria de uma variável valor inteiro na memória 1 CT1 para identificar a etapa de um processo utilizado na lógica de programação. Caso a condição 1 seja atendida a telemetria é enviada novamente.

cloud.send_int(1, valor, true);

if(condicao_1)
{
    cloud.clear(1);
}


cloud.send_str​

Envia um valor string (de até 30 caracteres) como telemetria para o servidor IoT.

DICA

Use esse recurso em situações em que a função send_int ou outra não atenda. Lembre-se que é possível pós processar os dados diretamente na plataforma. Esse recurso normalmente consome mais banco de dados e mais tráfego de dados. Esse tipo de telemetria não consome recursos das 4096 memórias alocadas para telemetria, as tags são strings e podem conter qualquer valor.

atenção!

Essa função não salva os valores na memória retentiva quando estiver desconectado.

cloud.send_str(key, value, ts=now);

Resposta: true se o dado foi enviado com sucesso ou false se o envio falhou.

Exemplo​

Enviar uma telemetria de um string com a key 'etapa' para identificar a etapa de um processo utilizado na lógica de programação. O timestamp deve ser o momento atual.

cloud.send_str('etapa', 'enchendo');

Resposta: true se o dado foi enviado com sucesso ou false se o envio falhou.

Agora nessa mesma situação deve ser enviado um timestamp antigo salvo na memoria...

cloud.send_str('etapa', 'enchendo', 1673032387);

Resposta: true se o dado foi enviado ou com sucesso ou false se o envio falhou.


cloud.alarm​

Envia parâmetros para o sistema de gestão de alarmes.

Dica para usuários que não utilizam o MHO Cloud

Essa função é implantada dentro do MHO Cloud para gerenciamento dos alarmes, caso esteja utilizando outro sistema é possível implementar funções parecidas dentro do seu sistema utilizando o mesmo padrão de tags. Os payloads são enviados da seguinte forma: {"alarmType": 1, "alarmText": "Esse é um alarme", "alarmNotify": "0100000"}

cloud.alarm(key, type, text, notify, controlBin=false);

Onde:

  • key: Tag de telemetria para utilização da tag controlBin;
  • type: Tipo de criticidade do alarme:
    • 0: limpo (utilizado para limpar o alarme criado previamente);
    • 1: crítico;
    • 2: alto;
    • 3: baixo;
    • 4: atenção;
    • 5: indeterminado.
  • text: Texto que representa o alarme;
  • notify: Configuração de notificação, passar parâmetro de array binário '0000000'
    • bit0: Email;
    • bit1: Telegram;
    • bit2: Central de notificações; (futuro)
    • bit3: SMS; (futuro)
    • bit4: WhatsApp; (futuro)
    • bit5: Slack; (futuro)
    • bit6: Teams; (futuro)
  • controlBin: Utilizado para controle binário dos envios.

Resposta: true se o dado foi enviado com sucesso ou false se o envio falhou.

Exemplo​

Enviar um alarme crítico com a mensagem 'Vazão baixa' e notificação por Telegram.

cloud.alarm(1, 1, "Vazão baixa", "0100000");

Resposta: true se o dado foi enviado com sucesso ou false se o envio falhou.



Insights​

cloud.insight​

Essa função foi pensada para utilização de informações de inteligência em situações que um alarme não pode ser gerado. Na maioria das vezes ela é gerada para alertar os usuários de possíveis problemas que podem estar acontecendo ou vão acontecer em um futuro próximo.

Dica para usuários que não utilizam o MHO Cloud

Essa função é implantada dentro do MHO Cloud para gerenciamento dos insights, caso esteja utilizando outro sistema é possível implementar funções parecidas dentro do seu sistema utilizando o mesmo padrão de tags. Os payloads são enviados da seguinte forma: {"insight": "Possível problema detectado no pressostato"}.

cloud.insight(insightKey, insight, resetTime=0);

Onde:

  • insightKey: Tag de insight para controle binário e de tempo do envio das telemetrias, ou seja cada tipo de insight deve ter a seu número (1 a 100);
  • insight: Texto enviado para o servidor;
  • resetTime: Utilizado para reset automático da tag binária de controle dos envios, tempo em minutos.
    • 0: Valor default quando não informado, reset automático desabilitado, o usuário deve chamar manualmente a função insightClear

Resposta:

  • -2: Erro ao enviar.
  • -1: Servidor desconectado
  • -0: Tag binária não permite o envio.
  • 1: Enviado com sucesso.

Exemplo​

Enviar um insight com a mensagem 'Possível problema no pressostato' com reset automático para novo envio após 6 horas (360 minutos).

cloud.insight(1, "Possível problema no pressostato", 360);

cloud.insightClear​

Função utilizada para limpar a tag binária de controle de envio dos insights.

cloud.insightClear(insightKey);

Resposta:

  • -2: Erro ao enviar.
  • -1: Servidor desconectado
  • -0: Tag binária não permite o envio.
  • 1: Enviado com sucesso.

Exemplo​

Enviar um insight com a mensagem 'Possível problema no pressostato' com reset automático para novo envio após 6 horas (360 minutos).

cloud.insightClear(1);

Resposta: true.


cloud.insightStatus​

Função utilizada para ler status da tag binária de controle de envio dos insights.

cloud.insightStatus(insightKey);

Resposta: true/false.

Exemplo​

Ler o status de um insight.

cloud.insightStatus(1);

Resposta: true/false.



Configurações​

Funções para configuração das portas e envios. As configurações podem ser realizadas em tempo de execução.

cloud.configDI​

DICA

Desabilite canais de telemetria para dados não importantes. Otimize o consumo de dados.

Habilita ou desabilita a telemetria do canal desejado. Por padrão todos os canais de DIs são habilitados.

cloud.configDI(DI, state);

Resposta: true se o canal for configurado com sucesso, false se o canal for 0 e erro se o canal não existir.

Exemplo​

Desabilitar a DI1.

cloud.configDI(1, false);

Resposta: true.


cloud.configDO​

Habilita ou desabilita a telemetria do canal desejado. Por padrão todos os canais de DOs são habilitados.

cloud.configDO(DO, state);

Resposta: true se o canal for configurado com sucesso, false se o canal for 0 e erro se o canal não existir.

Exemplo​

Desabilitar a DO5.

cloud.configDO(5, false);

Resposta: true.


cloud.configAI​

Habilita ou desabilita a telemetria do canal desejado. Os canais são configurados via webserver e por padrão iniciam todos desabilitados.

cloud.configAI(AI, state);

Resposta: true se o canal for configurado com sucesso, false se o canal for 0 e erro se o canal não existir.

Exemplo​

Desabilitar a AI1.

cloud.configAI(1, false);

Resposta: true.


cloud.remapIO​

Troca o nome da tag de telemetria enviada para o servidor. Útil para situações de grandes sistemas que compartilham as mesmas dashboards, porém por algum motivo a IO precisa ser remapeada.

cloud.remapIO(IOtype, IO_a, IO_b);

Resposta: true se os canais forem configurados com sucesso, erro se algum parâmetro for inserido incorretamente.

Exemplo DI​

Remapear a DI5 pela DI1 (trocar virtualmente a telemetria).

cloud.remapIO('DI', 5, 1);

Resposta: true.

Exemplo DO​

Remapear a DO2 pela DI2 (trocar virtualmente a telemetria).

cloud.remapIO('DO', 2, 1);

Resposta: true.

Exemplo AI​

Remapear a AI2 pela AI1 (trocar virtualmente a telemetria).

cloud.remapIO('AI', 2, 1);

Resposta: true.


cloud.setAlarm​

Função exclusiva de uso MHO Cloud.

Seta via dispositivo as configurações de alarme do servidor (MHO Cloud). Útil em grandes sistemas ou equipamentos padronizados que possuem as mesmas configurações de alarme.

let alarmObj = {DI1name: 'DPS', DI1true: 'ALARME 1', DI1false: 'OK', DI1notify: true};
cloud.setAlarm(alarmObj);

Resposta: true se a telemetria for enviada.



Comunicação m2m​

Funções para comunicação m2m entre equipamentos ou obtenção de parâmetros da plataforma.

cloud.setAtt​

Função exclusiva de uso MHO Cloud.

Função que seta os atributos compartilhados utilizados para que em todo evento de conexão com o servidor eles sejam sincronizados. As respostas vão para o callback sa_callback(obj);. Utilize na inicialização do programa definindo os atributos compartilhados desejados.

dica

Essa função deve ser chamada apenas uma vez com todas as variáveis de interesse no inicio do programa.

cloud.setAtt(stringList);

Resposta: true em sucesso ou error.

Onde:

  • stringList: Lista de atributos requisitados separados por virgula, sem espaço.

A resposta do servidor com os atributos serão enviados para o mhoJS via função de callback, sa_callback(obj), onde obj são os atributos compartilhados em formato de objeto. Veja o exemplo de uso m2m

Exemplo 1​

Definir o atributo res1_DI1.

cloud.setAtt('res1_DI1');

Resposta: true.

Exemplo 2​

Definir os atributos res1_DI1, res1_DI2 e res1_AI1.

cloud.setAtt('res1_DI1,res1_DI2,res1_AI1');

cloud.getAtt​

Função exclusiva de uso MHO Cloud.

Requisita os atributos compartilhados do dispositivo. Útil para comunicação m2m entre dispositivos ou para atualização de parâmetros como variáveis utilizado dentro do contexto mhoJS do equipamento.

cloud.getAtt(stringList);

Resposta: true se o atributo foi requisitado com sucesso, false se não pode ser requisitado.

Onde:

  • stringList: Lista de atributos requisitados separados por virgula, sem espaço.

A resposta do servidor com os atributos serão enviados para o mhoJS via função de callback, sa_callback(obj), onde obj são os atributos compartilhados em formato de objeto. Veja o exemplo de uso m2m

Exemplo 1​

Requisitar o atributo res1_DI1.

cloud.getAtt('res1_DI1');

Resposta: true.

Exemplo 2​

Requisitar os atributos res1_DI1, res1_DI2 e res1_AI1.

cloud.getAtt('res1_DI1,res1_DI2,res1_AI1');

Resposta: true.



Callbacks​

Funções chamadas em determinados eventos do programa.

sa_callback​

Função exclusiva de uso MHO Cloud.

Função chamada pelo servidor quando um atributo compartilhado é atualizado, utilizando em situações de m2m ou para definições de variáveis locais de forma remota.

Uso:

let sa_callback = function(obj){

};

mqtt_subscribe​

Para utilização em outros sistemas que não seja o MHO Cloud.

Função chamada quando o equipamento se conecta ao servidor MQTT, utilizada para se inscrever em tópicos MQTT.

let mqtt_subscribe = function(){

};

mqtt_callback​

Para utilização em outros sistemas que não seja o MHO Cloud. Função chamada quando uma telemetria é recebida no tópico subscrito.

Uso:

let mqtt_callback = function(topic, payload){
    
};