Memahami kembar digital IoT Plug and Play

Artikel
02/06/2024

Perangkat IoT Plug and Play mengimplementasikan model yang didefinisikan oleh skema Digital Twins Definition Language (DTDL). Model menjelaskan sekumpulan komponen, properti, perintah, dan pesan telemetri yang dapat digunakan perangkat tertentu.

Catatan

DTDL tidak eksklusif untuk IoT Plug and Play. Layanan IoT lainnya, seperti Azure Digital Twins, menggunakannya untuk mewakili seluruh lingkungan seperti jaringan pembangunan dan jaringan energi.

SDK layanan Azure IoT mencakup API yang memungkinkan layanan berinteraksi dengan digital twin perangkat. Misalnya, sebuah layanan dapat membaca properti perangkat dari digital twin atau menggunakan digital twin untuk memanggil perintah pada perangkat. Untuk mempelajari lebih lanjut, lihat contoh digital twin IoT Hub.

Perangkat IoT Plug and Play yang digunakan sebagai contoh dalam artikel ini mengimplementasikan model Pengontrol Suhu dengan komponen Thermostat.

Device twin dan digital twin

Bersama dengan kembar digital, Azure IoT Hub juga mempertahankan kembar perangkat untuk setiap perangkat yang terhubung. Device twin mirip dengan digital twin karena merupakan representasi dari properti perangkat. Hub IoT menginisialisasi kembar digital dan perangkat kembar saat pertama kali perangkat IoT Plug and Play disediakan. SDK layanan Azure IoT mencakup API untuk berinteraksi dengan device twin.

Kembaran perangkat adalah dokumen JSON yang menyimpan informasi status perangkat termasuk metadata, konfigurasi, dan kondisi. Untuk mempelajari lebih lanjut, lihat contoh klien layanan IoT Hub. Penyusun perangkat dan solusi dapat menggunakan set API dan SDK kembar perangkat yang sama untuk mengimplementasikan perangkat dan solusi menggunakan konvensi IoT Plug and Play. Di device twin, status properti bisa-tulis dibagi di seluruh properti yang diinginkan dan bagian properti yang dilaporkan. Semua properti baca-saja tersedia di dalam bagian properti yang dilaporkan.

API kembar digital beroperasi pada konstruksi DTDL tingkat tinggi seperti komponen, properti, dan perintah dan memudahkan penyusun solusi untuk membuat solusi IoT Plug and Play. Di digital twin, ada tampilan terpadu tentang status properti saat ini dan yang diinginkan. Status sinkronisasi untuk properti tertentu disimpan di bagian $metadata komponen default terkait.

Contoh JSON device twin

Cuplikan berikut menunjukkan device twin IoT Plug and Play yang diformat sebagai objek 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
    }
  }
}

Contoh digital twin

Cuplikan berikut menunjukkan digital twin yang diformat sebagai objek 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"
    }
  }
}

Tabel berikut menguraikan bidang-bidang di objek JSON digital twin:

Nama bidang	Deskripsi
`$dtId`	String yang disediakan pengguna yang mewakili ID perangkat kembar digital.
`{propertyName}`	Nilai properti di JSON.
`$metadata.$model`	[Opsional] ID antarmuka model yang mencirikan kembar digital ini.
`$metadata.{propertyName}.desiredValue`	[Hanya untuk properti bisa-tulis] Nilai yang diinginkan dari properti yang ditentukan.
`$metadata.{propertyName}.desiredVersion`	[Hanya untuk properti bisa-tulis] Versi nilai yang diinginkan dikelola oleh IoT Hub.
`$metadata.{propertyName}.ackVersion`	[Diperlukan, hanya untuk properti bisa-tulis] Versi yang diakui oleh perangkat yang mengimplementasikan kembar digital, harus dengan versi yang lebih besar atau sama dengan yang diinginkan.
`$metadata.{propertyName}.ackCode`	[Diperlukan, hanya untuk properti bisa-tulis] Kode `ack` yang dikembalikan oleh aplikasi perangkat yang mengimplementasikan kembar digital.
`$metadata.{propertyName}.ackDescription`	[Opsional, hanya untuk properti bisa-tulis] Deskripsi `ack` yang dikembalikan oleh aplikasi perangkat yang mengimplementasikan kembar digital.
`$metadata.{propertyName}.lastUpdateTime`	IoT Hub mempertahankan tanda waktu pembaruan terakhir properti oleh perangkat. Tanda waktu dalam UTC dan dikodekan dalam format ISO8601 YYYY-MM-DDTHH:MM:SS.mmmZ.
`{componentName}`	Objek JSON yang berisi nilai dan metadata properti komponen.
`{componentName}.{propertyName}`	Nilai properti komponen di JSON.
`{componentName}.$metadata`	Informasi metadata untuk komponen tersebut.

Properti

Properti adalah bidang data yang mewakili status entitas sama seperti properti dalam banyak bahasa pemrograman berorientasi objek.

Properti Baca-saja

Skema DTDL:

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

Dalam contoh ini, alwinexlepaho8329 adalah nilai saat ini dari properti baca-saja serialNumber yang dilaporkan oleh perangkat.

Cuplikan berikut menunjukkan representasi JSON yang berdampingan dari properti serialNumber:

Perangkat kembar

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

Digital twin

"serialNumber": "alwinexlepaho8329"

Properti bisa-tulis

Contoh berikut memperlihatkan properti bisa-tulis di komponen default.

DTDL:

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

Perangkat kembar

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

Digital twin

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

Dalam contoh ini, 3.0 adalah nilai saat ini dari properti fanSpeed yang dilaporkan oleh perangkat. 2.0 adalah nilai yang diinginkan yang ditetapkan oleh solusi. Nilai yang diinginkan dan status sinkronisasi properti tingkat akar diatur dalam $metadata tingkat akar untuk digital twin. Ketika perangkat online, perangkat dapat menerapkan pembaruan ini dan melaporkan kembali nilai yang diperbarui.

Komponen

Komponen memungkinkan Anda membangun antarmuka model sebagai rakitan antarmuka lain. Misalnya, antarmuka Termostat dapat dimasukkan sebagai komponen thermostat1 dan thermostat2 dalam model Pengontrol Suhu.

Dalam device twin, komponen diidentifikasi oleh penanda { "__t": "c"}. Dalam digital twin, $metadata menandai komponen.

Dalam contoh ini, thermostat1 adalah komponen dengan dua properti:

maxTempSinceLastReboot adalah properti baca-saja.
targetTemperature adalah properti bisa-tulis yang berhasil disinkronkan oleh perangkat. Nilai yang diinginkan dan status sinkronisasi properti ini ada di $metadata komponen.

Cuplikan berikut menunjukkan representasi JSON yang berdampingan dari komponen thermostat1:

Perangkat kembar

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

"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 digital twin

API digital twin meliputi operasi Get Digital Twin, Update Digital Twin, Invoke Component Command dan Invoke Command lebih mengelola digital twin. Anda dapat menggunakan REST API secara langsung atau melalui salah satu SDK layanan.

Kejadian perubahan digital ganda

Saat peristiwa perubahan ganda digital diaktifkan, peristiwa dipicu setiap kali nilai komponen atau properti yang diinginkan saat ini atau yang diinginkan berubah. Peristiwa perubahan digital twin dihasilkan dalam format JSON Patch. Peristiwa yang sesuai dihasilkan dalam format device twin jika peristiwa perubahan twin diaktifkan.

Untuk mempelajari cara mengaktifkan perutean untuk peristiwa digital twin, lihat Menggunakan perutean pesan IoT Hub untuk mengirim pesan perangkat-ke-cloud ke titik akhir yang berbeda. Untuk memahami format pesan, lihat Membuat dan membaca pesan IoT Hub.

Misalnya, peristiwa perubahan digital twin berikut dipicu saat targetTemperature diatur oleh solusi:

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

Peristiwa perubahan digital twin berikut dipicu saat perangkat melaporkan bahwa perubahan di atas telah diterapkan:

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

Catatan

Pesan pemberitahuan perubahan twin digandakan saat diaktifkan di pemberitahuan perubahan device twin dan digital twin.

Langkah berikutnya

Sekarang setelah Anda mempelajari tentang digital twins, berikut adalah beberapa sumber daya lainnya:

Bagikan melalui

Memahami kembar digital IoT Plug and Play

Device twin dan digital twin

Contoh JSON device twin

Contoh digital twin

Properti

Properti Baca-saja

Properti bisa-tulis

Komponen

API digital twin

Kejadian perubahan digital ganda

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan: