Usar modelos IoT Plug and Play em uma solução de IoT

Artigo
03/22/2024

Este artigo descreve como, em uma solução IoT, você pode identificar a ID do modelo de um dispositivo IoT Plug and Play e, em seguida, recuperar sua definição de modelo.

Existem duas grandes categorias de solução de IoT:

Uma solução criada especificamente funciona com um conjunto conhecido de modelos para os dispositivos IoT Plug and Play que se conectam à solução. Você usa esses modelos ao desenvolver a solução.
Uma solução orientada por modelo funciona com o modelo de qualquer dispositivo IoT Plug and Play. A criação de uma solução orientada por modelo é mais complexa, mas a vantagem é que sua solução funciona com quaisquer dispositivos que sejam adicionados no futuro. Uma solução de IoT orientada por modelo recupera um modelo e o usa para determinar a telemetria, as propriedades e os comandos que o dispositivo implementa.

Para usar um modelo IoT Plug and Play, uma solução IoT:

Identifica o ID do modelo implementado pelo dispositivo, módulo ou módulo IoT Plug and Play conectado à solução.
Usa o ID do modelo para recuperar a definição de modelo do dispositivo conectado de um repositório de modelo ou armazenamento personalizado.

Identificar o ID do modelo

Quando um dispositivo IoT Plug and Play se conecta ao Hub IoT, ele registra a ID do modelo que implementa com o Hub IoT.

O Hub IoT notifica a solução com o ID do modelo de dispositivo como parte do fluxo de conexão do dispositivo.

Uma solução pode obter a ID do modelo do dispositivo IoT Plug and Play usando um dos três métodos a seguir:

Obter API Twin de Dispositivo

A solução pode usar a API Get Device Twin para recuperar a ID do modelo do dispositivo IoT Plug and Play.

Gorjeta

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

No seguinte trecho de resposta gêmea do dispositivo, modelId contém a ID do modelo de um 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": {...}
    }
}

Obtenha a API Digital Twin

A solução pode usar a API Get Digital Twin para recuperar o ID do modelo implementado pelo dispositivo IoT Plug and Play.

No seguinte trecho de resposta de gêmeo digital, $metadata.$model contém a ID do modelo de um dispositivo IoT Plug and Play:

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

Notificação de evento de alteração de gêmeo digital

Uma conexão de dispositivo resulta em uma notificação de evento de alteração do Digital Twin. Uma solução precisa se inscrever para esta notificação de evento. Para saber como habilitar o roteamento para eventos de gêmeos digitais, consulte Usar o roteamento de mensagens do Hub IoT para enviar mensagens do dispositivo para a nuvem para diferentes pontos de extremidade.

A solução pode usar o evento mostrado no trecho a seguir para saber mais sobre o dispositivo IoT Plug and Play que está se conectando e obter sua 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"
  }
]

Recuperar uma definição de modelo

Uma solução usa a ID do modelo identificada acima para recuperar a definição de modelo correspondente.

Uma solução pode obter a definição do modelo usando uma das seguintes opções:

Repositório de modelos

As soluções podem recuperar modelos DTDL do repositório de modelos de dispositivo (DMR). O DMR é um repositório público, hospedado pela Microsoft, que contém uma coleção de modelos DTDL com curadoria. Os modelos de dispositivos públicos armazenados no DMR estão disponíveis para todos consumirem e integrarem em seus aplicativos a partir do ponto de extremidade https://devicemodels.azure.compúblico.

Depois de identificar o ID do modelo para uma nova conexão de dispositivo, execute estas etapas:

Recupere a definição do modelo usando o ID do modelo do repositório do modelo. Para obter mais informações, consulte Resolver modelos.
Usando a definição de modelo do dispositivo conectado, você pode enumerar os recursos do dispositivo.
Usando os recursos enumerados do dispositivo, você pode permitir que os usuários interajam com o dispositivo.

Resolver modelos

As convenções DMR incluem outros artefatos para simplificar o consumo de modelos hospedados. Esses recursos são opcionais para repositórios personalizados ou privados.

Índice. Todos os DTMIs disponíveis são expostos através de um índice composto por uma sequência de arquivos json, por exemplo: https://devicemodels.azure.com/index.page.2.json
Ampliado. Um arquivo com todas as dependências está disponível para cada interface, por exemplo: https://devicemodels.azure.com/dtmi/com/example/temperaturecontroller-1.expanded.json
Metadados. Esse arquivo expõe os principais atributos de um repositório e é atualizado periodicamente com o instantâneo dos modelos publicados mais recentes. Ele inclui recursos que um repositório implementa, como se o índice do modelo ou os arquivos de modelo expandidos estão disponíveis. Você pode acessar os metadados DMR em https://devicemodels.azure.com/metadata.json

Para acessar programaticamente os modelos DTDL públicos no DMR, você pode usar o ModelsRepositoryClient disponível no pacote NuGet Azure.IoT.ModelsRepository. Esse cliente é configurado por padrão para consultar o DMR público disponível em devicemodels.azure.com e pode ser configurado para qualquer repositório personalizado.

O cliente aceita um DTMI como entrada e retorna um dicionário com todas as interfaces necessárias:

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

A saída esperada exibe as DTMI três interfaces encontradas na cadeia de dependência:

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

O ModelsRepositoryClient pode ser configurado para consultar um DMR personalizado -disponível através de http(s)- e para especificar a resolução de dependência usando o ModelDependencyResolution sinalizador:

Desativado. Retorna somente a interface especificada, sem qualquer dependência.
Ativado. Retorna todas as interfaces na cadeia de dependência

Gorjeta

Os repositórios personalizados podem não expor o .expanded.json arquivo. Quando esse arquivo não estiver disponível, o cliente fará fallback para processar cada dependência localmente.

O código de exemplo a seguir mostra como inicializar o ModelsRepositoryClient usando uma URL base de repositório personalizada, neste caso usando as raw URLs da API do GitHub sem usar o expanded formulário, pois ele não está disponível no raw ponto de extremidade. O AzureEventSourceListener é inicializado para inspecionar a solicitação HTTP executada pelo 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));

Há mais exemplos disponíveis no repositório GitHub do SDK do Azure: Azure.Iot.ModelsRepository/samples.

Loja personalizada

As soluções podem armazenar essas definições de modelo em um sistema de arquivos local, em um armazenamento de arquivos público ou usar uma implementação personalizada.