Använda IoT Plug and Play-modeller i en IoT-lösning

Artikel
03/22/2024

I den här artikeln beskrivs hur du i en IoT-lösning kan identifiera modell-ID för en IoT Plug and Play-enhet och sedan hämta dess modelldefinition.

Det finns två breda kategorier av IoT-lösning:

En specialbyggd lösning fungerar med en känd uppsättning modeller för IoT Plug and Play-enheter som ansluter till lösningen. Du använder dessa modeller när du utvecklar lösningen.
En modelldriven lösning fungerar med modellen för alla IoT Plug and Play-enheter. Att skapa en modelldriven lösning är mer komplext, men fördelen är att din lösning fungerar med alla enheter som läggs till i framtiden. En modelldriven IoT-lösning hämtar en modell och använder den för att fastställa telemetri, egenskaper och kommandon som enheten implementerar.

Om du vill använda en IoT Plug and Play-modell, en IoT-lösning:

Identifierar modell-ID för modellen som implementeras av IoT Plug and Play-enheten, modulen eller IoT Edge-modulen som är ansluten till lösningen.
Använder modell-ID:t för att hämta modelldefinitionen för den anslutna enheten från en modelllagringsplats eller ett anpassat arkiv.

Identifiera modell-ID

När en IoT Plug and Play-enhet ansluter till IoT Hub registreras modell-ID för den modell som den implementerar med IoT Hub.

IoT Hub meddelar lösningen med enhetsmodell-ID:t som en del av enhetsanslutningsflödet.

En lösning kan hämta modell-ID för IoT Plug and Play-enheten med någon av följande tre metoder:

Hämta API för enhetstvilling

Lösningen kan använda API:et Hämta enhetstvilling för att hämta modell-ID för IoT Plug and Play-enheten.

Dricks

För moduler och IoT Edge-moduler använder du ModuleClient.getTwin.

I följande svarsfragment modelId för enhetstvillingar innehåller modell-ID för en IoT Plug and Play-enhet:

{
    "deviceId": "sample-device",
    "etag": "AAAAAAAAAAc=",
    "deviceEtag": "NTk0ODUyODgx",
    "status": "enabled",
    "statusUpdateTime": "0001-01-01T00:00:00Z",
    "connectionState": "Disconnected",
    "lastActivityTime": "2020-07-17T06:12:26.8402249Z",
    "cloudToDeviceMessageCount": 0,
    "authenticationType": "sas",
    "x509Thumbprint": {
        "primaryThumbprint": null,
        "secondaryThumbprint": null
    },
    "modelId": "dtmi:com:example:TemperatureController;1",
    "version": 15,
    "properties": {...}
    }
}

Hämta API för digital tvilling

Lösningen kan använda API:et Get Digital Twin för att hämta modell-ID:t för modellen som implementeras av IoT Plug and Play-enheten.

I följande svarsfragment $metadata.$model för digital tvilling innehåller modell-ID:t för en IoT Plug and Play-enhet:

{
    "$dtId": "sample-device",
    "$metadata": {
        "$model": "dtmi:com:example:TemperatureController;1",
        "serialNumber": {
            "lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
        }
    }
}

Händelsemeddelande om ändring av digital tvilling

En enhetsanslutning resulterar i ett händelsemeddelande om ändring av Digital Twin. En lösning måste prenumerera på det här händelsemeddelandet. Information om hur du aktiverar routning för digitala tvillinghändelser finns i Använda IoT Hub-meddelanderoutning för att skicka meddelanden från enhet till molnet till olika slutpunkter.

Lösningen kan använda händelsen som visas i följande kodfragment för att lära dig mer om IoT Plug and Play-enheten som ansluter och hämtar dess modell-ID:

iothub-connection-device-id:sample-device
iothub-enqueuedtime:7/22/2020 8:02:27 PM
iothub-message-source:digitalTwinChangeEvents
correlation-id:100f322dc2c5
content-type:application/json-patch+json
content-encoding:utf-8
[
  {
    "op": "replace",
    "path": "/$metadata/$model",
    "value": "dtmi:com:example:TemperatureController;1"
  }
]

Hämta en modelldefinition

En lösning använder modell-ID som identifierats ovan för att hämta motsvarande modelldefinition.

En lösning kan hämta modelldefinitionen med något av följande alternativ:

Modelldatabas

Lösningar kan hämta DTDL-modeller från enhetsmodelllagringsplatsen (DMR). DMR är en offentlig lagringsplats som hanteras av Microsoft och som innehåller en samling utvalda DTDL-modeller. De offentliga enhetsmodeller som lagras i DMR är tillgängliga för alla att använda och integrera i sina program från den offentliga slutpunkten https://devicemodels.azure.com.

Följ dessa steg när du har identifierat modell-ID:t för en ny enhetsanslutning:

Hämta modelldefinitionen med hjälp av modell-ID:t från modelllagringsplatsen. Mer information finns i Lösa modeller.
Med hjälp av modelldefinitionen för den anslutna enheten kan du räkna upp enhetens funktioner.
Med hjälp av enhetens uppräknade funktioner kan du göra det möjligt för användare att interagera med enheten.

Lösa modeller

DMR-konventionerna innehåller andra artefakter för att förenkla förbrukningen av värdbaserade modeller. De här funktionerna är valfria för anpassade eller privata lagringsplatser.

Index. Alla tillgängliga DTMI:er exponeras via ett index som består av en sekvens med json-filer, till exempel: https://devicemodels.azure.com/index.page.2.json
Expanderad. En fil med alla beroenden är tillgänglig för varje gränssnitt, till exempel: https://devicemodels.azure.com/dtmi/com/example/temperaturecontroller-1.expanded.json
Metadata. Den här filen exponerar nyckelattribut för en lagringsplats och uppdateras regelbundet med den senaste publicerade ögonblicksbilden av modeller. Den innehåller funktioner som en lagringsplats implementerar, till exempel om modellindexet eller expanderade modellfiler är tillgängliga. Du kan komma åt DMR-metadata på https://devicemodels.azure.com/metadata.json

Om du vill ha programmatisk åtkomst till de offentliga DTDL-modellerna i DMR kan du använda det ModelsRepositoryClient tillgängliga i NuGet-paketet Azure.IoT.ModelsRepository. Den här klienten konfigureras som standard för att fråga den offentliga DMR som är tillgänglig på devicemodels.azure.com och kan konfigureras till valfri anpassad lagringsplats.

Klienten accepterar en DTMI som indata och returnerar en ordlista med alla nödvändiga gränssnitt:

using Azure.IoT.ModelsRepository;

var client = new ModelsRepositoryClient();
ModelResult models = client.GetModel("dtmi:com:example:TemperatureController;1");
models.Content.Keys.ToList().ForEach(k => Console.WriteLine(k));

De förväntade utdata visar de tre gränssnitten DTMI som finns i beroendekedjan:

dtmi:com:example:TemperatureController;1
dtmi:com:example:Thermostat;1
dtmi:azure:DeviceManagement:DeviceInformation;1

ModelsRepositoryClient Kan konfigureras för att fråga en anpassad DMR -tillgänglig via http(s)- och för att ange beroendematchning med hjälp ModelDependencyResolution av flaggan:

Inaktiverat. Returnerar endast det angivna gränssnittet, utan beroende.
Aktiverat. Returnerar alla gränssnitt i beroendekedjan

Dricks

Anpassade lagringsplatser kanske inte exponerar .expanded.json filen. När den här filen inte är tillgänglig återgår klienten till att bearbeta varje beroende lokalt.

Följande exempelkod visar hur du initierar ModelsRepositoryClient med hjälp av en anpassad databasbas-URL, i det här fallet med hjälp av raw URL:erna från GitHub-API:et expanded utan att använda formuläret eftersom det inte är tillgängligt i raw slutpunkten. AzureEventSourceListener Initieras för att inspektera HTTP-begäran som utförs av klienten:

using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

var client = new ModelsRepositoryClient(
    new Uri("https://raw.githubusercontent.com/Azure/iot-plugandplay-models/main"));

ModelResult model = await client.GetModelAsync(
    "dtmi:com:example:TemperatureController;1", 
    dependencyResolution: ModelDependencyResolution.Enabled);

model.Content.Keys.ToList().ForEach(k => Console.WriteLine(k));

Det finns fler exempel på Azure SDK GitHub-lagringsplatsen: Azure.Iot.ModelsRepository/samples.

Anpassat arkiv

Lösningar kan lagra dessa modelldefinitioner i ett lokalt filsystem, i ett offentligt filarkiv eller använda en anpassad implementering.