Lernprogramm: Azure Device Update für IoT Hub mit einem Raspberry Pi-Image

Device Update for Azure IoT Hub unterstützt image-, paket- und skriptbasierte Updates. In diesem Lernprogramm wird ein end-to-end imagebasiertes Geräteupdate für IoT Hub-Update mithilfe eines Yocto-Bilds auf einem Raspberry Pi 3 B+-Board veranschaulicht.

Bildupdates bieten ein hohes Maß an Vertrauen im Endzustand des Geräts und stellen nicht die gleichen Paket- und Abhängigkeitsverwaltungs-Herausforderungen wie paket- oder skriptbasierte Updates dar. Es ist einfacher, die Ergebnisse einer Imageaktualisierung zwischen einer Vorproduktions- und Produktionsumgebung zu replizieren oder einfach ein A/B-Failovermodell zu übernehmen.

In diesem Tutorial:

• Herunterladen und Installieren eines Image-Updates.
• Zuweisen eines Tags zu Ihrem IoT-Gerät.
• Importieren der Bildaktualisierung.
• Bereitstellen des Imageupdates.
• Anzeigen des Bereitstellungsverlaufs des Updates.

Voraussetzungen

• Ein Device Update-Konto und eine Instanz, die mit einem IoT-Hub konfiguriert sind.

• Ein Raspberry Pi 3 IoT-Board, das über Ethernet mit Hardware verbunden ist, die die Bilddateien herunterladen und extrahieren und das Gerät steuern kann.

  Hinweis

  Image-Updates in diesem Tutorial wurden auf der Raspberry Pi B3-Platine überprüft.

Registrieren des Geräts und Abrufen der Verbindungszeichenfolge

Fügen Sie Ihr Gerät zur Geräteregistrierung in Ihrem IoT-Hub hinzu, und rufen Sie die Verbindungszeichenfolge IoT Hub für das Gerät ab.

1. Öffnen Sie im Azure-Portaldie IoT-Hubseite, die Ihrer Device Update-Instanz zugeordnet ist.
2. Wählen Sie im linken Navigationsbereich Geräteverwaltung>Geräte aus.
3. Wählen Sie auf der Seite "Geräte " die Option "Gerät hinzufügen" aus.
4. Geben Sie unter Geräte-ID einen Namen für das Gerät ein. Stellen Sie sicher, dass das Kontrollkästchen Schlüssel automatisch generieren aktiviert wird.
5. Wählen Sie Speichern. Das Gerät wird in der Liste auf der Seite "Geräte" angezeigt.
6. Wählen Sie auf der Seite Geräte das Gerät aus, das Sie registriert haben.
7. On the device page, select the Copy icon next to Connection string (primary key). Speichern Sie diese Geräte-Verbindungszeichenfolge, um sie beim Konfigurieren des Device Update-Agents zu verwenden.

Hinweis

Zu Demonstrationszwecken verwendet dieses Tutorial eine Geräte-Verbindungszeichenfolge, um sich beim IoT-Hub zu authentifizieren und eine Verbindung herzustellen. Für Produktionsszenarien ist es besser, Modulidentität und IoT Identity Service zum Bereitstellen von Geräten zu verwenden. Weitere Informationen finden Sie unter Device Update Agent Provisioning.

Einrichten von Raspberry Pi

Die Datei Tutorial_RaspberryPi3.zip enthält alle erforderlichen Dateien für das Tutorial. Laden Sie die Datei aus dem Abschnitt Assets der neuesten Version auf der Seite GitHub Device Update Releases herunter und entpacken Sie sie.

Im extrahierten Ordner Tutorial_RaspberryPi3 befindet sich das Basis-Image, das Sie auf das Raspberry Pi-Board flashen können: adu-base-image-raspberrypi3.wic. Das Basis-Image verwendet einen Yocto-Build, der auf der Version 3.4.4 basiert. Das Image verfügt über den Geräteupdate-Agent und SWUpdate, der das Dualpartitionsupdate für Geräteupdates aktiviert. Weitere Informationen zu den Yocto-Layern finden Sie unter Ein benutzerdefiniertes Linux-basiertes System mit dem Device Update-Agent und dem Yocto-Projekt erstellen.

