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.
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:
- Visual Studio (Community, Professional oder Enterprise): Stellen Sie sicher, dass Sie die Workload Desktopentwicklung mit C++ aktivieren, wenn Sie Visual Studio installieren.
- Git.
- CMake.
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
Ö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.
Navigieren Sie im Projektmappen-Explorer zum Beispiel iothub_client/samples/pnp/pnp_temperature_controller/ , wenn der Vorgang in Visual Studio abgeschlossen ist.
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.
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>" } } ] }
Klicken Sie mit der rechten Maustaste auf die Datei pnp_temperature_controller.c, und wählen Sie die Option Als Startelement festlegen aus.
Fügen Sie zum Nachverfolgen der Codeausführung in Visual Studio der Funktion
main
in der Dateimain
einen Breakpoint hinzu.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:
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
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:
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.
Öffnen Sie den Azure-IoT-Explorer.
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.
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.
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.
Klicken Sie auf die Geräte-ID des Geräts, das Sie zuvor erstellt haben.
Im Menü auf der linken Seite werden die verschiedenen Arten von Informationen angezeigt, die für das Gerät verfügbar sind.
Wählen Sie IoT Plug and Play components (IoT Plug & Play-Komponenten) aus, um die Modellinformationen für Ihr Gerät anzuzeigen.
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.
Wählen Sie die Seite Telemetrie und dann Start aus, um die vom Gerät für diese Komponente gesendeten Telemetriedaten anzuzeigen.
Wählen Sie die Seite Eigenschaften (mit Schreibschutz) aus, um die für diese Komponente gemeldeten schreibgeschützten Eigenschaften anzuzeigen.
Navigieren Sie zur Seite Properties (writable) (Eigenschaften (schreibbar)), um die schreibbaren Eigenschaften anzuzeigen, die Sie für diese Komponente aktualisieren können.
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.
Klicken Sie auf die Schaltfläche Aktualisieren, damit der neue Wert angezeigt wird.
Wählen Sie die Seite Befehle aus, um alle Befehle für diese Komponente anzuzeigen.
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 FunktionPnP_ProcessTwinData
zum Verarbeiten der Daten aufgerufen. FürPnP_ProcessTwinData
wird dasPnP_ProcessTwinData
verwendet, um den JSON-Code zu analysieren und anschließend die einzelnen Eigenschaften durchzugehen. Hierbei wird für jedes ElementPnP_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.
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.
Öffnen Sie den Azure-IoT-Explorer.
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.
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.
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.
Klicken Sie auf die Geräte-ID des Geräts, das Sie zuvor erstellt haben.
Im Menü auf der linken Seite werden die verschiedenen Arten von Informationen angezeigt, die für das Gerät verfügbar sind.
Wählen Sie IoT Plug and Play components (IoT Plug & Play-Komponenten) aus, um die Modellinformationen für Ihr Gerät anzuzeigen.
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.
Wählen Sie die Seite Telemetrie und dann Start aus, um die vom Gerät für diese Komponente gesendeten Telemetriedaten anzuzeigen.
Wählen Sie die Seite Eigenschaften (mit Schreibschutz) aus, um die für diese Komponente gemeldeten schreibgeschützten Eigenschaften anzuzeigen.
Navigieren Sie zur Seite Properties (writable) (Eigenschaften (schreibbar)), um die schreibbaren Eigenschaften anzuzeigen, die Sie für diese Komponente aktualisieren können.
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.
Klicken Sie auf die Schaltfläche Aktualisieren, damit der neue Wert angezeigt wird.
Wählen Sie die Seite Befehle aus, um alle Befehle für diese Komponente anzuzeigen.
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:
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.
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.
Öffnen Sie den Azure-IoT-Explorer.
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.
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.
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.
Klicken Sie auf die Geräte-ID des Geräts, das Sie zuvor erstellt haben.
Im Menü auf der linken Seite werden die verschiedenen Arten von Informationen angezeigt, die für das Gerät verfügbar sind.
Wählen Sie IoT Plug and Play components (IoT Plug & Play-Komponenten) aus, um die Modellinformationen für Ihr Gerät anzuzeigen.
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.
Wählen Sie die Seite Telemetrie und dann Start aus, um die vom Gerät für diese Komponente gesendeten Telemetriedaten anzuzeigen.
Wählen Sie die Seite Eigenschaften (mit Schreibschutz) aus, um die für diese Komponente gemeldeten schreibgeschützten Eigenschaften anzuzeigen.
Navigieren Sie zur Seite Properties (writable) (Eigenschaften (schreibbar)), um die schreibbaren Eigenschaften anzuzeigen, die Sie für diese Komponente aktualisieren können.
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.
Klicken Sie auf die Schaltfläche Aktualisieren, damit der neue Wert angezeigt wird.
Wählen Sie die Seite Befehle aus, um alle Befehle für diese Komponente anzuzeigen.
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:
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.
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.
- 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
undgetMaxMinReport
definiert. - Durch die Funktion
commandHandler
wird definiert, wie das Gerät auf einen Befehl antwortet.
- Durch die DTDL des Geräts werden die Befehle
Sie beginnt mit dem Senden von Telemetriedaten unter Verwendung von
setInterval
undsendTelemetry
.Sie verwendet die Funktion
helperCreateReportedPropertiesPatch
, um die Eigenschaften zu erstellen, und die FunktionupdateComponentReportedProperties
, 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.
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.
Öffnen Sie den Azure-IoT-Explorer.
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.
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.
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.
Klicken Sie auf die Geräte-ID des Geräts, das Sie zuvor erstellt haben.
Im Menü auf der linken Seite werden die verschiedenen Arten von Informationen angezeigt, die für das Gerät verfügbar sind.
Wählen Sie IoT Plug and Play components (IoT Plug & Play-Komponenten) aus, um die Modellinformationen für Ihr Gerät anzuzeigen.
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.
Wählen Sie die Seite Telemetrie und dann Start aus, um die vom Gerät für diese Komponente gesendeten Telemetriedaten anzuzeigen.
Wählen Sie die Seite Eigenschaften (mit Schreibschutz) aus, um die für diese Komponente gemeldeten schreibgeschützten Eigenschaften anzuzeigen.
Navigieren Sie zur Seite Properties (writable) (Eigenschaften (schreibbar)), um die schreibbaren Eigenschaften anzuzeigen, die Sie für diese Komponente aktualisieren können.
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.
Klicken Sie auf die Schaltfläche Aktualisieren, damit der neue Wert angezeigt wird.
Wählen Sie die Seite Befehle aus, um alle Befehle für diese Komponente anzuzeigen.
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.
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:
Er importiert
pnp_helper.py
, um Zugriff auf Hilfsmethoden zu erhalten.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
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.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.Er definiert Befehlshandlerimplementierungen. Diese Handler definieren, wie das Gerät auf eingehende Befehlsanforderungen reagiert.
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.
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.
Er definiert einen Listener für Befehlsanforderungen.
Er definiert einen Listener für die Aktualisierung gewünschter Eigenschaften.
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 Wertmethod_name
, einen Wertuser_command_handler
und einen optionalen Wertcreate_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:
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.
Öffnen Sie den Azure-IoT-Explorer.
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.
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.
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.
Klicken Sie auf die Geräte-ID des Geräts, das Sie zuvor erstellt haben.
Im Menü auf der linken Seite werden die verschiedenen Arten von Informationen angezeigt, die für das Gerät verfügbar sind.
Wählen Sie IoT Plug and Play components (IoT Plug & Play-Komponenten) aus, um die Modellinformationen für Ihr Gerät anzuzeigen.
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.
Wählen Sie die Seite Telemetrie und dann Start aus, um die vom Gerät für diese Komponente gesendeten Telemetriedaten anzuzeigen.
Wählen Sie die Seite Eigenschaften (mit Schreibschutz) aus, um die für diese Komponente gemeldeten schreibgeschützten Eigenschaften anzuzeigen.
Navigieren Sie zur Seite Properties (writable) (Eigenschaften (schreibbar)), um die schreibbaren Eigenschaften anzuzeigen, die Sie für diese Komponente aktualisieren können.
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.
Klicken Sie auf die Schaltfläche Aktualisieren, damit der neue Wert angezeigt wird.
Wählen Sie die Seite Befehle aus, um alle Befehle für diese Komponente anzuzeigen.
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: