Konsep dan status perintah - AWS IoT Core
Perintah konsep kunciStatus perintahStatus pelaksanaan perintah

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Konsep dan status perintah

Gunakan AWS IoT Perintah untuk mengirim instruksi dari cloud ke perangkat yang terhubung. Untuk menggunakan fitur ini:

  1. Buat perintah dengan muatan yang berisi konfigurasi yang diperlukan untuk berjalan di perangkat.

  2. Tentukan perangkat target yang akan menerima muatan dan melakukan tindakan.

  3. Jalankan perintah pada perangkat target dan ambil informasi status. Untuk memecahkan masalah, lihat CloudWatch log.

Untuk informasi selengkapnya tentang alur kerja ini, lihatAlur kerja perintah tingkat tinggi.

Perintah konsep kunci

Konsep kunci berikut membantu Anda memahami fitur Perintah. Ketentuan digunakan secara konsisten di seluruh dokumentasi ini:

  • Command - Template yang dapat digunakan kembali yang mendefinisikan instruksi perangkat

  • Eksekusi - Sebuah instance dari perintah yang berjalan pada perangkat

  • Nama benda - Pengidentifikasi untuk perangkat yang terdaftar di registri IoT

  • ID Klien - Pengidentifikasi MQTT untuk perangkat yang tidak terdaftar

  • Payload - Data instruksi yang dikirim ke perangkat

  • Topik - Saluran MQTT untuk komunikasi perintah

Commands

Perintah adalah instruksi yang dikirim dari cloud ke perangkat IoT Anda sebagai pesan MQTT. Setelah menerima muatan, perangkat memproses instruksi dan mengambil tindakan yang sesuai, seperti memodifikasi pengaturan konfigurasi, mentransmisikan pembacaan sensor, atau mengunggah log. Perangkat kemudian mengembalikan hasil ke cloud, memungkinkan pemantauan dan kontrol jarak jauh.

Namespace

Saat membuat perintah, tentukan namespace-nya. Untuk AWS IoT Device Management perintah, gunakan AWS-IoT namespace default dan berikan payload atau payloadTemplate. Untuk AWS IoT FleetWise perintah, gunakan AWS-IoT-FleetWise namespace. Untuk informasi selengkapnya, lihat Perintah jarak jauh di Panduan AWS IoT FleetWise Pengembang.

Muatan

Saat membuat perintah, berikan muatan statis yang menentukan tindakan yang harus dilakukan perangkat. Muatan dapat menggunakan format apa pun yang didukung. Untuk memastikan perangkat menafsirkan muatan dengan benar, sebaiknya tentukan jenis format payload. Perangkat yang menggunakan MQTT5 protokol dapat mengikuti standar MQTT untuk mengidentifikasi format. Indikator format untuk JSON atau CBOR tersedia dalam topik permintaan perintah.

Templat muatan

Template payload mendefinisikan payload perintah dengan placeholder yang menghasilkan muatan berbeda saat runtime berdasarkan nilai parameter yang Anda berikan. Misalnya, alih-alih membuat muatan terpisah untuk nilai suhu yang berbeda, buat satu templat dengan placeholder suhu dan tentukan nilainya selama eksekusi. Ini menghilangkan pemeliharaan beberapa muatan serupa.

Perangkat target

Untuk menjalankan perintah, tentukan perangkat target menggunakan nama benda (untuk perangkat yang terdaftar AWS IoT) atau ID klien MQTT (untuk perangkat yang tidak terdaftar). ID klien adalah pengidentifikasi unik yang didefinisikan dalam MQTT protokol yang digunakan untuk menghubungkan perangkat ke AWS IoT. Lihat perinciannya di Pertimbangan perangkat target.

Topik perintah

Sebelum menjalankan perintah, perangkat harus berlangganan topik permintaan perintah. Saat Anda menjalankan perintah, muatan dikirim ke perangkat pada topik ini. Setelah eksekusi, perangkat mempublikasikan hasil dan status ke topik respons perintah. Untuk informasi selengkapnya, lihat Topik perintah.

Eksekusi perintah

Eksekusi adalah contoh dari perintah yang berjalan pada perangkat target. Saat Anda memulai eksekusi, payload dikirimkan ke perangkat dan ID eksekusi unik dihasilkan. Perangkat menjalankan perintah dan melaporkan kemajuan ke AWS IoT. Logika sisi perangkat menentukan perilaku eksekusi dan pelaporan status ke topik yang dicadangkan.

Kondisi nilai parameter

Saat membuat perintah dengan templat payload, tentukan kondisi nilai untuk memvalidasi nilai parameter sebelum eksekusi. Kondisi nilai memastikan parameter memenuhi persyaratan, mencegah eksekusi yang tidak valid.

Operator yang didukung berdasarkan CommandParameterValuejenis

