Entenda os gêmeos digitais IoT Plug and Play

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 de serviço do Azure IoT 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 quando um dispositivo IoT Plug and Play é provisionado pela primeira vez. 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 escriturável é dividido entre as propriedades desejadas e as propriedades relatadas. Todas as propriedades somente leitura estão disponíveis na seção das 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 de leitura apenas, conforme relatado 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, o { "__t": "c"} marcador identifica um componente. 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 destas propriedades estão no componente $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 para gerenciar 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 gémeos digitais

Quando os eventos de alteração de gémeos digitais estão ativados, um evento é acionado 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 a solução define um targetTemperature valor:

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 informa que a alteração desejada anterior 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
  }
]