Esercitazione: Connessione un modulo di Plug and Play IoT (C#)

Articolo
02/06/2024

Questa esercitazione illustra come connettere un modulo Plug and Play IoT generico.

Un dispositivo è un dispositivo Plug and Play IoT se:

Pubblica l'ID modello quando si connette a un hub IoT.
Implementa le proprietà e i metodi descritti nel modello DTDL (Digital Twins Definition Language) identificato dall'ID modello.

Per altre informazioni su come vengono usati i modelli DTDL e gli ID modello nei dispositivi, vedere Guida per sviluppatori di Plug and Play IoT. I moduli usano gli ID modello e i modelli DTDL allo stesso modo.

Per illustrare come implementare un modulo Plug and Play IoT, questa esercitazione illustra come:

Aggiungere un dispositivo con un modulo all'hub IoT.
Convertire l'esempio di dispositivo C# termostato in un modulo generico.
Usare l'SDK del servizio per interagire con il modulo.

Prerequisiti

Prima di continuare, assicurarsi di aver configurato l'ambiente, incluso l'hub IoT.

Per completare questa esercitazione, installare il software seguente nell'ambiente di sviluppo locale:

Installare la versione più recente di .NET per il sistema operativo da https://dot.net.
Git.

Usare lo strumento Azure IoT Explorer per aggiungere un nuovo dispositivo denominato my-module-device all'hub IoT.

Aggiungere un modulo denominato my-module a my-module-device:

Nello strumento Azure IoT Explorer passare al dispositivo my-module-device.
Selezionare Identità del modulo, quindi selezionare + Aggiungi.
Immettere my-module come nome dell'identità del modulo e selezionare Salva.
Nell'elenco di identità di moduli selezionare my-module. Quindi copiare la stringa di connessione primaria. Questa stringa di connessione del modulo verrà usata più avanti nell'esercitazione.

Selezionare la scheda Modulo gemello e notare che non sono presenti proprietà desiderate o segnalate:

{
  "deviceId": "my-module-device",
  "moduleId": "my-module",
  "etag": "AAAAAAAAAAE=",
  "deviceEtag": "NjgzMzQ1MzQ1",
  "status": "enabled",
  "statusUpdateTime": "0001-01-01T00:00:00Z",
  "connectionState": "Disconnected",
  "lastActivityTime": "0001-01-01T00:00:00Z",
  "cloudToDeviceMessageCount": 0,
  "authenticationType": "sas",
  "x509Thumbprint": {
    "primaryThumbprint": null,
    "secondaryThumbprint": null
  },
  "modelId": "",
  "version": 2,
  "properties": {
    "desired": {
      "$metadata": {
        "$lastUpdated": "0001-01-01T00:00:00Z"
      },
      "$version": 1
      },
      "reported": {
        "$metadata": {
          "$lastUpdated": "0001-01-01T00:00:00Z"
      },
      "$version": 1
    }
  }
}

Scaricare il codice

Se non è già stato fatto, clonare il repository GitHub Azure IoT Hub SDK per dispositivi in C# nel computer locale:

Aprire un prompt dei comandi in una cartella di propria scelta. Usare il comando seguente per clonare il repository GitHub azure IoT C# SDK in questo percorso:

git clone https://github.com/Azure/azure-iot-sdk-csharp.git

Preparare il progetto

Per aprire e preparare il progetto di esempio:

Passare alla cartella azure-iot-sdk-csharp/iothub/device/samples/solutions/PnpDeviceSamples/Thermostat .
Aggiungere le variabili di ambiente seguenti all'ambiente della shell:

Nome Valore

IOTHUB_DEVICE_SECURITY_TYPE connectionString

IOTHUB_MODULE_CONNECTION_STRING La stringa di connessione del modulo annotata in precedenza

Per altre informazioni sulla configurazione di esempio, vedere il file Leggimi dell'esempio.

Nome	Valore
IOTHUB_DEVICE_SECURITY_TYPE	connectionString
IOTHUB_MODULE_CONNECTION_STRING	La stringa di connessione del modulo annotata in precedenza

Modificare il codice

Per modificare il codice in modo che funzioni come modulo invece che come dispositivo:

Nell'editor di testo o nell'IDE aprire Parameter.cs e modificare la riga che imposta la variabile Primary Connessione ionString come indicato di seguito:
```
public string PrimaryConnectionString { get; set; } = Environment.GetEnvironmentVariable("IOTHUB_MODULE_CONNECTION_STRING");
```
Nell'editor di testo o nell'IDE aprire Program.cs e sostituire le nove istanze della DeviceClient classe con la ModuleClient classe .

Suggerimento

Usare la funzionalità di ricerca e sostituzione di Visual Studio con le opzioni Maiuscole e minuscole e Parola intera abilitate per sostituire DeviceClient con ModuleClient.
Nell'editor di testo o nell'IDE aprire Thermostat.cs e sostituire entrambe le istanze della DeviceClient classe con la ModuleClient classe .
Salvare le modifiche apportate ai file.
Per eseguire l'esempio nell'ambiente della shell, assicurarsi di essere nella cartella azure-iot-sdk-csharp/iothub/device/samples/solutions/PnpDeviceSamples/Thermostat e che siano impostate le variabili di ambiente. Eseguire quindi:
```
dotnet build
dotnet run
```

Se si esegue il codice e quindi si usa Azure IoT Explorer per visualizzare il modulo gemello aggiornato, viene visualizzato il dispositivo gemello aggiornato con la proprietà segnalata dall'ID modello e dal modulo:

{
  "deviceId": "my-module-device",
  "moduleId": "my-module",
  "etag": "AAAAAAAAAAE=",
  "deviceEtag": "MTk0ODMyMjI4",
  "status": "enabled",
  "statusUpdateTime": "0001-01-01T00:00:00Z",
  "connectionState": "Connected",
  "lastActivityTime": "2022-11-16T13:56:43.1711257Z",
  "cloudToDeviceMessageCount": 0,
  "authenticationType": "sas",
  "x509Thumbprint": {
    "primaryThumbprint": null,
    "secondaryThumbprint": null
  },
  "modelId": "dtmi:com:example:Thermostat;1",
  "version": 5,
  "properties": {
    "desired": {
      "$metadata": {
        "$lastUpdated": "0001-01-01T00:00:00Z"
      },
      "$version": 1
    },
    "reported": {
      "targetTemperature": {
        "value": 0,
        "ac": 203,
        "av": 0,
        "ad": "Initialized with default value"
      },
      "maxTempSinceLastReboot": 23.4,
      "$metadata": {
        "$lastUpdated": "2022-11-16T14:06:59.4376422Z",
        "targetTemperature": {
          "$lastUpdated": "2022-11-16T13:55:55.6688872Z",
          "value": {
            "$lastUpdated": "2022-11-16T13:55:55.6688872Z"
          },
          "ac": {
            "$lastUpdated": "2022-11-16T13:55:55.6688872Z"
          },
          "av": {
            "$lastUpdated": "2022-11-16T13:55:55.6688872Z"
          },
          "ad": {
            "$lastUpdated": "2022-11-16T13:55:55.6688872Z"
          }
        },
        "maxTempSinceLastReboot": {
          "$lastUpdated": "2022-11-16T14:06:59.4376422Z"
        }
      },
      "$version": 2
    }
  }
}

Interagire con un modulo di dispositivo

Gli SDK di servizio consentono di recuperare l'ID modello dei dispositivi e dei moduli Plug and Play IoT connessi. È possibile usare gli SDK di servizio per impostare proprietà scrivibili e chiamare i comandi:

In un altro ambiente shell passare alla cartella azure-iot-sdk-csharp\iothub\service\samples\solutions\PnpServiceSamples\Thermostat .
Aggiungere le variabili di ambiente seguenti all'ambiente della shell:

Nome Valore

IOTHUB_DEVICE_ID my-module-device

IOTHUB_CONNECTION_STRING Il valore annotato quando è stato completato il passaggio Configurare l'ambiente

Suggerimento

La stringa di connessione dell'hub IoT si può trovare anche nello strumento Azure IoT Explorer.
Nell'editor di testo o nell'IDE aprire il file ThermostatSample.cs e modificare la riga che chiama un comando come indicato di seguito:
```
CloudToDeviceMethodResult result = await _serviceClient.InvokeDeviceMethodAsync(_deviceId, "my-module", commandInvocation);
```
Nel file ThermostatSample.cs modificare la riga che recupera il dispositivo gemello nel modo seguente:
```
Twin twin = await s_registryManager.GetTwinAsync(s_deviceId, "my-module");
```
Salva le modifiche.
Verificare che l'esempio client del modulo sia ancora in esecuzione e quindi eseguire questo esempio di servizio:
```
dotnet build
dotnet run
```

Nome	Valore
IOTHUB_DEVICE_ID	my-module-device
IOTHUB_CONNECTION_STRING	Il valore annotato quando è stato completato il passaggio Configurare l'ambiente

L'output dell'esempio di servizio mostra l'ID modello del dispositivo gemello e la chiamata al comando:

[11/16/2022 14:27:56]dbug: Microsoft.Azure.Devices.Samples.ThermostatSample[0]
  Get the my-module-device device twin.
...
[11/16/2022 14:27:58]dbug: Microsoft.Azure.Devices.Samples.ThermostatSample[0]
  The my-module-device device twin has a model with ID dtmi:com:example:Thermostat;1.
[11/16/2022 14:27:58]dbug: Microsoft.Azure.Devices.Samples.ThermostatSample[0]
  Update the targetTemperature property on the my-module-device device twin to 44.
[11/16/2022 14:27:58]dbug: Microsoft.Azure.Devices.Samples.ThermostatSample[0]
  Get the my-module-device device twin.
...
[11/16/2022 14:27:58]dbug: Microsoft.Azure.Devices.Samples.ThermostatSample[0]
  Invoke the getMaxMinReport command on my-module-device device twin.
[11/16/2022 14:27:59]dbug: Microsoft.Azure.Devices.Samples.ThermostatSample[0]
  Command getMaxMinReport was invoked on device twin my-module-device.
Device returned status: 200.
Report: {"maxTemp":23.4,"minTemp":23.4,"avgTemp":23.39999999999999,"startTime":"2022-11-16T14:26:00.7446533+00:00","endTime":"2022-11-16T14:27:54.3102604+00:00"}

L'output del client del modulo mostra la risposta del gestore del comando:

[11/16/2022 14:27:59]Microsoft.Azure.Devices.Client.Samples.ThermostatSample[0] Command: Received - Generating max, min and avg temperature report since 16/11/2022 14:25:58.
[11/16/2022 14:27:59]Microsoft.Azure.Devices.Client.Samples.ThermostatSample[0] Command: MaxMinReport since 16/11/2022 14:25:58: maxTemp=23.4, minTemp=23.4, avgTemp=23.39999999999999, startTime=16/11/2022 14:26:00, endTime=16/11/2022 14:27:54

Conversione in un modulo IoT Edge

Per convertire questo esempio in modo che funzioni come modulo IoT Edge di Plug and Play IoT, è necessario inserire l'applicazione in un contenitore. Non è necessario apportare altre modifiche al codice. La variabile di ambiente della stringa di connessione viene inserita dal runtime di IoT Edge all'avvio. Per altre informazioni, vedere Usare Visual Studio 2019 per sviluppare ed eseguire il debug di moduli per Azure IoT Edge.

Per informazioni su come distribuire il modulo in contenitori, vedere:

È possibile usare lo strumento Azure IoT Explorer per vedere:

L'ID modello del dispositivo IoT Edge nel modulo gemello.
I dati di telemetria inviati dal dispositivo IoT Edge.
Gli aggiornamenti delle proprietà del modulo gemello IoT Edge che attivano le notifiche di Plug and Play IoT.
Il modulo IoT Edge reagisce ai comandi Plug and Play IoT.

Pulire le risorse

Se si prevede di continuare con altri articoli per sviluppatori di dispositivi, è possibile mantenere e riutilizzare le risorse usate in questo articolo. In caso contrario, è possibile eliminare le risorse create in questo articolo per evitare altri addebiti.

È possibile eliminare l'hub e il dispositivo registrato contemporaneamente eliminando l'intero gruppo di risorse con il comando dell'interfaccia della riga di comando di Azure seguente. Non usare questo comando se queste risorse condividono un gruppo di risorse con altre risorse che si vogliono conservare.

az group delete --name <YourResourceGroupName>

Per eliminare solo l'hub IoT, eseguire questo comando usando l'interfaccia della riga di comando di Azure:

az iot hub delete --name <YourIoTHubName>

Per eliminare solo l'identità del dispositivo registrato con l'hub IoT, eseguire questo comando usando l'interfaccia della riga di comando di Azure:

az iot hub device-identity delete --hub-name <YourIoTHubName> --device-id <YourDeviceID>

È anche possibile rimuovere dal computer di sviluppo i file di esempio clonati.

Passaggi successivi

In questa esercitazione si è appreso come connettere un dispositivo Plug and Play IoT con moduli a un hub IoT. Per altre informazioni sui modelli di dispositivo Plug and Play IoT, vedere:

Guida per sviluppatori alla modellazione di Plug and Play IoT