Enviar mensagens de nuvem para dispositivo com o Hub IoT (Node.js)

  • Artigo

O Hub IoT do Azure é um serviço totalmente gerenciado que ajuda a permitir comunicações bidirecionais confiáveis e seguras entre milhões de dispositivos e um back-end de solução.

Este artigo mostra como:

  • Enviar mensagens de nuvem para dispositivo (CD2), do back-end da solução para um único dispositivo, por meio do Hub IoT

  • Receber mensagens da nuvem para dispositivo em um dispositivo

  • Solicite confirmação de entrega (comentários), do back-end da sua solução, para as mensagens enviadas a um dispositivo do Hub IoT

Observação

Os recursos descritos neste artigo estão disponíveis apenas na camada padrão do Hub IoT. Para obter mais informações sobre as camadas básica e padrão/gratuita do Hub IoT, confira Escolher a camada certa do Hub IoT para a sua solução.

No final do tutorial, você executará dois aplicativos de console do Node.js:

  • simple_sample_device: um aplicativo do dispositivo de exemplo incluído no SDK de Internet das Coisas do Azure para Node.js, que se conecta ao seu hub IoT e recebe mensagens de nuvem para dispositivo.

  • SendCloudToDevice: um aplicativo de serviço que envia uma mensagem da nuvem para o aplicativo do dispositivo através do Hub IoT e, em seguida, recebe sua confirmação de entrega.

Observação

O Hub IoT tem suporte a SDK para várias plataformas de dispositivo e linguagens (C, Java, Python e JavaScript) por meio dos SDKs do dispositivo IoT do Azure.

Para saber mais sobre mensagens da nuvem para o dispositivo, confira Enviar mensagens da nuvem para dispositivo em um Hub IoT.

Pré-requisitos

  • Uma assinatura do Azure. Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

  • Um Hub IoT na assinatura do Azure. Caso você ainda não tenha um hub, poderá seguir as etapas em Criar um hub IoT.

  • Um dispositivo registrado em seu hub IoT. Se você ainda não registrou um dispositivo, registre um no portal do Azure.

  • Este artigo usa códigos de exemplo do SDK de Internet das Coisas do Azure para Node.js.

    • Baixe ou clone o repositório SDK do GitHub no computador de desenvolvimento.
    • Verifique se a versão 10.0.x ou posterior do Node.js esteja instalada no computador de desenvolvimento. Preparar o ambiente de desenvolvimento descreve como instalar o Node.js para este artigo no Windows ou no Linux.

  • Verifique se a porta 8883 está aberta no firewall. O exemplo de dispositivo deste artigo usa o protocolo MQTT, que se comunica pela porta 8883. Essa porta poderá ser bloqueada em alguns ambientes de rede corporativos e educacionais. Para obter mais informações e maneiras de resolver esse problema, confira Como se conectar ao Hub IoT (MQTT).

Obter a cadeia de conexão do dispositivo

Neste artigo, você executará um aplicativo de exemplo que simula um dispositivo que recebe mensagens da nuvem para o dispositivo enviadas por meio de seu Hub IoT. O aplicativo de exemplo simple_sample_device incluído no SDK de Internet das Coisas do Azure para Node.js se conecta ao seu hub de IoT e atua como seu dispositivo simulado. O exemplo usa a cadeia de conexão primária do dispositivo registrado no hub IoT.

Para obter a cadeia de conexão primária de um dispositivo registrado no hub IoT, siga estas etapas:

  1. No portal do Azure, selecione Grupos de recursos. Selecione o grupo de recursos em que o Hub está localizado e, em seguida, selecione o seu hub na lista de recursos.

  2. No painel esquerdo do hub IoT, em Gerenciamento de Dispositivos, selecione Dispositivos.

  3. Na lista de dispositivos, selecione o dispositivo apropriado.

  4. Copie a Cadeia de conexão primária e salve o valor.

    Captura de tela mostrando como recuperar a cadeia de conexão primária de um dispositivo registrado no seu hub IoT no portal do Azure.

