Compreender os duplos digitais Plug and Play do IoT

Artigo
02/07/2024

Um dispositivo IoT Plug and Play implementa um modelo descrito pelo esquema DTDL (Digital Twins Definition Language). Um modelo descreve o conjunto de componentes, propriedades, comandos e mensagens de telemetria que um determinado dispositivo pode ter.

Nota

A DTDL não é exclusiva do IoT Plug and Play. Outros serviços de IoT, como os Gêmeos Digitais do Azure, usam-no para representar ambientes inteiros, como edifícios e redes de energia.

Os SDKs do serviço IoT do Azure incluem APIs que permitem que um serviço interaja com o gêmeo digital de um dispositivo. Por exemplo, um serviço pode ler as propriedades do dispositivo do gêmeo digital ou usar o gêmeo digital para chamar um comando em um dispositivo. Para saber mais, consulte Exemplos de gêmeos digitais do Hub IoT.

O exemplo de dispositivo IoT Plug and Play neste artigo implementa um modelo de controlador de temperatura que tem componentes de termostato .

Gêmeos de dispositivo e gêmeos digitais

Junto com um gêmeo digital, o Hub IoT do Azure também mantém um gêmeo de dispositivo para cada dispositivo conectado. Um gêmeo de dispositivo é semelhante a um gêmeo digital na medida em que é uma representação das propriedades de um dispositivo. Um hub IoT inicializa um gêmeo digital e um gêmeo de dispositivo na primeira vez que um dispositivo IoT Plug and Play é provisionado. Os SDKs do serviço IoT do Azure incluem APIs para interagir com gêmeos de dispositivo.

os dispositivos duplos são documentos JSON que armazenam informações de estado dos dispositivos, incluindo metadados, configurações e condições. Para saber mais, consulte Exemplos de cliente de serviço do Hub IoT. Os construtores de dispositivos e soluções podem usar o mesmo conjunto de APIs e SDKs gêmeos de dispositivo para implementar dispositivos e soluções usando convenções IoT Plug and Play. Em um dispositivo gêmeo, o estado de uma propriedade gravável é dividido entre as propriedades desejadas e as seções de propriedades relatadas. Todas as propriedades somente leitura estão disponíveis na seção de propriedades relatadas.

As APIs de gêmeos digitais operam em construções DTDL de alto nível, como componentes, propriedades e comandos, e facilitam a criação de soluções IoT Plug and Play pelos construtores de soluções. Em um gêmeo digital, há uma visão unificada do estado atual e desejado da propriedade. O estado de sincronização de uma determinada propriedade é armazenado na seção do componente $metadata padrão correspondente.

Exemplo de JSON gêmeo de dispositivo

O trecho a seguir mostra um dispositivo gêmeo IoT Plug and Play formatado como um objeto JSON:

{
  "deviceId": "sample-device",
  "modelId": "dtmi:com:example:TemperatureController;1",
  "version": 15,
  "properties": {
    "desired": {
      "thermostat1": {
        "__t": "c",
        "targetTemperature": 21.8
      },
      "$metadata": {...},
      "$version": 4
    },
    "reported": {
      "serialNumber": "alwinexlepaho8329",
      "thermostat1": {
        "maxTempSinceLastReboot": 25.3,
        "__t": "c",
        "targetTemperature": {
          "value": 21.8,
          "ac": 200,
          "ad": "Successfully executed patch",
        }
      },
      "$metadata": {...},
      "$version": 11
    }
  }
}

Exemplo de gêmeo digital

O trecho a seguir mostra o gêmeo digital formatado como um objeto JSON:

{
  "$dtId": "sample-device",
  "serialNumber": "alwinexlepaho8329",
  "thermostat1": {
    "maxTempSinceLastReboot": 25.3,
    "targetTemperature": 21.8,
    "$metadata": {
      "targetTemperature": {
        "desiredValue": 21.8,
        "desiredVersion": 4,
        "ackVersion": 4,
        "ackCode": 200,
        "ackDescription": "Successfully executed patch",
        "lastUpdateTime": "2020-07-17T06:11:04.9309159Z"
      },
      "maxTempSinceLastReboot": {
         "lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
      }
    }
  },
  "$metadata": {
    "$model": "dtmi:com:example:TemperatureController;1",
    "serialNumber": {
      "lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
    }
  }
}

