Apa yang dimaksud templat perangkat?

Templat perangkat di Azure IoT Central adalah cetak biru yang menentukan karakteristik dan perilaku jenis perangkat yang terhubung ke aplikasi Anda. Misalnya, templat perangkat menentukan telemetri yang dikirim perangkat sehingga IoT Central dapat membuat visualisasi yang menggunakan unit dan Jenis data yang benar.

Penyusun solusi menambahkan templat perangkat ke aplikasi IoT Central. Pengembang perangkat menulis kode perangkat yang menerapkan perilaku yang ditentukan dalam templat perangkat. Untuk mempelajari selengkapnya tentang data yang ditukar perangkat dengan IoT Central, lihat Payload telemetri, properti, dan perintah.

Templat perangkat menyertakan bagian berikut:

  • Model perangkat. Bagian templat perangkat ini menentukan cara perangkat berinteraksi dengan aplikasi Anda. Setiap model perangkat memiliki ID unik. Pengembang perangkat menerapkan perilaku yang ditentukan dalam model.
    • Komponen root. Setiap model perangkat memiliki komponen root. Antarmuka komponen root menjelaskan kemampuan yang spesifik untuk model perangkat itu.
    • Komponen. Model perangkat dapat menyertakan komponen selain komponen root untuk menjelaskan kemampuan perangkat tersebut. Setiap komponen memiliki antarmuka yang menjelaskan kemampuan komponen. Antarmuka komponen dapat digunakan kembali di model perangkat lain. Misalnya, beberapa model perangkat telepon dapat menggunakan antarmuka kamera yang sama.
    • Antarmuka yang diwariskan. Model perangkat berisi satu atau lebih antarmuka yang memperluas kemampuan komponen root.
  • Properti cloud. Bagian templat perangkat ini memungkinkan pengembang solusi menentukan metadata perangkat apa pun untuk disimpan. Properti cloud tidak pernah disinkronkan dengan perangkat dan hanya ada dalam aplikasi. Properti cloud tidak memengaruhi kode yang ditulis pengembang perangkat untuk menerapkan model perangkat.
  • Tampilan. Bagian templat perangkat ini memungkinkan pengembang solusi menentukan visualisasi untuk melihat data dari perangkat, dan formulir untuk mengelola dan mengontrol perangkat. Tampilan menggunakan model perangkat, properti cloud, dan kustomisasi. Tampilan tidak memengaruhi kode yang ditulis pengembang perangkat untuk menerapkan model perangkat.

Menetapkan perangkat ke templat perangkat

Agar perangkat berinteraksi dengan IoT Central, perangkat harus ditetapkan ke templat perangkat. Penugasan ini dilakukan dengan salah satu dari empat cara:

  • Saat Mendaftarkan perangkat di halaman Perangkat , Anda dapat mengidentifikasi templat yang harus digunakan perangkat.
  • Saat mengimpor daftar perangkat secara massal, Anda dapat memilih templat perangkat semua perangkat dalam daftar yang harus digunakan.
  • Anda dapat menetapkan perangkat yang tidak ditetapkan secara manual ke templat perangkat setelah tersambung.
  • Anda dapat secara otomatis menetapkan perangkat ke templat perangkat dengan mengirim ID model saat perangkat pertama kali terhubung ke aplikasi Anda.

Penetapan otomatis

IoT Central dapat secara otomatis menetapkan perangkat ke templat perangkat saat perangkat tersambung. Perangkat harus mengirim ID model saat tersambung. IoT Central menggunakan ID model untuk mengidentifikasi templat perangkat untuk model perangkat tertentu. Proses penemuan bekerja sebagai berikut:

  1. Jika templat perangkat sudah diterbitkan di aplikasi IoT Central, perangkat ditetapkan ke templat perangkat.
  2. Jika templat perangkat belum diterbitkan di aplikasi IoT Central, IoT Central mencari model perangkat di repositori model publik. Jika IoT Central menemukan model, IoT Central menggunakannya untuk menghasilkan templat perangkat dasar.
  3. Jika IoT Central tidak menemukan model di repositori model publik, perangkat ditandai sebagai Tidak Ditetapkan. Operator dapat membuat templat perangkat untuk perangkat lalu memigrasikan perangkat yang tidak ditetapkan ke templat perangkat baru, atau membuat templat perangkat secara otomatis berdasarkan data yang dikirim perangkat.