Receber mensagens no aplicativo do dispositivo

Nesta seção, execute o aplicativo do dispositivo de amostra simple_sample_device para receber mensagens C2D enviadas através do seu hub IoT. Abra um novo prompt de comando e navegue para a pasta azure-iot-sdk-node\device\samples\javascript, sob a pasta em que você expandiu o SDK Node.js do Azure IoT. Execute os comandos a seguir, substituindo o valor do espaço reservado {Your device connection string} pela cadeia de conexão do dispositivo copiada do dispositivo registrado no hub IoT.

set IOTHUB_DEVICE_CONNECTION_STRING={Your device connection string}
node simple_sample_device.js

A saída a seguir é do aplicativo de dispositivo de exemplo depois que ele é iniciado e se conecta com êxito ao hub IoT:

Client connected
Client connected
Client connected
Sending message: {"deviceId":"myFirstDevice","windSpeed":10.949952400617569,"temperature":26.0096515658525,"humidity":72.59398225838534}
Client connected
Client connected
send status: MessageEnqueued
Sending message: {"deviceId":"myFirstDevice","windSpeed":12.917649160180087,"temperature":27.336831253904613,"humidity":77.37300365434534}

Neste exemplo, o dispositivo invoca a função complete para notificar o Hub IoT de que ele processou a mensagem e que ela pode ser removida com segurança da fila do dispositivo. A chamada à função complete não será necessária se você estiver usando o transporte MQTT e puder ser omitida. Ela é necessária para AMQP e HTTPS.

Com AMQP e HTTPS, mas não MQTT, o dispositivo também pode:

  • Abandonar temporariamente uma mensagem, fazendo com que um Hub IoT retenha a mensagem na fila do dispositivo para consumo futuro.
  • Rejeitar uma mensagem, o que irá removê-la permanentemente da fila de espera do dispositivo.

Se algo impedir o dispositivo de concluir, abandonar ou rejeitar a mensagem, o Hub IoT, após um tempo limite fixo, colocará a mensagem na fila de entrega novamente. Por esse motivo, a lógica de processamento de mensagem no aplicativo de dispositivo deve ser idempotente, de modo que receber a mesma mensagem várias vezes produza o mesmo resultado.

Para obter mais informações sobre o ciclo de vida de mensagem da nuvem para dispositivo e como o Hub IoT processa mensagens de nuvem para dispositivo, confira Enviar mensagens de nuvem para dispositivo por meio de um Hub IoT.

Observação

Se você usar HTTPS em vez de MQTT ou AMQP como transporte, a instância Client verificará se há mensagens do Hub IoT com pouca frequência (pelo menos a cada 25 minutos). Para obter mais informações sobre as diferenças entre a compatibilidade a MQTT, AMQP e HTTPS, consulte Diretrizes de comunicação da nuvem para dispositivo e Escolher um protocolo de comunicação.

Obter a cadeia de conexão do hub IoT

Neste artigo, você criará um serviço de back-end para enviar mensagens de nuvem para dispositivo por meio do seu Hub IoT. Para enviar mensagens de nuvem para dispositivo, o serviço precisa da permissão conexão de serviço. Por padrão, todo Hub IoT é criado com uma política de acesso compartilhado chamada serviço que concede essa permissão.

Para obter a cadeia de conexão do Hub IoT para a política de serviço, siga estas etapas:

  1. No portal do Azure, selecione Grupos de recursos. Selecione o grupo de recursos em que o Hub está localizado e, em seguida, selecione o seu hub na lista de recursos.

  2. No painel do lado esquerdo do hub IoT, selecione Políticas de acesso compartilhado.

  3. Na lista de políticas, selecione a política de serviço.

  4. Copie a Cadeia de conexão primária e salve o valor.

Captura de tela que mostra como recuperar a cadeia de conexão do seu Hub IoT no portal do Azure.

