Inviare messaggi da cloud a dispositivo con l'hub IoT (Node.js)

  • Articolo

L'hub IoT di Azure è un servizio completamente gestito che consente di abilitare comunicazioni bidirezionali affidabili e sicure tra milioni di dispositivi e un back-end della soluzione.

Questo articolo illustra come:

  • Inviare messaggi da cloud a dispositivo (C2D) dal back-end della soluzione a un singolo dispositivo tramite hub IoT

  • Ricevere messaggi da cloud a dispositivo in un dispositivo

  • Richiedere il riconoscimento di recapito (feedback), dal back-end della soluzione, per i messaggi inviati a un dispositivo da hub IoT

Nota

Le funzionalità descritte in questo articolo sono disponibili solo nel livello Standard dell'hub IoT. Per altre informazioni sui livelli di hub IoT standard e standard, vedere Scegliere il livello di hub IoT appropriato per la soluzione.

Al termine di questo articolo si eseguono due app console Node.js:

  • simple_sample_device: un'app del dispositivo di esempio inclusa in Microsoft Azure IoT SDK per Node.js, che si connette all'hub IoT e riceve messaggi da cloud a dispositivo.

  • SendCloudToDevice: un'app di servizio che invia un messaggio da cloud a dispositivo all'app per dispositivi tramite hub IoT e quindi riceve il riconoscimento del recapito.

Nota

hub IoT supporta SDK per molte piattaforme e linguaggi per dispositivi (C, Java, Python e JavaScript) tramite gli SDK per dispositivi IoT di Azure.

Per altre informazioni sui messaggi da cloud a dispositivo, vedere Inviare messaggi da cloud a dispositivo da un hub IoT.

Prerequisiti

  • Una sottoscrizione di Azure. Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.

  • Un hub IoT nella sottoscrizione di Azure. Se non si ha ancora un hub, è possibile seguire la procedura descritta in Creare un hub IoT.

  • Un dispositivo registrato nell'hub IoT. Se non è ancora stato registrato un dispositivo, registrare un dispositivo nel portale di Azure.

  • Questo articolo usa il codice di esempio di Azure IoT SDK per Node.js.

    • Scaricare o clonare il repository SDK da GitHub nel computer di sviluppo.
    • Assicurarsi che Node.js versione 10.0.x o successiva sia installato nel computer di sviluppo. Preparare l'ambiente di sviluppo descrive come installare Node.js per questo articolo in Windows o Linux.

  • Assicurarsi che la porta 8883 sia aperta nel firewall. L'esempio di dispositivo di questo articolo usa il protocollo MQTT, che comunica tramite la porta 8883. Questa porta potrebbe essere bloccata in alcuni ambienti di rete aziendali e didattici. Per altre informazioni e soluzioni alternative per questo problema, vedere Connettersi all'hub IoT (MQTT).

Ottenere la stringa di connessione del dispositivo

In questo articolo viene eseguita un'app di esempio che simula un dispositivo, che riceve messaggi da cloud a dispositivo inviati tramite il hub IoT. L'app di esempio simple_sample_device inclusa in Microsoft Azure IoT SDK per Node.js si connette all'hub IoT e funge da dispositivo simulato. L'esempio usa la stringa di connessione primaria del dispositivo registrato nell'hub IoT.

Per ottenere la stringa di connessione primaria per un dispositivo registrato nell'hub IoT, seguire questa procedura:

  1. Nel portale di Azure fare clic su Gruppi di risorse. Selezionare il gruppo di risorse in cui si trova l'hub e quindi selezionare l'hub dall'elenco di risorse.

  2. Nel riquadro a sinistra dell'hub IoT, in Gestione dispositivi selezionare Dispositivi.

  3. Nell'elenco dei dispositivi selezionare il dispositivo appropriato.

  4. Copiare la stringa di connessione primaria e salvare il valore.

    Screenshot che mostra come recuperare la stringa di connessione primaria per un dispositivo registrato nell'hub IoT nel portale di Azure.

Ricevere messaggi nell'app per dispositivi

In questa sezione eseguire l'app del dispositivo di esempio simple_sample_device per ricevere messaggi C2D inviati tramite l'hub IoT. Aprire un nuovo prompt dei comandi e passare alla cartella azure-iot-sdk-node\device\samples\javascript , nella cartella in cui è stato espanso Azure IoT Node.js SDK. Eseguire i comandi seguenti, sostituendo il {Your device connection string} valore segnaposto con la stringa di connessione del dispositivo copiata dal dispositivo registrato nell'hub IoT.

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

L'output seguente proviene dall'app del dispositivo di esempio dopo l'avvio e la connessione all'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}

In questo esempio, il dispositivo richiama la funzione completa per notificare hub IoT che ha elaborato il messaggio e che può essere rimosso in modo sicuro dalla coda del dispositivo. La chiamata al completamento non è necessaria se si usa il trasporto MQTT e può essere omessa. È necessario per AMQP e HTTPS.

Con AMQP e HTTPS, ma non MQTT, il dispositivo può anche:

  • Abbandonare un messaggio, che comporta hub IoT conservare il messaggio nella coda del dispositivo per un utilizzo futuro.
  • Rifiutare un messaggio, che rimuove definitivamente il messaggio dalla coda del dispositivo.

Se si verifica un evento che impedisce al dispositivo di completare, abbandonare o rifiutare il messaggio, hub IoT, dopo un periodo di timeout fisso, accoda nuovamente il messaggio per il recapito. Per questo motivo, la logica di elaborazione dei messaggi nell'app per dispositivo deve essere idempotente, in modo che la ricezione dello stesso messaggio più volte produa lo stesso risultato.

Per altre informazioni sul ciclo di vita dei messaggi da cloud a dispositivo e su come hub IoT elabora i messaggi da cloud a dispositivo, vedere Inviare messaggi da cloud a dispositivo da un hub IoT.

Nota

Se si usa HTTPS anziché MQTT o AMQP come trasporto, l'istanza client verifica la presenza di messaggi da hub IoT raramente (almeno ogni 25 minuti). Per altre informazioni sulle differenze tra il supporto di MQTT, AMQP e HTTPS, vedere Linee guida sulle comunicazioni da cloud a dispositivo e Scegliere un protocollo di comunicazione.

Ottenere la stringa di connessione dell'hub IoT

In questo articolo viene creato un servizio back-end per inviare messaggi da cloud a dispositivo tramite il hub IoT. Per inviare messaggi da cloud a dispositivo, è necessario che il servizio disponga dell'autorizzazione di connessione al servizio. Per impostazione predefinita, ogni hub IoT viene creato con un servizio con nome di criteri di accesso condiviso che concede tale autorizzazione.

Per ottenere la stringa di connessione dell'hub IoT per i criteri del servizio, seguire questa procedura:

  1. Nel portale di Azure fare clic su Gruppi di risorse. Selezionare il gruppo di risorse in cui si trova l'hub e quindi selezionare l'hub dall'elenco di risorse.

  2. Nel riquadro sinistro dell'hub IoT selezionare Criteri di accesso condiviso.

  3. Dall'elenco dei criteri selezionare i criteri del servizio.

  4. Copiare la stringa di connessione primaria e salvare il valore.

Screenshot che mostra come recuperare la stringa di connessione dal hub IoT nel portale di Azure.

Per altre informazioni sui criteri di accesso condiviso e sulle autorizzazioni dell'hub IoT, vedere Controllo dell'accesso e autorizzazioni.

Inviare un messaggio da cloud a dispositivo

In questa sezione si crea un'app console Node.js che invia messaggi da cloud a dispositivo all'app del dispositivo simulato. È necessario l'ID dispositivo dal dispositivo e la stringa di connessione dell'hub IoT.

  1. Creare una cartella vuota denominata sendcloudtodevicemessage. Aprire un prompt dei comandi, passare alla cartella sendcloudtodevicemessage e quindi eseguire il comando seguente per creare un package.json file in tale cartella. Premere INVIO a ogni prompt presentato dal npm comando per accettare l'impostazione predefinita per il prompt:

    npm init

  2. Eseguire questo comando al prompt dei comandi nella cartella sendcloudtodevicemessage per installare il pacchetto azure-iothub:

    npm install azure-iothub --save

  3. Con un editor di testo, creare un file SendCloudToDeviceMessage.js nella cartella sendcloudtodevicemessage.

  4. Aggiungere le istruzioni require seguenti all'inizio del file SendCloudToDeviceMessage.js :

    'use strict';

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

  5. Aggiungere il codice seguente al file SendCloudToDeviceMessage.js . Sostituire i valori segnaposto "{iot hub connection string}" e "{device ID}" con la stringa di connessione dell'hub IoT e l'ID dispositivo annotati in precedenza:

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

var serviceClient = Client.fromConnectionString(connectionString);

  6. Aggiungere la funzione seguente per stampare i risultati dell'operazione sulla 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. Aggiungere la funzione seguente per stampare i messaggi di feedback del recapito sulla console:

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

  8. Aggiungere il codice seguente per inviare un messaggio al dispositivo e gestire il messaggio di feedback quando il dispositivo accetta il messaggio da cloud a 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. Salvare e chiudere il file SendCloudToDeviceMessage.js .

Eseguire le applicazioni

A questo momento si è pronti per eseguire le applicazioni.

  1. Al prompt dei comandi nella cartella azure-iot-sdk-node\device\samples\javascript eseguire il comando seguente per inviare dati di telemetria a hub IoT e per ascoltare i messaggi da cloud a dispositivo:

    node simple_sample_device.js

    Eseguire un'app di dispositivo simulato

  2. A un prompt dei comandi nella cartella sendcloudtodevicemessage eseguire questo comando per inviare un messaggio da cloud a dispositivo e attendere il feedback di acknowledgment:

    node SendCloudToDeviceMessage.js

    Eseguire l'app per inviare il comando da cloud a dispositivo

    Nota

    Per semplicità, questo articolo non implementa criteri di ripetizione dei tentativi. Nel codice di produzione è consigliabile implementare criteri di ripetizione dei tentativi, ad esempio un backoff esponenziale, come suggerito nell'articolo Gestione degli errori temporanei.

Passaggi successivi

In questo articolo si è appreso come inviare e ricevere messaggi da cloud a dispositivo.