Cuplikan layar berikut ini memperlihatkan kepada Anda cara melihat ID model templat perangkat di IoT Central. Di templat perangkat, pilih komponen, lalu pilih Edit identitas:

Cuplikan layar memperlihatkan ID model dalam templat perangkat termostat.

Anda dapat melihat model termostat di repositori model publik. Definisi ID model terlihat seperti:

"@id": "dtmi:com:example:Thermostat;1"

Gunakan payload DPS berikut untuk menetapkan perangkat ke templat perangkat:

{
  "modelId":"dtmi:com:example:TemperatureController;2"
}

Untuk mempelajari selengkapnya tentang payload DPS, lihat kode sampel yang digunakan dalam Tutorial: Buat dan sambungkan aplikasi klien ke aplikasi Azure IoT Central Anda.

Model perangkat

Model perangkat menentukan cara perangkat berinteraksi dengan aplikasi IoT Central Anda. Pengembang perangkat harus memastikan bahwa perangkat menerapkan perilaku yang ditentukan dalam model perangkat sehingga IoT Central dapat memantau dan mengelola perangkat. Model perangkat terdiri dari satu antarmuka atau lebih,dan setiap antarmuka dapat menentukan koleksi jenis telemetri, properti perangkat, dan perintah. Pengembang solusi dapat mengimpor file JSON yang menentukan model perangkat lengkap atau antarmuka individual ke dalam templat perangkat, atau menggunakan UI web di IoT Central untuk membuat atau mengedit model perangkat.

Untuk mempelajari selengkapnya tentang mengedit model perangkat, lihat Mengedit templat perangkat yang sudah ada

Pengembang solusi juga dapat mengekspor file JSON dari templat perangkat yang berisi model perangkat lengkap atau antarmuka individual. Pengembang perangkat dapat menggunakan dokumen JSON ini untuk memahami bagaimana perangkat harus berkomunikasi dengan aplikasi IoT Central.

File JSON yang mendefinisikan model perangkat menggunakan Digital Twin Definition Language (DTDL) V2. IoT Central mengharapkan file JSON berisi model perangkat dengan antarmuka yang ditentukan dalam barisan, bukan dalam file terpisah. Untuk mempelajari selengkapnya, lihat Panduan pemodelan IoT Plug and Play.

Perangkat IoT khas terdiri dari:

  • Bagian kustom, yang merupakan hal-hal yang membuat perangkat Anda unik.
  • Bagian standar, yang merupakan hal-hal yang umum untuk semua perangkat.

Bagian-bagian ini disebut antarmuka dalam model perangkat. Antarmuka menentukan detail setiap bagian yang diterapkan perangkat Anda. Antarmuka dapat digunakan kembali di seluruh model perangkat. Di DTDL, komponen mengacu pada antarmuka lain, yang dapat didefinisikan dalam file DTDL terpisah atau pada bagian yang terpisah dari file.

Contoh berikut menunjukkan kerangka model perangkat untuk perangkat pengontrol suhu. Komponen root mencakup definisi untuk workingSet, serialNumber, dan reboot. Model perangkat juga mencakup dua komponen thermostat serta komponen deviceInformation. Isi dari tiga komponen telah dihapus demi keringkasan:

