Interpretacja bliźniaczej reprezentacji urządzenia IoT Plug and Play

Artykuł
02/06/2024

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.

Uwaga

Język DTDL nie jest wyłączny dla usługi IoT Plug and Play. Inne usługi IoT, takie jak Azure Digital Twins, używają ich do reprezentowania całych środowisk, takich jak budynki i sieci energetyczne.

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źniacze reprezentacje urządzeń i cyfrowe reprezentacje bliźniacze

Oprócz cyfrowej reprezentacji bliźniaczej usługa Azure IoT Hub obsługuje również bliźniacze reprezentacje urządzenia dla każdego połączonego urządzenia. Bliźniacze reprezentacje urządzenia są podobne do cyfrowej reprezentacji bliźniaczej, ponieważ są to reprezentacje właściwości urządzenia. Centrum IoT inicjuje cyfrową reprezentację bliźniaczą i bliźniaczkę urządzenia po raz pierwszy aprowizowania urządzenia IoT Plug and Play. Zestawy SDK usługi Azure IoT obejmują interfejsy API do interakcji z bliźniaczymi reprezentacjami urządzeń.

Bliźniacze reprezentacje urządzeń 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 API bliźniaczych reprezentacji urządzeń i zestawów SDK do implementowania urządzeń i rozwiązań przy użyciu konwencji IoT Plug and Play. W bliźniaczej reprezentacji urządzenia stan właściwości zapisywalnej jest podzielony na żądane właściwości i zgłoszone sekcje 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 cyfrowej reprezentacji bliźniaczej działają na konstrukcjach DTDL wysokiego poziomu, takich jak składniki, właściwości i polecenia oraz ułatwiają konstruktorom rozwiązań tworzenie rozwiązań IoT Plug and Play. W cyfrowej reprezentacji bliźniaczej istnieje ujednolicony widok bieżącego i żądanego stanu właściwości. 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 kodu przedstawia bliźniacze reprezentacje 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 cyfrowej reprezentacji bliźniaczej

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

W poniższej tabeli opisano pola w obiekcie JSON cyfrowej reprezentacji bliźniaczej:

Nazwa pola	opis
`$dtId`	Ciąg dostarczony przez użytkownika reprezentujący identyfikator cyfrowej reprezentacji bliźniaczej urządzenia.
`{propertyName}`	Wartość właściwości w formacie JSON.
`$metadata.$model`	[Opcjonalnie] Identyfikator interfejsu modelu, który charakteryzuje tę cyfrową reprezentację bliźniaczą.
`$metadata.{propertyName}.desiredValue`	[Tylko dla właściwości zapisywalnych] Żądana wartość określonej właściwości.
`$metadata.{propertyName}.desiredVersion`	[Tylko dla właściwości zapisywalnych] Wersja żądanej wartości obsługiwanej przez usługę IoT Hub.
`$metadata.{propertyName}.ackVersion`	[Wymagane, tylko dla właściwości zapisywalnych] Wersja potwierdzona przez urządzenie wdrażające cyfrową reprezentację bliźniaczą musi być większa lub równa żądanej wersji.
`$metadata.{propertyName}.ackCode`	[Wymagane, tylko dla właściwości zapisywalnych] `ack` Kod zwrócony przez aplikację urządzenia wdrażającą cyfrową reprezentację bliźniaczą.
`$metadata.{propertyName}.ackDescription`	[Opcjonalne, tylko dla właściwości zapisywalnych] `ack` Opis zwrócony przez aplikację urządzenia wdrażającą cyfrową reprezentację bliźniaczą.
`$metadata.{propertyName}.lastUpdateTime`	Usługa IoT Hub utrzymuje znacznik czasu ostatniej aktualizacji właściwości przez urządzenie. Znaczniki czasu są w formacie UTC i zakodowane w formacie ISO8601 RRRR-MM-DDTHH:MM:SS.mmmZ.
`{componentName}`	Obiekt JSON zawierający wartości właściwości i metadane składnika.
`{componentName}.{propertyName}`	Wartość właściwości składnika w formacie JSON.
`{componentName}.$metadata`	Informacje o metadanych składnika.

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ą serialNumber właściwości tylko do odczytu zgłoszonej przez urządzenie.

Następujące fragmenty kodu pokazują obok siebie reprezentację serialNumber JSON właściwości:

Bliźniacze reprezentacje urządzenia

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

Reprezentacja bliźniaków cyfrowych

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

Bliźniacze reprezentacje urządzenia

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

Reprezentacja bliźniaków cyfrowych

{
"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ść.

Elementy

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

W bliźniaczej reprezentacji urządzenia składnik jest identyfikowany przez { "__t": "c"} znacznik. W cyfrowej reprezentacji bliźniaczej 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 kodu pokazują obok siebie reprezentację thermostat1 kodu JSON składnika:

Bliźniacze reprezentacje urządzenia

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

Reprezentacja bliźniaków cyfrowych

"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 cyfrowej reprezentacji bliźniaczej

Interfejsy API cyfrowej reprezentacji bliźniaczej to Get Digital Twin, Update Digital Twin, Invoke Component Command and Invoke Command (Wywoływanie poleceń) operacje 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 cyfrowej reprezentacji bliźniaczej

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

Aby dowiedzieć się, jak włączyć routing dla zdarzeń urządzenia i cyfrowej reprezentacji bliźniaczej, 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 po targetTemperature ustawieniu przez rozwiązanie:

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 cyfrowej reprezentacji bliźniaczej jest wyzwalane, gdy urządzenie zgłasza, że zastosowano powyżej żądaną zmianę:

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

Uwaga

Komunikaty powiadomień o zmianie bliźniaczej reprezentacji bliźniaczej są dwukrotnie włączone zarówno w powiadomieniu o zmianie reprezentacji urządzenia, jak i cyfrowej reprezentacji bliźniaczej.

Następne kroki

Teraz, gdy znasz już cyfrowe reprezentacje bliźniacze, oto kilka dodatkowych zasobów:

Interpretacja bliźniaczej reprezentacji urządzenia IoT Plug and Play

Bliźniacze reprezentacje urządzeń i cyfrowe reprezentacje bliźniacze

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

Przykład cyfrowej reprezentacji bliźniaczej

Właściwości

Właściwość tylko do odczytu

Właściwość zapisywalna

Elementy

Interfejsy API cyfrowej reprezentacji bliźniaczej

Zdarzenia zmiany cyfrowej reprezentacji bliźniaczej

Następne kroki

Dodatkowe zasoby