Az IoT Plug and Play digitális ikreinek ismertetése

Cikk
02/06/2024

Az IoT Plug and Play-eszközök a Digital Twins Definition Language (DTDL) sémája által leírt modellt implementálják. A modell leírja azokat az összetevőket, tulajdonságokat, parancsokat és telemetriai üzeneteket, amelyekkel egy adott eszköz rendelkezhet.

Feljegyzés

A DTDL nem kizárólagos az IoT Plug and Play szolgáltatásban. Más IoT-szolgáltatások, például az Azure Digital Twins teljes környezetek, például épületek és energiahálózatok megjelenítésére használják.

Az Azure IoT szolgáltatás SDK-jai olyan API-kat tartalmaznak, amelyek lehetővé teszik egy szolgáltatás számára az eszköz digitális ikerpéldányának használatát. Egy szolgáltatás például beolvassa az eszköz tulajdonságait a digitális ikerpéldányból, vagy a digitális ikerpéldány használatával meghívhat egy parancsot egy eszközön. További információkért lásd az IoT Hub digitális ikerpéldányainak példáit.

A cikkben szereplő IoT Plug and Play-eszköz egy hőmérséklet-vezérlő modellt implementál, amely termosztát-összetevőkkel rendelkezik.

Ikereszközök és digitális ikerpéldányok

A digitális ikerpéldány mellett az Azure IoT Hub minden csatlakoztatott eszközhöz is fenntart egy ikereszközt . Az ikereszköz hasonló a digitális ikerpéldányhoz, mivel az egy eszköz tulajdonságainak ábrázolása. Az IoT Hub inicializál egy digitális ikerpéldányt és egy ikereszközt az IoT Plug and Play-eszköz első üzembe helyezésekor. Az Azure IoT szolgáltatás SDK-jai az ikereszközökkel való interakcióhoz használható API-kat tartalmaznak.

Az ikereszközök JSON-dokumentumok, amelyek az eszközök állapotinformációit, például a metaadatokat, konfigurációkat és állapotokat tárolják. További információkért tekintse meg az IoT Hub szolgáltatás ügyfél-példáit. Az eszköz- és megoldáskészítők ugyanazt az ikereszköz API-kat és SDK-kat használhatják az eszközök és megoldások IoT Plug and Play-konvenciók használatával történő implementálásához. Az ikereszközön a írható tulajdonság állapota fel van osztva a kívánt tulajdonságok és a jelentett tulajdonságok szakaszai között. Az összes írásvédett tulajdonság elérhető a jelentett tulajdonságok szakaszban.

A digitális iker API-k olyan magas szintű DTDL-szerkezeteken működnek, mint az összetevők, tulajdonságok és parancsok, és megkönnyítik a megoldáskészítők számára az IoT Plug and Play-megoldások létrehozását. Egy digitális ikerpéldányban egységes nézet látható a tulajdonság aktuális és kívánt állapotáról. Egy adott tulajdonság szinkronizálási állapotát a megfelelő alapértelmezett összetevőszakasz $metadata tárolja.

Példa ikereszköz JSON-ra

Az alábbi kódrészlet egy JSON-objektumként formázott IoT Plug and Play-eszközt mutat be:

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

Példa digitális ikerpéldányra

Az alábbi kódrészlet a JSON-objektumként formázott digitális ikerpéldányt mutatja be:

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

Az alábbi táblázat a digitális ikerpéldány JSON-objektumának mezőit ismerteti:

Mező neve	Leírás
`$dtId`	Egy felhasználó által megadott sztring, amely az eszköz digitális ikereszközének azonosítóját jelöli.
`{propertyName}`	Egy tulajdonság értéke a JSON-ban.
`$metadata.$model`	[Nem kötelező] A digitális ikerpéldányt jellemző modellfelület azonosítója.
`$metadata.{propertyName}.desiredValue`	[Csak írható tulajdonságok esetén] A megadott tulajdonság kívánt értéke.
`$metadata.{propertyName}.desiredVersion`	[Csak írható tulajdonságok esetén] Az IoT Hub által fenntartott kívánt érték verziója.
`$metadata.{propertyName}.ackVersion`	[Kötelező, csak írható tulajdonságokhoz] A digitális ikerpéldányt megvalósító eszköz által elismert verziónak nagyobb vagy egyenlőnek kell lennie a kívánt verzióval.
`$metadata.{propertyName}.ackCode`	[Kötelező, csak írható tulajdonságokhoz] A `ack` digitális ikerpéldányt implementáló eszközalkalmazás által visszaadott kód.
`$metadata.{propertyName}.ackDescription`	[Nem kötelező, csak írható tulajdonságok esetén] A `ack` digitális ikerpéldányt implementáló eszközalkalmazás által visszaadott leírás.
`$metadata.{propertyName}.lastUpdateTime`	Az IoT Hub fenntartja a tulajdonság utolsó frissítésének időbélyegét az eszközön. Az időbélyegek UTC-ben vannak, és ISO8601 YYYY-MM-DDTHH:MM:SS.mmmZ formátumban vannak kódolva.
`{componentName}`	Az összetevő tulajdonságértékeit és metaadatait tartalmazó JSON-objektum.
`{componentName}.{propertyName}`	Az összetevő tulajdonságának értéke a JSON-ban.
`{componentName}.$metadata`	Az összetevő metaadatai.

Tulajdonságok

A tulajdonságok olyan adatmezők, amelyek egy entitás állapotát képviselik, ugyanúgy, mint számos objektumorientált programozási nyelv tulajdonságai.

Írásvédett tulajdonság

DTDL-séma:

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

Ebben a példában alwinexlepaho8329 az eszköz által jelentett írásvédett tulajdonság aktuális értéke serialNumber .

Az alábbi kódrészletek a tulajdonság egymás melletti JSON-ábrázolását serialNumber mutatják:

Ikereszköz

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

Digitális ikerpéldány

"serialNumber": "alwinexlepaho8329"

Írható tulajdonság

Az alábbi példák egy írható tulajdonságot mutatnak be az alapértelmezett összetevőben.

DTDL:

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

Ikereszköz

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

Digitális ikerpéldány

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

Ebben a példában 3.0 az eszköz által jelentett tulajdonság aktuális értéke fanSpeed . 2.0 a megoldás által beállított kívánt érték. A gyökérszintű tulajdonság kívánt értéke és szinkronizálási állapota a digitális ikerpéldány gyökérszintén $metadata belül van beállítva. Amikor az eszköz online állapotba kerül, alkalmazhatja ezt a frissítést, és jelentést készíthet a frissített értékről.

Összetevők

Az összetevők lehetővé teszik a modell felületének összeállítását más felületek szerelvényeként. A Termosztát interfész például összetevőkként thermostat1 és thermostat2 a Hőmérséklet-vezérlő modellmodellben is beépíthető.

Az ikereszközben a jelölő azonosítja az összetevőt { "__t": "c"} . Egy digitális ikerpéldányban az összetevők jelenléte $metadata jelzi.

Ebben a példában thermostat1 egy összetevő két tulajdonsággal rendelkezik:

maxTempSinceLastReboot írásvédett tulajdonság.
targetTemperature egy írható tulajdonság, amelyet az eszköz sikeresen szinkronizált. Ezeknek a tulajdonságoknak a kívánt értéke és szinkronizálási állapota az összetevőben $metadatatalálható.

Az alábbi kódrészletek az összetevő egymás melletti JSON-ábrázolását thermostat1 mutatják:

Ikereszköz

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

Digitális ikerpéldány

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

Digitális iker API-k

A digitális ikerpéldány API-k közé tartozik a Get Digital Twin, a Digital Twin frissítése, a Komponens parancs meghívása és a Parancs meghívása művelet, amely jobban kezeli a digitális ikerpéldányt. A REST API-kat közvetlenül vagy a szolgáltatás SDK-k egyikén keresztül is használhatja.

Digitális ikermódosítási események

Ha a digitális iker módosítási eseményei engedélyezve vannak, az esemény akkor aktiválódik, amikor az összetevő vagy a tulajdonság aktuális vagy kívánt értéke megváltozik. A digitális ikerpéldány-változási események JSON Patch formátumban jönnek létre. A megfelelő események ikereszköz-formátumban jönnek létre, ha engedélyezve vannak az ikermódosítási események.

Az eszköz- és digitális ikeresemények útválasztásának engedélyezéséről az IoT Hub üzenet-útválasztásának használata az eszközről a felhőbe irányuló üzenetek különböző végpontokra való küldéséhez című témakörben olvashat. Az üzenetformátum megismeréséhez tekintse meg az IoT Hub-üzenetek létrehozását és olvasását.

Például a következő digitális ikerpéldány-változási esemény aktiválódik, amikor targetTemperature a megoldás beállítja:

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

A következő digitális ikerpéldány-változási esemény akkor aktiválódik, amikor az eszköz a fenti kívánt módosítás alkalmazását jelenti:

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

Feljegyzés

Az ikerpéldány változásértesítési üzenetei az eszköz és a digitális ikerpéldány változásértesítésének bekapcsolásakor megkétszereződnek.

Következő lépések

Most, hogy megismerkedett a digitális ikerpéldányokkal, íme néhány további forrás:

Share via

Az IoT Plug and Play digitális ikreinek ismertetése

Ikereszközök és digitális ikerpéldányok

Példa ikereszköz JSON-ra

Példa digitális ikerpéldányra

Tulajdonságok

Írásvédett tulajdonság

Írható tulajdonság

Összetevők

Digitális iker API-k

Digitális ikermódosítási események

Következő lépések

További források