[
  {
    "@context": [
      "dtmi:iotcentral:context;2",
      "dtmi:dtdl:context;2"
    ],
    "@id": "dtmi:com:example:TemperatureController;2",
    "@type": "Interface",
    "contents": [
      {
        "@type": [
          "Telemetry",
          "DataSize"
        ],
        "description": {
          "en": "Current working set of the device memory in KiB."
        },
        "displayName": {
          "en": "Working Set"
        },
        "name": "workingSet",
        "schema": "double",
        "unit": "kibibit"
      },
      {
        "@type": "Property",
        "displayName": {
          "en": "Serial Number"
        },
        "name": "serialNumber",
        "schema": "string",
        "writable": false
      },
      {
        "@type": "Command",
        "commandType": "synchronous",
        "description": {
          "en": "Reboots the device after waiting the number of seconds specified."
        },
        "displayName": {
          "en": "Reboot"
        },
        "name": "reboot",
        "request": {
          "@type": "CommandPayload",
          "description": {
            "en": "Number of seconds to wait before rebooting the device."
          },
          "displayName": {
            "en": "Delay"
          },
          "name": "delay",
          "schema": "integer"
        }
      },
      {
        "@type": "Component",
        "displayName": {
          "en": "thermostat1"
        },
        "name": "thermostat1",
        "schema": "dtmi:com:example:Thermostat;2"
      },
      {
        "@type": "Component",
        "displayName": {
          "en": "thermostat2"
        },
        "name": "thermostat2",
        "schema": "dtmi:com:example:Thermostat;2"
      },
      {
        "@type": "Component",
        "displayName": {
          "en": "DeviceInfo"
        },
        "name": "deviceInformation",
        "schema": "dtmi:azure:DeviceManagement:DeviceInformation;1"
      }
    ],
    "displayName": {
      "en": "Temperature Controller"
    }
  },
  {
    "@context": "dtmi:dtdl:context;2",
    "@id": "dtmi:com:example:Thermostat;2",
    "@type": "Interface",
    "displayName": "Thermostat",
    "description": "Reports current temperature and provides desired temperature control.",
    "contents": [
      ...
    ]
  },
  {
    "@context": "dtmi:dtdl:context;2",
    "@id": "dtmi:azure:DeviceManagement:DeviceInformation;1",
    "@type": "Interface",
    "displayName": "Device Information",
    "contents": [
      ...
    ]
  }
]

Antarmuka memiliki beberapa bidang yang diperlukan:

  • @id: ID unik dalam bentuk Nama Sumber Daya Seragam sederhana.
  • @type: menyatakan bahwa objek ini adalah antarmuka.
  • @context: menentukan versi DTDL yang digunakan untuk antarmuka.
  • contents: mencantumkan properti, telemetri, dan perintah yang membentuk perangkat Anda. Kapabilitas dapat didefinisikan dalam beberapa antarmuka.

Ada beberapa bidang opsional yang bisa Anda gunakan untuk menambahkan detail lebih lanjut ke model kapabilitas, seperti nama tampilan dan deskripsi.

Setiap entri dalam daftar antarmuka di bagian penerapan memiliki:

  • name: nama pemrograman antarmuka.
  • schema: antarmuka yang diterapkan model kemampuan.

Antarmuka

DTDL memungkinkan Anda menjelaskan kemampuan perangkat Anda. Kemampuan terkait dikelompokkan ke dalam antarmuka. Antarmuka menjelaskan properti, telemetri, dan perintah bagian dari penerapan perangkat Anda:

  • Properties. Properti adalah bidang data yang mewakili status perangkat Anda. Gunakan properti untuk mewakili status perangkat yang tahan lama, seperti kondisi on-off dari pompa pendingin. Properti juga dapat mewakili properti perangkat dasar, seperti versi firmware perangkat. Anda dapat mendeklarasikan properti sebagai baca-saja atau bisa-tulis. Hanya perangkat yang dapat memperbarui nilai properti baca-saja. Operator dapat mengatur nilai properti bisa-tulis untuk dikirim ke perangkat.
  • Telemetry. Bidang telemetri mewakili pengukuran dari sensor. Setiap kali perangkat Anda mengambil pengukuran sensor, perangkat harus mengirim peristiwa telemetri yang berisi data sensor.
  • Commands. Perintah yang mewakili metode yang dapat dijalankan pengguna perangkat Anda di perangkat. Misalnya, perintah setel ulang atau perintah untuk mengaktifkan atau menonaktifkan kipas.

