Uso de los modelos IoT Plug and Play en una solución de IoT

Artículo
03/29/2024

En este artículo se describe cómo, puede identificar el id. de modelo de un dispositivo IoT Plug and Play y recuperar su definición de modelo en una solución de IoT.

Hay dos grandes categorías de soluciones IoT:

Una solución compilada específicamente funciona con un conjunto conocido de modelos para los dispositivos IoT Plug and Play que se conectarán a la solución. Estos modelos se usan al desarrollar la solución.
Las soluciones basadas en modelos funcionan con el modelo de cualquier dispositivo IoT Plug and Play. La creación de una solución basada en modelos es más compleja, pero la ventaja es que la solución funciona con cualquier dispositivo que agregue en el futuro. Una solución de IoT basada en modelos puede recuperar un modelo y usarlo para determinar la telemetría, las propiedades y los comandos que implementa el dispositivo.

Para usar un modelo IoT Plug and Play, una solución de IoT realiza lo siguiente:

Identifica el identificador de modelo del modelo implementado por el dispositivo IoT Plug and Play, el módulo o el módulo IoT Edge conectados a la solución.
Usa el id. del modelo para recuperar la definición del modelo del dispositivo conectado desde un repositorio de modelos o un almacén personalizado.

Identificación del id. de modelo

Cuando un dispositivo IoT Plug and Play se conecta a IoT Hub, registra el id. de modelo del modelo que se implementa con IoT Hub.

IoT Hub proporciona a la solución el id. del modelo de dispositivo como parte del flujo de conexión del dispositivo.

Una solución puede obtener el id. de modelo del dispositivo IoT Plug and Play mediante uno de los tres métodos siguientes:

Get Device Twin API

La solución puede usar la API Get Device Twin para recuperar el id. de modelo del dispositivo IoT Plug and Play.

Sugerencia

Para módulos y módulos IoT Edge, use ModuleClient.getTwin.

En el siguiente fragmento de código de respuesta del dispositivo gemelo, modelId contiene el id. de modelo de un dispositivo IoT Plug and Play:

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

Get Digital Twin API

La solución puede usar la API Get Digital Twin para recuperar el id. de modelo del modelo que implementó el dispositivo IoT Plug and Play.

En el siguiente fragmento de código de respuesta del gemelo digital, $metadata.$model contiene el id. de modelo de un dispositivo IoT Plug and Play:

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

Notificación de eventos de cambio del gemelo digital

Una conexión del dispositivo da como resultado una notificación del evento de cambio de gemelo digital. Una solución debe suscribirse a esta notificación de eventos. Para información sobre cómo habilitar el enrutamiento para eventos de gemelo digital, consulte Uso del enrutamiento de mensajes de IoT Hub para enviar mensajes del dispositivo a la nube a distintos puntos de conexión.

La solución puede usar el evento que se muestra en el siguiente fragmento de código para obtener información sobre el dispositivo IoT Plug and Play que se conecta y obtiene su id. de modelo:

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

Recuperación de la definición del modelo

Una solución usa el id. de modelo identificado anteriormente para recuperar la definición de modelo correspondiente.

Una solución puede obtener la definición del modelo mediante una de las siguientes opciones:

Repositorio de modelos

Las soluciones pueden recuperar modelos DTDL del repositorio de modelos de dispositivo (DMR). El DMR es un repositorio público hospedado por Microsoft que contiene una colección de modelos DTDL mantenidos. Los modelos de dispositivos públicos almacenados en el DMR están disponibles para que todos los usuarios los consuman e integren en sus aplicaciones desde el punto de conexión público https://devicemodels.azure.com.

Una vez haya identificado el id. de modelo de una nueva conexión de dispositivo, siga estos pasos:

Recupere la definición del modelo mediante el id. de modelo del repositorio de modelos. Para obtener más información, consulte Resolución de modelos.
Con la definición de modelo del dispositivo conectado, puede enumerar las capacidades del dispositivo.
Con las funcionalidades enumeradas del dispositivo, puede permitir a los usuarios interactuar con el dispositivo.

Resolver modelos

Las convenciones de DMR incluyen artefactos adicionales para simplificar el consumo de modelos hospedados. Estas características son opcionales en repositorios personalizados o privados.

Index. Todos los DTMI disponibles se exponen mediante un índice compuesto por una secuencia de archivos JSON, por ejemplo: https://devicemodels.azure.com/index.page.2.json
Expanded. Hay un archivo con todas las dependencias disponible para cada interfaz, por ejemplo: https://devicemodels.azure.com/dtmi/com/example/temperaturecontroller-1.expanded.json
Metadatos. Este archivo expone los atributos clave de un repositorio y se actualiza periódicamente con la instantánea de modelos publicados más reciente. Incluye características que se implementan en un repositorio, como si el índice del modelo o los archivos de modelo expandido están disponibles. Puede acceder a los metadatos de DMR en https://devicemodels.azure.com/metadata.json

Para acceder mediante programación a los modelos de DTDL públicos en DMR, puede usar el ModelsRepositoryClient disponible en el paquete NuGet Azure.IoT.ModelsRepository. Este cliente está configurado de forma predeterminada para consultar el DMR público disponible en devicemodels.azure.com y se puede configurar en cualquier repositorio personalizado.

El cliente acepta un objeto DTMI como entrada y devuelve un diccionario con todas las interfaces requeridas:

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

La salida esperada muestra el objeto DTMI de las tres interfaces que se encuentran en la cadena de dependencias:

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

El objeto ModelsRepositoryClient se puede configurar para consultar un DMR personalizado, disponible a través de HTTP(S), y especificar la resolución de dependencias mediante la marca ModelDependencyResolution:

Deshabilitado. Devuelve solo la interfaz especificada, sin ninguna dependencia.
Habilitado. Devuelve todas las interfaces de la cadena de dependencias.

Sugerencia

Es posible que los repositorios personalizados no expongan el archivo .expanded.json. Cuando este archivo no esté disponible, el cliente volverá a procesar cada dependencia localmente.

En el siguiente código de ejemplo se muestra cómo inicializar el objeto ModelsRepositoryClient mediante una dirección URL base de repositorio personalizado (en este caso, mediante las direcciones URL raw de la API de GitHub sin usar el formulario expanded, ya que no está disponible en el punto de conexión raw). El objeto AzureEventSourceListener se inicializa para inspeccionar la solicitud HTTP realizada por el cliente:

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

Hay más ejemplos disponibles en el repositorio de GitHub del SDK de Azure: Azure.Iot.ModelsRepository/samples.

Almacén personalizado

Las soluciones pueden almacenar estas definiciones de modelo en un sistema de archivos local, en un almacén de archivos público o usar una implementación personalizada.