Lär dig mer om digitala tvillingar i IoT Plug and Play

Artikel
02/06/2024

En IoT Plug and Play-enhet implementerar en modell som beskrivs av DTDL-schemat (Digital Twins Definition Language). En modell beskriver den uppsättning komponenter, egenskaper, kommandon och telemetrimeddelanden som en viss enhet kan ha.

Kommentar

DTDL är inte exklusivt för IoT Plug and Play. Andra IoT-tjänster, till exempel Azure Digital Twins, använder det för att representera hela miljöer som byggnader och energinät.

Azure IoT-tjänstens SDK:er innehåller API:er som gör att en tjänst kan interagera med en enhets digitala tvilling. En tjänst kan till exempel läsa enhetsegenskaper från den digitala tvillingen eller använda den digitala tvillingen för att anropa ett kommando på en enhet. Mer information finns i exempel på digitala IoT Hub-tvillingar.

Exempelenheten IoT Plug and Play i den här artikeln implementerar en temperaturstyrenhetsmodell som har termostatkomponenter .

Enhetstvillingar och digitala tvillingar

Tillsammans med en digital tvilling har Azure IoT Hub även en enhetstvilling för varje ansluten enhet. En enhetstvilling liknar en digital tvilling eftersom det är en representation av en enhets egenskaper. En IoT-hubb initierar en digital tvilling och en enhetstvilling första gången en IoT Plug and Play-enhet etableras. Azure IoT-tjänstens SDK:er innehåller API:er för att interagera med enhetstvillingar.

Enhetstvillingar är JSON-dokument som lagrar information om enhetstillstånd, som metadata, konfigurationer och villkor. Mer information finns i IoT Hub-tjänstklientexempel. Både enhets- och lösningsbyggare kan använda samma uppsättning API:er och SDK:er för enhetstvillingar för att implementera enheter och lösningar med hjälp av IoT Plug and Play-konventioner. I en enhetstvilling delas tillståndet för en skrivbar egenskap upp i de önskade egenskaperna och rapporterade egenskapsavsnitt . Alla skrivskyddade egenskaper är tillgängliga i avsnittet rapporterade egenskaper.

API:erna för digitala tvillingar fungerar på högnivå-DTDL-konstruktioner som komponenter, egenskaper och kommandon och gör det enklare för lösningsbyggare att skapa IoT Plug and Play-lösningar. I en digital tvilling finns det en enhetlig vy över egenskapens aktuella och önskade tillstånd. Synkroniseringstillståndet för en viss egenskap lagras i motsvarande standardkomponentavsnitt $metadata .

JSON-exempel för enhetstvilling

Följande kodfragment visar en IoT Plug and Play-enhetstvilling formaterad som ett JSON-objekt:

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

Exempel på digital tvilling

Följande kodfragment visar den digitala tvillingen formaterad som ett JSON-objekt:

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

I följande tabell beskrivs fälten i JSON-objektet för den digitala tvillingen:

Fältnamn	beskrivning
`$dtId`	En användaranvändarsträng som representerar ID:t för enhetens digitala tvilling.
`{propertyName}`	Värdet för en egenskap i JSON.
`$metadata.$model`	[Valfritt] ID:t för modellgränssnittet som kännetecknar den här digitala tvillingen.
`$metadata.{propertyName}.desiredValue`	[Endast för skrivbara egenskaper] Önskat värde för den angivna egenskapen.
`$metadata.{propertyName}.desiredVersion`	[Endast för skrivbara egenskaper] Den version av det önskade värdet som underhålls av IoT Hub.
`$metadata.{propertyName}.ackVersion`	[Krävs, endast för skrivbara egenskaper] Den version som bekräftas av enheten som implementerar den digitala tvillingen måste vara större eller lika med önskad version.
`$metadata.{propertyName}.ackCode`	[Krävs, endast för skrivbara egenskaper] Koden `ack` som returneras av enhetsappen som implementerar den digitala tvillingen.
`$metadata.{propertyName}.ackDescription`	[Valfritt, endast för skrivbara egenskaper] Beskrivningen `ack` som returneras av enhetsappen som implementerar den digitala tvillingen.
`$metadata.{propertyName}.lastUpdateTime`	IoT Hub underhåller tidsstämpeln för den senaste uppdateringen av egenskapen av enheten. Tidsstämplarna är i UTC och kodade i ISO8601 format YYYY-MM-DDTHH:MM:SS.mmmZ.
`{componentName}`	Ett JSON-objekt som innehåller komponentens egenskapsvärden och metadata.
`{componentName}.{propertyName}`	Värdet för komponentens egenskap i JSON.
`{componentName}.$metadata`	Metadatainformationen för komponenten.

Egenskaper

Egenskaper är datafält som representerar tillståndet för en entitet precis som egenskaperna i många objektorienterade programmeringsspråk.

Skrivskyddad egenskap

DTDL-schema:

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

I det här exemplet alwinexlepaho8329 är det aktuella värdet för den serialNumber skrivskyddade egenskapen som rapporterats av enheten.

Följande kodfragment visar JSON-representationen sida vid sida för serialNumber egenskapen:

Enhetstvilling

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

Digital tvilling

"serialNumber": "alwinexlepaho8329"

Skrivbar egenskap

I följande exempel visas en skrivbar egenskap i standardkomponenten.

DTDL:

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

Enhetstvilling

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

Digital tvilling

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

I det här exemplet 3.0 är det aktuella värdet för egenskapen som fanSpeed rapporterats av enheten. 2.0 är det önskade värdet som anges av lösningen. Önskat värde och synkroniseringstillstånd för en rotnivåegenskap anges inom rotnivå $metadata för en digital tvilling. När enheten är online kan den tillämpa den här uppdateringen och rapportera tillbaka det uppdaterade värdet.

Komponenter

Med komponenter kan du skapa ett modellgränssnitt som en sammansättning av andra gränssnitt. Termostatgränssnittet kan till exempel införlivas som komponenter thermostat1 och thermostat2 i modellmodellen Temperaturstyrenhet.

I en enhetstvilling identifieras en komponent av { "__t": "c"} markören. I en digital tvilling markerar förekomsten av $metadata en komponent.

I det här exemplet thermostat1 är en komponent med två egenskaper:

maxTempSinceLastReboot är en skrivskyddad egenskap.
targetTemperature är en skrivbar egenskap som har synkroniserats av enheten. Det önskade värdet och synkroniseringstillståndet för dessa egenskaper finns i komponentens $metadata.

Följande kodfragment visar JSON-representationen sida vid sida för komponenten thermostat1 :

Enhetstvilling

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

Digital tvilling

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

API:er för digital tvilling

Api:erna för digitala tvillingar inkluderar Get Digital Twin, Update Digital Twin, Invoke Component Command och Invoke Command operations more managing a digital twin (Hämta digital tvilling), Update Digital Twin (Uppdatera digital tvilling), Invoke Component Command (Anropa komponentkommando ) och Invoke Command (Anropa kommandoåtgärder ) som mer hanterar en digital tvilling. Du kan antingen använda REST-API:erna direkt eller via någon av tjänst-SDK:erna.

Ändringshändelser för digitala tvillingar

När ändringshändelser för digitala tvillingar är aktiverat utlöses en händelse när komponentens eller egenskapens aktuella eller önskade värde ändras. Ändringshändelser för digitala tvillingar genereras i JSON Patch-format . Motsvarande händelser genereras i enhetstvillingformatet om tvillingändringshändelser är aktiverade.

Information om hur du aktiverar routning för enhets- och digitala tvillinghändelser finns i Använda IoT Hub-meddelanderoutning för att skicka meddelanden från enhet till moln till olika slutpunkter. Information om meddelandeformatet finns i Skapa och läsa IoT Hub-meddelanden.

Till exempel utlöses följande ändringshändelse för digitala tvillingar när targetTemperature den anges av lösningen:

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

Följande ändringshändelse för digitala tvillingar utlöses när enheten rapporterar att den önskade ändringen ovan tillämpades:

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

Kommentar

Meddelanden om dubbla ändringsmeddelanden fördubblas när de aktiveras i ändringsmeddelandet för både enhet och digital tvilling.

Nästa steg

Nu när du har lärt dig mer om digitala tvillingar finns här några fler resurser:

Lär dig mer om digitala tvillingar i IoT Plug and Play

Enhetstvillingar och digitala tvillingar

JSON-exempel för enhetstvilling

Exempel på digital tvilling

Egenskaper

Skrivskyddad egenskap

Skrivbar egenskap

Komponenter

API:er för digital tvilling

Ändringshändelser för digitala tvillingar

Nästa steg

Ytterligare resurser