Cara menggunakan perintah perangkat dalam solusi Azure IoT Central

  • Artikel

Panduan cara penggunaan ini menunjukkan kepada Anda cara menggunakan perintah yang ditentukan dalam templat perangkat.

Operator dapat menggunakan antarmuka pengguna IoT Central untuk memanggil perintah pada perangkat. Perintah mengontrol perilaku perangkat. Misalnya, operator mungkin memanggil perintah untuk me-reboot perangkat atau mengumpulkan data diagnostik.

Perangkat dapat:

  • Segera menanggapi perintah.
  • Tanggapi IoT Central saat menerima perintah kemudian memberi tahu IoT Central saat perintah jangka panjang selesai.

Secara default, perintah mengharapkan perangkat tersambung dan gagal jika perangkat tidak dapat dijangkau. Jika Anda memilih opsi Antrean jika offline di antarmuka pengguna templat perangkat, perintah dapat diantrekan hingga perangkat online. Perintah offline ini dijelaskan di bagian terpisah nanti di artikel ini.

Untuk mempelajari tentang konvensi perintah IoT Pug dan Play, lihat konvensi IoT Plug and Play.

Untuk mempelajari selengkapnya tentang data perintah yang ditukar perangkat dengan IoT Central, lihat Payload telemetri, properti, dan perintah.

Untuk mempelajari cara mengelola perintah dengan menggunakan IoT Central REST API, lihat Cara menggunakan IoT Central REST API untuk mengontrol perangkat..

Untuk mempelajari cara menerapkan perintah di perangkat tanpa menggunakan SDK perangkat, lihat Berkomunikasi dengan hub IoT menggunakan protokol MQTT.

Menentukan perintah Anda

Perintah standar dikirim ke perangkat untuk menginstruksikan perangkat untuk melakukan sesuatu. Perintah dapat menyertakan parameter dengan informasi tambahan. Misalnya, perintah untuk membuka katup pada perangkat dapat memiliki parameter yang menentukan seberapa banyak katup harus dibuka. Perintah juga dapat menerima nilai yang dikembalikan saat perangkat menyelesaikan perintah. Misalnya, perintah yang meminta perangkat untuk menjalankan beberapa diagnostik dapat menerima laporan diagnostik sebagai nilai yang dikembalikan.

Perintah ditentukan sebagai bagian dari templat perangkat. Cuplikan layar berikut ini memperlihatkan definisi perintah Get Max-Min report yang berbeda di templat perangkat Termostat. Perintah ini memiliki parameter permintaan dan respons:

Screenshot showing Get Max Min Report command in Thermostat device template.

Tabel berikut menunjukkan pengaturan konfigurasi untuk kemampuan perintah:

Bidang Deskripsi
Nama Tampilan Nilai perintah yang digunakan pada ubin dasbor dan bentuk perangkat.
Nama Nama perintah. IoT Central membuat nilai untuk bidang ini dari nama tampilan, tetapi Anda dapat memilih nilai Anda sendiri jika perlu. Bidang ini harus berupa alfanumerik. Kode perangkat menggunakan nilai Nama ini.
Jenis Kemampuan Perintah.
Antrean jika offline Apakah menjadikan perintah ini sebagai perintah offline.
Deskripsi Deskripsi kemampuan perintah.
Komentar Setiap komentar tentang kemampuan perintah.
Minta Payload untuk perintah perangkat.
Respons Payload respons perintah perangkat.

Untuk mempelajari tentang Digital Twin Definition Language (DTDL) yang digunakan Azure IoT Central untuk menentukan perintah dalam templat perangkat, lihat Perintah konvensi > IoT Plug and Play.

Bidang opsional, seperti nama tampilan dan deskripsi, memungkinkan Anda menambahkan detail selengkapnya ke antarmuka dan kemampuan.

Perintah standar

Untuk menangani perintah standar, perangkat mengirimkan nilai respons segera setelah menerima perintah dari IoT Central. Anda dapat menggunakan SDK perangkat Azure IoT untuk menangani perintah standar yang dipanggil oleh aplikasi IoT Central Anda.

Misalnya implementasi dalam beberapa bahasa, lihat Membuat dan menyambungkan aplikasi klien ke aplikasi Azure IoT Central Anda.

Cuplikan layar berikut menunjukkan bagaimana respons perintah yang berhasil ditampilkan di antarmuka pengguna IoT Central:

Screenshot showing how to view command payload for a standard command.

Catatan

Untuk perintah standar, ada batas waktu 30 detik. Jika perangkat tidak merespons dalam waktu 30 detik, IoT Central mengasumsikan bahwa perintah gagal. Periode batas waktu ini tidak dapat dikonfigurasi.

Perintah jangka panjang

Dalam perintah yang berjalan lama, perangkat tidak segera menyelesaikan perintah. Sebagai gantinya, perangkat mengakui tanda terima perintah dan kemudian mengonfirmasi bahwa perintah selesai. Pendekatan ini memungkinkan perangkat menyelesaikan operasi jangka panjang tanpa menjaga koneksi ke IoT Central terbuka.

