Verbinden Ihres Geräts mit der vorkonfigurierten Remoteüberwachungslösung (Windows)
Übersicht über das Szenario
In diesem Szenario erstellen Sie ein Gerät, das die folgenden Telemetriedaten an die vorkonfigurierte Lösung für die Remoteüberwachung sendet:
- Externe Temperatur
- Interne Temperatur
- Luftfeuchtigkeit
Zur Vereinfachung erzeugt der Code auf dem Gerät Beispielwerte. Sie sollten das Beispiel jedoch erweitern, indem Sie echte Sensoren an Ihr Gerät anschließen und tatsächliche Telemetriedaten senden.
Das Gerät kann auch auf Methoden antworten, die über das Lösungsdashboard aufgerufen werden, und auf die gewünschten Eigenschaftswerte, die im Lösungsdashboard festgelegt werden.
Um dieses Tutorial abzuschließen, benötigen Sie ein aktives Azure-Konto. Wenn Sie über kein Konto verfügen, können Sie in nur wenigen Minuten ein kostenloses Testkonto erstellen. Ausführliche Informationen finden Sie unter Einen Monat kostenlos testen.
Vorbereitung
Bevor Sie Code für Ihr Gerät schreiben, müssen Sie Ihre vorkonfigurierte Lösung für die Remoteüberwachung und ein neues benutzerdefiniertes Gerät in dieser Lösung bereitstellen.
Bereitstellen der vorkonfigurierten Lösung für die Remoteüberwachung
Das von Ihnen in diesem Tutorial erstellte Gerät sendet Daten an eine Instanz der vorkonfigurierten Lösung für die Remoteüberwachung. Führen Sie die folgenden Schritte aus, wenn Sie die vorkonfigurierte Lösung für die Remoteüberwachung noch nicht in Ihrem Azure-Konto bereitgestellt haben:
- Klicken Sie auf der Seite https://www.azureiotsolutions.com/ auf +, um eine Lösung zu erstellen.
- Klicken Sie im Bereich Remoteüberwachung auf Auswählen, um die Lösung zu erstellen.
- Geben Sie auf der Seite Create Remote monitoring solution (Remoteüberwachungslösung erstellen) einen Lösungsnamen Ihrer Wahl ein, wählen Sie die gewünschte Region für die Bereitstellung aus, und wählen Sie dann das gewünschte Azure-Abonnement aus. Klicken Sie dann auf Lösung erstellen.
- Warten Sie, bis der Bereitstellungsvorgang abgeschlossen ist.
Warnung
Die vorkonfigurierten Lösungen verwenden abrechenbare Azure-Dienste. Achten Sie darauf, die vorkonfigurierte Lösung aus dem Abonnement zu entfernen, wenn Sie fertig sind, um unnötige Gebühren zu vermeiden. Sie können eine vorkonfigurierte Lösung vollständig aus Ihrem Abonnement entfernen, indem Sie die Seite https://www.azureiotsolutions.com/ besuchen.
Wenn der Bereitstellungsprozess für die Remoteüberwachungslösung abgeschlossen ist, klicken Sie auf Starten, um das Lösungsdashboard im Browser zu öffnen.
Bereitstellen des Geräts in der Remoteüberwachungslösung
Hinweis
Wenn Sie bereits ein Gerät in der Lösung bereits bereitgestellt haben, können Sie diesen Schritt überspringen. Für das Erstellen der Clientanwendung müssen Sie die Anmeldeinformationen des Geräts kennen.
Damit ein Gerät eine Verbindung mit der vorkonfigurierten Lösung herstellen kann, muss es sich mit gültigen Anmeldeinformationen bei IoT Hub identifizieren können. Sie können die Anmeldeinformationen für das Gerät aus dem Lösungsdashboard abrufen. Sie fügen die Anmeldeinformationen für das Gerät später in diesem Tutorial zu Ihrer Clientanwendung hinzu.
Um Ihrer Remoteüberwachungslösung ein Gerät hinzuzufügen, führen Sie im Lösungsdashboard die folgenden Schritte aus:
Klicken Sie in der linken unteren Ecke des Dashboards auf Gerät hinzufügen.
Klicken Sie im Bereich Benutzerdefiniertes Gerät auf Neue hinzufügen.
Wählen Sie die Option Ich möchte meine eigene Geräte-ID definieren. Geben Sie eine Geräte-ID wie mydevice ein, und klicken Sie auf ID prüfen, um zu prüfen, ob der Name bereits verwendet wird. Klicken Sie dann auf Erstellen, um das Gerät bereitzustellen.
Notieren Sie sich die Anmeldeinformationen des Geräts (Geräte-ID, IoT Hub-Hostname und Geräteschlüssel). Ihre Clientanwendung benötigt diese Werte, um eine Verbindung mit der Remoteüberwachungslösung herzustellen. Klicken Sie anschließend auf Fertig.
Wählen Sie Ihr Gerät im Lösungsdashboard in der Liste mit den Geräten aus. Klicken Sie anschließend im Bereich Gerätedetails auf Gerät aktivieren. Der Status Ihres Geräts lautet jetzt Wird ausgeführt. Die Remoteüberwachungslösung kann jetzt Telemetriedaten von Ihrem Gerät empfangen und Methoden auf dem Gerät aufrufen.
Erstellen einer C-Beispielprojektmappe unter Windows
Die folgenden Schritte zeigen, wie Sie eine Clientanwendung erstellen, die mit der vorkonfigurierten Lösung für die Remoteüberwachung kommuniziert. Diese Anwendung wird in C geschrieben und erstellt und unter Windows ausgeführt.
Erstellen Sie ein Startprojekt in Visual Studio 2015 oder Visual Studio 2017, und fügen Sie die NuGet-Pakete für den IoT Hub-Geräteclient hinzu.
Erstellen Sie in Visual Studio 2015 eine C-Konsolenanwendung mit Visual C++ in der Win32-Konsolenanwendungsvorlage. Geben Sie dem Projekt den Namen RMDevice.
Stellen Sie auf der Seite Anwendungseinstellungen im Win32-Anwendungsassistenten sicher, dass Konsolenanwendung ausgewählt ist, und deaktivieren Sie die Kontrollkästchen Vorkompilierter Header und Prüfungen für den Security Development Lifecycle (SDL).
Löschen Sie im Projektmappen-Explorerdie Dateien „stdafx.h“, „targetver.h“ und „stdafx.cpp“.
Benennen Sie im Projektmappen-Explorerdie Datei „RMDevice.cpp“ in „RMDevice.c“ um.
Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt RMDevice, und klicken Sie dann auf NuGet-Pakete verwalten. Klicken Sie auf Durchsuchen, suchen Sie dann die folgenden NuGet-Pakete, und installieren Sie sie:
- Microsoft.Azure.IoTHub.Serializer
- Microsoft.Azure.IoTHub.IoTHubClient
- Microsoft.Azure.IoTHub.MqttTransport
Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt RMDevice, und klicken Sie dann auf Eigenschaften, um das Dialogfeld Eigenschaftenseiten des Projekts zu öffnen. Weitere Informationen hierzu finden Sie unter Festlegen von Visual C++-Projekteigenschaften.
Klicken Sie auf den Ordner Linker und dann auf die Eigenschaftenseite Eingabe.
Fügen Sie crypt32.lib zur Eigenschaft Zusätzliche Abhängigkeiten hinzu. Klicken Sie auf OK und dann erneut auf OK, um die Eigenschaftenwerte für das Projekt zu speichern.
Fügen Sie die Parson JSON-Bibliothek dem RMDevice-Projekt hinzu, und fügen Sie die erforderlichen #include
-Anweisungen hinzu:
Klonen Sie in einem geeigneten Ordner auf Ihrem Computer das Parson GitHub-Repository mit dem folgenden Befehl:
git clone https://github.com/kgabis/parson.git
Kopieren Sie die Dateien „parson.h“ und „parson.c“ aus der lokalen Kopie des Parson-Repositorys in Ihren RMDevice-Projektordner.
Klicken Sie in Visual Studio mit der rechten Maustaste auf das Projekt RMDevice. Klicken Sie auf Hinzufügen und dann auf Vorhandenes Element.
Wählen Sie im Dialogfeld Vorhandenes Element hinzufügen die Dateien „parson.h“ und „parson.c“ im RMDevice-Projektordner aus. Klicken Sie dann auf Hinzufügen, um diese zwei Dateien Ihrem Projekt hinzuzufügen.
Öffnen Sie in Visual Studio die Datei „RMDevice.c“. Ersetzen Sie die vorhandenen
#include
-Anweisungen durch folgenden Code:#include "iothubtransportmqtt.h" #include "schemalib.h" #include "iothub_client.h" #include "serializer_devicetwin.h" #include "schemaserializer.h" #include "azure_c_shared_utility/threadapi.h" #include "azure_c_shared_utility/platform.h" #include "parson.h"
Hinweis
Jetzt können Sie Ihr Projekt erstellen und dabei überprüfen, ob die richtigen Abhängigkeiten eingerichtet sind.
Angeben des Verhaltens des IoT-Geräts
Die Clientbibliothek des IoT Hub-Serialisierungsprogramms verwendet ein Modell, um das Format der Nachrichten anzugeben, die das Gerät mit IoT Hub austauscht.
Fügen Sie die folgenden Variablendeklarationen nach den
#include
-Anweisungen hinzu. Ersetzen Sie die Platzhalterwerte „[Device ID]“ und „[Device Key]“ durch die Werte, die Sie für Ihr Gerät aus dem Dashboard der Remoteüberwachungslösung notiert haben. Ersetzen Sie „[IoTHub Name]“ durch den IoT Hub-Hostnamen aus dem Lösungsdashboard. Beispiel: Wenn der IoT Hub-Hostname contoso.azure-devices.net lautet, ersetzen Sie [IoTHub Name] durch contoso:static const char* deviceId = "[Device Id]"; static const char* connectionString = "HostName=[IoTHub Name].azure-devices.net;DeviceId=[Device Id];SharedAccessKey=[Device Key]";
Fügen Sie den folgenden Code hinzu, um das Modell zu definieren, das dem Gerät die Kommunikation mit IoT Hub ermöglicht. Dieses Modell gibt Folgendes an:
- Das Gerät kann die Temperatur, die externe Temperatur, die Luftfeuchtigkeit und eine Geräte-ID als Telemetriedaten senden.
- Das Gerät kann Metadaten für das Gerät an IoT Hub senden. Grundlegende Metadaten werden beim Start in einem Objekt vom Typ DeviceInfo gesendet.
- Das Gerät kann gemeldete Eigenschaften an den Gerätezwilling in IoT Hub senden. Diese gemeldeten Eigenschaften werden als Konfigurations-, Geräte- und Systemeigenschaften gruppiert.
- Das Gerät kann gewünschte Eigenschaften, die im Gerätezwilling in IoT Hub festgelegt wurden, empfangen und auf sie reagieren.
- Das Gerät kann auf die direkten Methoden Reboot und InitiateFirmwareUpdate reagieren, die über das Lösungsportal aufgerufen werden. Informationen zu den unterstützten direkten Methoden werden vom Gerät mithilfe gemeldeter Eigenschaften gesendet.
// Define the Model BEGIN_NAMESPACE(Contoso); /* Reported properties */ DECLARE_STRUCT(SystemProperties, ascii_char_ptr, Manufacturer, ascii_char_ptr, FirmwareVersion, ascii_char_ptr, InstalledRAM, ascii_char_ptr, ModelNumber, ascii_char_ptr, Platform, ascii_char_ptr, Processor, ascii_char_ptr, SerialNumber ); DECLARE_STRUCT(LocationProperties, double, Latitude, double, Longitude ); DECLARE_STRUCT(ReportedDeviceProperties, ascii_char_ptr, DeviceState, LocationProperties, Location ); DECLARE_MODEL(ConfigProperties, WITH_REPORTED_PROPERTY(double, TemperatureMeanValue), WITH_REPORTED_PROPERTY(uint8_t, TelemetryInterval) ); /* Part of DeviceInfo */ DECLARE_STRUCT(DeviceProperties, ascii_char_ptr, DeviceID, _Bool, HubEnabledState ); DECLARE_DEVICETWIN_MODEL(Thermostat, /* Telemetry (temperature, external temperature and humidity) */ WITH_DATA(double, Temperature), WITH_DATA(double, ExternalTemperature), WITH_DATA(double, Humidity), WITH_DATA(ascii_char_ptr, DeviceId), /* DeviceInfo */ WITH_DATA(ascii_char_ptr, ObjectType), WITH_DATA(_Bool, IsSimulatedDevice), WITH_DATA(ascii_char_ptr, Version), WITH_DATA(DeviceProperties, DeviceProperties), /* Device twin properties */ WITH_REPORTED_PROPERTY(ReportedDeviceProperties, Device), WITH_REPORTED_PROPERTY(ConfigProperties, Config), WITH_REPORTED_PROPERTY(SystemProperties, System), WITH_DESIRED_PROPERTY(double, TemperatureMeanValue, onDesiredTemperatureMeanValue), WITH_DESIRED_PROPERTY(uint8_t, TelemetryInterval, onDesiredTelemetryInterval), /* Direct methods implemented by the device */ WITH_METHOD(Reboot), WITH_METHOD(InitiateFirmwareUpdate, ascii_char_ptr, FwPackageURI), /* Register direct methods with solution portal */ WITH_REPORTED_PROPERTY(ascii_char_ptr_no_quotes, SupportedMethods) ); END_NAMESPACE(Contoso);
Implementieren des Geräteverhaltens
Fügen Sie nun den Code hinzu, der das im Modell definierte Verhalten implementiert.
Fügen Sie zur Behandlung der gewünschten Eigenschaften, die auf dem Lösungsdashboard festgelegt werden, die folgenden Funktionen hinzu. Diese gewünschten Eigenschaften sind im Modell definiert:
void onDesiredTemperatureMeanValue(void* argument) { /* By convention 'argument' is of the type of the MODEL */ Thermostat* thermostat = argument; printf("Received a new desired_TemperatureMeanValue = %f\r\n", thermostat->TemperatureMeanValue); } void onDesiredTelemetryInterval(void* argument) { /* By convention 'argument' is of the type of the MODEL */ Thermostat* thermostat = argument; printf("Received a new desired_TelemetryInterval = %d\r\n", thermostat->TelemetryInterval); }
Fügen Sie zur Behandlung der direkten Methoden, die über den IoT Hub aufgerufen werden, die folgenden Funktionen hinzu. Diese direkten Methoden sind im Modell definiert:
/* Handlers for direct methods */ METHODRETURN_HANDLE Reboot(Thermostat* thermostat) { (void)(thermostat); METHODRETURN_HANDLE result = MethodReturn_Create(201, "\"Rebooting\""); printf("Received reboot request\r\n"); return result; } METHODRETURN_HANDLE InitiateFirmwareUpdate(Thermostat* thermostat, ascii_char_ptr FwPackageURI) { (void)(thermostat); METHODRETURN_HANDLE result = MethodReturn_Create(201, "\"Initiating Firmware Update\""); printf("Recieved firmware update request. Use package at: %s\r\n", FwPackageURI); return result; }
Fügen Sie die folgende Funktion hinzu, die eine Nachricht an die vorkonfigurierte Lösung sendet:
/* Send data to IoT Hub */ static void sendMessage(IOTHUB_CLIENT_HANDLE iotHubClientHandle, const unsigned char* buffer, size_t size) { IOTHUB_MESSAGE_HANDLE messageHandle = IoTHubMessage_CreateFromByteArray(buffer, size); if (messageHandle == NULL) { printf("unable to create a new IoTHubMessage\r\n"); } else { if (IoTHubClient_SendEventAsync(iotHubClientHandle, messageHandle, NULL, NULL) != IOTHUB_CLIENT_OK) { printf("failed to hand over the message to IoTHubClient"); } else { printf("IoTHubClient accepted the message for delivery\r\n"); } IoTHubMessage_Destroy(messageHandle); } free((void*)buffer); }
Fügen Sie den folgenden Rückrufhandler hinzu, der ausgeführt wird, wenn das Gerät neue gemeldete Eigenschaftswerte an die vorkonfigurierte Lösung gesendet hat:
/* Callback after sending reported properties */ void deviceTwinCallback(int status_code, void* userContextCallback) { (void)(userContextCallback); printf("IoTHub: reported properties delivered with status_code = %u\n", status_code); }
Fügen Sie die folgende Funktion hinzu, um eine Verbindung zwischen Ihrem Gerät und der vorkonfigurierten Lösung in der Cloud herzustellen und Daten auszutauschen. Diese Funktion führt folgende Schritte aus:
- Sie initialisiert die Plattform.
- Sie registriert den Contoso-Namespace mit der Serialisierungsbibliothek.
- Sie initialisiert den Client mit der Geräteverbindungszeichenfolge.
- Sie erstellt eine Instanz des Modells Thermostat.
- Sie erstellt und sendet gemeldete Eigenschaftswerte.
- Sie sendet ein Objekt vom Typ DeviceInfo.
- Sie erstellt eine Schleife, um im Sekundentakt Telemetriedaten zu senden.
- Sie hebt die Initialisierung aller Ressourcen auf.
void remote_monitoring_run(void) { if (platform_init() != 0) { printf("Failed to initialize the platform.\n"); } else { if (SERIALIZER_REGISTER_NAMESPACE(Contoso) == NULL) { printf("Unable to SERIALIZER_REGISTER_NAMESPACE\n"); } else { IOTHUB_CLIENT_HANDLE iotHubClientHandle = IoTHubClient_CreateFromConnectionString(connectionString, MQTT_Protocol); if (iotHubClientHandle == NULL) { printf("Failure in IoTHubClient_CreateFromConnectionString\n"); } else { #ifdef MBED_BUILD_TIMESTAMP // For mbed add the certificate information if (IoTHubClient_SetOption(iotHubClientHandle, "TrustedCerts", certificates) != IOTHUB_CLIENT_OK) { printf("Failed to set option \"TrustedCerts\"\n"); } #endif // MBED_BUILD_TIMESTAMP Thermostat* thermostat = IoTHubDeviceTwin_CreateThermostat(iotHubClientHandle); if (thermostat == NULL) { printf("Failure in IoTHubDeviceTwin_CreateThermostat\n"); } else { /* Set values for reported properties */ thermostat->Config.TemperatureMeanValue = 55.5; thermostat->Config.TelemetryInterval = 3; thermostat->Device.DeviceState = "normal"; thermostat->Device.Location.Latitude = 47.642877; thermostat->Device.Location.Longitude = -122.125497; thermostat->System.Manufacturer = "Contoso Inc."; thermostat->System.FirmwareVersion = "2.22"; thermostat->System.InstalledRAM = "8 MB"; thermostat->System.ModelNumber = "DB-14"; thermostat->System.Platform = "Plat 9.75"; thermostat->System.Processor = "i3-7"; thermostat->System.SerialNumber = "SER21"; /* Specify the signatures of the supported direct methods */ thermostat->SupportedMethods = "{\"Reboot\": \"Reboot the device\", \"InitiateFirmwareUpdate--FwPackageURI-string\": \"Updates device Firmware. Use parameter FwPackageURI to specify the URI of the firmware file\"}"; /* Send reported properties to IoT Hub */ if (IoTHubDeviceTwin_SendReportedStateThermostat(thermostat, deviceTwinCallback, NULL) != IOTHUB_CLIENT_OK) { printf("Failed sending serialized reported state\n"); } else { printf("Send DeviceInfo object to IoT Hub at startup\n"); thermostat->ObjectType = "DeviceInfo"; thermostat->IsSimulatedDevice = 0; thermostat->Version = "1.0"; thermostat->DeviceProperties.HubEnabledState = 1; thermostat->DeviceProperties.DeviceID = (char*)deviceId; unsigned char* buffer; size_t bufferSize; if (SERIALIZE(&buffer, &bufferSize, thermostat->ObjectType, thermostat->Version, thermostat->IsSimulatedDevice, thermostat->DeviceProperties) != CODEFIRST_OK) { (void)printf("Failed serializing DeviceInfo\n"); } else { sendMessage(iotHubClientHandle, buffer, bufferSize); } /* Send telemetry */ thermostat->Temperature = 50; thermostat->ExternalTemperature = 55; thermostat->Humidity = 50; thermostat->DeviceId = (char*)deviceId; while (1) { unsigned char*buffer; size_t bufferSize; (void)printf("Sending sensor value Temperature = %f, Humidity = %f\n", thermostat->Temperature, thermostat->Humidity); if (SERIALIZE(&buffer, &bufferSize, thermostat->DeviceId, thermostat->Temperature, thermostat->Humidity, thermostat->ExternalTemperature) != CODEFIRST_OK) { (void)printf("Failed sending sensor value\r\n"); } else { sendMessage(iotHubClientHandle, buffer, bufferSize); } ThreadAPI_Sleep(1000); } IoTHubDeviceTwin_DestroyThermostat(thermostat); } } IoTHubClient_Destroy(iotHubClientHandle); } serializer_deinit(); } } platform_deinit(); }
Im Anschluss finden Sie ein Beispiel für eine Telemetrienachricht, die an die vorkonfigurierte Lösung gesendet wird:
{"DeviceId":"mydevice01", "Temperature":50, "Humidity":50, "ExternalTemperature":55}
Erstellen und Ausführen des Beispiels
Fügen Sie Code hinzu, um die remote_monitoring_run-Funktion aufzurufen und dann die Geräteanwendung zu erstellen und auszuführen.
Ersetzen Sie die main-Funktion durch folgenden Code, um die remote_monitoring_run-Funktion aufzurufen:
int main() { remote_monitoring_run(); return 0; }
Klicken Sie auf Erstellen und dann auf Projektmappe erstellen, um die Geräteanwendung zu erstellen.
Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt RMDevice, klicken Sie auf Debuggen, und klicken Sie dann auf Neue Instanz starten, um das Beispiel auszuführen. Die Konsole zeigt Meldungen an, während die Anwendung Beispieltelemetriedaten an die vorkonfigurierte Lösung sendet, empfängt die im Lösungsdashboard festgelegten gewünschten Eigenschaftswerte und antwortet auf Methoden, die über das Lösungsdashboard aufgerufen werden.
Anzeigen der Gerätetelemetrie im Dashboard
Das Dashboard in der Remoteüberwachungslösung ermöglicht Ihnen das Anzeigen der Telemetrie, die Ihre Geräte an IoT Hub senden.
Wechseln Sie in Ihrem Browser zum Dashboard der Remoteüberwachungslösung, und klicken Sie im linken Bereich auf Geräte, um zur Geräteliste zu gelangen.
In der Geräteliste wird angezeigt, dass das Gerät den Status Wird ausgeführt hat. Wenn nicht, können Sie im Bereich Gerätedetails auf Gerät aktivieren.
Klicken Sie auf Dashboard, um zu diesem zurückzukehren. Wählen Sie in der Dropdownliste Anzuzeigendes Gerät Ihr Gerät aus, um dessen Telemetrie anzuzeigen. Die Telemetrie der Beispielanwendung ist mit 50 Einheiten für die Innentemperatur, 55 Einheiten für die Außentemperatur und 50 Einheiten für die Luftfeuchtigkeit konfiguriert.
Aufrufen einer Methode auf Ihrem Gerät
Das Dashboard in der Remoteüberwachungslösung ermöglicht es Ihnen, über IoT Hub Methoden auf Ihren Geräten aufzurufen. Beispielsweise können Sie in der Remoteüberwachungslösung eine Methode zum Simulieren des Neustarts eines Gerät aufrufen.
Klicken Sie im Dashboard der Remoteüberwachungslösung im linken Bereich auf Geräte, um zur Geräteliste zu gelangen.
Klicken Sie in der Geräteliste auf die Geräte-ID für Ihr Gerät.
Klicken Sie im Bereich Gerätedetails auf Methoden.
Wählen Sie in der Dropdownliste Methode die Option InitiateFirmwareUpdate, und geben Sie dann unter FWPACKAGEURI eine Pseudo-URL ein. Klicken Sie auf Invoke Method (Methode aufrufen), um die Methode auf dem Gerät aufzurufen.
In der Konsole wird bei der Ausführung Ihres Gerätecodes eine Meldung angezeigt, wenn das Gerät die Methode verarbeitet. Die Ergebnisse der Methode werden dem Verlauf im Lösungsportal hinzugefügt:
Nächste Schritte
Im Artikel Anpassen vorkonfigurierter Lösungen werden einige Möglichkeiten zum Erweitern dieses Beispiels beschrieben. Mögliche Erweiterungen umfassen die Verwendung echter Sensoren und die Implementierung zusätzlicher Befehle.
Weitere Informationen finden Sie unter Berechtigungen für die Website „azureiotsuite.com“.