Verwenden der Azure IoT Central-Geräte-Bridge, um andere IoT-Clouds mit IoT Central zu verbinden

Artikel
06/14/2023

Die IoT Central-Gerätebrücke ist eine Open-Source-Lösung, die andere IoT-Clouds wie Sigfox, Particle Device Cloud und The Things Network mit Ihrer IoT Central-Anwendung verbindet. Die Geräte-Bridge leitet Daten von Geräten, die mit anderen IoT-Clouds verbunden sind, an Ihre IoT Central-Anwendung weiter. Von der Geräte-Bridge werden nur Daten an IoT Central weitergeleitet. Es werden jedoch keine Befehle oder Eigenschaftenupdates von IoT Central an die Geräte zurückgesendet.

Mit der Gerätebrücke können Sie die Leistungsfähigkeit von IoT Central mit Geräten kombinieren, z. B.:

Anlagenverfolgungsgeräte, die mit sigfoxs Low-Power Wide Area Network verbunden sind.
Luftqualitätsüberwachungsgeräte in der Partikelgeräte-Cloud.
Bodenfeuchteüberwachungsgeräte im The Things Network.

Sie können IoT Central-Features wie Regeln und Analysen für die Daten verwenden, Workflows in Power Automate und Azure Logic Apps erstellen oder die Daten exportieren.

Von der Geräte-Bridge-Lösung werden mehrere Azure-Ressourcen in Ihrem Azure-Abonnement bereitgestellt, die zusammenarbeiten, um Gerätenachrichten zu transformieren und an IoT Central weiterzuleiten.

Voraussetzungen

Zum Ausführen der Schritte in dieser Anleitung ist Folgendes erforderlich:

Ein aktives Azure-Abonnement. Wenn Sie kein Azure-Abonnement besitzen, können Sie ein kostenloses Konto erstellen, bevor Sie beginnen.
Eine IoT Central-Anwendung, die mit der Vorlage Benutzerdefinierte Anwendung erstellt wurde. Weitere Informationen finden Sie unter Erstellen einer IoT Central-Anwendung und Über Ihre Anwendung.

Überblick

Die IoT Central-Geräte-Bridge ist eine Open-Source-Lösung in GitHub. Sie verwendet eine benutzerdefinierte Azure Resource Manager-Vorlage, um mehrere Ressourcen in Ihrem Azure-Abonnement bereitzustellen. Dazu zählt auch eine Funktions-App in Azure Functions.

Die Funktions-App ist die Kernkomponente der Geräte-Bridge. Sie empfängt HTTP POST-Anforderungen von anderen IoT-Plattformen über einen einfachen Webhook. Das Repository für die Azure IoT Central-Geräte-Bridge enthält Beispiele, die die Verbindungsherstellung mit Sigfox-, Particle- und The Things Network-Clouds veranschaulichen. Diese Lösung kann erweitert werden, um eine Verbindung mit Ihrer benutzerdefinierten IoT-Cloud herzustellen – vorausgesetzt, Ihre Plattform kann HTTP POST-Anforderungen an Ihre Funktions-App senden.

Die Daten werden von der Funktions-App in ein von IoT Central akzeptiertes Format transformiert und unter Verwendung des Gerätebereitstellungsdiensts und der Geräteclient-APIs weitergeleitet:

Screenshot of an Azure Functions definition showing the code.

Wenn Ihre IoT Central-Anwendung die Geräte-ID in der weitergeleiteten Nachricht erkennt, werden die Telemetriedaten des Geräts in IoT Central angezeigt. Wenn Ihre IoT Central-Anwendung die Geräte-ID nicht erkennt, versucht die Funktions-App, ein neues Gerät mit der Geräte-ID zu registrieren. Das neue Gerät wird in Ihrer IoT Central-Anwendung auf der Seite Geräte als nicht zugewiesenes Gerät angezeigt. Auf der Seite Geräte können Sie das neue Gerät einer Gerätevorlage zuweisen und dann die Telemetriedaten anzeigen.

Bereitstellen der Geräte-Bridge

So stellen Sie die Geräte-Bridge in Ihrem Abonnement bereit:

Navigieren Sie in Ihrer IoT Central-Anwendung zur Seite Berechtigungen > Geräteverbindungsgruppen.
1. Notieren Sie sich den Wert für ID-Bereich. Dieser Wert wird beim Bereitstellen der Geräte-Bridge verwendet.
2. Öffnen Sie auf der gleichen Seite die Registrierungsgruppe SAS-IoT-Devices. Kopieren Sie auf der Gruppenseite SAS-IoT-Devices den Primärschlüssel. Dieser Wert wird beim Bereitstellen der Geräte-Bridge verwendet.
Verwenden Sie die folgende Schaltfläche "Bereitstellen in Azure ", um die benutzerdefinierte Resource Manager-Vorlage zu öffnen, die die Funktions-App für Ihr Abonnement bereitstellt. Verwenden Sie den ID-Bereich und den Primärschlüssel aus dem vorherigen Schritt:

Nach Abschluss der Bereitstellung müssen Sie die npm-Pakete installieren, die für die Funktion erforderlich sind:

Öffnen Sie im Azure-Portal die in Ihrem Abonnement bereitgestellte Funktions-App. Wechseln Sie dann zu Entwicklungstools>Konsole. Führen Sie in der Konsole die folgenden Befehle aus, um die Pakete zu installieren:
```
cd IoTCIntegration
npm install
```
Die Ausführung dieser Befehle kann mehrere Minuten dauern. Gegebenenfalls angezeigte Warnmeldungen können ignoriert werden.
Wählen Sie nach Abschluss der Paketinstallation auf der Seite Übersicht der Funktions-App die Option Neu starten aus:
Die Funktion kann jetzt verwendet werden. Externe Systeme können HTTP POST-Anforderungen verwenden, um Gerätedaten über die Geräte-Bridge an Ihre IoT Central-Anwendung zu senden. Navigieren Sie zum Abrufen der Funktions-URL zu Funktionen > IoTCIntegration > Programmieren und testen > Funktions-URL abrufen:

Nachrichtentext muss im folgenden Format an die Geräte-Bridge gesendet werden:

"device": {
  "deviceId": "my-cloud-device"
},
"measurements": {
  "temp": 20.31,
  "pressure": 50,
  "humidity": 8.5,
  "ledColor": "blue"
}

Jeder Schlüssel im Objekt measurements muss mit dem Namen eines Telemetrietyps in der Gerätevorlage in der IoT Central-Anwendung übereinstimmen. Die Angabe der Schnittstellen-ID im Nachrichtentext wird von dieser Lösung nicht unterstützt. Wenn also zwei verschiedene Schnittstellen über einen Telemetrietyp gleichen Namens verfügen, erscheint die Messung in beiden Telemetriedatenströmen in Ihrer IoT Central-Anwendung.

Sie können ein Feld vom Typ timestamp in den Text einschließen, um das UTC-Datum und die UTC-Uhrzeit der Nachricht anzugeben. Für dieses Feld muss das ISO 8601-Format verwendet werden. Beispiel: 2020-06-08T20:16:54.602Z. Wenn Sie keinen Zeitstempel einschließen, werden das aktuelle Datum und die aktuelle Uhrzeit verwendet.

Sie können ein Feld vom Typ modelId in den Text einschließen. Mithilfe dieses Felds kann das Gerät während der Bereitstellung einer Gerätevorlage zugewiesen werden.

Die Geräte-ID (deviceId) muss alphanumerisch sein und darf nur Kleinbuchstaben und ggf. Bindestriche enthalten.

Wenn Sie das Feld modelId nicht einschließen oder die Modell-ID von IoT Central nicht erkannt wird, wird im Falle einer Nachricht mit einer unbekannten Geräte-ID (deviceId) in IoT Central ein neues nicht zugewiesenes Gerät erstellt. Ein Operator kann das Gerät manuell zur richtigen Gerätevorlage migrieren. Weitere Informationen finden Sie unter Verwalten von Geräten in Ihrer Azure IoT Central-Anwendung > Migrieren von Geräten zu einer Vorlage.

Hinweis

Solange das Gerät keiner Vorlage zugewiesen ist, wird bei allen HTTP-Aufrufen für die Funktion der Fehlerstatus 403 zurückgegeben.

Wenn Sie für die Funktions-App die Protokollierung mit Application Insights aktivieren möchten, navigieren Sie in Ihrer Funktions-App im Azure-Portal zu Überwachung > Protokolle. Wählen Sie Application Insights aktivieren aus.

Bereitgestellte Ressourcen

Durch die Resource Manager-Vorlage werden in Ihrem Azure-Abonnement folgende Ressourcen bereitgestellt:

Funktionen-App
App Service-Plan
Speicherkonto
Key Vault (Schlüsseltresor)

Der Schlüsseltresor dient zum Speichern des SAS-Gruppenschlüssels für Ihre IoT Central-Anwendung.

Die Funktions-App wird auf der Grundlage eines Verbrauchsplan ausgeführt. Diese Option bietet zwar keine dedizierten Computeressourcen, ermöglicht es der Geräte-Bridge jedoch, Hunderte von Gerätenachrichten pro Minute zu bewältigen, was für kleinere Gerätebestände sowie für Geräte geeignet ist, von denen seltener Nachrichten gesendet werden. Wenn für Ihre Anwendung sehr viele Gerätenachrichten gestreamt werden müssen, ersetzen Sie den Verbrauchsplan durch einen dedizierten App Service-Plan. Dieser Plan bietet dedizierte Computeressourcen, die schnellere Serverantwortzeiten ermöglichen. Mit einem App Service-Standardplan wurde für die Azure-Funktion in diesem Repository eine maximale Leistung von rund 1.500 Gerätenachrichten pro Minute ermittelt. Weitere Informationen finden Sie unter Azure Functions-Hostingoptionen.

Wenn Sie anstelle eines Verbrauchsplans einen dedizierten App Service-Plan verwenden möchten, müssen Sie die benutzerdefinierte Vorlage vor der Bereitstellung bearbeiten. Wählen Sie Vorlage bearbeiten aus.

Screenshot that shows the edit template option for an Azure Resource Manager template.

Ersetzen Sie das folgende Segment:

{
  "type": "Microsoft.Web/serverfarms",
  "apiVersion": "2015-04-01",
  "name": "[variables('planName')]",
  "location": "[resourceGroup().location]",
  "properties": {
    "name": "[variables('planName')]",
    "computeMode": "Dynamic",
    "sku": "Dynamic"
  }
},

durch

{
  "type": "Microsoft.Web/serverfarms",
  "sku": {
      "name": "S1",
      "tier": "Standard",
      "size": "S1",
      "family": "S",
      "capacity": 1
  },
  "kind": "app",
  "name": "[variables('planName')]",
  "apiVersion": "2016-09-01",
  "location": "[resourceGroup().location]",
  "tags": {
      "iotCentral": "device-bridge",
      "iotCentralDeviceBridge": "app-service-plan"
  },
  "properties": {
      "name": "[variables('planName')]"
  }
},

Bearbeiten Sie als Nächstes die Vorlage, um "alwaysOn": true in die Konfiguration für die Ressource functionapp unter "properties": {"SiteConfig": {...}} einzuschließen. Durch die alwaysOn-Konfiguration wird sichergestellt, dass die Funktions-App immer ausgeführt wird.

Beispiele

In den folgenden Beispielen wird die Geräte-Bridge für verschiedene IoT-Clouds konfiguriert:

Beispiel 1: Verbinden von Particle-Geräten über die Geräte-Bridge

Wenn Sie ein Particle-Gerät über die Geräte-Bridge mit IoT Central verbinden möchten, wechseln Sie zur Particle-Konsole, und erstellen Sie eine neue Webhookintegration. Legen Sie das Anforderungsformat auf JSON fest. Verwenden Sie unter Erweiterte Einstellungen das folgende benutzerdefinierte Textformat:

{
  "device": {
    "deviceId": "{{{PARTICLE_DEVICE_ID}}}"
  },
  "measurements": {
    "{{{PARTICLE_EVENT_NAME}}}": "{{{PARTICLE_EVENT_VALUE}}}"
  }
}

Fügen Sie die Funktions-URL aus Ihrer Funktions-App ein. Daraufhin werden Particle-Geräte als nicht zugewiesene Geräte in IoT Central angezeigt. Weitere Informationen finden Sie im Blogbeitrag zum Integrieren Particle-basierter Projekte in Azure IoT Central.

Beispiel 2: Verbinden von Sigfox-Geräten über die Geräte-Bridge

Auf einigen Plattformen können Sie möglicherweise nicht das Format von Gerätenachrichten angeben, die über einen Webhook gesendet werden. Für solche Systeme müssen die Nutzdaten der Nachricht vor der Verarbeitung durch die Geräte-Bridge in das erwartete Textformat konvertiert werden. Die Konvertierung kann in der gleichen Funktion durchgeführt werden, von der auch die Geräte-Bridge ausgeführt wird.

In diesem Abschnitt wird gezeigt, wie Sie die Nutzdaten einer Sigfox-Webhookintegration in das von der Geräte-Bridge erwartete Textformat konvertieren. Gerätedaten werden von der Sigfox-Cloud in einem hexadezimalen Zeichenfolgenformat übertragen. Der Einfachheit halber enthält die Geräte-Bridge eine Konvertierungsfunktion für dieses Format, die eine Teilmenge der möglichen Feldtypen in Sigfox-Gerätenutzdaten akzeptiert: int und uint mit 8, 16, 32 oder 64 Bits, float mit 32 oder 64 Bits sowie Little-Endian und Big-Endian. Für die Verarbeitung von Nachrichten einer Sigfox-Webhookintegration muss die Datei IoTCIntegration/index.js in der Funktions-App wie im Anschluss beschrieben geändert werden.

Fügen Sie zum Konvertieren der Nachrichtennutzdaten vor dem Aufruf von handleMessage in Zeile 21 den folgenden Code hinzu, und ersetzen Sie dabei payloadDefinition durch Ihre Sigfox-Nutzdatendefinition:

const payloadDefinition = 'gforce::uint:8 lat::uint:8 lon::uint:16'; // Replace this with your payload definition

req.body = {
    device: {
        deviceId: req.body.device
    },
    measurements: require('./converters/sigfox')(payloadDefinition, req.body.data)
};

Von Sigfox-Geräten wird der Antwortcode 204 erwartet. Fügen Sie nach dem Aufruf von handleMessage in Zeile 21 den folgenden Code hinzu:

context.res = {
    status: 204
};

Beispiel 3: Verbinden von The Things Network-Geräten über die Geräte-Bridge

So verbinden Sie The Things Network-Geräte mit IoT Central:

Fügen Sie Ihrer Anwendung in The Things Network eine neue HTTP-Integration hinzu: Anwendung > Integrationen > Integration hinzufügen > HTTP-Integration.
Achten Sie darauf, dass Ihre Anwendung eine Decoderfunktion enthält, durch die die Nutzdaten Ihrer Gerätenachrichten vor dem Senden an die Funktion automatisch in JSON konvertiert werden: Anwendung > Nutzdatenfunktionen > Decoder.

Im folgenden Beispiel wird eine JavaScript-Decoderfunktion verwendet, mit der gängige numerische Typen aus Binärdaten decodiert werden können:

function Decoder(bytes, port) {
  function bytesToFloat(bytes, decimalPlaces) {
    var bits = (bytes[3] << 24) | (bytes[2] << 16) | (bytes[1] << 8) | bytes[0];
    var sign = (bits >>> 31 === 0) ? 1.0 : -1.0;
    var e = bits >>> 23 & 0xff;
    var m = (e === 0) ? (bits & 0x7fffff) << 1 : (bits & 0x7fffff) | 0x800000;
    var f = Math.round((sign * m * Math.pow(2, e - 150)) * Math.pow(10, decimalPlaces)) / Math.pow(10, decimalPlaces);
    return f;
  }

  function bytesToInt32(bytes, signed) {
    var bits = bytes[0] | (bytes[1] << 8) | (bytes[2] << 16) | (bytes[3] << 24);
    var sign = 1;

    if (signed && bits >>> 31 === 1) {
      sign = -1;
      bits = bits & 0x7FFFFFFF;
    }

    return bits * sign;
  }

  function bytesToShort(bytes, signed) {
    var bits = bytes[0] | (bytes[1] << 8);
    var sign = 1;

    if (signed && bits >>> 15 === 1) {
      sign = -1;
      bits = bits & 0x7FFF;
    }

    return bits * sign;
  }

  return {
    temperature: bytesToFloat(bytes.slice(0, 4), 2),
    presscounter: bytesToInt32(bytes.slice(4, 8), true),
    blueLux: bytesToShort(bytes.slice(8, 10), false)
  };
}

Fügen Sie nach dem Definieren der Integration vor dem Aufruf von handleMessage in Zeile 21 der Datei IoTCIntegration/index.js Ihrer Funktions-App den folgenden Code hinzu. Durch diesen Code wird der Text Ihrer HTTP-Integration in das erwartete Format konvertiert.

req.body = {
  device: {
    deviceId: req.body.end_device_ids.device_id.toLowerCase()
  },
  measurements: req.body.uplink_message.decoded_payload
};

Hinweis

Im vorherigen Codeausschnitt wird die benutzerfreundliche Geräte-ID verwendet. Die Things Network-Meldung enthält auch eine technische ID, auf die Sie mit zugreifen req.body.dev_eui.toLowerCase() können. Weitere Informationen finden Sie unter The Things Network – Datenformate.

Begrenzungen

Von der Geräte-Bridge werden nur Nachrichten an IoT Central weitergeleitet. Es werden jedoch keine Nachrichten an die Geräte zurückgesendet. Aus diesem Grund funktionieren Eigenschaften und Befehle nicht für Geräte, die über diese Gerätebrücke eine Verbindung mit IoT Central herstellen. Da keine Gerätezwillingsvorgänge unterstützt werden, ist es nicht möglich, Geräteeigenschaften über die Geräte-Bridge zu aktualisieren. Um diese Features verwenden zu können, muss ein Gerät mithilfe eines der Azure IoT-Geräte-SDKs direkt mit Azure IoT verbunden werden.

Nächste Schritte

Nachdem Sie sich hier mit der Bereitstellung der IoT Central-Geräte-Bridge vertraut gemacht haben, können Sie mit dem folgenden Schritt fortfahren:

Verwalten von Geräten