IoT Plug en Play-modellen gebruiken in een IoT-oplossing

Artikel
03/22/2024

In dit artikel wordt beschreven hoe u in een IoT-oplossing model-id van een IoT-Plug en Play apparaat kunt identificeren en vervolgens de modeldefinitie kunt ophalen.

Er zijn twee algemene categorieën IoT-oplossing:

Een speciaal gebouwde oplossing werkt met een bekende set modellen voor de IoT-Plug en Play-apparaten die verbinding maken met de oplossing. U gebruikt deze modellen wanneer u de oplossing ontwikkelt.
Een modelgestuurde oplossing werkt met het model van elk IoT Plug en Play-apparaat. Het bouwen van een modelgestuurde oplossing is complexer, maar het voordeel is dat uw oplossing werkt met alle apparaten die in de toekomst worden toegevoegd. Een modelgestuurde IoT-oplossing haalt een model op en gebruikt dit om de telemetrie, eigenschappen en opdrachten te bepalen die het apparaat implementeert.

Een IoT-Plug en Play-model gebruiken, een IoT-oplossing:

Identificeert de model-id van het model dat is geïmplementeerd door de IoT-Plug en Play-apparaat-, module- of IoT Edge-module die is verbonden met de oplossing.
Gebruikt de model-id om de modeldefinitie van het verbonden apparaat op te halen uit een modelopslagplaats of aangepast archief.

Model-id identificeren

Wanneer een IoT Plug en Play-apparaat verbinding maakt met IoT Hub, wordt de model-id geregistreerd van het model dat wordt geïmplementeerd met IoT Hub.

IoT Hub meldt de oplossing met de apparaatmodel-id als onderdeel van de apparaatverbindingsstroom.

Een oplossing kan de model-id van het IoT Plug en Play-apparaat ophalen met behulp van een van de volgende drie methoden:

Apparaatdubbel-API ophalen

De oplossing kan de Api apparaatdubbel ophalen gebruiken om de model-id van het IoT-Plug en Play-apparaat op te halen.

Tip

Gebruik ModuleClient.getTwin voor modules en IoT Edge-modules.

In het volgende antwoordfragment modelId van de apparaatdubbel bevat u de model-id van een IoT-Plug en Play-apparaat:

{
    "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": {...}
    }
}

Digital Twin-API ophalen

De oplossing kan de Get Digital Twin-API gebruiken om de model-id op te halen van het model dat is geïmplementeerd door het IoT Plug en Play-apparaat.

In het volgende antwoordfragment $metadata.$model van een digitale dubbel bevat u de model-id van een IoT-Plug en Play-apparaat:

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

Gebeurtenismelding voor wijziging van digitale dubbel

Een apparaatverbinding resulteert in een melding van een Digital Twin-wijzigings gebeurtenis . Een oplossing moet zich abonneren op deze gebeurtenismelding. Zie IoT Hub-berichtroutering gebruiken om apparaat-naar-cloud-berichten naar verschillende eindpunten te verzenden voor meer informatie over het inschakelen van routering voor digitale dubbelgebeurtenissen.

De oplossing kan de gebeurtenis gebruiken die wordt weergegeven in het volgende codefragment voor meer informatie over het IoT-Plug en Play-apparaat dat verbinding maakt en de model-id opvragen:

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"
  }
]

Een modeldefinitie ophalen

Een oplossing maakt gebruik van model-id die hierboven is geïdentificeerd om de bijbehorende modeldefinitie op te halen.

Een oplossing kan de modeldefinitie ophalen met behulp van een van de volgende opties:

Modelopslagplaats

Oplossingen kunnen DTDL-modellen ophalen uit de apparaatmodelopslagplaats (DMR). De DMR is een openbare opslagplaats, gehost door Microsoft, die een verzameling gecureerde DTDL-modellen bevat. De modellen voor openbare apparaten die zijn opgeslagen in de DMR zijn beschikbaar voor iedereen om te gebruiken en te integreren in hun toepassingen vanaf het openbare eindpunt https://devicemodels.azure.com.

Nadat u de model-id voor een nieuwe apparaatverbinding hebt geïdentificeerd, voert u de volgende stappen uit:

Haal de modeldefinitie op met behulp van de model-id uit de modelopslagplaats. Zie Modellen oplossen voor meer informatie.
Met behulp van de modeldefinitie van het verbonden apparaat kunt u de mogelijkheden van het apparaat inventariseren.
Met behulp van de opgesomde mogelijkheden van het apparaat kunt u gebruikers in staat stellen om met het apparaat te communiceren.

Modellen oplossen

De DMR-conventies omvatten andere artefacten voor het vereenvoudigen van het verbruik van gehoste modellen. Deze functies zijn optioneel voor aangepaste of privéopslagplaatsen.

Index. Alle beschikbare DTMIs worden weergegeven via een index die is samengesteld door een reeks json-bestanden, bijvoorbeeld: https://devicemodels.azure.com/index.page.2.json
Uitgevouwen. Een bestand met alle afhankelijkheden is beschikbaar voor elke interface, bijvoorbeeld: https://devicemodels.azure.com/dtmi/com/example/temperaturecontroller-1.expanded.json
Metagegevens. Dit bestand bevat belangrijke kenmerken van een opslagplaats en wordt periodiek vernieuwd met de meest recente momentopname van gepubliceerde modellen. Het bevat functies die een opslagplaats implementeert, zoals of de modelindex of uitgebreide modelbestanden beschikbaar zijn. U hebt toegang tot de DMR-metagegevens op https://devicemodels.azure.com/metadata.json

Als u programmatisch toegang wilt krijgen tot de openbare DTDL-modellen in de DMR, kunt u het ModelsRepositoryClient nuget-pakket Azure.IoT.ModelsRepository gebruiken. Deze client is standaard geconfigureerd om een query uit te voeren op de openbare DMR die beschikbaar is op devicemodels.azure.com en kan worden geconfigureerd voor elke aangepaste opslagplaats.

De client accepteert een DTMI als invoer en retourneert een woordenlijst met alle vereiste interfaces:

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 verwachte uitvoer geeft de DTMI drie interfaces weer die in de afhankelijkheidsketen zijn gevonden:

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

De ModelsRepositoryClient kan worden geconfigureerd om een query uit te voeren op een aangepaste DMR die beschikbaar is via http(s) en om de afhankelijkheidsresolutie op te geven met behulp van de ModelDependencyResolution vlag:

Disabled. Retourneert alleen de opgegeven interface, zonder enige afhankelijkheid.
Ingeschakeld. Retourneert alle interfaces in de afhankelijkheidsketen

Tip

Aangepaste opslagplaatsen maken het .expanded.json bestand mogelijk niet beschikbaar. Wanneer dit bestand niet beschikbaar is, valt de client terug om elke afhankelijkheid lokaal te verwerken.

In de volgende voorbeeldcode ziet u hoe u de ModelsRepositoryClient url initialiseert met behulp van een aangepaste basis-URL van de opslagplaats, in dit geval met behulp van de raw URL's van de GitHub-API zonder het expanded formulier te gebruiken, omdat deze niet beschikbaar is in het raw eindpunt. De AzureEventSourceListener aanvraag wordt geïnitialiseerd om de HTTP-aanvraag te inspecteren die door de client wordt uitgevoerd:

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));

Er zijn meer voorbeelden beschikbaar in de GitHub-opslagplaats van de Azure SDK: Azure.Iot.ModelsRepository/samples.

Aangepast archief

Oplossingen kunnen deze modeldefinities opslaan in een lokaal bestandssysteem, in een openbaar bestandsarchief of een aangepaste implementatie gebruiken.