Para obter mais informações sobre permissões e políticas de acesso compartilhado do Hub IoT, consulte Controle de acesso e permissões.

Envie uma mensagem da nuvem para o dispositivo

Nesta seção, você criará um aplicativo do console do Node.js que envia mensagens da nuvem ao dispositivo para o aplicativo do dispositivo simulado. Você precisa da ID do dispositivo e da cadeia de conexão do hub IoT.

  1. Crie uma pasta vazia denominada sendcloudtodevicemessage. Abra um prompt de comando, navegue até a pasta sendcloudtodevicemessage e execute o comando a seguir para criar um arquivo package.json nessa pasta. Pressione Enter em cada prompt apresentado pelo comando npm para aceitar o padrão para esse prompt:

    npm init

  2. No prompt de comando, na pasta sendcloudtodevicemessage, execute o seguinte comando para instalar o pacote azure-iothub:

    npm install azure-iothub --save

  3. Usando um editor de texto, crie um arquivo SendCloudToDeviceMessage.js na pasta sendcloudtodevicemessage.

  4. Adicione as seguintes instruções require no início do arquivo SendCloudToDeviceMessage.js :

    'use strict';

var Client = require('azure-iothub').Client;
var Message = require('azure-iot-common').Message;

  5. Adicione o seguinte código ao arquivo SendCloudToDeviceMessage.js . Substitua os valores de espaço reservado "{iot hub connection string}" e "{device ID}" pela cadeia de conexão do hub IoT e pela ID do dispositivo anotadas anteriormente:

    var connectionString = '{iot hub connection string}';
var targetDevice = '{device id}';

var serviceClient = Client.fromConnectionString(connectionString);

  6. Adicione a seguinte função para imprimir os resultados da operação no console:

    function printResultFor(op) {
  return function printResult(err, res) {
    if (err) console.log(op + ' error: ' + err.toString());
    if (res) console.log(op + ' status: ' + res.constructor.name);
  };
}

  7. Adicione a seguinte função para imprimir mensagens de comentários de entrega para o console:

    function receiveFeedback(err, receiver){
  receiver.on('message', function (msg) {
    console.log('Feedback message:')
    console.log(msg.getData().toString('utf-8'));
  });
}

  8. Adicione o seguinte código para enviar uma mensagem ao dispositivo e lidar com a mensagem de comentário quando o dispositivo reconhecer a mensagem da nuvem para o dispositivo:

    serviceClient.open(function (err) {
  if (err) {
    console.error('Could not connect: ' + err.message);
  } else {
    console.log('Service client connected');
    serviceClient.getFeedbackReceiver(receiveFeedback);
    var message = new Message('Cloud to device message.');
    message.ack = 'full';
    message.messageId = "My Message ID";
    console.log('Sending message: ' + message.getData());
    serviceClient.send(targetDevice, message, printResultFor('send'));
  }
});

  9. Salve e feche o arquivo SendCloudToDeviceMessage.js .

Executar os aplicativos

Tudo pronto para executar os aplicativos.

  1. No prompt de comando na pasta azure-iot-sdk-node\device\samples\javascript, execute o seguinte comando para enviar telemetria ao Hub IoT e escutar mensagens de nuvem para dispositivo:

    node simple_sample_device.js

    Executar um aplicativo de dispositivo simulado

  2. No prompt de comando na pasta sendcloudtodevicemessage, execute o comando a seguir para enviar uma mensagem da nuvem para o dispositivo e esperar os comentários de confirmação:

    node SendCloudToDeviceMessage.js

    Execute o aplicativo para enviar o comando da nuvem para o dispositivo

    Observação

    Para simplificar, este artigo não implementa nenhuma política de repetição. No código de produção, implemente políticas de repetição (como uma retirada exponencial), conforme sugerido no artigo Tratamento de falhas transitórias.

Próximas etapas

Neste artigo, você aprendeu a enviar e receber mensagens de nuvem para dispositivo.