Usare Plug and Play IoT modelli in una soluzione IoT

Articolo
03/22/2024

Questo articolo descrive come, in una soluzione IoT, è possibile identificare l'ID modello di un dispositivo Plug and Play IoT e quindi recuperarne la definizione del modello.

Esistono due ampie categorie di soluzioni IoT:

Una soluzione creata appositamente funziona con un set noto di modelli per i dispositivi Plug and Play IoT che si connettono alla soluzione. Questi modelli vengono usati quando si sviluppa la soluzione.
Una soluzione basata su modello funziona con il modello di qualsiasi dispositivo Plug and Play IoT. La creazione di una soluzione basata su modello è più complessa, ma il vantaggio è che la soluzione funziona con tutti i dispositivi aggiunti in futuro. Una soluzione IoT basata su modello recupera un modello e la usa per determinare i dati di telemetria, le proprietà e i comandi implementati dal dispositivo.

Per usare un modello Plug and Play IoT, una soluzione IoT:

Identifica l'ID modello del modello implementato dal modulo Plug and Play IoT dispositivo, modulo o IoT Edge connesso alla soluzione.
Usa l'ID modello per recuperare la definizione del modello del dispositivo connesso da un repository di modelli o da un archivio personalizzato.

Identificare l'ID modello

Quando un dispositivo Plug and Play IoT si connette a hub IoT, registra l'ID modello del modello implementato con hub IoT.

hub IoT notifica alla soluzione l'ID del modello di dispositivo come parte del flusso di connessione del dispositivo.

Una soluzione può ottenere l'ID modello del dispositivo Plug and Play IoT usando uno dei tre metodi seguenti:

Ottenere l'API del dispositivo gemello

La soluzione può usare l'API Get Device Twin per recuperare l'ID modello del dispositivo Plug and Play IoT.

Suggerimento

Per i moduli e i moduli IoT Edge, usare ModuleClient.getTwin.

Nel frammento di risposta del dispositivo gemello modelId seguente contiene l'ID modello di un dispositivo Plug and Play IoT:

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

Ottenere l'API di Gemelli digitali

La soluzione può usare l'API Get Digital Twin per recuperare l'ID modello del modello implementato dal dispositivo Plug and Play IoT.

Nel frammento di risposta del gemello $metadata.$model digitale seguente contiene l'ID modello di un dispositivo Plug and Play IoT:

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

Notifica degli eventi di modifica di Gemelli digitali

Una connessione del dispositivo genera una notifica di evento di modifica di Gemelli digitali. Una soluzione deve sottoscrivere questa notifica degli eventi. Per informazioni su come abilitare il routing per gli eventi di Gemelli digitali, vedere Usare hub IoT routing dei messaggi per inviare messaggi da dispositivo a cloud a endpoint diversi.

La soluzione può usare l'evento illustrato nel frammento di codice seguente per informazioni sul dispositivo Plug and Play IoT che si connette e ottiene il relativo ID modello:

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

Recuperare una definizione di modello

Una soluzione usa l'ID modello identificato in precedenza per recuperare la definizione del modello corrispondente.

Una soluzione può ottenere la definizione del modello usando una delle opzioni seguenti:

Repository modelli

Le soluzioni possono recuperare i modelli DTDL dal repository del modello di dispositivo (DMR). Dmr è un repository pubblico, ospitato da Microsoft, che contiene una raccolta di modelli DTDL curati. I modelli di dispositivo pubblico archiviati nella dmr sono disponibili per tutti gli utenti per l'uso e l'integrazione nelle applicazioni dall'endpoint https://devicemodels.azure.compubblico .

Dopo aver identificato l'ID modello per una nuova connessione al dispositivo, seguire questa procedura:

Recuperare la definizione del modello usando l'ID modello dal repository del modello. Per altre informazioni, vedere Risolvere i modelli.
Usando la definizione del modello del dispositivo connesso, è possibile enumerare le funzionalità del dispositivo.
Usando le funzionalità enumerate del dispositivo, è possibile consentire agli utenti di interagire con il dispositivo.

Risolvere i modelli

Le convenzioni dmr includono altri artefatti per semplificare l'utilizzo di modelli ospitati. Queste funzionalità sono facoltative per i repository personalizzati o privati.

Index. Tutte le DTMI disponibili vengono esposte tramite un indice composto da una sequenza di file JSON, ad esempio: https://devicemodels.azure.com/index.page.2.json
Espansa. Un file con tutte le dipendenze è disponibile per ogni interfaccia, ad esempio: https://devicemodels.azure.com/dtmi/com/example/temperaturecontroller-1.expanded.json
Metadata. Questo file espone gli attributi chiave di un repository e viene aggiornato periodicamente con lo snapshot dei modelli pubblicati più recente. Include funzionalità implementate da un repository, ad esempio se sono disponibili l'indice del modello o i file di modello espansi. È possibile accedere ai metadati dmr all'indirizzo https://devicemodels.azure.com/metadata.json

Per accedere ai modelli DTDL pubblici in DMR a livello di codice, è possibile usare il ModelsRepositoryClient file disponibile nel pacchetto NuGet Azure.IoT.ModelsRepository. Questo client è configurato per impostazione predefinita per eseguire una query sulla dmr pubblica disponibile in devicemodels.azure.com e può essere configurato in qualsiasi repository personalizzato.

Il client accetta come DTMI input e restituisce un dizionario con tutte le interfacce necessarie:

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

L'output previsto visualizza le DTMI tre interfacce trovate nella catena di dipendenze:

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

ModelsRepositoryClient Può essere configurato per eseguire query su una dmr personalizzata disponibile tramite http(s) e per specificare la risoluzione delle dipendenze usando il ModelDependencyResolution flag :

Disabled. Restituisce solo l'interfaccia specificata, senza alcuna dipendenza.
Abilitati. Restituisce tutte le interfacce nella catena di dipendenze

Suggerimento

I repository personalizzati potrebbero non esporre il .expanded.json file. Quando questo file non è disponibile, il client eseguirà il fallback per elaborare ogni dipendenza in locale.

Il codice di esempio seguente illustra come inizializzare ModelsRepositoryClient usando un URL di base del repository personalizzato, in questo caso usando gli raw URL dell'API GitHub senza usare il expanded modulo perché non è disponibile nell'endpoint raw . Viene AzureEventSourceListener inizializzato per controllare la richiesta HTTP eseguita dal client:

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

Sono disponibili altri esempi nel repository GitHub di Azure SDK: Azure.Iot.ModelsRepository/samples.

Archivio personalizzato

Le soluzioni possono archiviare queste definizioni di modello in un file system locale, in un archivio file pubblico o usare un'implementazione personalizzata.