Bagikan melalui

Cara menggunakan perintah dalam solusi Azure IoT Central

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

Operator dapat menggunakan UI 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:

  • Menanggapi perintah segera.
  • Tanggapi IoT Central ketika menerima perintah dan kemudian memberi tahu IoT Central ketika 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 REST API IoT Central, lihat Cara menggunakan REST API IoT Central untuk mengontrol perangkat.

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

Tentukan 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 berapa banyak untuk membuka katup. Perintah juga dapat menerima nilai pengembalian saat perangkat menyelesaikan perintah. Misalnya, perintah yang meminta perangkat untuk menjalankan beberapa diagnostik dapat menerima laporan diagnostik sebagai nilai pengembalian.

Perintah didefinisikan sebagai bagian dari templat perangkat. Cuplikan layar berikut menunjukkan definisi perintah Laporan Maks-Min dalam templat perangkat Termostat. Perintah ini memiliki parameter permintaan dan respons:

Cuplikan layar memperlihatkan perintah Dapatkan Laporan Maks Min di templat perangkat Termostat.

Tabel berikut ini memperlihatkan pengaturan konfigurasi untuk kemampuan perintah:

Bidang Description
Nama Tampilan Nilai perintah yang digunakan pada petak dasbor dan formulir perangkat.
Nama Nama perintah. IoT Central menghasilkan nilai untuk bidang ini dari nama tampilan, tetapi Anda dapat memilih nilai Anda sendiri jika perlu. Bidang ini harus alfanumerik. Kode perangkat menggunakan nilai Nama ini.
Jenis Kapabilitas Perintah.
Antrean jika offline Apakah akan menjadikan perintah ini sebagai perintah offline .
Description Deskripsi kemampuan perintah.
Comment Komentar apa pun tentang kemampuan perintah.
Permohonan Payload untuk perintah perangkat.
Jawaban 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 dan deskripsi tampilan, 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 Tutorial: Membuat dan menyambungkan aplikasi klien ke aplikasi Azure IoT Central Anda.

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

Cuplikan layar memperlihatkan cara melihat payload perintah untuk perintah standar.

Nota

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.

Nota

Perintah jangka panjang bukan bagian dari konvensi IoT Plug and Play. IoT Central memiliki konvensi tersendiri untuk menerapkan perintah berjangka panjang.

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

Cuplikan kode berikut menunjukkan bagaimana perangkat dapat menerapkan perintah yang berjalan lama:

Nota

Artikel ini menggunakan Node.js untuk kesederhanaan.

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. Handler perintah ini:

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

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

Cuplikan layar yang memperlihatkan perintah jangka panjang selesai.

Perintah offline

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

Nota

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

Nota

Artikel ini menggunakan Node.js untuk kesederhanaan.

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

Cuplikan layar yang memperlihatkan UI untuk perintah offline.

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 daftar nama metode :

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

Nota

Waktu hidup default untuk perintah offline adalah 24 jam, setelah itu 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:

Cuplikan layar yang memperlihatkan contoh panggilan perintah pada perangkat yang tidak ditetapkan.

Langkah selanjutnya

Sekarang setelah Anda tahu 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.

  • Last updated on