Freigeben über


Tutorial: Herstellen einer Verbindung zwischen unter Linux oder Windows ausgeführten IoT Plug & Play-Geräteanwendungen mit mehreren Komponenten und IoT Hub

In diesem Tutorial erfahren Sie, wie Sie eine exemplarische IoT Plug & Play-Geräteanwendung mit Komponenten erstellen, mit Ihrem IoT-Hub verbinden und die an den Hub gesendeten Informationen mithilfe des Tools Azure IoT-Explorer anzeigen. Die Beispielanwendung ist in C geschrieben und im Azure IoT-Geräte-SDK für C enthalten. Ein Lösungsentwickler kann das Tool Azure IoT-Explorer verwenden, um mehr über die Funktionen eines IoT Plug & Play-Geräts zu erfahren, ohne Gerätecode anzeigen zu müssen.

Code durchsuchen

In diesem Tutorial führen Sie Folgendes durch:

  • Laden Sie den Beispielcode herunter.
  • Erstellen Sie den Beispielcode.
  • Führen Sie die Beispielgeräteanwendung aus, und überprüfen Sie, ob sie eine Verbindung mit Ihrem IoT-Hub herstellt.
  • Überprüfen Sie den Quellcode.

Voraussetzungen

Vergewissern Sie sich, dass Sie Ihre Umgebung eingerichtet haben (einschließlich Ihres IoT-Hubs), bevor Sie den Vorgang fortsetzen.

Sie können dieses Tutorial unter Linux oder Windows durcharbeiten. Die Shellbefehle in diesem Tutorial entsprechen der Linux-Konvention für die Pfadtrennzeichen /. Wenn Sie den Anleitungen unter Windows folgen, sollten Sie diese Trennzeichen durch \ ersetzen.

Die Voraussetzungen sind je nach Betriebssystem unterschiedlich:

Linux

In diesem Tutorial wird davon ausgegangen, dass Sie Ubuntu Linux nutzen. Die Schritte in diesem Tutorial wurden unter Ubuntu 18.04 getestet.

Installieren Sie die folgende Software in Ihrer lokalen Linux-Umgebung, um dieses Tutorial unter Linux durchzuarbeiten:

Installieren Sie GCC, Git, cmake und alle erforderlichen Abhängigkeiten mit dem Befehl apt-get:

sudo apt-get update
sudo apt-get install -y git cmake build-essential curl libcurl4-openssl-dev libssl-dev uuid-dev

Überprüfen Sie, ob die Version von cmake höher als 2.8.12 und die Version von GCC höher als 4.4.7 ist.

cmake --version
gcc --version

Windows

Installieren Sie die folgende Software in Ihrer lokalen Windows-Umgebung, um dieses Tutorial unter Windows ausführen zu können:

Laden Sie den Code herunter.

Wenn Sie das Tutorial: Verbinden einer unter Linux oder Windows ausgeführten IoT Plug & Play-Beispielgeräteanwendung mit IoT Hub (C) abgeschlossen haben, wurde der Code bereits heruntergeladen.

In diesem Tutorial wird eine Entwicklungsumgebung vorbereitet, die Sie zum Klonen und Erstellen des Azure IoT Hub-Geräte-SDK für C verwenden können.

Öffnen Sie eine Eingabeaufforderung in einem Ordner Ihrer Wahl. Führen Sie den folgenden Befehl zum Klonen des GitHub-Repositorys für das Azure IoT-C-SDK und die zugehörigen Bibliotheken an diesem Speicherort aus:

git clone https://github.com/Azure/azure-iot-sdk-c.git
cd azure-iot-sdk-c
git submodule update --init

Sie sollten damit rechnen, dass die Ausführung dieses Vorgangs mehrere Minuten in Anspruch nimmt.

Erstellen und Ausführen des Codes

Sie können den Code erstellen und ausführen, indem Sie Visual Studio oder cmake in der Befehlszeile verwenden.

Verwenden von Visual Studio

  1. Öffnen Sie den Stammordner des geklonten Repositorys. Nach einigen Sekunden werden über die CMake-Unterstützung in Visual Studio alle Komponenten erstellt, die Sie zum Ausführen und Debuggen des Projekts benötigen.

  2. Navigieren Sie im Projektmappen-Explorer zum Beispiel iothub_client/samples/pnp/pnp_temperature_controller/ , wenn der Vorgang in Visual Studio abgeschlossen ist.

  3. Klicken Sie mit der rechten Maustaste auf die Datei pnp_temperature_controller.c, und wählen Sie die Option Debugkonfiguration hinzufügen aus. Wählen Sie Default (Standard) aus.

  4. In Visual Studio wird die Datei launch.vs.json geöffnet. Bearbeiten Sie diese Datei wie im folgenden Codeausschnitt gezeigt, um die erforderlichen Umgebungsvariablen festzulegen. Sie haben sich nach Abschluss des Vorgangs Einrichten Ihrer Umgebung für die IoT Plug & Play-Schnellstarts und -Tutorials die Bereichs-ID und den Primärschlüssel für die Registrierung notiert:

    {
      "version": "0.2.1",
      "defaults": {},
      "configurations": [
        {
          "type": "default",
          "project": "iothub_client\\samples\\pnp\\pnp_temperature_controller\\pnp_temperature_controller.c",
          "projectTarget": "",
          "name": "pnp_temperature_controller.c",
          "env": {
            "IOTHUB_DEVICE_SECURITY_TYPE": "DPS",
            "IOTHUB_DEVICE_DPS_ID_SCOPE": "<Your ID scope>",
            "IOTHUB_DEVICE_DPS_DEVICE_ID": "my-pnp-device",
            "IOTHUB_DEVICE_DPS_DEVICE_KEY": "<Your enrollment primary key>"
          }
        }
      ]
    }
    
  5. Klicken Sie mit der rechten Maustaste auf die Datei pnp_temperature_controller.c, und wählen Sie die Option Als Startelement festlegen aus.

  6. Fügen Sie zum Nachverfolgen der Codeausführung in Visual Studio der Funktion main in der Datei main einen Breakpoint hinzu.

  7. Sie können das Beispiel jetzt über das Menü Debuggen ausführen und debuggen.

Das Gerät ist jetzt zum Empfangen von Befehlen und Eigenschaftsaktualisierungen bereit und hat damit begonnen, Telemetriedaten an den Hub zu senden. Behalten Sie die Ausführung des Beispiels während der nächsten Schritte bei.

Verwenden von cmake in der Befehlszeile

So erstellen Sie das Beispiel:

  1. Erstellen Sie im Stammordner des geklonten Geräte-SDK den Unterordner cmake, und navigieren Sie zu diesem Ordner:

    cd azure-iot-sdk-c
    mkdir cmake
    cd cmake
    
  2. Führen Sie die folgenden Befehle aus, um die Projektdateien für das SDK und die Beispiele zu generieren und zu erstellen:

    cmake ..
    cmake --build .
    

In Einrichten Ihrer Umgebung haben Sie vier Umgebungsvariablen erstellt, um das Beispiel so zu konfigurieren, dass der Device Provisioning-Dienst (Device Provisioning Service, DPS) zum Herstellen einer Verbindung mit Ihrem IoT-Hub verwendet wird:

  • IOTHUB_DEVICE_SECURITY_TYPE mit dem Wert DPS
  • IOTHUB_DEVICE_DPS_ID_SCOPE mit dem Bereich „DPS-ID“.
  • IOTHUB_DEVICE_DPS_DEVICE_ID mit dem Wert my-pnp-device.
  • IOTHUB_DEVICE_DPS_DEVICE_KEY mit dem Primärschlüssel für die Registrierung.
  • IOTHUB_DEVICE_DPS_ENDPOINT mit dem Wert global.azure-devices-provisioning.net.

Weitere Informationen zur Beispielkonfiguration finden Sie in der Beispiel-Infodatei.

So führen Sie das Beispiel aus:

  1. Navigieren Sie im Ordner cmake zu dem Ordner, der die ausführbare Datei enthält, und führen Sie diese aus:

    # Bash
    cd iothub_client/samples/pnp/pnp_temperature_controller
    ./pnp_temperature_controller
    
    REM Windows
    cd iothub_client\samples\pnp\pnp_temperature_controller\Debug
    pnp_temperature_controller.exe
    

Das Gerät ist jetzt zum Empfangen von Befehlen und Eigenschaftsaktualisierungen bereit und hat damit begonnen, Telemetriedaten an den Hub zu senden. Behalten Sie die Ausführung des Beispiels während der nächsten Schritte bei.

Verwenden von Azure IoT-Explorer zum Überprüfen des Codes

Überprüfen Sie nach dem Start des Geräteclientbeispiels mithilfe von Azure IoT-Explorer, ob das Beispiel funktioniert.

  1. Öffnen Sie den Azure-IoT-Explorer.

  2. Wenn Sie Ihrem IoT-Hub noch keine Verbindung hinzugefügt haben, wählen Sie auf der Seite IoT-Hubs die Option + Verbindung hinzufügen aus. Geben Sie die Verbindungszeichenfolge für den zuvor erstellten IoT-Hub ein, und wählen Sie Speichern aus.

  3. Klicken Sie auf der Seite IoT Plug and Play Settings (IoT Plug & Play-Einstellungen) auf + Hinzufügen > Lokaler Ordner, und wählen Sie den lokalen Ordner models aus, in dem Sie Ihre Modelldateien gespeichert haben.

  4. Klicken Sie auf der Seite IoT-Hubs auf den Namen des Hubs, den Sie verwenden möchten. Eine Liste der Geräte wird angezeigt, die beim IoT-Hub registriert sind.

  5. Klicken Sie auf die Geräte-ID des Geräts, das Sie zuvor erstellt haben.

  6. Im Menü auf der linken Seite werden die verschiedenen Arten von Informationen angezeigt, die für das Gerät verfügbar sind.

  7. Wählen Sie IoT Plug and Play components (IoT Plug & Play-Komponenten) aus, um die Modellinformationen für Ihr Gerät anzuzeigen.

  8. Sie können die verschiedenen Komponenten des Geräts anzeigen. Die Standardkomponente und alle zusätzlichen Komponenten. Wählen Sie eine Komponente aus, mit der Sie arbeiten möchten.

  9. Wählen Sie die Seite Telemetrie und dann Start aus, um die vom Gerät für diese Komponente gesendeten Telemetriedaten anzuzeigen.

  10. Wählen Sie die Seite Eigenschaften (mit Schreibschutz) aus, um die für diese Komponente gemeldeten schreibgeschützten Eigenschaften anzuzeigen.

  11. Navigieren Sie zur Seite Properties (writable) (Eigenschaften (schreibbar)), um die schreibbaren Eigenschaften anzuzeigen, die Sie für diese Komponente aktualisieren können.

  12. Wählen Sie eine Eigenschaft nach ihrem Namen aus, geben Sie einen neuen Wert ein, und wählen Sie Update desired value (Gewünschten Wert aktualisieren) aus.

  13. Klicken Sie auf die Schaltfläche Aktualisieren, damit der neue Wert angezeigt wird.

  14. Wählen Sie die Seite Befehle aus, um alle Befehle für diese Komponente anzuzeigen.

  15. Wählen Sie den zu testenden Befehl aus, und legen Sie ggf. den Parameter fest. Wählen Sie Befehl senden aus, um den Befehl auf dem Gerät aufzurufen. Sie können sehen, dass Ihr Gerät auf den Befehl im Eingabeaufforderungsfenster antwortet, in dem der Beispielcode ausgeführt wird.

Überprüfen des Codes

In diesem Beispiel wird ein IoT Plug & Play-Temperaturregler implementiert. Bei diesem Beispiel wird ein Modell mit mehreren Komponenten implementiert. In der DTDL-Modelldatei (Digital Twins Definition Language) für das Temperaturgerät werden die vom Gerät implementierten Telemetriedaten, Eigenschaften und Befehle definiert.

Hilfsfunktionen für IoT Plug & Play

In diesem Beispiel werden im Code einige Hilfsfunktionen aus dem Ordner /common genutzt:

pnp_device_client_ll enthält die Verbindungsmethode für IoT Plug & Play mit der model-id als Parameter: PnP_CreateDeviceClientLLHandle.

pnp_protocol enthält die Hilfsfunktionen für IoT Plug & Play:

  • PnP_CreateReportedProperty
  • PnP_CreateReportedPropertyWithStatus
  • PnP_ParseCommandName
  • PnP_CreateTelemetryMessageHandle
  • PnP_ProcessTwinData
  • PnP_CopyPayloadToString
  • PnP_CreateDeviceClientLLHandle_ViaDps

Diese Hilfsfunktionen sind so generisch gehalten, dass Sie sie auch in Ihrem eigenen Projekt verwenden können. In diesem Beispiel werden sie in den drei Dateien verwendet, die den einzelnen Komponenten des Modells entsprechen:

  • pnp_deviceinfo_component
  • pnp_temperature_controller
  • pnp_thermostat_component

In der Datei pnp_deviceinfo_component werden in der Funktion SendReportedPropertyForDeviceInformation beispielsweise zwei Hilfsfunktionen genutzt:

if ((jsonToSend = PnP_CreateReportedProperty(componentName, propertyName, propertyValue)) == NULL)
{
    LogError("Unable to build reported property response for propertyName=%s, propertyValue=%s", propertyName, propertyValue);
}
else
{
    const char* jsonToSendStr = STRING_c_str(jsonToSend);
    size_t jsonToSendStrLen = strlen(jsonToSendStr);

    if ((iothubClientResult = IoTHubDeviceClient_LL_SendReportedState(deviceClientLL, (const unsigned char*)jsonToSendStr, jsonToSendStrLen, NULL, NULL)) != IOTHUB_CLIENT_OK)
    {
        LogError("Unable to send reported state for property=%s, error=%d", propertyName, iothubClientResult);
    }
    else
    {
        LogInfo("Sending device information property to IoTHub.  propertyName=%s, propertyValue=%s", propertyName, propertyValue);
    }
}

Dieses Muster gilt für alle Komponenten des Beispiels.

Codeflow

Mit der Funktion main wird die Verbindung initialisiert und die Modell-ID gesendet:

deviceClient = CreateDeviceClientAndAllocateComponents();

Im Code wird PnP_CreateDeviceClientLLHandle genutzt, um eine Verbindung mit dem IoT-Hub herzustellen, modelId als Option festzulegen und die Gerätemethode und Gerätezwilling-Rückrufhandler für direkte Methoden und Gerätezwillingsaktualisierungen festzulegen:

g_pnpDeviceConfiguration.deviceMethodCallback = PnP_TempControlComponent_DeviceMethodCallback;
g_pnpDeviceConfiguration.deviceTwinCallback = PnP_TempControlComponent_DeviceTwinCallback;
g_pnpDeviceConfiguration.modelId = g_temperatureControllerModelId;
...

deviceClient = PnP_CreateDeviceClientLLHandle(&g_pnpDeviceConfiguration);

&g_pnpDeviceConfiguration enthält auch die Verbindungsinformationen. Die Umgebungsvariable IOTHUB_DEVICE_SECURITY_TYPE bestimmt, ob im Beispiel eine Verbindungszeichenfolge oder der Device Provisioning-Dienst zum Herstellen der Verbindung mit dem IoT-Hub genutzt wird.

Wenn vom Gerät eine Modell-ID gesendet wird, wird es zu einem IoT Plug & Play-Gerät.