Contoh berikut menunjukkan definisi antarmuka termostat:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:Thermostat;2",
  "@type": "Interface",
  "displayName": "Thermostat",
  "description": "Reports current temperature and provides desired temperature control.",
  "contents": [
    {
      "@type": [
        "Telemetry",
        "Temperature"
      ],
      "name": "temperature",
      "displayName": "Temperature",
      "description": "Temperature in degrees Celsius.",
      "schema": "double",
      "unit": "degreeCelsius"
    },
    {
      "@type": [
        "Property",
        "Temperature"
      ],
      "name": "targetTemperature",
      "schema": "double",
      "displayName": "Target Temperature",
      "description": "Allows to remotely specify the desired target temperature.",
      "unit": "degreeCelsius",
      "writable": true
    },
    {
      "@type": [
        "Property",
        "Temperature"
      ],
      "name": "maxTempSinceLastReboot",
      "schema": "double",
      "unit": "degreeCelsius",
      "displayName": "Max temperature since last reboot.",
      "description": "Returns the max temperature since last device reboot."
    },
    {
      "@type": "Command",
      "name": "getMaxMinReport",
      "displayName": "Get Max-Min report.",
      "description": "This command returns the max, min and average temperature from the specified time to the current time.",
      "request": {
        "name": "since",
        "displayName": "Since",
        "description": "Period to return the max-min report.",
        "schema": "dateTime"
      },
      "response": {
        "name": "tempReport",
        "displayName": "Temperature Report",
        "schema": {
          "@type": "Object",
          "fields": [
            {
              "name": "maxTemp",
              "displayName": "Max temperature",
              "schema": "double"
            },
            {
              "name": "minTemp",
              "displayName": "Min temperature",
              "schema": "double"
            },
            {
              "name": "avgTemp",
              "displayName": "Average Temperature",
              "schema": "double"
            },
            {
              "name": "startTime",
              "displayName": "Start Time",
              "schema": "dateTime"
            },
            {
              "name": "endTime",
              "displayName": "End Time",
              "schema": "dateTime"
            }
          ]
        }
      }
    }
  ]
}

Contoh ini memperlihatkan dua properti (satu baca-saja dan satu bisa-tulis), jenis telemetri, dan perintah. Deskripsi bidang minimal memiliki:

  • @type untuk menentukan jenis kemampuan: Telemetry, Property, atau Command. Dalam beberapa kasus, jenis ini mencakup jenis semantik yang memungkinkan IoT Central membuat beberapa asumsi tentang cara menangani nilai.
  • name untuk nilai telemetri.
  • schema untuk menentukan jenis data untuk telemetri atau properti. Nilai ini bisa menjadi jenis primitif, seperti ganda, bilangan bulat, boolean, atau untai (karakter). Jenis dan peta objek yang kompleks juga didukung.

Bidang opsional, seperti nama tampilan dan deskripsi, memungkinkan Anda menambahkan detail lebih lanjut ke antarmuka dan kapabilitas.

Properti

Secara default, properti memiliki fitur baca-saja. Properti baca-saja berarti perangkat melaporkan pembaruan nilai properti ke aplikasi IoT Central Anda. Aplikasi IoT Central Anda tidak dapat menetapkan nilai properti baca-saja.

Pada antarmuka Anda juga dapat menandai properti menjadi bisa-tulis. Perangkat dapat menerima pembaruan ke properti bisa-tulis dari aplikasi IoT Central Anda serta melaporkan pembaruan nilai properti ke aplikasi Anda.

Perangkat tidak perlu tersambung untuk mengatur nilai properti. Nilai yang diperbarui ditransfer ketika perangkat berikutnya terhubung ke aplikasi. Perilaku ini berlaku untuk properti baca-saja dan bisa-tulis.

