Meer informatie over IoT Plug en Play digitale apparaatdubbels
Een IoT Plug en Play-apparaat implementeert een model dat wordt beschreven door het DTDL-schema (Digital Twins Definition Language). Een model beschrijft de set onderdelen, eigenschappen, opdrachten en telemetrieberichten die een bepaald apparaat kan hebben.
Notitie
DTDL is niet exclusief voor IoT-Plug en Play. Andere IoT-services, zoals Azure Digital Twins, gebruiken deze om volledige omgevingen, zoals gebouwen en energienetwerken, weer te geven.
De SDK's van de Azure IoT-service bevatten API's waarmee een service kan communiceren met de digitale dubbel van een apparaat. Een service kan bijvoorbeeld apparaateigenschappen van de digitale dubbel lezen of de digitale dubbel gebruiken om een opdracht op een apparaat aan te roepen. Zie Voorbeelden van digitale dubbels voor IoT Hub voor meer informatie.
In het voorbeeld van Een IoT Plug en Play-apparaat in dit artikel wordt een temperatuurcontrollermodel geïmplementeerd met thermostaatonderdelen.
Apparaatdubbels en digitale dubbels
Naast een digitale dubbel onderhoudt Azure IoT Hub ook een apparaatdubbel voor elk verbonden apparaat. Een apparaatdubbel is vergelijkbaar met een digitale dubbel omdat het een weergave is van de eigenschappen van een apparaat. Een IoT-hub initialiseert een digitale dubbel en een apparaatdubbel de eerste keer dat een IoT-Plug en Play-apparaat wordt ingericht. De SDK's van de Azure IoT-service bevatten API's voor interactie met apparaatdubbels.
Apparaatdubbels zijn JSON-documenten waarin statusinformatie van een apparaat zijn opgeslagen, zoals metagegevens, configuraties en voorwaarden. Zie voorbeelden van ioT Hub-serviceclients voor meer informatie. Apparaat- en oplossingsbouwers kunnen beide dezelfde set API's voor apparaatdubbels en SDK's gebruiken om apparaten en oplossingen te implementeren met behulp van IoT-Plug en Play-conventies. In een apparaatdubbel wordt de status van een beschrijfbare eigenschap verdeeld over de gewenste eigenschappen en gerapporteerde eigenschappensecties. Alle alleen-lezen eigenschappen zijn beschikbaar in de sectie gerapporteerde eigenschappen.
De digital twin-API's werken op DTDL-constructies op hoog niveau, zoals onderdelen, eigenschappen en opdrachten, en maakt het voor ontwikkelaars van oplossingen eenvoudiger om IoT Plug en Play-oplossingen te maken. In een digitale dubbel is er een uniforme weergave van de huidige en gewenste status van de eigenschap. De synchronisatiestatus voor een bepaalde eigenschap wordt opgeslagen in de bijbehorende standaardonderdeelsectie $metadata .
JSON-voorbeeld van apparaatdubbel
In het volgende fragment ziet u een IoT-Plug en Play apparaatdubbel die is opgemaakt als een JSON-object:
{
"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
}
}
}
Voorbeeld van digitale dubbel
In het volgende fragment ziet u de digitale dubbel die is opgemaakt als een JSON-object:
{
"$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"
}
}
}
In de volgende tabel worden de velden in het JSON-object van de digitale dubbel beschreven:
| Veldnaam | Beschrijving |
|---|---|
$dtId |
Een door de gebruiker geleverde tekenreeks die de id van de digitale dubbel van het apparaat vertegenwoordigt. |
{propertyName} |
De waarde van een eigenschap in JSON. |
$metadata.$model |
[Optioneel] De id van de modelinterface die deze digitale dubbel karakteriseert. |
$metadata.{propertyName}.desiredValue |
[Alleen voor schrijfbare eigenschappen] De gewenste waarde van de opgegeven eigenschap. |
$metadata.{propertyName}.desiredVersion |
[Alleen voor schrijfbare eigenschappen] De versie van de gewenste waarde die wordt onderhouden door IoT Hub. |
$metadata.{propertyName}.ackVersion |
[Vereist, alleen voor beschrijfbare eigenschappen] De versie die wordt bevestigd door het apparaat dat de digitale dubbel implementeert, moet deze groter of gelijk zijn aan de gewenste versie. |
$metadata.{propertyName}.ackCode |
[Vereist, alleen voor beschrijfbare eigenschappen] De ack code die wordt geretourneerd door de apparaat-app die de digitale dubbel implementeert. |
$metadata.{propertyName}.ackDescription |
[Optioneel, alleen voor schrijfbare eigenschappen] De ack beschrijving die wordt geretourneerd door de apparaat-app die de digitale dubbel implementeert. |
$metadata.{propertyName}.lastUpdateTime |
IoT Hub onderhoudt de tijdstempel van de laatste update van de eigenschap door het apparaat. De tijdstempels zijn in UTC en gecodeerd in de ISO8601 indeling JJJJ-MM-DDTHH:MM:SS.mmmZ. |
{componentName} |
Een JSON-object met de eigenschapswaarden en metagegevens van het onderdeel. |
{componentName}.{propertyName} |
De waarde van de eigenschap van het onderdeel in JSON. |
{componentName}.$metadata |
De metagegevensinformatie voor het onderdeel. |
Eigenschappen
Eigenschappen zijn gegevensvelden die de status van een entiteit vertegenwoordigen, net zoals de eigenschappen in veel objectgeoriënteerde programmeertalen.
Alleen-lezen eigenschap
DTDL-schema:
{
"@type": "Property",
"name": "serialNumber",
"displayName": "Serial Number",
"description": "Serial number of the device.",
"schema": "string"
}
In dit voorbeeld alwinexlepaho8329 is dit de huidige waarde van de serialNumber eigenschap Alleen-lezen die door het apparaat wordt gerapporteerd.
In de volgende fragmenten ziet u de JSON-weergave naast elkaar van de serialNumber eigenschap:
Apparaatdubbel
"properties": {
"reported": {
"serialNumber": "alwinexlepaho8329"
}
}
Digitale dubbel
"serialNumber": "alwinexlepaho8329"
Beschrijfbare eigenschap
In de volgende voorbeelden ziet u een beschrijfbare eigenschap in het standaardonderdeel.
DTDL:
{
"@type": "Property",
"name": "fanSpeed",
"displayName": "Fan Speed",
"writable": true,
"schema": "double"
}
Apparaatdubbel
{
"properties": {
"desired": {
"fanSpeed": 2.0,
},
"reported": {
"fanSpeed": {
"value": 3.0,
"ac": 200,
"av": 1,
"ad": "Successfully executed patch version 1"
}
}
},
}
Digitale dubbel
{
"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"
}
}
}
In dit voorbeeld 3.0 is dit de huidige waarde van de fanSpeed eigenschap die door het apparaat is gerapporteerd. 2.0 is de gewenste waarde die door de oplossing is ingesteld. De gewenste waarde en synchronisatiestatus van een eigenschap op hoofdniveau worden ingesteld op hoofdniveau $metadata voor een digitale dubbel. Wanneer het apparaat online komt, kan het deze update toepassen en de bijgewerkte waarde rapporteren.
Onderdelen
Met onderdelen kunt u een modelinterface bouwen als een assembly van andere interfaces. De thermostaatinterface kan bijvoorbeeld worden opgenomen als onderdelen thermostat1 en thermostat2 in het modelmodel temperatuurcontroller.
In een apparaatdubbel wordt een onderdeel geïdentificeerd door de { "__t": "c"} markering. In een digitale dubbel markeert de aanwezigheid van $metadata een onderdeel.
In dit voorbeeld thermostat1 is een onderdeel met twee eigenschappen:
maxTempSinceLastRebootis een alleen-lezen eigenschap.targetTemperatureis een beschrijfbare eigenschap die is gesynchroniseerd door het apparaat. De gewenste waarde en synchronisatiestatus van deze eigenschappen bevinden zich in de component$metadata.
In de volgende fragmenten ziet u de JSON-weergave naast elkaar van het thermostat1 onderdeel:
Apparaatdubbel
"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
}
}
Digitale dubbel
"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's voor digitale dubbels
De API's voor digitale dubbels omvatten Get Digital Twin, Update Digital Twin, Invoke Component Command en Invoke Command-bewerkingen voor het beheer van een digitale dubbel. U kunt de REST API's rechtstreeks of via een van de service-SDK's gebruiken.
Gebeurtenissen met wijziging van dubbel
Wanneer digitale gebeurtenissen met wijziging in een dubbel zijn ingeschakeld, wordt een gebeurtenis geactiveerd wanneer de huidige of gewenste waarde van het onderdeel of de eigenschap wordt gewijzigd. Gebeurtenissen voor wijziging van digitale dubbels worden gegenereerd in JSON Patch-indeling . Overeenkomende gebeurtenissen worden gegenereerd in de indeling van de apparaatdubbel als dubbele wijzigingsevenementen zijn ingeschakeld.
Zie IoT Hub-berichtroutering gebruiken om apparaat-naar-cloud-berichten naar verschillende eindpunten te verzenden voor meer informatie over het inschakelen van routering voor apparaat- en digitale dubbelgebeurtenissen. Zie IoT Hub-berichten maken en lezen voor meer informatie over de berichtindeling.
De volgende wijzigingsgebeurtenis voor digitale dubbels wordt bijvoorbeeld geactiveerd wanneer targetTemperature deze wordt ingesteld door de oplossing:
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
}
}
]
De volgende wijzigingsgebeurtenis voor digitale dubbels wordt geactiveerd wanneer het apparaat rapporteert dat de bovenstaande gewenste wijziging is toegepast:
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
}
]
Notitie
Meldingsberichten voor dubbelwijzigingen worden verdubbeld wanneer deze zijn ingeschakeld in meldingen over wijziging van apparaten en digitale dubbels.
Volgende stappen
Nu u meer hebt geleerd over digitale dubbels, vindt u hier nog enkele bronnen: