Informazioni sui gemelli digitali Plug and Play IoT

Articolo
02/06/2024

Un dispositivo Plug and Play IoT implementa un modello descritto dallo schema DTDL (Digital Twins Definition Language). Un modello descrive il set di componenti, proprietà, comandi e messaggi di telemetria che un determinato dispositivo può avere.

Nota

DTDL non è esclusivo per Plug and Play IoT. Altri servizi IoT, ad esempio Gemelli digitali di Azure, lo usano per rappresentare interi ambienti, ad esempio edifici e reti energetiche.

Gli SDK del servizio Azure IoT includono API che consentono a un servizio di interagire con il gemello digitale di un dispositivo. Ad esempio, un servizio può leggere le proprietà del dispositivo dal gemello digitale o usare il gemello digitale per chiamare un comando in un dispositivo. Per altre informazioni, vedere hub IoT esempi di gemelli digitali.

L'esempio Plug and Play IoT dispositivo in questo articolo implementa un modello temperature Controller con componenti Termostato.

Dispositivi gemelli e gemelli digitali

Insieme a un gemello digitale, hub IoT di Azure mantiene anche un dispositivo gemello per ogni dispositivo connesso. Un dispositivo gemello è simile a un gemello digitale in quanto è una rappresentazione delle proprietà di un dispositivo. Un hub IoT inizializza un gemello digitale e un dispositivo gemello la prima volta che viene effettuato il provisioning di un dispositivo Plug and Play IoT. Gli SDK del servizio Azure IoT includono API per l'interazione con i dispositivi gemelli.

i dispositivi gemelli sono documenti JSON che archiviano informazioni sullo stato dei dispositivi, tra cui metadati, configurazioni e condizioni. Per altre informazioni, vedere esempi di client del servizio hub IoT. I generatori di dispositivi e soluzioni possono usare entrambi lo stesso set di API del dispositivo gemello e SDK per implementare dispositivi e soluzioni usando convenzioni di Plug and Play IoT. In un dispositivo gemello lo stato di una proprietà scrivibile viene suddiviso tra le proprietà desiderate e le sezioni delle proprietà segnalate. Tutte le proprietà di sola lettura sono disponibili nella sezione delle proprietà segnalate.

Le API del gemello digitale operano su costrutti DTDL di alto livello, ad esempio componenti, proprietà e comandi e semplificano la creazione di soluzioni Plug and Play IoT per i generatori di soluzioni. In un gemello digitale è disponibile una visualizzazione unificata dello stato corrente e desiderato della proprietà. Lo stato di sincronizzazione per una determinata proprietà viene archiviato nella sezione corrispondente del componente $metadata predefinito.

Esempio JSON del dispositivo gemello

Il frammento di codice seguente mostra un dispositivo gemello Plug and Play IoT formattato come oggetto 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
    }
  }
}

Esempio di gemelli digitali

Il frammento di codice seguente mostra il gemello digitale formattato come oggetto 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"
    }
  }
}

La tabella seguente descrive i campi nell'oggetto JSON del gemello digitale:

Nome del campo	Descrizione
`$dtId`	Stringa fornita dall'utente che rappresenta l'ID del dispositivo gemello digitale.
`{propertyName}`	Valore di una proprietà in JSON.
`$metadata.$model`	[Facoltativo] ID dell'interfaccia del modello che caratterizza questo gemello digitale.
`$metadata.{propertyName}.desiredValue`	[Solo per le proprietà scrivibili] Valore desiderato della proprietà specificata.
`$metadata.{propertyName}.desiredVersion`	[Solo per le proprietà scrivibili] Versione del valore desiderato gestito da hub IoT.
`$metadata.{propertyName}.ackVersion`	[Obbligatorio, solo per le proprietà scrivibili] La versione riconosciuta dal dispositivo che implementa il gemello digitale deve essere maggiore o uguale alla versione desiderata.
`$metadata.{propertyName}.ackCode`	[Obbligatorio, solo per le proprietà scrivibili] Codice `ack` restituito dall'app per dispositivi che implementa il gemello digitale.
`$metadata.{propertyName}.ackDescription`	[Facoltativo, solo per le proprietà scrivibili] `ack` Descrizione restituita dall'app per dispositivi che implementa il gemello digitale.
`$metadata.{propertyName}.lastUpdateTime`	hub IoT mantiene il timestamp dell'ultimo aggiornamento della proprietà dal dispositivo. I timestamp sono in formato UTC e codificati nel formato ISO8601 AAAA-MM-GGTHH:MM:SS.mmmZ.
`{componentName}`	Oggetto JSON contenente i valori e i metadati delle proprietà del componente.
`{componentName}.{propertyName}`	Valore della proprietà del componente in JSON.
`{componentName}.$metadata`	Informazioni sui metadati per il componente.

Proprietà

Le proprietà sono campi dati che rappresentano lo stato di un'entità esattamente come le proprietà in molti linguaggi di programmazione orientati agli oggetti.

Proprietà di sola lettura

Schema DTDL:

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

In questo esempio è alwinexlepaho8329 il valore corrente della proprietà di serialNumber sola lettura segnalata dal dispositivo.

I frammenti di codice seguenti mostrano la rappresentazione JSON affiancata della serialNumber proprietà:

Dispositivo gemello

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

Gemello digitale

"serialNumber": "alwinexlepaho8329"

Proprietà scrivibile

Negli esempi seguenti viene mostrata una proprietà scrivibile nel componente predefinito.

DTDL:

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

Dispositivo gemello

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

Gemello digitale

{
"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 questo esempio è 3.0 il valore corrente della fanSpeed proprietà segnalata dal dispositivo. 2.0 è il valore desiderato impostato dalla soluzione. Il valore desiderato e lo stato di sincronizzazione di una proprietà a livello radice viene impostato all'interno del livello $metadata radice per un gemello digitale. Quando il dispositivo viene online, può applicare questo aggiornamento e segnalare il valore aggiornato.

Componenti

I componenti consentono di compilare un'interfaccia del modello come assembly di altre interfacce. Ad esempio, l'interfaccia Thermostat può essere incorporata come componenti thermostat1 e thermostat2 nel modello del modello Temperature Controller.

In un dispositivo gemello un componente viene identificato dal { "__t": "c"} marcatore. In un gemello digitale la presenza di $metadata contrassegna un componente.

In questo esempio è thermostat1 un componente con due proprietà:

maxTempSinceLastReboot è una proprietà di sola lettura.
targetTemperature è una proprietà scrivibile sincronizzata correttamente dal dispositivo. Il valore desiderato e lo stato di sincronizzazione di queste proprietà si trovano nell'oggetto del $metadatacomponente.

I frammenti di codice seguenti mostrano la rappresentazione JSON affiancata del thermostat1 componente:

Dispositivo gemello

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

Gemello digitale

"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 del gemello digitale

Le API del gemello digitale includono Get Digital Twin, Update Digital Twin, Invoke Component Command e Invoke Command operations more managing a digital twin(Ottieni gemello digitale), Update Digital Twin (Aggiorna gemello digitale), Invoke Component Command (Richiama comando componente) e Invoke Command operations more managing a digital twin (Ottieni gemello digitale), Update Digital Twin (Aggiorna gemello digitale), Invoke Component Command (Richiama comando componente) e Invoke Command È possibile usare direttamente le API REST o uno degli SDK del servizio.

Eventi di modifica del gemello digitale

Quando sono abilitati gli eventi di modifica del gemello digitale, viene attivato un evento ogni volta che viene modificato il valore attuale o desiderato del componente o della proprietà. Gli eventi di modifica del gemello digitale vengono generati in formato Patch JSON. Gli eventi corrispondenti vengono generati nel formato del dispositivo gemello se sono abilitati gli eventi di modifica dei dispositivi gemelli.

Per informazioni su come abilitare il routing per gli eventi di dispositivi e gemelli digitali, vedere Usare hub IoT routing dei messaggi per inviare messaggi da dispositivo a cloud a endpoint diversi. Per informazioni sul formato dei messaggi, vedere Creare e leggere hub IoT messaggi.

Ad esempio, l'evento di modifica del gemello digitale seguente viene attivato quando targetTemperature viene impostato dalla soluzione:

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

L'evento di modifica del gemello digitale seguente viene attivato quando il dispositivo segnala che è stata applicata la modifica desiderata precedente:

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

Nota

I messaggi di notifica delle modifiche dei dispositivi gemelli vengono raddoppiati quando sono attivati sia nella notifica di modifica del dispositivo che del gemello digitale.

Passaggi successivi

Dopo aver appreso le informazioni sui gemelli digitali, ecco alcune altre risorse:

Informazioni sui gemelli digitali Plug and Play IoT

Dispositivi gemelli e gemelli digitali

Esempio JSON del dispositivo gemello

Esempio di gemelli digitali

Proprietà

Proprietà di sola lettura

Proprietà scrivibile

Componenti

API del gemello digitale

Eventi di modifica del gemello digitale

Passaggi successivi

Risorse aggiuntive