Compreender os duplos digitais Plug and Play do IoT

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.

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:

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:

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

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

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

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

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

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

Próximos passos

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

• Como usar APIs de gêmeos digitais IoT Plug and Play
• Interaja com um dispositivo a partir da sua solução
• IoT Digital Twin REST API
• Azure IoT explorer