Catatan

Perintah jangka panjang bukan bagian dari konvensi IoT Plug and Play. IoT Central memiliki konvensi sendiri untuk menerapkan perintah yang berjalan lama.

Bagian ini memperlihatkan kepada Anda bagaimana perangkat dapat menunda pengiriman konfirmasi bahwa perintah selesai.

Cuplikan kode berikut menunjukkan bagaimana perangkat dapat menerapkan perintah jangka panjang:

Catatan

Artikel ini menggunakan Node.js untuk kemudahan.

client.onDeviceMethod('rundiagnostics', commandHandler);

// ...

const commandHandler = async (request, response) => {
  switch (request.methodName) {
  case 'rundiagnostics': {
    console.log('Starting long-running diagnostics run ' + request.payload);
    await sendCommandResponse(request, response, 202, 'Diagnostics run started');

    // Long-running operation here
    // ...

    const patch = {
      rundiagnostics: {
        value: 'Diagnostics run complete at ' + new Date().toLocaleString()
      }
    };

    deviceTwin.properties.reported.update(patch, function (err) {
      if (err) throw err;
      console.log('Properties have been reported for component');
    });
    break;
  }
  default:
    await sendCommandResponse(request, response, 404, 'unknown method');
    break;
  }
};

Panggilan ke onDeviceMethod menyiapkan metode commandHandler. Pengendali perintah ini:

  1. Periksa nama perintah.
  2. Panggilan sendCommandResponse untuk mengirim respons kembali ke IoT Central. Respons ini mencakup kode respons 202 untuk menunjukkan hasil yang tertunda.
  3. Menyelesaikan operasi yang sudah berjalan lama.
  4. Menggunakan properti yang dilaporkan dengan nama yang sama dengan perintah untuk memberi tahu IoT Central bahwa perintah selesai.

Cuplikan layar berikut menunjukkan antarmuka pengguna IoT Central saat menerima pembaruan properti yang menunjukkan perintah selesai:

Screenshot that shows long-running command finished.

Perintah offline

Bagian ini memperlihatkan kepada Anda cara perangkat menangani perintah offline. Jika perangkat sedang online, perangkat dapat menangani perintah offline segera setelah diterima. Jika perangkat offline, perangkat menangani perintah offline saat berikutnya tersambung ke IoT Central. Perangkat tidak dapat mengirim nilai balik sebagai respons terhadap perintah offline.

Catatan

Perintah offline bukan bagian dari konvensi IoT Plug and Play. IoT Central memiliki konvensi sendiri untuk menerapkan perintah offline.

Catatan

Artikel ini menggunakan Node.js untuk kemudahan.

Cuplikan layar berikut menunjukkan perintah offline yang disebut GenerateDiagnostics. Parameter permintaan adalah objek dengan properti tanggalwaktu yang disebut StartTime dan properti enumerasi bilangan bulat yang disebut Bank:

Screenshot that shows the UI for an offline command.

Cuplikan kode berikut menunjukkan bagaimana klien dapat mendengarkan perintah offline dan menampilkan konten pesan:

client.on('message', function (msg) {
  console.log('Body: ' + msg.data);
  console.log('Properties: ' + JSON.stringify(msg.properties));
  client.complete(msg, function (err) {
    if (err) {
      console.error('complete error: ' + err.toString());
    } else {
      console.log('complete sent');
    }
  });
});

Output dari cuplikan kode sebelumnya menunjukkan payload dengan nilai StartTime dan Bank. Daftar properti menyertakan nama perintah dalam item daftarmethod-name:

Body: {"StartTime":"2021-01-06T06:00:00.000Z","Bank":2}
Properties: {"propertyList":[{"key":"iothub-ack","value":"none"},{"key":"method-name","value":"GenerateDiagnostics"}]}

Catatan

Time-to-live default untuk perintah offline adalah 24 jam, setelah pesan kedaluwarsa.

Perintah pada perangkat yang tidak ditetapkan

Anda dapat memanggil perintah di perangkat yang tidak ditetapkan ke templat perangkat. Untuk memanggil perintah pada perangkat yang tidak ditetapkan, navigasikan ke perangkat di bagian Perangkat , pilih Kelola perangkat lalu Perintah. Masukkan nama metode, payload, dan nilai lain yang diperlukan. Cuplikan layar berikut menunjukkan UI yang Anda gunakan untuk memanggil perintah:

Screenshot that shows an example of calling a command on an unassigned device.

Langkah berikutnya

Sekarang setelah Anda mempelajari cara menggunakan perintah di aplikasi Azure IoT Central Anda, lihat Payload telemetri, properti, dan perintah untuk mempelajari selengkapnya tentang parameter perintah dan Membuat dan menyambungkan aplikasi klien ke aplikasi Azure IoT Central Anda untuk melihat sampel kode lengkap dalam bahasa yang berbeda.