A tabela a seguir descreve os campos no objeto JSON do gêmeo digital:

Nome do campo	Description
`$dtId`	Uma cadeia de caracteres fornecida pelo usuário que representa a ID do gêmeo digital do dispositivo.
`{propertyName}`	O valor de uma propriedade em JSON.
`$metadata.$model`	[Opcional] O ID da interface do modelo que caracteriza este gêmeo digital.
`$metadata.{propertyName}.desiredValue`	[Apenas para propriedades graváveis] O valor desejado da propriedade especificada.
`$metadata.{propertyName}.desiredVersion`	[Apenas para propriedades graváveis] A versão do valor desejado mantida pelo Hub IoT.
`$metadata.{propertyName}.ackVersion`	[Obrigatório, apenas para propriedades graváveis] A versão reconhecida pelo dispositivo que implementa o gêmeo digital, deve por maior ou igual à versão desejada.
`$metadata.{propertyName}.ackCode`	[Obrigatório, apenas para propriedades graváveis] O `ack` código retornado pelo aplicativo do dispositivo que implementa o gêmeo digital.
`$metadata.{propertyName}.ackDescription`	[Opcional, apenas para propriedades graváveis] A `ack` descrição retornada pelo aplicativo do dispositivo que implementa o gêmeo digital.
`$metadata.{propertyName}.lastUpdateTime`	O Hub IoT mantém o carimbo de data/hora da última atualização da propriedade pelo dispositivo. Os carimbos de data/hora estão em UTC e codificados no formato ISO8601 AAAA-MM-DDTHH:MM:SS.mmmZ.
`{componentName}`	Um objeto JSON que contém os valores de propriedade e metadados do componente.
`{componentName}.{propertyName}`	O valor da propriedade do componente em JSON.
`{componentName}.$metadata`	As informações de metadados para o componente.

Propriedades

Propriedades são campos de dados que representam o estado de uma entidade, assim como as propriedades em muitas linguagens de programação orientadas a objetos.

Propriedade somente leitura

Esquema DTDL:

{
    "@type": "Property",
    "name": "serialNumber",
    "displayName": "Serial Number",
    "description": "Serial number of the device.",
    "schema": "string"
}

Neste exemplo, alwinexlepaho8329 é o valor atual da serialNumber propriedade somente leitura relatada pelo dispositivo.

Os trechos a seguir mostram a representação JSON lado a lado da serialNumber propriedade:

Dispositivo twin

"properties": {
"reported": {
"serialNumber": "alwinexlepaho8329"
}
}

Gêmeo digital

"serialNumber": "alwinexlepaho8329"

Propriedade gravável

Os exemplos a seguir mostram uma propriedade gravável no componente padrão.

DTDL:

{
  "@type": "Property",
  "name": "fanSpeed",
  "displayName": "Fan Speed",
  "writable": true,
  "schema": "double"
}

Dispositivo twin

{
"properties": {
"desired": {
"fanSpeed": 2.0,
},
"reported": {
"fanSpeed": {
"value": 3.0,
"ac": 200,
"av": 1,
"ad": "Successfully executed patch version 1"
}
}
},
}

Gêmeo digital

{
"fanSpeed": 3.0,
"$metadata": {
"fanSpeed": {
"desiredValue": 2.0,
"desiredVersion": 2,
"ackVersion": 1,
"ackCode": 200,
"ackDescription": "Successfully executed patch version 1",
"lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
}
}
}

Neste exemplo, 3.0 é o fanSpeed valor atual da propriedade relatada pelo dispositivo. 2.0 é o valor desejado definido pela solução. O valor desejado e o estado de sincronização de uma propriedade de nível raiz são definidos dentro do nível $metadata raiz para um gêmeo digital. Quando o dispositivo fica online, ele pode aplicar essa atualização e relatar o valor atualizado.

Componentes

Os componentes permitem que você construa uma interface de modelo como uma montagem de outras interfaces. Por exemplo, a interface do termostato pode ser incorporada como componentes thermostat1 e thermostat2 no modelo do controlador de temperatura.

Em um dispositivo gêmeo { "__t": "c"} , um componente é identificado pelo marcador. Em um gêmeo digital, a presença de $metadata marca um componente.

Neste exemplo, thermostat1 é um componente com duas propriedades:

maxTempSinceLastReboot é uma propriedade somente leitura.
targetTemperature é uma propriedade gravável que foi sincronizada com êxito pelo dispositivo. O valor desejado e o estado de sincronização dessas propriedades estão no .$metadata

Os trechos a seguir mostram a representação JSON lado a lado do thermostat1 componente:

Dispositivo twin

"properties": {
"desired": {
"thermostat1": {
"__t": "c",
"targetTemperature": 21.8
},
"$metadata": {
},
"$version": 4
},
"reported": {
"thermostat1": {
"maxTempSinceLastReboot": 25.3,
"__t": "c",
"targetTemperature": {
"value": 21.8,
"ac": 200,
"ad": "Successfully executed patch",
"av": 4
}
},
"$metadata": {
},
"$version": 11
}
}

Gêmeo digital

"thermostat1": {
"maxTempSinceLastReboot": 25.3,
"targetTemperature": 21.8,
"$metadata": {
"targetTemperature": {
"desiredValue": 21.8,
"desiredVersion": 4,
"ackVersion": 4,
"ackCode": 200,
"ackDescription": "Successfully executed patch",
"lastUpdateTime": "2020-07-17T06:11:04.9309159Z"
},
"maxTempSinceLastReboot": {
"lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
}
}
}

APIs de gêmeos digitais

As APIs de gêmeo digital incluem operações Get Digital Twin, Update Digital Twin, Invoke Component Command e Invoke Command mais gerenciando um gêmeo digital. Você pode usar as APIs REST diretamente ou por meio de um dos SDKs de serviço.

Eventos de alteração de duplos digitais

Quando os eventos de alteração de duplos digitais estão ativados, é acionado um evento sempre que o valor atual ou desejado do componente ou da propriedade é alterado. Os eventos de alteração de gêmeos digitais são gerados no formato JSON Patch . Os eventos correspondentes são gerados no formato twin do dispositivo se os eventos twin change estiverem ativados.

Para saber como habilitar o roteamento para eventos de dispositivo e gêmeo digital, consulte Usar o roteamento de mensagens do Hub IoT para enviar mensagens do dispositivo para a nuvem para diferentes pontos de extremidade. Para entender o formato da mensagem, consulte Criar e ler mensagens do Hub IoT.

Por exemplo, o seguinte evento de alteração de gêmeo digital é acionado quando targetTemperature definido pela solução:

iothub-connection-device-id:sample-device
iothub-enqueuedtime:7/17/2020 6:11:04 AM
iothub-message-source:digitalTwinChangeEvents
correlation-id:275d463fa034
content-type:application/json-patch+json
content-encoding:utf-8
[
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature",
    "value": {
      "desiredValue": 21.8,
      "desiredVersion": 4
    }
  }
]

O seguinte evento de alteração de gêmeo digital é acionado quando o dispositivo relata que a alteração desejada acima foi aplicada:

iothub-connection-device-id:sample-device
iothub-enqueuedtime:7/17/2020 6:11:05 AM
iothub-message-source:digitalTwinChangeEvents
correlation-id:275d464a2c80
content-type:application/json-patch+json
content-encoding:utf-8
[
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature/ackCode",
    "value": 200
  },
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature/ackDescription",
    "value": "Successfully executed patch"
  },
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature/ackVersion",
    "value": 4
  },
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature/lastUpdateTime",
    "value": "2020-07-17T06:11:04.9309159Z"
  },
  {
    "op": "add",
    "path": "/thermostat1/targetTemperature",
    "value": 21.8
  }
]

Nota

As mensagens de notificação de alteração dupla são dobradas quando ativadas na notificação de alteração de gêmeos digitais e do dispositivo.

Próximos passos

Agora que você já aprendeu sobre gêmeos digitais, aqui estão mais alguns recursos:

Compreender os duplos digitais Plug and Play do IoT

Gêmeos de dispositivo e gêmeos digitais

Exemplo de JSON gêmeo de dispositivo

Exemplo de gêmeo digital

Propriedades

Propriedade somente leitura

Propriedade gravável

Componentes

APIs de gêmeos digitais

Eventos de alteração de duplos digitais

Próximos passos

Recursos adicionais