Informazioni sui gemelli digitali Plug and Play IoT

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.

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:

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à:

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

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

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

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

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

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

Passaggi successivi

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

• Come usare Plug and Play IoT API del gemello digitale
• Interagire con un dispositivo dalla soluzione
• API REST di Gemelli digitali IoT
• Azure IoT Explorer