Die Updatedateien, die Sie über Geräteupdate importieren, sind:

• SWUpdate file adu-update-image-raspberrypi3-1.2.0.swu
• Benutzerdefiniertes SWUpdate-Skript example-a-b-update.sh
• Manifest EDS-ADUClient.yocto-update.1.2.0.importmanifest.json

Verwenden von bmaptool zum Einspielen der SD-Karte

Wichtig

Die Software Azure Device Update for Azure IoT Hub unterliegt den folgenden Lizenzbedingungen:

• Lizenz für Device Update für IoT Hub
• Lizenz für den Übermittlungsoptimierungs-Client

Lesen Sie die Lizenzbedingungen, bevor Sie den Agent verwenden. Die Installation und Nutzung des Agents stellt eine Zustimmung zu diesen Bedingungen dar. Wenn Sie den Lizenzbedingungen nicht zustimmen, verwenden Sie den Device Update-Agent nicht.

Verwenden Sie ein Betriebssystem-Flashing-Tool, um das Geräteupdate-Basisimage auf der SD-Karte zu installieren, die Sie auf dem Raspberry Pi-Gerät verwenden. Die folgenden Anweisungen werden verwendet bmaptool , um auf die SD-Karte zu flashen. Ersetzen Sie den <device> Platzhalter durch den Gerätenamen und den <path to image> Platzhalter durch den Pfad zur heruntergeladenen Bilddatei.

1. Installieren Sie das bmap-tools Hilfsprogramm, wenn Sie es nicht haben.

   sudo apt-get install bmap-tools
   

2. Suchen Sie den SD-Kartenpfad in /dev. Der Pfad sollte etwa wie /dev/sd* oder /dev/mmcblk*aussehen. Sie können das Hilfsprogramm dmesg verwenden, um den richtigen Pfad zu finden.

3. Heben Sie die Einbindung aller eingebundenen Partitionen vor dem Einspielen auf.

   sudo umount /dev/<device>
   

4. Stellen Sie sicher, dass Sie über Schreibberechtigungen für das Gerät verfügen.

   sudo chmod a+rw /dev/<device>
   

5. Spielen Sie die SD-Karte ein.

   sudo bmaptool copy <path to image> /dev/<device>
   

   Tipp

   Zum schnelleren Einspielen laden Sie die Bitmapdatei und die Imagedatei herunter, und speichern Sie sie in demselben Verzeichnis.

Konfigurieren des Device Update-Agents auf Raspberry Pi

1. Stellen Sie sicher, dass der Raspberry Pi mit dem Netzwerk verbunden ist.

2. Stellen Sie eine Secure Shell (SSH)-Verbindung zum Raspberry Pi her, indem Sie den folgenden Befehl in einem PowerShell-Fenster ausführen:

   ssh raspberrypi3 -l root
   

Erstellen der Geräteaktualisierungskonfigurationsdateien

Die Konfigurationsdateien du-config.json und du-diagnostics-config.json für Device Update müssen sich auf dem Gerät befinden. Führen Sie zum Erstellen der Dateien die folgenden Befehle im Terminal aus, die beim Raspberry Pi angemeldet sind.

1. Führen Sie den folgenden Befehl aus, um die du-config.json Datei zu erstellen oder sie zur Bearbeitung zu öffnen:

   nano /adu/du-config.json
   

