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

Artigo
04/01/2024

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

Há duas categorias amplas de solução de IoT:

Uma solução especialmente concebida funciona com um conjunto conhecido de modelos para dispositivos IoT Plug and Play que se conectam à solução. Você usa esses modelos ao desenvolver a solução.
Uma solução baseada em modelos funciona com o modelo de qualquer dispositivo IoT Plug and Play. A criação de uma solução baseada em modelos é mais complexa, mas o benefício é que sua solução funciona com qualquer dispositivo que é adicionado no futuro. Uma solução de IoT baseada em modelos recupera um modelo e o usa para determinar a telemetria, as propriedades e os comandos que o dispositivo implementa.

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

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

Identificar a ID do modelo

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

O Hub IoT notifica a solução com a 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:

API Obter Dispositivo Gêmeo

A solução pode usar a API Obter Dispositivo Gêmeo para recuperar a ID do modelo do dispositivo IoT Plug and Play.

Dica

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

No trecho de resposta do dispositivo gêmeo a seguir, 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": {...}
    }
}

API Obter o Gêmeo Digital

A solução pode usar a API Obter Gêmeo Digital para recuperar a ID do modelo implementado pelo dispositivo IoT Plug and Play.

No trecho de resposta do gêmeo digital a seguir, $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ções de evento de alteração do gêmeo digital

Uma conexão de dispositivo resulta em uma notificação de Evento de alteração do Gêmeo Digital. Uma solução precisa assinar essa notificação de evento. Para saber como habilitar o roteamento para eventos de gêmeo digital, confira Usar o roteamento de mensagem do Hub IoT para enviar mensagens do dispositivo para nuvem a diferentes pontos de extremidade.

A solução pode usar o evento mostrado no snippet a seguir para saber mais sobre o dispositivo IoT Plug and Play que está se conectando e obter sua ID do 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 do 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 dispositivos (DMR). O DMR é um repositório público hospedado pela Microsoft que contém uma coleção de modelos DTDL selecionados. 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 público https://devicemodels.azure.com.

Após identificar a ID do modelo para uma nova conexão de dispositivo, siga estas etapas:

Recupere a definição de modelo usando a ID do modelo do repositório de modelos. Para obter mais informações, veja 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 habilitar que os usuários interajam com o dispositivo.

Resolver modelos

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

Index. Todos os DTMIs disponíveis são expostos por meio de um índice composto por uma sequência de arquivos JSON, por exemplo: https://devicemodels.azure.com/index.page.2.json
Expandido. 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 os recursos que um repositório implementa, por exemplo, se o índice de modelo ou os arquivos de modelo expandidos estão disponíveis. Você pode acessar os metadados do 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 uma 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 a DTMI das 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 por meio de HTTPs – e para especificar a resolução de dependência usando o sinalizador ModelDependencyResolution:

Desabilitada. Retorna apenas a interface especificada, sem nenhuma dependência.
Habilitado. Retorna todas as interfaces na cadeia de dependências

Dica

Repositórios personalizados podem não expor o arquivo .expanded.json. 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 de base de repositório personalizado, neste caso, usando as URLs raw da API do GitHub, sem usar o formulário expanded – já que ela não está disponível no ponto de extremidaderaw. 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 do GitHub de SDK do Azure: Azure.Iot.ModelsRepository/samples.

Repositório personalizado

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