Jenis numerik (INTEGER, LONG, DOUBLE, UNSIGNEDLONG)

  • EQUALS- Nilai harus sama dengan angka yang ditentukan

  • NOT_EQUALS- Nilai tidak boleh sama dengan angka yang ditentukan

  • GREATER_THAN- Nilai harus lebih besar dari angka yang ditentukan

  • GREATER_THAN_EQUALS- Nilai harus lebih besar dari atau sama dengan angka yang ditentukan

  • LESS_THAN- Nilai harus kurang dari angka yang ditentukan

  • LESS_THAN_EQUALS- Nilai harus kurang dari atau sama dengan angka yang ditentukan

  • IN_RANGE- Nilai harus dalam kisaran yang ditentukan (inklusif)

  • NOT_IN_RANGE- Nilai harus berada di luar rentang yang ditentukan (inklusif)

  • IN_SET- Nilai harus cocok dengan salah satu angka yang ditentukan

  • NOT_IN_SET- Nilai tidak boleh cocok dengan nomor yang ditentukan

Jenis string (STRING)

  • EQUALS- Nilai harus sama dengan string yang ditentukan

  • NOT_EQUALS- Nilai tidak harus sama dengan string yang ditentukan

  • IN_SET- Nilai harus cocok dengan salah satu string yang ditentukan

  • NOT_IN_SET- Nilai tidak boleh cocok dengan string yang ditentukan

Jenis Boolean

  • Kondisi nilai tidak didukung

Tipe biner

  • Kondisi nilai tidak didukung

Contoh: Perintah kontrol suhu

{
  "commandId": "SetTemperature",
  "namespace": "AWS-IoT",
  "payloadTemplate": "{\"temperature\": \"${aws:iot:commandexecution::parameter:temperature}\"}",
  "parameters": [
    {
      "name": "temperature",
      "type": "INTEGER",
      "valueConditions": [
        {
          "comparisonOperator": "IN_RANGE",
          "operand": {
            "numberRange": {
              "min": "60",
              "max": "80"
            }
          }
        }
      ]
    }
  ]
}

Dalam contoh ini, temperature parameter harus antara 60 dan 80 (inklusif). Permintaan eksekusi dengan nilai di luar rentang ini gagal validasi.

catatan

Kondisi nilai dievaluasi saat pemanggilan API. StartCommandExecution Validasi yang gagal mengembalikan kesalahan dan mencegah pembuatan eksekusi.

Prioritas dan evaluasi nilai parameter

Saat memulai eksekusi perintah dengan templat payload, nilai parameter diselesaikan menggunakan prioritas berikut:

  1. Parameter permintaan eksekusi - Nilai yang disediakan dalam StartCommandExecution permintaan mengambil prioritas tertinggi

  2. Nilai default perintah - Jika parameter tidak disediakan dalam permintaan eksekusi, parameter defaultValue digunakan

  3. Tidak ada nilai - Jika tidak ada yang disediakan, eksekusi gagal sebagai parameter yang diperlukan untuk menghasilkan permintaan eksekusi

Kondisi nilai dievaluasi pada nilai parameter akhir yang diturunkan di atas pada prioritas dan sebelum pembuatan eksekusi. Jika validasi gagal, permintaan eksekusi mengembalikan kesalahan.

Contoh: SetTemperature perintah dengan defaultValue

{
  "parameters": [
    {
      "name": "temperature",
      "type": "INTEGER",
      "defaultValue": {"I": 72},
      "valueConditions": [
        {
          "comparisonOperator": "IN_RANGE",
          "operand": {"numberRange": {"min": "60", "max": "80"}}
        }
      ]
    }
  ]
}

Saat memulai eksekusi:

  • Jika Anda memberikan "temperature": {"I": 75} permintaan, 75 digunakan

  • Jika Anda menghilangkan parameter suhu, nilai default 72 digunakan

  • Kedua nilai divalidasi terhadap kondisi rentang [60,80]

Status perintah

Perintah dalam Anda Akun AWS dapat berada di salah satu dari tiga status: Tersedia, Usang, atau Penghapusan tertunda.

Available

Setelah pembuatan berhasil, perintah berada dalam status Tersedia dan dapat dieksekusi pada perangkat.

Usang

Tandai perintah untuk penghentian saat tidak lagi diperlukan. Perintah yang tidak digunakan lagi tidak dapat memulai eksekusi baru, tetapi eksekusi yang tertunda terus selesai. Untuk mengaktifkan eksekusi baru, kembalikan perintah ke status Tersedia.

Penghapusan tertunda

Ketika Anda menandai perintah untuk penghapusan, itu dihapus secara otomatis jika tidak digunakan lagi lebih lama dari batas waktu maksimum (default: 12 jam). Tindakan ini bersifat permanen. Jika tidak digunakan lagi atau tidak digunakan lagi kurang dari batas waktu, perintah memasuki status penghapusan Tertunda dan dihapus setelah batas waktu berakhir.

Status pelaksanaan perintah

Saat Anda memulai eksekusi pada perangkat target, ia memasuki CREATED status dan dapat bertransisi ke status lain berdasarkan laporan perangkat. Anda dapat mengambil informasi status dan melacak eksekusi.

catatan

Anda dapat menjalankan beberapa perintah secara bersamaan di perangkat. Gunakan kontrol konkurensi untuk membatasi eksekusi per perangkat dan mencegah kelebihan beban. Untuk eksekusi bersamaan maksimum per perangkat, lihat AWS IoT Device Management perintah kuota.