2. Der Editor öffnet die du-config.json Datei. Wenn Sie die Datei erstellen, ist sie leer. Kopieren Sie den folgenden Code, und fügen Sie ihn in die Datei ein, und ersetzen Sie die Beispielwerte durch alle erforderlichen Konfigurationen für Ihr Gerät. Ersetzen Sie die Beispielzeichenfolge connectionData durch die Geräteverbindungszeichenfolge, die Sie im Schritt zur Geräteregistrierung kopiert haben.

   {
      "schemaVersion": "1.0",
      "aduShellTrustedUsers": [
         "adu",
         "do"
      ],
      "manufacturer": "contoso",
      "model": "virtual-vacuum-v2",
      "agents": [
         {
         "name": "main",
         "runas": "adu",
         "connectionSource": {
            "connectionType": "string",
            "connectionData": "HostName=<hub_name>.azure-devices.net;DeviceId=<device_id>;SharedAccessKey=<device_key>" 
         },
         "manufacturer": "contoso",
         "model": "virtual-vacuum-v2"
         }
      ]
   }  
   

3. Drücken Sie STRG+X , um den Editor zu beenden, und geben Sie y ein, um Ihre Änderungen zu speichern.

4. Erstellen Sie die Datei du-diagnostics-config.json, indem Sie ähnliche Befehle verwenden. Erstellen und Öffnen der Datei:

   nano /adu/du-diagnostics-config.json
   

5. Kopieren Sie den folgenden du-diagnostics-config.json Code, und fügen Sie ihn in die Datei ein. Die Werte sind die Standardspeicherorte des Geräteupdateprotokolls, und Sie müssen sie nur ändern, wenn sich Ihre Konfiguration von der Standardeinstellung unterscheidet.

   {
      "logComponents":[
         {
            "componentName":"adu",
            "logPath":"/adu/logs/"
         },
         {
            "componentName":"do",
            "logPath":"/var/log/deliveryoptimization-agent/"
         }
      ],
      "maxKilobytesToUploadPerLogPath":50
   }
   

6. Drücken Sie STRG+X , um den Editor zu beenden, und geben Sie y ein, um Ihre Änderungen zu speichern.

7. Verwenden Sie den folgenden Befehl, um die Dateien im Verzeichnis /adu/ anzuzeigen. Beide Konfigurationsdateien sollten angezeigt werden.

   ls -la /adu/
   

8. Verwenden Sie den folgenden Befehl, um den Geräteupdate-Systemdaemon neu zu starten und sicherzustellen, dass Konfigurationen angewendet werden.

   systemctl start deviceupdate-agent
   

9. Überprüfen Sie mit dem folgenden Befehl, ob der Agent live ist:

   systemctl status deviceupdate-agent
   

   Der Status sollte als lebendig und grün angezeigt werden.

Herstellen einer Verbindung mit dem Gerät im IoT Hub und Hinzufügen eines Gruppentags

1. Wählen Sie auf der Azure-Portal-Seite des IoT-Hubs für Ihre Device Update-Instanz im linken Navigationsbereich Geräteverwaltung>Geräte aus.

2. Wählen Sie auf der Seite Geräte den Namen Ihres Geräts aus.

3. Wählen Sie oben auf der Geräteseite Gerätezwilling aus.

4. Suchen Sie auf der Seite Gerätezwilling im "reported"-Abschnitt des Gerätezwilling-"properties"-Bereichs nach der Linux-Kernel-Version Ihres Geräts.

   Für ein neues Gerät, das noch kein Update von Device Update erhalten hat, stellt der Eigenschaftswert DeviceManagement:DeviceInformation:1.swVersion die Firmware-Version dar, die auf dem Gerät ausgeführt wird. Nachdem das Gerät ein Update angewendet hat, stellt der Wert der AzureDeviceUpdateCore:ClientMetadata:4.installedUpdateId-Eigenschaft die Firmwareversion dar.

   Die Dateinamen des Basis- und Aktualisierungs-Images haben das Format adu-<Image-Typ>-Image-<Maschine>-<Versionsnummer>.<Erweiterung>. Beachten Sie die Versionsnummern, die beim Importieren des Updates verwendet werden sollen.