Jangan gunakan properti untuk mengirim telemetri dari perangkat Anda. Misalnya, properti yang mudah seperti temperatureSetting=80 harus berarti bahwa suhu perangkat telah diatur ke 80, dan perangkat mencoba untuk sampai ke, atau tinggal di, suhu ini.

Untuk properti bisa-tulis, aplikasi perangkat mengembalikan kondisi kode status, versi, dan deskripsi yang diinginkan untuk menunjukkan apakah aplikasi menerima dan menerapkan nilai properti.

Telemetri

IoT Central memungkinkan Anda melihat telemetri di tampilan dan bagan perangkat, serta menggunakan aturan untuk memicu tindakan saat mencapai ambang batas. IoT Central menggunakan informasi dalam model perangkat, seperti jenis data, unit, dan nama tampilan, untuk menentukan cara menampilkan nilai telemetri. Anda juga dapat menampilkan nilai telemetri pada aplikasi dan dasbor pribadi.

Anda dapat menggunakan fitur ekspor data IoT Central untuk mengalirkan telemetri ke tujuan lain seperti penyimpanan atau Pusat Aktivitas.

Perintah

Perintah harus dijalankan dalam 30 detik secara default, dan perangkat harus terhubung saat perintah tiba. Hanya jika perangkat merespons tepat waktu, jika perangkat tidak terhubung, maka perintah akan gagal.

Perintah dapat memiliki parameter permintaan dan mengembalikan respons.

Perintah offline

Anda dapat memilih perintah antrean jika perangkat sedang offline dengan mengaktifkan opsi Antrean jika offline untuk perintah di templat perangkat.

Perintah offline adalah pemberitahuan satu arah ke perangkat dari solusi Anda. Perintah offline dapat memiliki parameter permintaan tetapi tidak dapat mengembalikan respons.

Catatan

Perintah offline ditandai seolah-olah durable Anda mengekspor model sebagai DTDL.

Properti cloud

Properti cloud merupakan bagian dari templat perangkat, tetapi bukan bagian dari model perangkat. Properti cloud memungkinkan pengembang solusi menentukan metadata perangkat apa pun untuk disimpan di aplikasi IoT Central. Properti cloud tidak memengaruhi kode yang ditulis pengembang perangkat untuk menerapkan model perangkat.

Pengembang solusi dapat menambahkan properti cloud ke formulir dan tampilan bersama properti perangkat untuk memungkinkan operator mengelola perangkat yang terhubung ke aplikasi. Pengembang solusi juga dapat menggunakan properti cloud sebagai bagian dari definisi aturan untuk membuat nilai ambang batas yang dapat diedit oleh operator.

Tampilan

Pengembang solusi membuat tampilan yang memungkinkan operator memantau dan mengelola perangkat yang terhubung. Tampilan merupakan bagian dari templat perangkat, sehingga tampilan dikaitkan dengan jenis perangkat tertentu. Tampilan dapat mencakup:

  • Bagan untuk memplot telemetri.
  • Petak untuk menampilkan properti perangkat baca-saja.
  • Petak peta untuk memungkinkan operator mengedit properti perangkat bisa-tulis.
  • Petak peta untuk memungkinkan operator mengedit properti cloud.
  • Petak untuk memungkinkan perintah panggilan operator, termasuk perintah yang mengharapkan muatan.
  • Petak untuk menampilkan label, gambar, atau teks markdown.

Telemetri, properti, dan perintah yang bisa Anda tambahkan ke tampilan ditentukan oleh model perangkat, properti cloud, dan kustomisasi di templat perangkat.

Langkah berikutnya

Sekarang setelah Anda mempelajari tentang templat perangkat, langkah berikutnya yang disarankan adalah membaca Muatan telemetri, properti, dan perintah untuk mempelajari selengkapnya tentang data pertukaran perangkat dengan IoT Central.