Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
Perangkat IoT Plug and Play mengimplementasikan model yang dijelaskan oleh skema Digital Twins Definition Language (DTDL ). Model menjelaskan sekumpulan komponen, properti, perintah, dan pesan telemetri yang dapat dimiliki perangkat tertentu.
Nota
DTDL tidak terbatas hanya untuk IoT Plug and Play. Layanan IoT lainnya, seperti Azure Digital Twins, menggunakannya untuk mewakili seluruh lingkungan seperti bangunan dan jaringan energi.
SDK layanan Azure IoT menyertakan API yang memungkinkan layanan berinteraksi dengan kembar digital perangkat. Misalnya, layanan dapat membaca properti perangkat dari kembar digital atau menggunakan kembar digital untuk memanggil perintah pada perangkat. Untuk mempelajari lebih lanjut, lihat Contoh kembar digital IoT Hub.
Contoh perangkat IoT Plug and Play dalam artikel ini mengimplementasikan model Pengontrol Suhu yang memiliki komponen Termostat .
Perangkat kembar dan kembar digital
Selain kembar digital, Azure IoT Hub juga mempertahankan kembar perangkat untuk setiap perangkat yang terhubung. Perangkat kembar mirip dengan kembar digital karena merupakan representasi properti perangkat. Hub IoT menginisialisasi kembar digital dan perangkat kembar saat pertama kali perangkat IoT Plug and Play disediakan. SDK layanan Azure IoT menyertakan API untuk berinteraksi dengan perangkat kembar.
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. Dalam kembar perangkat, status properti yang dapat ditulis dibagi dalam 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. Dalam kembar digital, ada tampilan terpadu mengenai kondisi properti saat ini dan yang diinginkan. Status sinkronisasi untuk properti tertentu disimpan di bagian komponen $metadata default yang sesuai.
Contoh JSON kembar perangkat
Cuplikan berikut menunjukkan kembar perangkat 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 kembar digital
Cuplikan berikut menunjukkan kembar digital 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 ini menjelaskan bidang dalam objek JSON kembar digital:
| 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 yang dapat ditulis] Nilai yang diinginkan untuk properti yang telah ditentukan. |
$metadata.{propertyName}.desiredVersion |
[Hanya untuk properti yang dapat ditulis] 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 lebih besar atau sama dengan versi yang diinginkan. |
$metadata.{propertyName}.ackCode |
[Diperlukan, hanya untuk properti yang dapat ditulis] 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 properti dan metadata komponen. |
{componentName}.{propertyName} |
Nilai properti komponen di JSON. |
{componentName}.$metadata |
Informasi metadata untuk komponen. |
Karakteristik
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 berdampingan dari properti serialNumber.
Perangkat kembar
"properties": {
"reported": {
"serialNumber": "alwinexlepaho8329"
}
}
Kembaran digital
"serialNumber": "alwinexlepaho8329"
Properti bisa-tulis
Contoh berikut menunjukkan 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"
}
}
},
}
Kembaran digital
{
"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 properti saat ini yang dilaporkan fanSpeed oleh perangkat.
2.0 adalah nilai yang diinginkan yang ditetapkan oleh solusi. Nilai yang diinginkan dan status sinkronisasi dari properti tingkat akar diatur pada tingkat akar $metadata 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 perangkat kembar, penanda { "__t": "c"} mengidentifikasi komponen. Dalam kembar digital, kehadiran $metadata menandai komponen.
Dalam contoh ini, thermostat1 adalah komponen dengan dua properti:
-
maxTempSinceLastRebootmerupakan properti hanya-baca. -
targetTemperatureadalah properti bisa-tulis yang berhasil disinkronkan oleh perangkat. Nilai yang diinginkan dan status sinkronisasi properti ini berada di komponen$metadata.
Cuplikan berikut menunjukkan representasi JSON berdampingan untuk komponen thermostat1 tersebut.
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
}
}
Kembaran digital
"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 kembar digital
API digital twin termasuk Get Digital Twin, Update Digital Twin, Invoke Component Command, dan Invoke Command untuk mengelola digital twin. Anda dapat menggunakan REST API secara langsung atau melalui salah satu SDK layanan.
Kejadian perubahan digital ganda
Saat peristiwa perubahan kembar digital diaktifkan, suatu peristiwa akan dipicu setiap kali nilai saat ini atau yang diinginkan dari komponen atau properti berubah. Peristiwa perubahan kembar digital dihasilkan dalam format Patch JSON . Peristiwa terkait dihasilkan dalam format kembar perangkat jika peristiwa perubahan kembar diaktifkan.
Untuk mempelajari cara mengaktifkan perutean untuk event perangkat dan digital twin, lihat Gunakan perutean pesan IoT Hub untuk mengirim pesan perangkat ke cloud menuju titik akhir yang berbeda. Untuk memahami format pesan, lihat Membuat dan membaca pesan IoT Hub.
Misalnya, peristiwa perubahan kembar digital berikut dipicu saat solusi menetapkan suatu nilai targetTemperature.
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 kembar digital berikut dipicu saat perangkat melaporkan bahwa perubahan yang diinginkan sebelumnya 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
}
]
Nota
Pesan pemberitahuan perubahan pada kembar digital dikirimkan dua kali saat fitur ini diaktifkan baik di perangkat maupun pada kembar digital.