Hinzufügen eines Gruppentags

Device Update organisiert Geräte automatisch in Gruppen basierend auf ihren zugewiesenen Tags und Kompatibilitätseigenschaften. Jedes Gerät kann zu nur einer Gruppe gehören, aber Gruppen können mehrere Untergruppen zum Sortieren von unterschiedlichen Geräteklassen haben. Weitere Informationen zu Tags und Gruppen finden Sie unter Verwalten von Gerätegruppen.

1. Löschen Sie im Gerätezwilling alle vorhandenen Geräteupdate-Tagwerte, indem Sie sie auf NULL festlegen, und fügen Sie dann das folgende neue Geräteupdate-Gruppentag hinzu. Wenn Sie eine Modulidentität mit dem Geräteupdate-Agent verwenden, fügen Sie das Tag im Module Identity Twin anstelle des Gerätezwillings hinzu.

   "tags": {
       "ADUGroup": "<CustomTagValue>"
   },
   

   Der folgende Screenshot zeigt, wo in der Datei das Tag hinzugefügt werden soll.

   

2. Wählen Sie Speichern.

Importieren des Updates

1. Wählen Sie auf der Azure-Portal-Seite des IoT-Hubs für Ihre Device Update-Instanz im linken Navigationsbereich Geräteverwaltung>Updates aus.

2. Wählen Sie auf der Seite „Updates“ die Option „Neues Update importieren“aus.

3. Wählen Sie auf der Seite Update importieren Aus dem Speichercontainer auswählen aus.

4. Wählen Sie auf der Seite Speicherkonten ein vorhandenes Speicherkonto aus oder erstellen Sie ein neues Konto, indem Sie Speicherkonto auswählen.

5. Wählen Sie auf der Seite Container einen vorhandenen Container aus oder erstellen Sie einen neuen Container, indem Sie Container auswählen. Sie verwenden den Container, um die Updatedateien für den Import zu stufen.

   

   Tipp

   Um versehentlichen Import von Dateien aus früheren Updates zu vermeiden, verwenden Sie bei jedem Import eines Updates einen neuen Container. Wenn Sie keinen neuen Container verwenden, müssen Sie alle Dateien aus dem vorhandenen Container löschen.

6. Wählen Sie auf der Container-Seite Hochladen aus. Ziehen Sie die folgenden Update-Dateien aus dem heruntergeladenen Ordner Tutorial_RaspberryPi3 per Drag-and-Drop hinein oder durchsuchen Sie den Ordner und wählen Sie sie aus:

   • adu-update-image-raspberrypi3-1.2.0.swu
   • example-a-b-update.sh
   • EDS-ADUClient.yocto-update.1.2.0.importmanifest.json

7. Wählen Sie die Option Hochladen. Nach dem Hochladen werden die Dateien auf der Containerseite angezeigt.

8. Überprüfen Sie auf der Containerseite die zu importierenden Dateien, und wählen Sie dann Auswählenaus.

   

9. Wählen Sie auf dem Bildschirm Update importieren die Option Update importieren aus.

   

Der Importvorgang beginnt, und der Bildschirm wechselt zur Seite Updates. Nach erfolgreichem Import wird es im Tab Updates angezeigt. Weitere Informationen zum Importvorgang finden Sie unter Importieren eines Updates in Device Update.

Auswählen der Gerätegruppe

Sie können das Gruppentag verwenden, das Sie auf Ihr Gerät angewendet haben, um das Update für die Gerätegruppe bereitzustellen. Wählen Sie oben auf der Seite Updates den Tab Gruppen und Bereitstellungen, um die Liste der Gruppen und Bereitstellungen sowie das Updateüberwachungs-Diagramm anzuzeigen.

Das Updatekonformitätsdiagramm zeigt die Anzahl von Geräten in verschiedenen Konformitätszuständen: Mit neuestem Update, Neue Updates verfügbar und Updates werden ausgeführt. Weitere Informationen finden Sie unter Konformität von Device Update.

Unter Gruppenname sehen Sie eine Liste aller Gerätegruppen für Geräte, die mit diesem IoT-Hub verbunden sind, sowie deren verfügbare Updates. Links zur Bereitstellung der Updates finden Sie unter Status. Alle Geräte, die nicht den Anforderungen der Geräteklasse einer Gruppe entsprechen, erscheinen in einer entsprechenden ungültigen Gruppe. Weitere Informationen zu Tags und Gruppen finden Sie unter Verwalten von Gerätegruppen.

Sie sollten die Gerätegruppe sehen, die das in diesem Tutorial eingerichtete Gerät enthält, zusammen mit den verfügbaren Updates für die Geräte in der Gruppe. Möglicherweise müssen Sie die Seite aktualisieren. Um das beste verfügbare Update für eine Gruppe aus dieser Ansicht bereitzustellen, wählen Sie Bereitstellen neben der Gruppe aus.

Bereitstellen des Updates

1. Wählen Sie auf der Seite Gruppendetails den Tab Aktuelle Bereitstellung aus und klicken Sie anschließend im Abschnitt Verfügbare Updates neben dem gewünschten Update auf Bereitstellen. Das beste verfügbare Update für die Gruppe wird mit einer Best-Hervorhebung gekennzeichnet.

   

2. Planen Sie auf der Seite Bereitstellung erstellen Ihre Bereitstellung so, dass sie sofort oder in der Zukunft startet, und wählen Sie anschließend Erstellen aus.

   

   Tipp

   Das Startdatum und die Uhrzeit sind standardmäßig auf Werte festgelegt, die vom aktuellen Zeitpunkt aus 24 Stunden in der Zukunft liegen. Wenn die Bereitstellung früher beginnen soll, wählen Sie unbedingt ein anderes Datum und eine andere Uhrzeit aus.

3. Unter Bereitstellungsdetails wird der Status in Aktiv geändert. Im Abschnitt Verfügbare Updates wird das ausgewählte Update mit (wird bereitgestellt) gekennzeichnet.

   

4. Auf der Seite Updates können Sie das Compliance-Diagramm anzeigen, um zu sehen, dass das Update jetzt im Gange ist. Nachdem Ihr Gerät erfolgreich aktualisiert wurde, werden ihr Compliancediagramm und die Bereitstellungsdetails aktualisiert, um diesen Status widerzuspiegeln.

   

Updatebereitstellungsverlauf anzeigen

Anzeigen des Bereitstellungsverlaufs:

1. Wählen Sie oben auf der Seite Gruppendetails den Tab Bereitstellungsverlauf aus und klicken Sie auf den Details-Link neben der von Ihnen erstellten Bereitstellung.

   

2. Wählen Sie auf der Seite Bereitstellungsdetails Aktualisieren, um die neuesten Statusdetails anzuzeigen.

   

Bereinigen von Ressourcen

Wenn Sie die in diesem Tutorial erstellten Ressourcen nicht mehr benötigen, können Sie sie löschen.

1. Wechseln Sie im Azure-Portal zur Ressourcengruppe, die die Ressourcen enthält.
2. Wenn Sie alle Ressourcen in der Gruppe löschen möchten, wählen Sie Ressourcengruppe löschen aus.
3. Wenn Sie nur einige der Ressourcen löschen möchten, verwenden Sie die Kontrollkästchen, um die gewünschten Ressourcen auszuwählen, und klicken Sie anschließend auf Löschen.

Nächste Schritte

• Testen von Device Update for IoT Hub mithilfe eines Simulator-Agents
• Geräteupdate für IoT Hub mit einem Paket-Agent

Zugehöriger Inhalt

• Device Update-Kontos und -Instanzen
• Device Update-Zugriffssteuerungsrollen
• Geräteupdate und IoT Plug and Play