Nachdem die Rückrufhandler eingerichtet wurden, reagiert das Gerät auf Zwillingsaktualisierungen und Aufrufe direkter Methoden:

  • Für den Gerätezwillingsrückruf wird von PnP_TempControlComponent_DeviceTwinCallback die Funktion PnP_ProcessTwinData zum Verarbeiten der Daten aufgerufen. Für PnP_ProcessTwinData wird das PnP_ProcessTwinData verwendet, um den JSON-Code zu analysieren und anschließend die einzelnen Eigenschaften durchzugehen. Hierbei wird für jedes Element PnP_TempControlComponent_ApplicationPropertyCallback aufgerufen.

  • Beim Befehlsrückruf wird von der Funktion PnP_TempControlComponent_DeviceMethodCallback die Hilfsfunktion verwendet, um die Befehls- und Komponentennamen zu analysieren:

    PnP_ParseCommandName(methodName, &componentName, &componentNameSize, &pnpCommandName);
    

    Mit der Funktion PnP_TempControlComponent_DeviceMethodCallback wird anschließend der Befehl für die Komponente aufgerufen:

    LogInfo("Received PnP command for component=%.*s, command=%s", (int)componentNameSize, componentName, pnpCommandName);
    if (strncmp((const char*)componentName, g_thermostatComponent1Name, g_thermostatComponent1Size) == 0)
    {
        result = PnP_ThermostatComponent_ProcessCommand(g_thermostatHandle1, pnpCommandName, rootValue, response, responseSize);
    }
    else if (strncmp((const char*)componentName, g_thermostatComponent2Name, g_thermostatComponent2Size) == 0)
    {
        result = PnP_ThermostatComponent_ProcessCommand(g_thermostatHandle2, pnpCommandName, rootValue, response, responseSize);
    }
    else
    {
        LogError("PnP component=%.*s is not supported by TemperatureController", (int)componentNameSize, componentName);
        result = PNP_STATUS_NOT_FOUND;
    }
    

Mit der Funktion main werden die schreibgeschützten Eigenschaften initialisiert, die an den IoT-Hub gesendet werden:

PnP_TempControlComponent_ReportSerialNumber_Property(deviceClient);
PnP_DeviceInfoComponent_Report_All_Properties(g_deviceInfoComponentName, deviceClient);
PnP_TempControlComponent_Report_MaxTempSinceLastReboot_Property(g_thermostatHandle1, deviceClient);
PnP_TempControlComponent_Report_MaxTempSinceLastReboot_Property(g_thermostatHandle2, deviceClient);

Die Funktion main wird als Schleife ausgeführt, um die Ereignis- und Telemetriedaten für die einzelnen Komponenten zu aktualisieren:

while (true)
{
    PnP_TempControlComponent_SendWorkingSet(deviceClient);
    PnP_ThermostatComponent_SendTelemetry(g_thermostatHandle1, deviceClient);
    PnP_ThermostatComponent_SendTelemetry(g_thermostatHandle2, deviceClient);
}

Die Funktion PnP_ThermostatComponent_SendTelemetry veranschaulicht, wie Sie die Struktur PNP_THERMOSTAT_COMPONENT verwenden. Im Beispiel wird diese Struktur genutzt, um Informationen zu den zwei Thermostaten im Temperaturregler zu speichern. Im Code wird die Funktion PnP_CreateTelemetryMessageHandle zum Vorbereiten und Senden der Nachricht verwendet:

messageHandle = PnP_CreateTelemetryMessageHandle(pnpThermostatComponent->componentName, temperatureStringBuffer);
...
iothubResult = IoTHubDeviceClient_LL_SendEventAsync(deviceClientLL, messageHandle, NULL, NULL);

Mit der Funktion main werden die unterschiedlichen Komponenten zerstört, und die Verbindung mit dem Hub wird getrennt.

In diesem Tutorial erfahren Sie, wie Sie eine IoT Plug & Play-Beispielgeräteanwendung mit Komponenten erstellen, mit Ihrem IoT-Hub verbinden und die an den Hub gesendeten Informationen mithilfe des Azure IoT-Explorer-Tools anzeigen. Die Beispielanwendung wurde in C# geschrieben und ist im Azure IoT-Geräte-SDK für C# enthalten. Ein Lösungsentwickler kann mithilfe von Azure IoT-Explorer mehr über die Funktionen eines IoT Plug & Play-Geräts erfahren, ohne Gerätecode anzeigen zu müssen.

Code durchsuchen

In diesem Tutorial führen Sie Folgendes durch:

  • Laden Sie den Beispielcode herunter.
  • Erstellen Sie den Beispielcode.
  • Führen Sie die Beispielgeräteanwendung aus, und überprüfen Sie, ob sie eine Verbindung mit Ihrem IoT-Hub herstellt.
  • Überprüfen Sie den Quellcode.

Voraussetzungen

Vergewissern Sie sich, dass Sie Ihre Umgebung eingerichtet haben (einschließlich Ihres IoT-Hubs), bevor Sie den Vorgang fortsetzen.

Sie können dieses Tutorial unter Linux oder Windows durcharbeiten. Die Shellbefehle in diesem Tutorial entsprechen der Linux-Konvention für die Pfadtrennzeichen /. Wenn Sie den Anleitungen unter Windows folgen, sollten Sie diese Trennzeichen durch \ ersetzen.

Klonen des SDK-Repositorys mit dem Beispielcode

Wenn Sie das Tutorial Verbinden einer unter Windows ausgeführten IoT Plug & Play-Beispielgeräteanwendung mit IoT Hub (C#) abgeschlossen haben, wurde das Repository bereits geklont.

Klonen Sie die Beispiele aus dem GitHub-Repository mit den Azure IoT-Beispielen für C#. Öffnen Sie eine Eingabeaufforderung in einem Ordner Ihrer Wahl. Führen Sie den folgenden Befehl zum Klonen des GitHub-Repositorys mit Microsoft Azure IoT SDK für .NET aus:

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

Erstellen des Codes

Jetzt können Sie das Beispiel erstellen und ausführen. Führen Sie die folgenden Befehle zum Erstellen des Beispiels aus:

cd azure-iot-sdk-csharp/iothub/device/samples/solutions/PnpDeviceSamples/TemperatureController
dotnet build

Ausführen des Gerätebeispiels

Führen Sie den folgenden Befehl zum Ausführen des Beispiels aus:

dotnet run

Das Gerät ist jetzt zum Empfangen von Befehlen und Eigenschaftsaktualisierungen bereit und hat damit begonnen, Telemetriedaten an den Hub zu senden. Behalten Sie die Ausführung des Beispiels während der nächsten Schritte bei.

Überprüfen des Codes mithilfe von Azure IoT-Explorer

Überprüfen Sie nach dem Start des Geräteclientbeispiels mithilfe von Azure IoT-Explorer, ob das Beispiel funktioniert.

  1. Öffnen Sie den Azure-IoT-Explorer.

  2. Wenn Sie Ihrem IoT-Hub noch keine Verbindung hinzugefügt haben, wählen Sie auf der Seite IoT-Hubs die Option + Verbindung hinzufügen aus. Geben Sie die Verbindungszeichenfolge für den zuvor erstellten IoT-Hub ein, und wählen Sie Speichern aus.

  3. Klicken Sie auf der Seite IoT Plug and Play Settings (IoT Plug & Play-Einstellungen) auf + Hinzufügen > Lokaler Ordner, und wählen Sie den lokalen Ordner models aus, in dem Sie Ihre Modelldateien gespeichert haben.

  4. Klicken Sie auf der Seite IoT-Hubs auf den Namen des Hubs, den Sie verwenden möchten. Eine Liste der Geräte wird angezeigt, die beim IoT-Hub registriert sind.

  5. Klicken Sie auf die Geräte-ID des Geräts, das Sie zuvor erstellt haben.

  6. Im Menü auf der linken Seite werden die verschiedenen Arten von Informationen angezeigt, die für das Gerät verfügbar sind.

  7. Wählen Sie IoT Plug and Play components (IoT Plug & Play-Komponenten) aus, um die Modellinformationen für Ihr Gerät anzuzeigen.

  8. Sie können die verschiedenen Komponenten des Geräts anzeigen. Die Standardkomponente und alle zusätzlichen Komponenten. Wählen Sie eine Komponente aus, mit der Sie arbeiten möchten.

  9. Wählen Sie die Seite Telemetrie und dann Start aus, um die vom Gerät für diese Komponente gesendeten Telemetriedaten anzuzeigen.

  10. Wählen Sie die Seite Eigenschaften (mit Schreibschutz) aus, um die für diese Komponente gemeldeten schreibgeschützten Eigenschaften anzuzeigen.

  11. Navigieren Sie zur Seite Properties (writable) (Eigenschaften (schreibbar)), um die schreibbaren Eigenschaften anzuzeigen, die Sie für diese Komponente aktualisieren können.

  12. Wählen Sie eine Eigenschaft nach ihrem Namen aus, geben Sie einen neuen Wert ein, und wählen Sie Update desired value (Gewünschten Wert aktualisieren) aus.

  13. Klicken Sie auf die Schaltfläche Aktualisieren, damit der neue Wert angezeigt wird.

  14. Wählen Sie die Seite Befehle aus, um alle Befehle für diese Komponente anzuzeigen.

  15. Wählen Sie den zu testenden Befehl aus, und legen Sie ggf. den Parameter fest. Wählen Sie Befehl senden aus, um den Befehl auf dem Gerät aufzurufen. Sie können sehen, dass Ihr Gerät auf den Befehl im Eingabeaufforderungsfenster antwortet, in dem der Beispielcode ausgeführt wird.

Überprüfen des Codes

In diesem Beispiel wird ein IoT Plug & Play-Temperaturregler implementiert. Das in diesem Beispiel implementierte Modell umfasst mehrere Komponenten. In der DTDL-Modelldatei (Digital Twins Definition Language) für das Temperaturgerät werden die vom Gerät implementierten Telemetriedaten, Eigenschaften und Befehle definiert.

Der Gerätecode stellt mithilfe der Standardmethode CreateFromConnectionString eine Verbindung mit Ihrem IoT-Hub her. Das Gerät sendet die Modell-ID des in der Verbindungsanforderung implementierten DTDL-Modells. Ein Gerät, das eine Modell-ID sendet, ist ein IoT Plug & Play-Gerät:

private static DeviceClient InitializeDeviceClient(string hostname, IAuthenticationMethod authenticationMethod)
{
    var options = new ClientOptions
    {
        ModelId = ModelId,
    };

    var deviceClient = DeviceClient.Create(hostname, authenticationMethod, TransportType.Mqtt, options);
    deviceClient.SetConnectionStatusChangesHandler((status, reason) =>
    {
        s_logger.LogDebug($"Connection status change registered - status={status}, reason={reason}.");
    });

    return deviceClient;
}

Die Modell-ID wird im Code gespeichert, wie im folgenden Codeausschnitt zu sehen:

private const string ModelId = "dtmi:com:example:TemperatureController;1";

Nachdem das Gerät eine Verbindung mit Ihrem IoT-Hub hergestellt hat, registriert der Code die Befehlshandler. Der Befehl reboot wird in der Standardkomponente definiert. Der Befehl getMaxMinReport wird in den beiden Thermostatkomponenten definiert:

await _deviceClient.SetMethodHandlerAsync("reboot", HandleRebootCommandAsync, _deviceClient, cancellationToken);
await _deviceClient.SetMethodHandlerAsync("thermostat1*getMaxMinReport", HandleMaxMinReportCommandAsync, Thermostat1, cancellationToken);
await _deviceClient.SetMethodHandlerAsync("thermostat2*getMaxMinReport", HandleMaxMinReportCommandAsync, Thermostat2, cancellationToken);

Es gibt separate Handler für die Aktualisierung gewünschter Eigenschaften der beiden Thermostatkomponenten:

_desiredPropertyUpdateCallbacks.Add(Thermostat1, TargetTemperatureUpdateCallbackAsync);
_desiredPropertyUpdateCallbacks.Add(Thermostat2, TargetTemperatureUpdateCallbackAsync);

Durch den Beispielcode werden Telemetriedaten von beiden Thermostatkomponenten gesendet:

await SendTemperatureAsync(Thermostat1, cancellationToken);
await SendTemperatureAsync(Thermostat2, cancellationToken);

Von der Methode SendTemperatureTelemetryAsync wird die Klasse PnpHhelper verwendet, um Nachrichten für die jeweilige Komponente zu erstellen:

using Message msg = PnpHelper.CreateIothubMessageUtf8(telemetryName, JsonConvert.SerializeObject(currentTemperature), componentName);

Die Klasse PnpHelper enthält weitere Beispielmethoden, die Sie mit einem Modell mit mehreren Komponenten verwenden können.

Verwenden Sie Azure IoT-Explorer, um die Telemetriedaten und Eigenschaften der beiden Thermostatkomponenten anzuzeigen:

Gerät mit mehreren Komponenten in Azure IoT-Explorer

Mit dem Tool Azure IoT-Explorer können Sie auch Befehle in einer der beiden Thermostatkomponenten oder in der Standardkomponente aufrufen.

In diesem Tutorial erfahren Sie, wie Sie eine IoT Plug & Play-Beispielgeräteanwendung mit Komponenten erstellen, mit Ihrem IoT-Hub verbinden und die an den Hub gesendeten Informationen mithilfe des Tools Azure IoT-Explorer anzeigen. Die Beispielanwendung wurde in Java geschrieben und ist im Azure IoT-Geräte-SDK für Java enthalten. Ein Lösungsentwickler kann mithilfe von Azure IoT-Explorer mehr über die Funktionen eines IoT Plug & Play-Geräts erfahren, ohne Gerätecode anzeigen zu müssen.

Code durchsuchen

In diesem Tutorial führen Sie Folgendes durch:

  • Laden Sie den Beispielcode herunter.
  • Erstellen Sie den Beispielcode.
  • Führen Sie die Beispielgeräteanwendung aus, und überprüfen Sie, ob sie eine Verbindung mit Ihrem IoT-Hub herstellt.
  • Überprüfen Sie den Quellcode.

Voraussetzungen

Vergewissern Sie sich, dass Sie Ihre Umgebung eingerichtet haben (einschließlich Ihres IoT-Hubs), bevor Sie den Vorgang fortsetzen.

Sie können dieses Tutorial unter Linux oder Windows durcharbeiten. Die Shellbefehle in diesem Tutorial entsprechen der Linux-Konvention für die Pfadtrennzeichen /. Wenn Sie den Anleitungen unter Windows folgen, sollten Sie diese Trennzeichen durch \ ersetzen.

Installieren Sie die folgende Software in Ihrer lokalen Entwicklungsumgebung, um dieses Tutorial durcharbeiten zu können:

Laden Sie den Code herunter.

Wenn Sie das Tutorial Verbinden einer IoT Plug & Play-Beispielgeräteanwendung mit IoT Hub (Java) durchgearbeitet haben, wurde das Repository bereits geklont.

Öffnen Sie eine Eingabeaufforderung in einem Verzeichnis Ihrer Wahl. Führen Sie den folgenden Befehl aus, um das GitHub-Repository für Azure IoT-Java-SDKs und die zugehörigen Bibliotheken an diesem Speicherort zu klonen:

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

Dieser Vorgang kann mehrere Minuten dauern.

Erstellen des Codes

Navigieren Sie im geklonten Java SDK-Repository zum Stammordner des Temperaturreglerbeispiels, und erstellen Sie es:

cd azure-iot-sdk-java/device/iot-device-samples/pnp-device-sample/temperature-controller-device-sample
mvn clean package

Ausführen des Gerätebeispiels

In Einrichten Ihrer Umgebung haben Sie vier Umgebungsvariablen erstellt, um das Beispiel so zu konfigurieren, dass der Device Provisioning-Dienst (Device Provisioning Service, DPS) zum Herstellen einer Verbindung mit Ihrem IoT-Hub verwendet wird:

  • IOTHUB_DEVICE_SECURITY_TYPE mit dem Wert DPS
  • IOTHUB_DEVICE_DPS_ID_SCOPE mit dem Bereich „DPS-ID“.
  • IOTHUB_DEVICE_DPS_DEVICE_ID mit dem Wert my-pnp-device.
  • IOTHUB_DEVICE_DPS_DEVICE_KEY mit dem Primärschlüssel für die Registrierung.
  • IOTHUB_DEVICE_DPS_ENDPOINT mit dem Wert global.azure-devices-provisioning.net.

Navigieren Sie zum Ausführen der Beispielanwendung zum Ordner \device\iot-device-samples\pnp-device-sample\temperature-controller-device-sample, und führen Sie den folgenden Befehl aus:

mvn exec:java -Dexec.mainClass="samples.com.microsoft.azure.sdk.iot.device.TemperatureController"

Das Gerät ist jetzt zum Empfangen von Befehlen und Eigenschaftsaktualisierungen bereit und hat damit begonnen, Telemetriedaten an den Hub zu senden. Behalten Sie die Ausführung des Beispiels während der nächsten Schritte bei.

Überprüfen des Codes mithilfe von Azure IoT-Explorer

Überprüfen Sie nach dem Start des Geräteclientbeispiels mithilfe von Azure IoT-Explorer, ob das Beispiel funktioniert.

  1. Öffnen Sie den Azure-IoT-Explorer.

  2. Wenn Sie Ihrem IoT-Hub noch keine Verbindung hinzugefügt haben, wählen Sie auf der Seite IoT-Hubs die Option + Verbindung hinzufügen aus. Geben Sie die Verbindungszeichenfolge für den zuvor erstellten IoT-Hub ein, und wählen Sie Speichern aus.

  3. Klicken Sie auf der Seite IoT Plug and Play Settings (IoT Plug & Play-Einstellungen) auf + Hinzufügen > Lokaler Ordner, und wählen Sie den lokalen Ordner models aus, in dem Sie Ihre Modelldateien gespeichert haben.

  4. Klicken Sie auf der Seite IoT-Hubs auf den Namen des Hubs, den Sie verwenden möchten. Eine Liste der Geräte wird angezeigt, die beim IoT-Hub registriert sind.

  5. Klicken Sie auf die Geräte-ID des Geräts, das Sie zuvor erstellt haben.

  6. Im Menü auf der linken Seite werden die verschiedenen Arten von Informationen angezeigt, die für das Gerät verfügbar sind.

  7. Wählen Sie IoT Plug and Play components (IoT Plug & Play-Komponenten) aus, um die Modellinformationen für Ihr Gerät anzuzeigen.

  8. Sie können die verschiedenen Komponenten des Geräts anzeigen. Die Standardkomponente und alle zusätzlichen Komponenten. Wählen Sie eine Komponente aus, mit der Sie arbeiten möchten.

  9. Wählen Sie die Seite Telemetrie und dann Start aus, um die vom Gerät für diese Komponente gesendeten Telemetriedaten anzuzeigen.

  10. Wählen Sie die Seite Eigenschaften (mit Schreibschutz) aus, um die für diese Komponente gemeldeten schreibgeschützten Eigenschaften anzuzeigen.

  11. Navigieren Sie zur Seite Properties (writable) (Eigenschaften (schreibbar)), um die schreibbaren Eigenschaften anzuzeigen, die Sie für diese Komponente aktualisieren können.

  12. Wählen Sie eine Eigenschaft nach ihrem Namen aus, geben Sie einen neuen Wert ein, und wählen Sie Update desired value (Gewünschten Wert aktualisieren) aus.

  13. Klicken Sie auf die Schaltfläche Aktualisieren, damit der neue Wert angezeigt wird.

  14. Wählen Sie die Seite Befehle aus, um alle Befehle für diese Komponente anzuzeigen.

  15. Wählen Sie den zu testenden Befehl aus, und legen Sie ggf. den Parameter fest. Wählen Sie Befehl senden aus, um den Befehl auf dem Gerät aufzurufen. Sie können sehen, dass Ihr Gerät auf den Befehl im Eingabeaufforderungsfenster antwortet, in dem der Beispielcode ausgeführt wird.

Überprüfen des Codes

In diesem Beispiel wird ein IoT Plug & Play-Temperaturregler implementiert. Das in diesem Beispiel implementierte Modell umfasst mehrere Komponenten. In der DTDL-Modelldatei (Digital Twins Definition Language) für das Temperaturgerät werden die vom Gerät implementierten Telemetriedaten, Eigenschaften und Befehle definiert.

Vom Gerätecode wird die Standardklasse DeviceClient verwendet, um eine Verbindung mit Ihrem IoT-Hub herzustellen. Das Gerät sendet die Modell-ID des in der Verbindungsanforderung implementierten DTDL-Modells. Ein Gerät, das eine Modell-ID sendet, ist ein IoT Plug & Play-Gerät:

private static void initializeDeviceClient() throws URISyntaxException, IOException {
    ClientOptions options = new ClientOptions();
    options.setModelId(MODEL_ID);
    deviceClient = new DeviceClient(deviceConnectionString, protocol, options);

    deviceClient.registerConnectionStatusChangeCallback((status, statusChangeReason, throwable, callbackContext) -> {
        log.debug("Connection status change registered: status={}, reason={}", status, statusChangeReason);

        if (throwable != null) {
            log.debug("The connection status change was caused by the following Throwable: {}", throwable.getMessage());
            throwable.printStackTrace();
        }
    }, deviceClient);

    deviceClient.open();
}

Die Modell-ID wird im Code gespeichert, wie im folgenden Codeausschnitt zu sehen:

private static final String MODEL_ID = "dtmi:com:example:Thermostat;1";

Nachdem das Gerät eine Verbindung mit Ihrem IoT-Hub hergestellt hat, registriert der Code die Befehlshandler.

deviceClient.subscribeToDeviceMethod(new MethodCallback(), null, new MethodIotHubEventCallback(), null);

Es gibt separate Handler für die Aktualisierung gewünschter Eigenschaften der beiden Thermostatkomponenten:

deviceClient.startDeviceTwin(new TwinIotHubEventCallback(), null, new GenericPropertyUpdateCallback(), null);
Map<Property, Pair<TwinPropertyCallBack, Object>> desiredPropertyUpdateCallback = Stream.of(
        new AbstractMap.SimpleEntry<Property, Pair<TwinPropertyCallBack, Object>>(
                new Property(THERMOSTAT_1, null),
                new Pair<>(new TargetTemperatureUpdateCallback(), THERMOSTAT_1)),
        new AbstractMap.SimpleEntry<Property, Pair<TwinPropertyCallBack, Object>>(
                new Property(THERMOSTAT_2, null),
                new Pair<>(new TargetTemperatureUpdateCallback(), THERMOSTAT_2))
).collect(Collectors.toMap(AbstractMap.SimpleEntry::getKey, AbstractMap.SimpleEntry::getValue));

deviceClient.subscribeToTwinDesiredProperties(desiredPropertyUpdateCallback);

Durch den Beispielcode werden Telemetriedaten von beiden Thermostatkomponenten gesendet:

sendTemperatureReading(THERMOSTAT_1);
sendTemperatureReading(THERMOSTAT_2);

Von der Methode sendTemperatureReading wird die Klasse PnpHhelper verwendet, um Nachrichten für die jeweilige Komponente zu erstellen:

Message message = PnpHelper.createIotHubMessageUtf8(telemetryName, currentTemperature, componentName);

Die Klasse PnpHelper enthält weitere Beispielmethoden, die Sie mit einem Modell mit mehreren Komponenten verwenden können.

Verwenden Sie Azure IoT-Explorer, um die Telemetriedaten und Eigenschaften der beiden Thermostatkomponenten anzuzeigen:

Gerät mit mehreren Komponenten in Azure IoT-Explorer

Mit dem Tool Azure IoT-Explorer können Sie auch Befehle in einer der beiden Thermostatkomponenten oder in der Standardkomponente aufrufen.

In diesem Tutorial erfahren Sie, wie Sie eine IoT Plug & Play-Beispielgeräteanwendung mit Komponenten erstellen, mit Ihrem IoT-Hub verbinden und die an den Hub gesendeten Informationen mithilfe des Tools Azure IoT-Explorer anzeigen. Die Beispielanwendung wurde für Node.js geschrieben und ist im Azure IoT Hub-Geräte-SDK für Node.js enthalten. Ein Lösungsentwickler kann mithilfe von Azure IoT-Explorer mehr über die Funktionen eines IoT Plug & Play-Geräts erfahren, ohne Gerätecode anzeigen zu müssen.

Code durchsuchen

In diesem Tutorial führen Sie Folgendes durch:

  • Laden Sie den Beispielcode herunter.
  • Führen Sie die Beispielgeräteanwendung aus, und überprüfen Sie, ob sie eine Verbindung mit Ihrem IoT-Hub herstellt.
  • Überprüfen Sie den Quellcode.

Voraussetzungen

Vergewissern Sie sich, dass Sie Ihre Umgebung eingerichtet haben (einschließlich Ihres IoT-Hubs), bevor Sie den Vorgang fortsetzen.

Für dieses Tutorial muss sich Node.js auf Ihrem Entwicklungscomputer befinden. Sie können die neueste empfohlene Version für mehrere Plattformen von nodejs.org herunterladen.

Mit dem folgenden Befehl können Sie die aktuelle Node.js-Version auf Ihrem Entwicklungscomputer überprüfen:

node --version

Laden Sie den Code herunter.

Wenn Sie das Tutorial Verbinden einer unter Windows ausgeführten IoT Plug & Play-Beispielgeräteanwendung mit IoT Hub (Node) abgeschlossen haben, wurde das Repository bereits geklont.

Öffnen Sie eine Eingabeaufforderung in einem Verzeichnis Ihrer Wahl. Führen Sie den folgenden Befehl aus, um das GitHub-Repository Microsoft Azure IoT SDK for Node.js an diesem Speicherort zu klonen:

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

Installieren der erforderlichen Bibliotheken

Sie verwenden das Geräte-SDK, um den enthaltenen Beispielcode zu erstellen. Durch die von Ihnen erstellte Anwendung wird ein Plug & Play-Gerät mit mehreren Komponenten simuliert, das eine Verbindung mit einem IoT-Hub herstellt. Die Anwendung sendet Telemetriedaten und Eigenschaften und empfängt Befehle.

  1. Wechseln Sie in einem lokalen Terminalfenster zum Ordner Ihres geklonten Repositorys, und navigieren Sie zum Ordner /azure-iot-sdk-node/device/samples/javascript. Führen Sie dann den folgenden Befehl aus, um die erforderlichen Bibliotheken zu installieren:
npm install

Durch diesen Befehl werden die relevanten npm-Dateien installiert, die zum Ausführen der Beispiele im Ordner erforderlich sind.

Überprüfen des Codes

Navigieren Sie zum Ordner azure-iot-sdk-node\device\samples\javascript.

Der Ordner azure-iot-sdk-node\device\samples\javascript enthält den Beispielcode für den IoT Plug & Play-Temperaturregler.

Der Code in der Datei pnp_temperature_controller.js dient zum Implementieren eines IoT Plug & Play-Temperaturreglers. Das in diesem Beispiel implementierte Modell umfasst mehrere Komponenten. In der DTDL-Modelldatei (Digital Twins Definition Language) für das Temperaturgerät werden die vom Gerät implementierten Telemetriedaten, Eigenschaften und Befehle definiert.

Öffnen Sie die Datei pnp_temperature_controller.js in einem Code-Editor Ihrer Wahl. Mithilfe des Beispielcodes wird Folgendes gezeigt:

  • Definieren Sie den DTMI modelId für das Gerät, das Sie gerade implementieren. Dieser DTMI ist benutzerdefiniert und muss dem DTMI im DTDL-Modell des Temperaturreglers entsprechen.

  • Implementieren der im DTDL-Modell des Temperaturreglers definierten Komponenten. Von den Komponenten in einem echten Temperaturregler müssen die beiden folgenden Schnittstellen implementiert werden. Die beiden Schnittstellen sind bereits in einem zentralen Repository veröffentlicht. In diesem Beispiel werden die beiden folgenden Schnittstellen verwendet:

    • Thermostat
    • Von Azure entwickelte Geräteinformationen
  • Definieren von Komponentennamen. Dieses Beispiel umfasst zwei Thermostate und eine Geräteinformationskomponente.

  • Definieren Sie Befehlsnamen für die Befehle, auf die das Gerät reagiert.

  • Definieren der Konstante serialNumber. Die Seriennummer (serialNumber) ist für jedes Gerät fest vorgegeben.

  • Definieren der Befehlshandler

  • Definieren der Funktionen zum Senden von Befehlsantworten

  • Definieren von Hilfsfunktionen zum Protokollieren von Befehlsanforderungen

  • Definieren einer Hilfsfunktion zum Erstellen der Eigenschaften

  • Definieren eines Listeners für Eigenschaftsaktualisierungen

  • Definieren einer Funktion, um Telemetriedaten von diesem Gerät zu senden. Telemetriedaten werden von beiden Thermostaten und der Standardkomponente gesendet. Diese Funktion empfängt den Komponentennamen als Parameter.

  • Definieren einer Funktion vom Typ main, für die Folgendes gilt:

    • Sie verwendet das Geräte-SDK, um einen Geräteclient zu erstellen und eine Verbindung mit Ihrem IoT-Hub herzustellen. Vom Gerät wird die Modell-ID (modelId) bereitgestellt, damit es vom IoT-Hub als IoT Plug & Play-Gerät identifiziert werden kann.

    • Sie beginnt mit dem Lauschen auf Befehlsanforderungen unter Verwendung der Funktion onDeviceMethod. Von der Funktion wird ein Listener eingerichtet, um auf Anforderungen des Diensts zu lauschen:

      • Durch die DTDL des Geräts werden die Befehle reboot und getMaxMinReport definiert.
      • Durch die Funktion commandHandler wird definiert, wie das Gerät auf einen Befehl antwortet.
    • Sie beginnt mit dem Senden von Telemetriedaten unter Verwendung von setInterval und sendTelemetry.

    • Sie verwendet die Funktion helperCreateReportedPropertiesPatch, um die Eigenschaften zu erstellen, und die Funktion updateComponentReportedProperties, um die Eigenschaften zu aktualisieren.

    • Sie verwendet desiredPropertyPatchListener, um auf Eigenschaftsaktualisierungen zu lauschen.

    • Sie deaktiviert alle Listener und Aufgaben und beendet die Schleife, wenn Sie Q oder q drücken.

In Einrichten Ihrer Umgebung haben Sie vier Umgebungsvariablen erstellt, um das Beispiel so zu konfigurieren, dass der Device Provisioning-Dienst (Device Provisioning Service, DPS) zum Herstellen einer Verbindung mit Ihrem IoT-Hub verwendet wird:

  • IOTHUB_DEVICE_SECURITY_TYPE mit dem Wert DPS
  • IOTHUB_DEVICE_DPS_ID_SCOPE mit dem Bereich „DPS-ID“.
  • IOTHUB_DEVICE_DPS_DEVICE_ID mit dem Wert my-pnp-device.
  • IOTHUB_DEVICE_DPS_DEVICE_KEY mit dem Primärschlüssel für die Registrierung.
  • IOTHUB_DEVICE_DPS_ENDPOINT mit dem Wert global.azure-devices-provisioning.net.

Weitere Informationen zur Beispielkonfiguration finden Sie in der Beispiel-Infodatei.

Nachdem Sie nun mit dem Code vertraut sind, verwenden Sie den folgenden Befehl, um das Beispiel auszuführen:

node pnp_temperature_controller.js

Sie sehen die folgende Ausgabe. Das bedeutet, dass das Gerät mit dem Senden von Telemetriedaten an den Hub begonnen hat und jetzt zum Empfangen von Befehlen und Eigenschaftenaktualisierungen bereit ist.

Bestätigungsmeldungen des Geräts

Behalten Sie die Ausführung des Beispiels während der nächsten Schritte bei.

Überprüfen des Codes mithilfe von Azure IoT-Explorer

Überprüfen Sie nach dem Start des Geräteclientbeispiels mithilfe von Azure IoT-Explorer, ob das Beispiel funktioniert.

  1. Öffnen Sie den Azure-IoT-Explorer.

  2. Wenn Sie Ihrem IoT-Hub noch keine Verbindung hinzugefügt haben, wählen Sie auf der Seite IoT-Hubs die Option + Verbindung hinzufügen aus. Geben Sie die Verbindungszeichenfolge für den zuvor erstellten IoT-Hub ein, und wählen Sie Speichern aus.

  3. Klicken Sie auf der Seite IoT Plug and Play Settings (IoT Plug & Play-Einstellungen) auf + Hinzufügen > Lokaler Ordner, und wählen Sie den lokalen Ordner models aus, in dem Sie Ihre Modelldateien gespeichert haben.

  4. Klicken Sie auf der Seite IoT-Hubs auf den Namen des Hubs, den Sie verwenden möchten. Eine Liste der Geräte wird angezeigt, die beim IoT-Hub registriert sind.

  5. Klicken Sie auf die Geräte-ID des Geräts, das Sie zuvor erstellt haben.

  6. Im Menü auf der linken Seite werden die verschiedenen Arten von Informationen angezeigt, die für das Gerät verfügbar sind.

  7. Wählen Sie IoT Plug and Play components (IoT Plug & Play-Komponenten) aus, um die Modellinformationen für Ihr Gerät anzuzeigen.

  8. Sie können die verschiedenen Komponenten des Geräts anzeigen. Die Standardkomponente und alle zusätzlichen Komponenten. Wählen Sie eine Komponente aus, mit der Sie arbeiten möchten.

  9. Wählen Sie die Seite Telemetrie und dann Start aus, um die vom Gerät für diese Komponente gesendeten Telemetriedaten anzuzeigen.

  10. Wählen Sie die Seite Eigenschaften (mit Schreibschutz) aus, um die für diese Komponente gemeldeten schreibgeschützten Eigenschaften anzuzeigen.

  11. Navigieren Sie zur Seite Properties (writable) (Eigenschaften (schreibbar)), um die schreibbaren Eigenschaften anzuzeigen, die Sie für diese Komponente aktualisieren können.

  12. Wählen Sie eine Eigenschaft nach ihrem Namen aus, geben Sie einen neuen Wert ein, und wählen Sie Update desired value (Gewünschten Wert aktualisieren) aus.

  13. Klicken Sie auf die Schaltfläche Aktualisieren, damit der neue Wert angezeigt wird.

  14. Wählen Sie die Seite Befehle aus, um alle Befehle für diese Komponente anzuzeigen.

  15. Wählen Sie den zu testenden Befehl aus, und legen Sie ggf. den Parameter fest. Wählen Sie Befehl senden aus, um den Befehl auf dem Gerät aufzurufen. Sie können sehen, dass Ihr Gerät auf den Befehl im Eingabeaufforderungsfenster antwortet, in dem der Beispielcode ausgeführt wird.

In diesem Tutorial erfahren Sie, wie Sie eine IoT Plug & Play-Beispielgeräteanwendung mit Komponenten erstellen, mit Ihrem IoT-Hub verbinden und die an den Hub gesendeten Informationen mithilfe des Tools Azure IoT-Explorer anzeigen. Die Beispielanwendung wurde in Python geschrieben und ist im Azure IoT-Geräte-SDK für Python enthalten. Ein Lösungsentwickler kann mithilfe von Azure IoT-Explorer mehr über die Funktionen eines IoT Plug & Play-Geräts erfahren, ohne Gerätecode anzeigen zu müssen.

Code durchsuchen

In diesem Tutorial führen Sie Folgendes durch:

  • Laden Sie den Beispielcode herunter.
  • Führen Sie die Beispielgeräteanwendung aus, und überprüfen Sie, ob sie eine Verbindung mit Ihrem IoT-Hub herstellt.
  • Überprüfen Sie den Quellcode.

Voraussetzungen

Vergewissern Sie sich, dass Sie Ihre Umgebung eingerichtet haben (einschließlich Ihres IoT-Hubs), bevor Sie den Vorgang fortsetzen.

Sie können dieses Tutorial unter Linux oder Windows durcharbeiten. Die Shellbefehle in diesem Tutorial entsprechen der Linux-Konvention für die Pfadtrennzeichen /. Wenn Sie den Anleitungen unter Windows folgen, sollten Sie diese Trennzeichen durch \ ersetzen.

Für dieses Tutorial benötigen Sie auf Ihrem Entwicklungscomputer Python. Prüfen Sie das Azure IoT Python SDK auf die aktuellen Python-Versionsanforderungen. Sie können Ihre Python-Version mit dem folgenden Befehl überprüfen:

python --version

Die neueste empfohlene Version kann für mehrere Plattformen von python.org heruntergeladen werden.

Laden Sie den Code herunter.

Das azure-iot-device-Paket wird als PIP veröffentlicht.

Installieren Sie das Paket in Ihrer lokalen Python-Umgebung wie folgt:

pip install azure-iot-device

Wenn Sie das Tutorial Verbinden einer unter Windows ausgeführten IoT Plug & Play-Beispielgeräteanwendung mit IoT Hub (Python) abgeschlossen haben, wurde das Repository bereits geklont.

So klonen Sie das Python SDK IoT-Repository:

git clone --branch v2 https://github.com/Azure/azure-iot-sdk-python

Überprüfen des Codes

In diesem Beispiel wird ein IoT Plug & Play-Temperaturregler implementiert. Das in diesem Beispiel implementierte Modell umfasst mehrere Komponenten. In der DTDL-Modelldatei (Digital Twins Definition Language) für das Temperaturgerät werden die vom Gerät implementierten Telemetriedaten, Eigenschaften und Befehle definiert.

Der Ordner azure-iot-sdk-python\samples\pnp enthält den Beispielcode für das IoT Plug & Play-Gerät. Das Beispiel mit dem Temperaturregler umfasst folgende Dateien:

  • temp_controller_with_thermostats.py
  • pnp_helper.py

Der Temperaturregler hat mehrere Komponenten und eine Standardkomponente, die auf dem DTDL-Modell des Temperaturreglers basiert.

Öffnen Sie die Datei temp_controller_with_thermostats.py in einem Editor Ihrer Wahl. Der Code in dieser Datei bewirkt Folgendes:

  1. Er importiert pnp_helper.py, um Zugriff auf Hilfsmethoden zu erhalten.

  2. Er definiert zwei Modellbezeichner für digitale Zwillinge (Digital Twin Model Identifiers, DTMIs), um zwei Schnittstellen, die im DTDL-Modell definiert sind, eindeutig darzustellen. Von den Komponenten in einem echten Temperaturregler müssen die beiden folgenden Schnittstellen implementiert werden. Die beiden Schnittstellen sind bereits in einem zentralen Repository veröffentlicht. Die DTMIs müssen dem Benutzer bekannt sein und unterscheiden sich je nach Geräteimplementierungsszenario. Im vorliegenden Beispiel stellen die beiden Schnittstellen Folgendes dar:

    • Einen Thermostat
    • Von Azure entwickelte Geräteinformationen
  3. Er definiert die DTMI-Modell-ID (model_id) für das zu implementierende Gerät. Der DTMI ist benutzerdefiniert und muss dem DTMI in der DTDL-Modelldatei entsprechen.

  4. Er definiert die Namen, die für die Komponenten in der DTDL-Datei vergeben wurden. Die DTDL enthält zwei Thermostate und eine Geräteinformationskomponente. In der Standardkomponente wird außerdem die Konstante serial_number definiert. Die Seriennummer (serial_number) eines Geräts ist unveränderlich.

  5. Er definiert Befehlshandlerimplementierungen. Diese Handler definieren, wie das Gerät auf eingehende Befehlsanforderungen reagiert.

  6. Er definiert Funktionen zum Erstellen einer Befehlsantwort. Diese Funktionen definieren, wie das Gerät auf Befehlsanforderungen reagiert. Sie erstellen Befehlsantwortfunktionen, wenn von einem Befehl eine benutzerdefinierte Antwort an den IoT-Hub zurückgesendet werden muss. Wurde für einen Befehl keine Antwortfunktion bereitgestellt, wird eine generische Antwort gesendet. In diesem Beispiel ist nur für den Befehl getMaxMinReport eine benutzerdefinierte Antwort vorhanden.

  7. Er definiert eine Funktion, um Telemetriedaten von diesem Gerät zu senden. Telemetriedaten werden von den beiden Thermostaten und der Standardkomponente gesendet. Diese Funktion enthält einen optionalen Komponentennamenparameter, damit sie die Komponente identifizieren kann, von der die Telemetriedaten gesendet wurden.

  8. Er definiert einen Listener für Befehlsanforderungen.

  9. Er definiert einen Listener für die Aktualisierung gewünschter Eigenschaften.

  10. Er enthält eine Funktion vom Typ main, für die Folgendes gilt:

    • Sie verwendet das Geräte-SDK, um einen Geräteclient zu erstellen und eine Verbindung mit Ihrem IoT-Hub herzustellen. Vom Gerät wird die Modell-ID (model_id) gesendet, damit es vom IoT-Hub als IoT Plug & Play-Gerät identifiziert werden kann.

    • Sie verwendet die Funktion create_reported_properties in der Hilfsdatei, um die Eigenschaften zu erstellen. Übergeben Sie den Komponentennamen und die Eigenschaften als Schlüssel-Wert-Paare an diese Funktion.

    • Sie aktualisiert die lesbaren Eigenschaften für die zugehörigen Komponenten durch Aufrufen von patch_twin_reported_properties.

    • Sie beginnt mit dem Lauschen auf Befehlsanforderungen unter Verwendung der Funktion execute_command_listener. Von der Funktion wird ein Listener eingerichtet, um auf Anforderungen des Diensts zu lauschen. Beim Einrichten des Listeners geben Sie einen Wert method_name, einen Wert user_command_handler und einen optionalen Wert create_user_response_handler als Parameter an.

      • method_name dient zum Definieren der Befehlsanforderung. In diesem Beispiel definiert das Modell die Befehle reboot und getMaxMinReport.
      • Die Funktion user_command_handler definiert, was das Gerät tun soll, wenn es einen Befehl empfängt.
      • Die Funktion create_user_response_handler erstellt eine Antwort, die an Ihren IoT-Hub gesendet wird, wenn ein Befehl erfolgreich ausgeführt wird. Sie können diese Antwort im Portal anzeigen. Ohne Angabe dieser Funktion wird eine generische Antwort an den Dienst gesendet.
    • Sie verwendet execute_property_listener, um auf Eigenschaftsaktualisierungen zu lauschen.

    • Sie beginnt mit dem Senden von Telemetriedaten unter Verwendung von send_telemetry. Im Beispielcode wird eine Schleife verwendet, um drei Funktionen zum Senden von Telemetriedaten aufzurufen. Sie werden jeweils alle acht Sekunden aufgerufen.

    • Sie deaktiviert alle Listener und Aufgaben und beendet die Schleife, wenn Sie Q oder q drücken.

In Einrichten Ihrer Umgebung haben Sie vier Umgebungsvariablen erstellt, um das Beispiel so zu konfigurieren, dass der Device Provisioning-Dienst (Device Provisioning Service, DPS) zum Herstellen einer Verbindung mit Ihrem IoT-Hub verwendet wird:

  • IOTHUB_DEVICE_SECURITY_TYPE mit dem Wert DPS
  • IOTHUB_DEVICE_DPS_ID_SCOPE mit dem Bereich „DPS-ID“.
  • IOTHUB_DEVICE_DPS_DEVICE_ID mit dem Wert my-pnp-device.
  • IOTHUB_DEVICE_DPS_DEVICE_KEY mit dem Primärschlüssel für die Registrierung.
  • IOTHUB_DEVICE_DPS_ENDPOINT mit dem Wert global.azure-devices-provisioning.net.

Weitere Informationen zur Beispielkonfiguration finden Sie in der Beispiel-Infodatei.

Verwenden Sie den folgenden Befehl zum Ausführen des Beispiels:

python temp_controller_with_thermostats.py

Das Beispielgerät sendet im Abstand von wenigen Sekunden Telemetrienachrichten an Ihren IoT-Hub.

Die Ausgabe sieht wie folgt aus und gibt an, dass das Gerät Telemetriedaten an den Hub sendet und nun zum Empfangen von Befehlen und Eigenschaftenaktualisierungen bereit ist:

Bestätigungsmeldungen des Geräts

Behalten Sie die Ausführung des Beispiels während der nächsten Schritte bei.

Überprüfen des Codes mithilfe von Azure IoT-Explorer

Überprüfen Sie nach dem Start des Geräteclientbeispiels mithilfe von Azure IoT-Explorer, ob das Beispiel funktioniert.

  1. Öffnen Sie den Azure-IoT-Explorer.

  2. Wenn Sie Ihrem IoT-Hub noch keine Verbindung hinzugefügt haben, wählen Sie auf der Seite IoT-Hubs die Option + Verbindung hinzufügen aus. Geben Sie die Verbindungszeichenfolge für den zuvor erstellten IoT-Hub ein, und wählen Sie Speichern aus.

  3. Klicken Sie auf der Seite IoT Plug and Play Settings (IoT Plug & Play-Einstellungen) auf + Hinzufügen > Lokaler Ordner, und wählen Sie den lokalen Ordner models aus, in dem Sie Ihre Modelldateien gespeichert haben.

  4. Klicken Sie auf der Seite IoT-Hubs auf den Namen des Hubs, den Sie verwenden möchten. Eine Liste der Geräte wird angezeigt, die beim IoT-Hub registriert sind.

  5. Klicken Sie auf die Geräte-ID des Geräts, das Sie zuvor erstellt haben.

  6. Im Menü auf der linken Seite werden die verschiedenen Arten von Informationen angezeigt, die für das Gerät verfügbar sind.

  7. Wählen Sie IoT Plug and Play components (IoT Plug & Play-Komponenten) aus, um die Modellinformationen für Ihr Gerät anzuzeigen.

  8. Sie können die verschiedenen Komponenten des Geräts anzeigen. Die Standardkomponente und alle zusätzlichen Komponenten. Wählen Sie eine Komponente aus, mit der Sie arbeiten möchten.

  9. Wählen Sie die Seite Telemetrie und dann Start aus, um die vom Gerät für diese Komponente gesendeten Telemetriedaten anzuzeigen.

  10. Wählen Sie die Seite Eigenschaften (mit Schreibschutz) aus, um die für diese Komponente gemeldeten schreibgeschützten Eigenschaften anzuzeigen.

  11. Navigieren Sie zur Seite Properties (writable) (Eigenschaften (schreibbar)), um die schreibbaren Eigenschaften anzuzeigen, die Sie für diese Komponente aktualisieren können.

  12. Wählen Sie eine Eigenschaft nach ihrem Namen aus, geben Sie einen neuen Wert ein, und wählen Sie Update desired value (Gewünschten Wert aktualisieren) aus.

  13. Klicken Sie auf die Schaltfläche Aktualisieren, damit der neue Wert angezeigt wird.

  14. Wählen Sie die Seite Befehle aus, um alle Befehle für diese Komponente anzuzeigen.

  15. Wählen Sie den zu testenden Befehl aus, und legen Sie ggf. den Parameter fest. Wählen Sie Befehl senden aus, um den Befehl auf dem Gerät aufzurufen. Sie können sehen, dass Ihr Gerät auf den Befehl im Eingabeaufforderungsfenster antwortet, in dem der Beispielcode ausgeführt wird.

Bereinigen von Ressourcen

Wenn Sie den Vorgang mit weiteren Artikeln zu Geräteentwicklern fortsetzen möchten, können Sie die in diesem Artikel verwendeten Ressourcen beibehalten und wiederverwenden. Andernfalls können Sie die in diesem Artikel erstellten Ressourcen löschen, um weitere Gebühren zu vermeiden.

Sie können den Hub und das registrierte Gerät gleichzeitig löschen, indem Sie die gesamte Ressourcengruppe mit dem folgenden Azure CLI-Befehl löschen. Verwenden Sie diesen Befehl nicht, wenn für diese Ressourcen eine Ressourcengruppe genutzt wird, in der auch andere Ressourcen enthalten sind, die Sie beibehalten möchten.

az group delete --name <YourResourceGroupName>

Um nur den IoT-Hub zu löschen, führen Sie den folgenden Befehl über die Azure-Befehlszeilenschnittstelle aus:

az iot hub delete --name <YourIoTHubName>

Führen Sie mit der Azure-Befehlszeilenschnittstelle die folgenden Befehle aus, um nur die bei Ihrem IoT-Hub registrierte Geräte-ID zu löschen:

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

Möglicherweise sollten Sie auch die geklonten Beispieldateien von Ihrem Entwicklungscomputer entfernen.

Nächste Schritte

In diesem Tutorial haben Sie gelernt, wie Sie für ein IoT Plug & Play-Gerät mit Komponenten eine Verbindung mit einem IoT-Hub herstellen. Weitere Informationen zu IoT Plug & Play-Gerätemodellen finden Sie hier: