Konvensi IoT Plug and Play

Perangkat IoT Plug and Play harus mengikuti serangkaian konvensi saat bertukar pesan dengan IoT Hub. Perangkat IoT Plug and Play menggunakan protokol MQTT untuk berkomunikasi dengan IoT Hub. IoT Hub juga mendukung protokol AMQP yang tersedia di beberapa SDK perangkat IoT.

Perangkat dapat menyertakan modul, atau diimplementasikan dalam modul IoT Edge yang dihosting oleh runtime IoT Edge.

Anda menjelaskan telemetri, properti, dan perintah yang diterapkan perangkat IoT Plug and Play dengan model Digital Twins Definition Language (DTDL). Ada dua jenis model yang dirujuk dalam artikel ini:

  • Tidak ada komponen – Model tanpa komponen. Model mendeklarasikan telemetri, properti, dan perintah sebagai elemen tingkat atas di bagian konten antarmuka utama. Di alat penjelajah Azure IoT, model ini muncul sebagai satu komponen default.
  • Beberapa komponen – Model yang terdiri dari dua atau beberapa antarmuka. Antarmuka utama, yang muncul sebagai komponen default, dengan telemetri, properti, dan perintah. Satu atau beberapa antarmuka dideklarasikan sebagai komponen dengan lebih banyak telemetri, properti, dan perintah.

Untuk mengetahui informasi selengkapnya, lihat panduan pemodelan IoT Plug and Play.

Mengidentifikasi model

Untuk mengumumkan model yang diterapkannya, modul atau perangkat IoT Plug and Play menyertakan ID model dalam paket sambungan MQTT dengan menambahkan model-id ke bidang USERNAME.

Untuk mengidentifikasi model yang diterapkan oleh modul atau perangkat, layanan bisa mendapatkan ID model dari:

  • Bidang modelId kembaran perangkat.
  • Bidang $metadata.$model kembaran digital.
  • Pemberitahuan perubahan kembaran digital.

telemetri

  • Telemetri yang dikirim dari perangkat tanpa komponen tidak memerlukan metadata tambahan apa pun. Sistem ini akan menambahkan properti dt-dataschema.
  • Telemetri yang dikirim dari perangkat menggunakan komponen harus menambahkan nama komponen ke pesan telemetri.
  • Saat menggunakan MQTT, tambahkan $.sub properti dengan nama komponen ke topik telemetri, sistem menambahkan dt-subject properti .
  • Saat menggunakan AMQP, tambahkan dt-subject properti dengan nama komponen sebagai anotasi pesan.

Catatan

Telemetri dari komponen memerlukan satu pesan per komponen.

Untuk contoh telemetri lainnya, lihat Telemetri Payload >

Properti baca-saja

Perangkat menetapkan properti baca-saja yang kemudian dilaporkan ke aplikasi back-end.

Contoh properti baca-saja tanpa komponen

Perangkat atau modul dapat mengirim JSON valid yang mengikuti aturan DTDL.

DTDL yang menentukan properti pada antarmuka:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:example: Thermostat;1",
  "@type": "Interface",
  "contents": [
    {
      "@type": "Property",
      "name": "temperature",
      "schema": "double"
    }
  ]
}

Contoh payload properti yang dilaporkan:

"reported" :
{
  "temperature" : 21.3
}

Contoh properti baca-saja beberapa komponen

Perangkat atau modul harus menambahkan penanda {"__t": "c"} untuk menunjukkan bahwa elemen merujuk ke komponen.

DTDL yang mereferensikan komponen:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:TemperatureController;1",
  "@type": "Interface",
  "displayName": "Temperature Controller",
  "contents": [
    {
      "@type" : "Component",
      "schema": "dtmi:com:example:Thermostat;1",
      "name": "thermostat1"
    }
  ]
}

DTDL yang menentukan komponen:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:Thermostat;1",
  "@type": "Interface",
  "contents": [
    {
      "@type": "Property",
      "name": "temperature",
      "schema": "double"
    }
  ]
}

Contoh payload properti yang dilaporkan:

"reported": {
  "thermostat1": {
    "__t": "c",
    "temperature": 21.3
  }
}

Untuk contoh properti baca-saja lainnya, lihat Properti Payloads>.

Properti bisa-tulis

Aplikasi back-end mengatur properti bisa-tulis yang kemudian dikirim IoT Hub ke perangkat.