Tabel berikut menunjukkan status eksekusi dan transisinya berdasarkan progres eksekusi.

Status eksekusi perintah dan sumber
Status pelaksanaan perintah Diprakarsai oleh perangkat/cloud? Eksekusi terminal? Transisi status yang diizinkan
CREATED Cloud Tidak

  • IN_PROGRESS

  • SUCCEEDED

  • FAILED

  • MENOLAK

  • TIMED_OUT
IN_PROGRESS Perangkat Tidak

  • IN_PROGRESS

  • SUCCEEDED

  • FAILED

  • MENOLAK

  • TIMED_OUT
TIMED_OUT Perangkat dan cloud Tidak

  • SUCCEEDED

  • FAILED

  • MENOLAK

  • TIMED_OUT
SUCCEEDED Perangkat Ya Tidak berlaku
FAILED Perangkat Ya Tidak berlaku
REJECTED Perangkat Ya Tidak berlaku

Perangkat dapat mempublikasikan status dan pembaruan hasil kapan saja menggunakan perintah yang dicadangkan topik MQTT. Untuk memberikan konteks tambahan, perangkat dapat menggunakan reasonCode dan reasonDescription bidang dalam statusReason objek.

Diagram berikut menunjukkan transisi status eksekusi.

Gambar yang menunjukkan bagaimana transisi status eksekusi perintah antara berbagai status.
catatan

Ketika AWS IoT mendeteksi tidak ada respons perangkat dalam periode batas waktu, itu ditetapkan TIMED_OUT sebagai status sementara yang memungkinkan percobaan ulang dan perubahan status. Jika perangkat Anda melaporkan secara eksplisitTIMED_OUT, ini menjadi status terminal tanpa transisi lebih lanjut. Untuk informasi selengkapnya, lihat Eksekusi perintah non-terminal.

Bagian berikut menjelaskan eksekusi terminal dan non-terminal dan statusnya.

Eksekusi perintah non-terminal

Eksekusi adalah non-terminal jika dapat menerima pembaruan dari perangkat. Eksekusi non-terminal dianggap Aktif. Status berikut adalah non-terminal:

  • CREATED

    Saat Anda memulai eksekusi dari AWS IoT konsol atau menggunakan StartCommandExecution API, permintaan yang berhasil mengubah status menjadiCREATED. Dari status ini, eksekusi dapat beralih ke status non-terminal atau terminal lainnya.

  • IN_PROGRESS

    Setelah menerima muatan, perangkat dapat mulai menjalankan instruksi dan melakukan tindakan yang ditentukan. Saat mengeksekusi, perangkat dapat mempublikasikan tanggapan terhadap topik respons perintah dan memperbarui status keIN_PROGRESS. DariIN_PROGRESS, eksekusi dapat bertransisi ke status terminal atau non-terminal kecuali. CREATED

    catatan

    UpdateCommandExecutionAPI dapat dipanggil beberapa kali dengan IN_PROGRESS status. Tentukan detail eksekusi tambahan menggunakan statusReason objek.

  • TIMED_OUT

    Baik cloud dan perangkat dapat memicu status ini. Eksekusi dalam CREATED atau IN_PROGRESS status dapat berubah menjadi karena TIMED_OUT alasan berikut:

    • Setelah mengirim perintah, timer dimulai. Jika perangkat tidak merespons dalam durasi yang ditentukan, cloud akan mengubah statusnyaTIMED_OUT. Dalam hal ini, eksekusi non-terminal.

    • Perangkat dapat mengganti status ke status terminal apa pun atau melaporkan batas waktu dan menyetel status ke. TIMED_OUT Dalam hal ini, status tetap adaTIMED_OUT, tetapi bidang StatusReason objek berubah berdasarkan informasi perangkat. Eksekusi menjadi terminal.

    Untuk informasi selengkapnya, lihat Nilai waktu habis dan status TIMED_OUT eksekusi.

Eksekusi perintah terminal

Eksekusi menjadi terminal ketika tidak lagi menerima pembaruan dari perangkat. Status berikut adalah terminal. Eksekusi dapat bertransisi ke status terminal dari status non-terminal apa pun:CREATED,, IN_PROGRESS atau. TIMED_OUT

  • SUCCEEDED

    Jika perangkat berhasil menyelesaikan eksekusi, perangkat dapat mempublikasikan respons terhadap topik respons perintah dan memperbarui status keSUCCEEDED.

  • FAILED

    Ketika perangkat gagal menyelesaikan eksekusi, perangkat dapat mempublikasikan respons terhadap topik respons perintah dan memperbarui status keFAILED. Gunakan reasonCode dan reasonDescription bidang di statusReason objek, atau CloudWatch log, untuk memecahkan masalah kegagalan.

  • MENOLAK

    Ketika perangkat menerima permintaan yang tidak valid atau tidak kompatibel, perangkat dapat memanggil API dengan status. UpdateCommandExecution REJECTED Gunakan reasonDescription bidang reasonCode dan di statusReason objek, atau CloudWatch log, untuk memecahkan masalah.