Zrozumienie cyfrowych bliźniaków IoT Plug and Play

Urządzenie IoT Plug and Play implementuje model opisany w schemacie Digital Twins Definition Language (DTDL). Model opisuje zestaw składników, właściwości, poleceń i komunikatów telemetrycznych, które może mieć określone urządzenie.

Zestawy SDK usługi Azure IoT obejmują interfejsy API, które umożliwiają usłudze interakcję z cyfrową reprezentacją bliźniaczą urządzenia. Na przykład usługa może odczytywać właściwości urządzenia z cyfrowej reprezentacji bliźniaczej lub używać cyfrowej reprezentacji bliźniaczej do wywoływania polecenia na urządzeniu. Aby dowiedzieć się więcej, zobacz Przykłady cyfrowej reprezentacji bliźniaczej usługi IoT Hub.

Przykładowe urządzenie IoT Plug and Play w tym artykule implementuje model kontrolera temperatury , który zawiera składniki termostatu .

Bliźniak urządzenia i cyfrowy bliźniak

Oprócz cyfrowego bliźniaka, usługa Azure IoT Hub obsługuje również bliźniaka urządzenia dla każdego połączonego urządzenia. Bliźniaczy model urządzenia jest podobny do cyfrowego bliźniaka, ponieważ jest to reprezentacja właściwości urządzenia. Centrum IoT inicjuje cyfrowego bliźniaka i bliźniaka urządzenia przy pierwszej aprowizacji urządzenia IoT Plug and Play. Zestawy SDK Azure IoT obejmują interfejsy API do interakcji z bliźniaczymi urządzeniami.

Bliźniaki urządzenia to dokumenty JSON, które przechowują informacje o stanie urządzenia, takie jak metadane, konfiguracje i warunki. Aby dowiedzieć się więcej, zobacz Przykłady klientów usługi IoT Hub. Konstruktorzy urządzeń i rozwiązań mogą używać tego samego zestawu interfejsów programistycznych API bliźniaków urządzeń i zestawów SDK do implementowania urządzeń i rozwiązań, zachowując konwencje IoT Plug and Play. W bliźniaczej reprezentacji urządzenia stan właściwości zapisywalnej jest podzielony na sekcje żądanych właściwości i zgłoszonych właściwości. Wszystkie właściwości tylko do odczytu są dostępne w sekcji zgłoszonych właściwości.

Interfejsy API cyfrowych bliźniaków działają na konstrukcjach DTDL wysokiego poziomu, takich jak składniki, właściwości i polecenia, co ułatwia konstruktorom tworzenie rozwiązań IoT Plug and Play. W cyfrowym bliźniaku istnieje ujednolicony widok bieżącego i żądanego stanu obiektu. Stan synchronizacji dla danej właściwości jest przechowywany w odpowiedniej sekcji składnika $metadata domyślnego.

Przykładowy kod JSON bliźniaczej reprezentacji urządzenia

Poniższy fragment pokazuje bliźniaczy model urządzenia IoT Plug and Play sformatowane jako obiekt 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
    }
  }
}

Przykład cyfrowego bliźniaka

Poniższy fragment kodu przedstawia cyfrowy bliźniak sformatowany jako obiekt 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"
    }
  }
}

Poniższa tabela opisuje pola w obiekcie JSON cyfrowego bliźniaka:

Właściwości

Właściwości to pola danych, które reprezentują stan jednostki, podobnie jak właściwości w wielu językach programowania obiektowego.

Właściwość tylko do odczytu

Schemat DTDL:

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

W tym przykładzie alwinexlepaho8329 jest bieżącą wartością właściwości tylko do odczytu serialNumber, zgłoszoną przez urządzenie.

Następujące fragmenty pokazują porównawczo reprezentację JSON właściwości serialNumber.

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

"serialNumber": "alwinexlepaho8329"

Właściwość zapisywalna

W poniższych przykładach przedstawiono właściwość zapisywalną w składniku domyślnym.

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

W tym przykładzie 3.0 jest bieżącą wartością fanSpeed właściwości zgłoszonej przez urządzenie. 2.0 to żądana wartość ustawiona przez rozwiązanie. Żądana wartość i stan synchronizacji właściwości na poziomie głównym jest ustawiana na poziomie $metadata głównym dla cyfrowej reprezentacji bliźniaczej. Gdy urządzenie jest w trybie online, może zastosować tę aktualizację i zgłosić zaktualizowaną wartość.

Składniki

Składniki umożliwiają tworzenie interfejsu modelu jako zestawu innych interfejsów. Na przykład interfejs termostatu można włączyć jako składniki thermostat1 i thermostat2 w modelu kontrolera temperatury .

W bliźniaczym modelu urządzenia znacznik { "__t": "c"} identyfikuje składnik. W cyfrowym bliźniaku obecność $metadata oznacza składnik.

W tym przykładzie thermostat1 jest składnikiem z dwiema właściwościami:

• maxTempSinceLastReboot jest właściwością tylko do odczytu.
• targetTemperature to właściwość zapisywalna, która została pomyślnie zsynchronizowana przez urządzenie. Żądana wartość i stan synchronizacji tych właściwości znajdują się w składniku $metadata.

Następujące fragmenty pokazują równoległą reprezentację składnika thermostat1 w formacie JSON.

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

Interfejsy API cyfrowych bliźniaków

Interfejsy API cyfrowej reprezentacji bliźniaczej obejmują operacje Get Digital Twin, Update Digital Twin, Invoke Component Command (Wywoływanie składnika ) i Invoke Command (Wywoływanie poleceń ) na potrzeby zarządzania cyfrową reprezentacją bliźniaczą. Interfejsy API REST można używać bezpośrednio lub za pomocą jednego z zestawów SDK usługi.

Zdarzenia zmiany bliźniaka cyfrowego

W przypadku włączenia zdarzeń zmiany cyfrowej reprezentacji zdarzenie jest wyzwalane za każdym razem, gdy bieżąca lub żądana wartość składnika lub właściwości zostanie zmieniona. Zdarzenia zmiany cyfrowego bliźniaka są generowane w formacie poprawki JSON. Odpowiednie zdarzenia są generowane w formacie bliźniaczej reprezentacji urządzenia, jeśli są włączone zdarzenia zmiany bliźniaczej.

Aby dowiedzieć się, jak włączyć routing dla zdarzeń dotyczących urządzeń i cyfrowych bliźniaków, zobacz Używanie routingu komunikatów usługi IoT Hub w celu wysyłania komunikatów z urządzenia do chmury do różnych punktów końcowych. Aby zrozumieć format komunikatu, zobacz Tworzenie i odczytywanie komunikatów usługi IoT Hub.

Na przykład następujące zdarzenie zmiany cyfrowej reprezentacji bliźniaczej jest wyzwalane, gdy rozwiązanie ustawia targetTemperature wartość:

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

Następujące zdarzenie zmiany cyfrowego bliźniaka jest wyzwalane, gdy urządzenie zgłasza, że poprzednia żądana zmiana została zastosowana.

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