Perangkat atau modul harus mengonfirmasi bahwa telah menerima properti dengan mengirimkan properti yang dilaporkan. Properti yang dilaporkan harus menyertakan:

  • value - nilai sebenarnya properti (biasanya nilai yang diterima, tetapi perangkat mungkin memutuskan untuk melaporkan nilai yang berbeda).
  • ac - kode konfirmasi yang menggunakan kode status HTTP.
  • av - versi konfirmasi yang merujuk ke $version dari properti yang diinginkan. Anda dapat menemukan nilai ini dalam payload JSON properti yang diinginkan.
  • ad – deskripsi konfirmasi opsional.

Respons pengakuan

Saat melaporkan properti bisa-tulis, perangkat harus membuat pesan pengakuan, dengan menggunakan empat bidang dalam daftar sebelumnya, untuk menunjukkan status perangkat aktual, seperti yang dijelaskan dalam tabel berikut:

Status(ac) Versi(av) Value(value) Deskripsi(av)
200 Versi yang diinginkan Nilai yang diinginkan Nilai properti yang diinginkan diterima
202 Versi yang diinginkan Nilai yang diterima oleh perangkat Nilai properti yang diinginkan diterima, pembaruan sedang berlangsung (harus selesai dengan 200)
203 0 Nilai yang ditetapkan oleh perangkat Properti diatur dari perangkat, tidak mencerminkan apa pun yang diinginkan
400 Versi yang diinginkan Nilai aktual yang digunakan oleh perangkat Nilai properti yang diinginkan tidak diterima
500 Versi yang diinginkan Nilai aktual yang digunakan oleh perangkat Pengecualian saat menerapkan properti

Saat dimulai, perangkat harus meminta kembaran perangkat, dan memeriksa pembaruan properti bisa-tulis. Jika versi properti bisa-tulis meningkat saat perangkat offline, perangkat tersebut harus mengirimkan respons properti yang dilaporkan untuk mengonfirmasi bahwa telah menerima pembaruan.

Saat perangkat dimulai untuk pertama kalinya, perangkat dapat mengirim nilai awal untuk properti yang dilaporkan jika tidak menerima properti awal yang diinginkan dari hub IoT. Dalam hal ini, perangkat dapat mengirim nilai default dengan av ke 0 dan ac ke 203. Misalnya:

"reported": {
  "targetTemperature": {
    "value": 20.0,
    "ac": 203,
    "av": 0,
    "ad": "initialize"
  }
}

Perangkat dapat menggunakan properti yang dilaporkan untuk menyediakan informasi lain ke hub. Misalnya, perangkat dapat merespons serangkaian pesan dalam proses seperti:

"reported": {
  "targetTemperature": {
    "value": 35.0,
    "ac": 202,
    "av": 3,
    "ad": "In-progress - reporting current temperature"
  }
}

Ketika perangkat mencapai suhu target, perangkat mengirim pesan berikut:

"reported": {
  "targetTemperature": {
    "value": 20.0,
    "ac": 200,
    "av": 4,
    "ad": "Reached target temperature"
  }
}

Perangkat dapat melaporkan kesalahan seperti:

"reported": {
  "targetTemperature": {
    "value": 120.0,
    "ac": 500,
    "av": 3,
    "ad": "Target temperature out of range. Valid range is 10 to 99."
  }
}

Tipe objek

Jika properti yang dapat ditulis didefinisikan sebagai objek, layanan harus mengirim objek lengkap ke perangkat. Perangkat harus mengakui pembaruan dengan mengirimkan kembali informasi yang memadai ke layanan agar layanan memahami bagaimana perangkat telah bertindak pada pembaruan. Respons ini dapat mencakup:

  • Keseluruhan objek.
  • Hanya bidang yang diperbarui perangkat.
  • Subset dari bidang.

Untuk objek besar, pertimbangkan untuk meminimalkan ukuran objek yang Anda sertakan dalam pengakuan.

Contoh berikut menunjukkan properti bisa-tulis yang didefinisikan sebagai Object dengan empat bidang:

DTDL:

{
  "@type": "Property",
  "name": "samplingRange",
  "schema": {
    "@type": "Object",
    "fields": [
      {
        "name": "startTime",
        "schema": "dateTime"
      },
      {
        "name": "lastTime",
        "schema": "dateTime"
      },
      {
        "name": "count",
        "schema": "integer"
      },
      {
        "name": "errorCount",
        "schema": "integer"
      }
    ]
  },
  "displayName": "Sampling range"
  "writable": true
}

Untuk memperbarui properti bisa-tulis ini, kirim objek lengkap dari layanan yang terlihat seperti contoh berikut:

{
  "samplingRange": {
    "startTime": "2021-08-17T12:53:00.000Z",
    "lastTime": "2021-08-17T14:54:00.000Z",
    "count": 100,
    "errorCount": 5
  }
}

Perangkat merespons dengan pengakuan yang terlihat seperti contoh berikut:

{
  "samplingRange": {
    "ac": 200,
    "av": 5,
    "ad": "Weighing status updated",
    "value": {
      "startTime": "2021-08-17T12:53:00.000Z",
      "lastTime": "2021-08-17T14:54:00.000Z",
      "count": 100,
      "errorCount": 5
    }
  }
}

Contoh properti bisa-tulis tanpa komponen

Saat perangkat menerima beberapa properti yang diinginkan dalam satu payload, perangkat dapat mengirim respons properti yang dilaporkan di beberapa payload atau menggabungkan respons ke dalam satu payload.

Perangkat atau modul dapat mengirim JSON valid yang mengikuti aturan DTDL.

DTDL:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:example: Thermostat;1",
  "@type": "Interface",
  "contents": [
    {
      "@type": "Property",
      "name": "targetTemperature",
      "schema": "double",
      "writable": true
    },
    {
      "@type": "Property",
      "name": "targetHumidity",
      "schema": "double",
      "writable": true
    }
  ]
}

Contoh payload properti yang diinginkan:

"desired" :
{
  "targetTemperature" : 21.3,
  "targetHumidity" : 80,
  "$version" : 3
}

Contoh payload pertama properti yang dilaporkan:

"reported": {
  "targetTemperature": {
    "value": 21.3,
    "ac": 200,
    "av": 3,
    "ad": "complete"
  }
}

Contoh payload kedua properti yang dilaporkan:

"reported": {
  "targetHumidity": {
    "value": 80,
    "ac": 200,
    "av": 3,
    "ad": "complete"
  }
}

Catatan

Anda dapat memilih untuk menggabungkan dua payload properti yang dilaporkan ini menjadi satu payload tunggal.

Contoh properti bisa-tulis beberapa komponen

Perangkat atau modul harus menambahkan penanda {"__t": "c"} untuk menunjukkan bahwa elemen merujuk ke komponen.

Penanda dikirimkan hanya untuk pembaruan properti yang ditentukan dalam komponen. Pembaruan untuk properti yang ditentukan dalam komponen default tidak menyertakan penanda, lihat Contoh properti tidak ada komponen yang dapat ditulis.

Saat perangkat menerima beberapa properti yang dilaporkan dalam satu payload, perangkat dapat mengirim respons properti yang dilaporkan ke beberapa payload atau menggabungkan respons menjadi satu payload.

Perangkat atau modul harus mengonfirmasi bahwa telah menerima properti dengan mengirimkan properti yang dilaporkan:

DTDL yang mereferensikan komponen:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:TemperatureController;1",
  "@type": "Interface",
  "displayName": "Temperature Controller",
  "contents": [
    {
      "@type" : "Component",
      "schema": "dtmi:com:example:Thermostat;1",
      "name": "thermostat1"
    }
  ]
}

DTDL yang menentukan komponen:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:Thermostat;1",
  "@type": "Interface",
  "contents": [
    {
      "@type": "Property",
      "name": "targetTemperature",
      "schema": "double",
      "writable": true
    }
  ]
}

Contoh payload properti yang diinginkan:

"desired": {
  "thermostat1": {
    "__t": "c",
    "targetTemperature": 21.3,
    "targetHumidity": 80,
    "$version" : 3
  }
}

Contoh payload pertama properti yang dilaporkan:

"reported": {
  "thermostat1": {
    "__t": "c",
    "targetTemperature": {
      "value": 23,
      "ac": 200,
      "av": 3,
      "ad": "complete"
    }
  }
}

Contoh payload kedua properti yang dilaporkan:

"reported": {
  "thermostat1": {
    "__t": "c",
    "targetHumidity": {
      "value": 80,
      "ac": 200,
      "av": 3,
      "ad": "complete"
    }
  }
}

Catatan

Anda dapat memilih untuk menggabungkan dua payload properti yang dilaporkan ini menjadi satu payload tunggal.

Untuk contoh properti yang dapat ditulis lainnya, lihat Properti Payloads>.

Perintah

Tidak ada antarmuka komponen yang menggunakan nama perintah tanpa prefiks.

Pada perangkat atau modul, beberapa antarmuka komponen menggunakan nama perintah dengan format berikut: componentName*commandName.

Untuk contoh perintah lainnya, lihat Perintah Payload.>

Tip

IoT Central memiliki konvensi sendiri untuk menerapkan perintah Jangka Panjang dan perintah Offline.

Langkah berikutnya

Sekarang setelah Anda mempelajari tentang konvensi IoT Plug and Play, berikut adalah beberapa sumber daya lainnya: