Usare la gestione dei dispositivi per avviare un aggiornamento del firmware del dispositivo (.NET/Node)Use device management to initiate a device firmware update (.NET/Node)

Nell'esercitazione Introduzione alla gestione dei dispositivi è stato illustrato come usare il dispositivo gemello e le primitive dei metodi diretti per riavviare un dispositivo in modalità remota.In the Get started with device management tutorial, you saw how to use the device twin and direct methods primitives to remotely reboot a device. Questa esercitazione usa le stesse primitive dell'hub IoT e illustra come eseguire un aggiornamento del firmware simulato completo.This tutorial uses the same IoT Hub primitives and shows you how to do an end-to-end simulated firmware update. Questo modello viene usato nell'implementazione dell'aggiornamento del firmware per l'esempio di implementazione del dispositivo Raspberry Pi.This pattern is used in the firmware update implementation for the Raspberry Pi device implementation sample.

Questa esercitazione illustra come:This tutorial shows you how to:

  • Creare un'app console .NET che chiama il metodo diretto firmwareUpdate nell'app per dispositivo simulato tramite l'hub IoT.Create a .NET console app that calls the firmwareUpdate direct method in the simulated device app through your IoT hub.
  • Creare un'app di dispositivo simulato che implementa un metodo diretto firmwareUpdate.Create a simulated device app that implements a firmwareUpdate direct method. Questo metodo avvia un processo in più fasi che attende di scaricare l'immagine del firmware, quindi la scarica e infine la applica.This method initiates a multi-stage process that waits to download the firmware image, downloads the firmware image, and finally applies the firmware image. Durante l'esecuzione di ogni fase, il dispositivo usa le proprietà segnalate per aggiornare lo stato.During each stage of the update, the device uses the reported properties to report on progress.

Al termine dell'esercitazione saranno disponibili un'app per il dispositivo console Node.js e un'app back-end console .NET (C#):At the end of this tutorial, you have a Node.js console device app and a .NET (C#) console back-end app:

dmpatterns_fwupdate_service.js, che chiama un metodo diretto nell'app per dispositivo simulato, visualizza la risposta e visualizza regolarmente (ogni 500 ms) le proprietà segnalate aggiornate.dmpatterns_fwupdate_service.js, which calls a direct method in the simulated device app, displays the response, and periodically (every 500ms) displays the updated reported properties.

TriggerFWUpdate, che connette all'hub IoT con l'identità del dispositivo creata prima, riceve un metodo diretto firmwareUpdate, esegue un processo in più stati per simulare un aggiornamento del firmware, inclusi l'attesa del download dell'immagine, il download della nuova immagine e infine l'applicazione dell'immagine.TriggerFWUpdate, which connects to your IoT hub with the device identity created earlier, receives a firmwareUpdate direct method, runs through a multi-state process to simulate a firmware update including: waiting for the image download, downloading the new image, and finally applying the image.

Per completare l'esercitazione, sono necessari gli elementi seguenti:To complete this tutorial, you need the following:

  • Visual Studio 2015 o Visual Studio 2017.Visual Studio 2015 or Visual Studio 2017.
  • Node.js 4.0.x o versione successiva.Node.js version 4.0.x or later,
    Prepare your development environment (Preparare l'ambiente di sviluppo) descrive come installare Node.js per questa esercitazione in Windows o Linux.Prepare your development environment describes how to install Node.js for this tutorial on either Windows or Linux.
  • Un account Azure attivo.An active Azure account. Se non si ha un account, è possibile creare un account gratuito in pochi minuti.(If you don't have an account, you can create a free account in just a couple of minutes.)

Vedere l'articolo Introduzione alla gestione dei dispositivi per creare l'hub IoT e ottenere la stringa di connessione relativa.Follow the Get started with device management article to create your IoT hub and get your IoT Hub connection string.

Creare un hub IoTCreate an IoT hub

Creare un hub IoT per connettere l'app per dispositivo simulato.Create an IoT hub for your simulated device app to connect to. La procedura seguente illustra come completare questa attività usando il portale di Azure.The following steps show you how to complete this task by using the Azure portal.

  1. Accedere al portale di Azure.Sign in to the Azure portal.
  2. Selezionare Nuovo > Internet delle cose > Hub IoT.Select New > Internet of Things > IoT Hub.

    Indice del portale di Azure

  3. Nel riquadro Hub IoT immettere le informazioni seguenti per l'hub IoT:In the IoT hub pane, enter the following information for your IoT hub:

    • Nome: creare un nome per l'hub IoT.Name: Create a name for your IoT hub. Se il nome immesso è valido, viene visualizzato un segno di spunta verde.If the name you enter is valid, a green check mark appears.

    Importante

    L'hub IoT sarà individuabile pubblicamente come endpoint DNS, quindi evitare di indicare informazioni riservate nell'assegnazione del nome.The IoT hub will be publicly discoverable as a DNS endpoint, so make sure to avoid any sensitive information while naming it.

    • Piano tariffario e livello di scalabilità: per questa esercitazione selezionare il livello F1 gratuito.Pricing and scale tier: For this tutorial, select the F1 - Free tier. Per altre informazioni, vedere la pagina relativa a piano tariffario e livello di scalabilità.For more information, see the Pricing and scale tier.

    • Gruppo di risorse: creare un gruppo di risorse per ospitare l'hub IoT o usarne uno esistente.Resource group: Create a resource group to host the IoT hub or use an existing one. Per altre informazioni, vedere l'articolo su come usare i gruppi di risorse per gestire le risorse di Azure.For more information, see Use resource groups to manage your Azure resources

    • Località: selezionare la località più vicina.Location: Select the closest location to you.

    • Aggiungi al dashboard: selezionare questa opzione per semplificare l'accesso all'hub IoT dal dashboard.Pin to dashboard: Check this option for easy access to your IoT hub from the dashboard.

      Finestra Hub IoT

  4. Fare clic su Crea.Click Create. La creazione dell'hub IoT può richiedere alcuni minuti.Your IoT hub might take a few minutes to create. È possibile monitorare lo stato di avanzamento nel riquadro Notifiche.You can monitor the progress in the Notifications pane.

Ora che è stato creato un hub IoT, individuare le informazioni importanti che consentono di connettere dispositivi e applicazioni all'hub IoT.Now that you have created an IoT hub, locate the important information that you use to connect devices and applications to your IoT hub.

  1. Dopo avere creato l'hub IoT, fare clic sul nuovo riquadro dell'hub IoT nel portale di Azure per aprire la finestra delle proprietà.When the IoT hub has been created successfully, click the new tile for your IoT hub in the Azure portal to open the properties window for the new IoT hub. Annotare il Nome host, quindi fare clic su Criteri di accesso condiviso.Make a note of the Hostname, and then click Shared access policies.

    Finestra del nuovo hub IoT

  2. In Criteri di accesso condivisi fare clic sul criterio iothubowner, quindi copiare e annotare la stringa di connessione dell'hub IoT nella finestra iothubowner.In Shared access policies, click the iothubowner policy, and then copy and make note of the IoT Hub connection string in the iothubowner window. Per altre informazioni, vedere Controllo di accesso nella "Guida per gli sviluppatori dell'hub IoT".For more information, see Access control in the "IoT Hub developer guide."

    Criteri di accesso condivisi

Creare un'identità del dispositivoCreate a device identity

In questa sezione si usa uno strumento di Node.js denominato iothub-explorer per creare un'identità del dispositivo per questa esercitazione.In this section, you use a Node.js tool called iothub-explorer to create a device identity for this tutorial. Gli ID dispositivo fanno distinzione tra maiuscole e minuscole.Device IDs are case sensitive.

  1. Eseguire il codice seguente nell'ambiente della riga di comando:Run the following in your command-line environment:

    npm install -g iothub-explorer@latest

  2. Eseguire quindi il comando indicato di seguito per accedere all'hub.Then, run the following command to login to your hub. Sostituire {iot hub connection string} con la stringa di connessione all'hub IoT copiata prima:Substitute {iot hub connection string} with the IoT Hub connection string you previously copied:

    iothub-explorer login "{iot hub connection string}"

  3. Creare infine una nuova identità del dispositivo denominata myDeviceId con il comando:Finally, create a new device identity called myDeviceId with the command:

    iothub-explorer create myDeviceId --connection-string

    Importante

    L'ID dispositivo può essere visibile nei log raccolti per il supporto tecnico e la risoluzione dei problemi, quindi evitare di indicare informazioni riservate nell'assegnazione del nome.The device ID may be visible in the logs collected for customer support and troubleshooting, so make sure to avoid any sensitive information while naming it.

Annotare la stringa di connessione del dispositivo visualizzata nei risultati.Make a note of the device connection string from the result. Questa stringa di connessione del dispositivo viene usata dall'app del dispositivo per la connessione all'hub IoT come dispositivo.This device connection string is used by the device app to connect to your IoT Hub as a device.

Per creare identità del dispositivo a livello di codice, vedere Introduzione all'hub IoT.Refer to Getting started with IoT Hub to programmatically create device identities.

Attivare un aggiornamento del firmware remoto nel dispositivo con un metodo direttoTrigger a remote firmware update on the device using a direct method

In questa sezione viene creata un'app console .NET (tramite C#) che avvia un aggiornamento del firmware remoto in un dispositivo.In this section, you create a .NET console app (using C#) that initiates a remote firmware update on a device. L'applicazione usa un metodo diretto per avviare l'aggiornamento e usa le query di dispositivo gemello per ottenere periodicamente lo stato di aggiornamento del firmware attivo.The app uses a direct method to initiate the update and uses device twin queries to periodically get the status of the active firmware update.

  1. In Visual Studio aggiungere un progetto desktop di Windows classico in Visual C# usando il modello di progetto Applicazione console .In Visual Studio, add a Visual C# Windows Classic Desktop project to the current solution by using the Console Application project template. Assegnare al progetto il nome TriggerFWUpdate.Name the project TriggerFWUpdate.

    Nuovo progetto desktop di Windows classico in Visual C#

  2. In Esplora soluzioni fare clic con il pulsante destro del mouse sul progetto TriggerFWUpdate e quindi scegliere Gestisci pacchetti NuGet.In Solution Explorer, right-click the TriggerFWUpdate project, and then click Manage NuGet Packages....

  3. Nella finestra Gestione pacchetti NuGet selezionare Esplora, cercare microsoft.azure.devices, selezionare Installa per installare il pacchetto Microsoft.Azure.Devices e accettare le condizioni per l'uso.In the NuGet Package Manager window, select Browse, search for microsoft.azure.devices, select Install to install the Microsoft.Azure.Devices package, and accept the terms of use. Questa procedura scarica, installa e aggiunge un riferimento al pacchetto NuGet Azure IoT - SDK per dispositivi e alle relative dipendenze.This procedure downloads, installs, and adds a reference to the Azure IoT service SDK NuGet package and its dependencies.

    Finestra Gestione pacchetti NuGet

  4. Aggiungere le istruzione using seguenti all'inizio del file Program.cs :Add the following using statements at the top of the Program.cs file:

     using Microsoft.Azure.Devices;
     using Microsoft.Azure.Devices.Shared;
    
  5. Aggiungere i campi seguenti alla classe Program .Add the following fields to the Program class. Sostituire il valore dei segnaposti multipli con la stringa di connessione dell'hub IoT creato nella sezione precedente e l'ID del dispositivo.Replace the multiple placeholder values with the IoT Hub connection string for the hub that you created in the previous section and the Id of your device.

     static RegistryManager registryManager;
     static string connString = "{iot hub connection string}";
     static ServiceClient client;
     static JobClient jobClient;
     static string targetDevice = "{deviceIdForTargetDevice}";
    
  6. Aggiungere il metodo seguente alla classe Program :Add the following method to the Program class:

     public static async Task QueryTwinFWUpdateReported()
     {
         Twin twin = await registryManager.GetTwinAsync(targetDevice);
         Console.WriteLine(twin.Properties.Reported.ToJson());
     }
    
  7. Aggiungere il metodo seguente alla classe Program :Add the following method to the Program class:

     public static async Task StartFirmwareUpdate()
     {
         client = ServiceClient.CreateFromConnectionString(connString);
         CloudToDeviceMethod method = new CloudToDeviceMethod("firmwareUpdate");
         method.ResponseTimeout = TimeSpan.FromSeconds(30);
         method.SetPayloadJson(
             @"{
                 fwPackageUri : 'https://someurl'
             }");
    
         CloudToDeviceMethodResult result = await client.InvokeDeviceMethodAsync(targetDevice, method);
    
         Console.WriteLine("Invoked firmware update on device.");
     }
    
  8. Aggiungere infine le righe seguenti al metodo Main :Finally, add the following lines to the Main method:

     registryManager = RegistryManager.CreateFromConnectionString(connString);
     StartFirmwareUpdate().Wait();
     QueryTwinFWUpdateReported().Wait();
     Console.WriteLine("Press ENTER to exit.");
     Console.ReadLine();
    
  9. In Esplora soluzioni aprire Imposta progetti di avvio e assicurarsi che l'azione per il progetto TriggerFWUpdate sia impostata su Avvio.In the Solution Explorer, open the Set StartUp projects... and make sure the Action for TriggerFWUpdate project is Start.

  10. Compilare la soluzione.Build the solution.

Creare un'app di dispositivo simulatoCreate a simulated device app

In questa sezione verrà illustrato come:In this section, you:

  • Creare un'app console Node.js che risponde a un metodo diretto chiamato dal cloudCreate a Node.js console app that responds to a direct method called by the cloud
  • Attivare un aggiornamento del firmware simulatoTrigger a simulated firmware update
  • Usare le proprietà segnalate per abilitare le query nei dispositivi gemelli in modo da identificare i dispositivi e l'ora dell'ultimo completamento di un aggiornamento del firmwareUse the reported properties to enable device twin queries to identify devices and when they last completed a firmware update
  1. Creare una cartella vuota denominata manageddevice.Create an empty folder called manageddevice. Nella cartella manageddevice creare un file package.json eseguendo questo comando al prompt dei comandi.In the manageddevice folder, create a package.json file using the following command at your command prompt. Accettare tutte le impostazioni predefinite:Accept all the defaults:

    npm init
    
  2. Eseguire questo comando al prompt dei comandi nella cartella manageddevice per installare i pacchetti SDK per dispositivi azure-iot-device e azure-iot-device-mqtt:At your command prompt in the manageddevice folder, run the following command to install the azure-iot-device and azure-iot-device-mqtt Device SDK packages:

    npm install azure-iot-device azure-iot-device-mqtt --save
    
  3. Con un editor di testo creare un file dmpatterns_fwupdate_device.js nella cartella manageddevice.Using a text editor, create a dmpatterns_fwupdate_device.js file in the manageddevice folder.

  4. Aggiungere le istruzioni "require" seguenti all'inizio del file dmpatterns_fwupdate_device.js:Add the following 'require' statements at the start of the dmpatterns_fwupdate_device.js file:

    'use strict';
    
    var Client = require('azure-iot-device').Client;
    var Protocol = require('azure-iot-device-mqtt').Mqtt;
    
  5. Aggiungere una variabile connectionString e usarla per creare un'istanza Client.Add a connectionString variable and use it to create a Client instance. Sostituire il segnaposto {yourdeviceconnectionstring} con la stringa di connessione di cui si è preso nota prima nella sezione "Create a device identity" (Creare un'identità del dispositivo):Replace the {yourdeviceconnectionstring} placeholder with the connection string you previously made a note of in the "Create a device identity" section previously:

    var connectionString = '{yourdeviceconnectionstring}';
    var client = Client.fromConnectionString(connectionString, Protocol);
    
  6. Aggiungere la funzione seguente che viene usata per aggiornare le proprietà segnalate:Add the following function that is used to update reported properties:

    var reportFWUpdateThroughTwin = function(twin, firmwareUpdateValue) {
      var patch = {
          iothubDM : {
            firmwareUpdate : firmwareUpdateValue
          }
      };
    
      twin.properties.reported.update(patch, function(err) {
        if (err) throw err;
        console.log('twin state reported: ' + firmwareUpdateValue.status);
      });
    };
    
  7. Aggiungere le funzioni seguenti che simulano il download e l'applicazione dell'immagine del firmware:Add the following functions that simulate downloading and applying the firmware image:

    var simulateDownloadImage = function(imageUrl, callback) {
      var error = null;
      var image = "[fake image data]";
    
      console.log("Downloading image from " + imageUrl);
    
      callback(error, image);
    }
    
    var simulateApplyImage = function(imageData, callback) {
      var error = null;
    
      if (!imageData) {
        error = {message: 'Apply image failed because of missing image data.'};
      }
    
      callback(error);
    }
    
  8. Aggiungere la funzione seguente che imposta lo stato di aggiornamento del firmware tramite le proprietà segnalate su waiting.Add the following function that updates the firmware update status through the reported properties to waiting. In genere i dispositivi vengono informati che è disponibile un aggiornamento e i criteri definiti dall'amministratore fanno in modo che il dispositivo avvii il download e applichi l'aggiornamento.Typically, devices are informed of an available update and an administrator defined policy causes the device to start downloading and applying the update. In questa funzione viene eseguita la logica per abilitare tali criteri.This function is where the logic to enable that policy should run. Per semplicità, l'esempio attende quattro secondi prima di procedere al download dell'immagine del firmware:For simplicity, the sample waits for four seconds before proceeding to download the firmware image:

    var waitToDownload = function(twin, fwPackageUriVal, callback) {
      var now = new Date();
    
      reportFWUpdateThroughTwin(twin, {
        fwPackageUri: fwPackageUriVal,
        status: 'waiting',
        error : null,
        startedWaitingTime : now.toISOString()
      });
      setTimeout(callback, 4000);
    };
    
  9. Aggiungere la funzione seguente che imposta lo stato di aggiornamento del firmware tramite le proprietà segnalate su downloading.Add the following function that updates the firmware update status through the reported properties to downloading. La funzione simula quindi un download del firmware e infine imposta lo stato di aggiornamento del firmware su downloadFailed o su downloadComplete:The function then simulates a firmware download and finally updates the firmware update status to either downloadFailed or downloadComplete:

    var downloadImage = function(twin, fwPackageUriVal, callback) {
      var now = new Date();   
    
      reportFWUpdateThroughTwin(twin, {
        status: 'downloading',
      });
    
      setTimeout(function() {
        // Simulate download
        simulateDownloadImage(fwPackageUriVal, function(err, image) {
    
          if (err)
          {
            reportFWUpdateThroughTwin(twin, {
              status: 'downloadfailed',
              error: {
                code: error_code,
                message: error_message,
              }
            });
          }
          else {        
            reportFWUpdateThroughTwin(twin, {
              status: 'downloadComplete',
              downloadCompleteTime: now.toISOString(),
            });
    
            setTimeout(function() { callback(image); }, 4000);   
          }
        });
    
      }, 4000);
    }
    
  10. Aggiungere la funzione seguente che imposta lo stato di aggiornamento del firmware tramite le proprietà segnalate su applying.Add the following function that updates the firmware update status through the reported properties to applying. La funzione simula quindi l'applicazione dell'immagine del firmware e infine imposta lo stato di aggiornamento del firmware su applyFailed o su applyComplete:The function then simulates applying the firmware image and finally updates the firmware update status to either applyFailed or applyComplete:

    var applyImage = function(twin, imageData, callback) {
      var now = new Date();   
    
      reportFWUpdateThroughTwin(twin, {
        status: 'applying',
        startedApplyingImage : now.toISOString()
      });
    
      setTimeout(function() {
    
        // Simulate apply firmware image
        simulateApplyImage(imageData, function(err) {
          if (err) {
            reportFWUpdateThroughTwin(twin, {
              status: 'applyFailed',
              error: {
                code: err.error_code,
                message: err.error_message,
              }
            });
          } else { 
            reportFWUpdateThroughTwin(twin, {
              status: 'applyComplete',
              lastFirmwareUpdate: now.toISOString()
            });    
    
          }
        });
    
        setTimeout(callback, 4000);
    
      }, 4000);
    }
    
  11. Aggiungere la funzione seguente che gestisce il metodo diretto firmwareUpdate e avvia il processo di aggiornamento del firmware in più fasi:Add the following function that handles the firmwareUpdate direct method and initiates the multi-stage firmware update process:

    var onFirmwareUpdate = function(request, response) {
    
      // Respond the cloud app for the direct method
      response.send(200, 'FirmwareUpdate started', function(err) {
        if (!err) {
          console.error('An error occured when sending a method response:\n' + err.toString());
        } else {
          console.log('Response to method \'' + request.methodName + '\' sent successfully.');
        }
      });
    
      // Get the parameter from the body of the method request
      var fwPackageUri = request.payload.fwPackageUri;
    
      // Obtain the device twin
      client.getTwin(function(err, twin) {
        if (err) {
          console.error('Could not get device twin.');
        } else {
          console.log('Device twin acquired.');
    
          // Start the multi-stage firmware update
          waitToDownload(twin, fwPackageUri, function() {
            downloadImage(twin, fwPackageUri, function(imageData) {
              applyImage(twin, imageData, function() {});    
            });  
          });
    
        }
      });
    }
    
  12. Aggiungere infine il codice seguente che effettua la connessione all'hub IoT:Finally, add the following code that connects to your IoT hub:

    client.open(function(err) {
      if (err) {
        console.error('Could not connect to IotHub client');
      }  else {
        console.log('Client connected to IoT Hub.  Waiting for firmwareUpdate direct method.');
      }
    
      client.onDeviceMethod('firmwareUpdate', onFirmwareUpdate);
    });
    

Nota

Per semplicità, in questa esercitazione non si implementa alcun criterio di ripetizione dei tentativi.To keep things simple, this tutorial does not implement any retry policy. Nel codice di produzione è consigliabile implementare criteri per i tentativi, ad esempio un backoff esponenziale, come illustrato nell'articolo di MSDN Transient Fault Handling (Gestione degli errori temporanei).In production code, you should implement retry policies (such as an exponential backoff), as suggested in the MSDN article Transient Fault Handling.

Eseguire le appRun the apps

A questo punto è possibile eseguire le app.You are now ready to run the apps.

  1. Al prompt dei comandi nella cartella manageddevice eseguire questo comando per iniziare l'ascolto del metodo diretto di riavvio.At the command prompt in the manageddevice folder, run the following command to begin listening for the reboot direct method.

    node dmpatterns_fwupdate_device.js
    
  2. In Visual Studio fare clic con il pulsante destro del mouse sul progetto TriggerFWUpdate, selezionare Debug e Avvia nuova istanza.In Visual Studio, right-click on the TriggerFWUpdate project, select Debug and Start new instance.

  3. Nella console viene visualizzata la risposta del dispositivo al metodo diretto.You see the device response to the direct method in the console.

    Firmware aggiornato

Passaggi successiviNext steps

In questa esercitazione è stato usato un metodo diretto per attivare un aggiornamento del firmware remoto in un dispositivo e sono state usate le proprietà segnalate per conoscere lo stato del processo di aggiornamento del firmware.In this tutorial, you used a direct method to trigger a remote firmware update on a device and used the reported properties to follow the progress of the firmware update.

Per informazioni su come estendere la soluzione IoT e pianificare le chiamate al metodo su più dispositivi, vedere l'esercitazione Pianificare e trasmettere processi.To learn how to extend your IoT solution and schedule method calls on multiple devices, see the Schedule and broadcast jobs tutorial.