Tutorial: Menginstal Device SDK dan menjalankan aplikasi sampel untuk Device Shadows - AWS IoT Core
Langkah 1: Jalankan aplikasi contoh shadow.pyLangkah 2: Tinjau aplikasi sampel shadow.py Device SDKLangkah 3: Memecahkan masalah denganshadow.pyaplikasi sampelLangkah 4: Tinjau hasil dan langkah selanjutnya

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

Tutorial: Menginstal Device SDK dan menjalankan aplikasi sampel untuk Device Shadows

Bagian ini menunjukkan bagaimana Anda dapat menginstal perangkat lunak yang diperlukan danAWS IoTPerangkat SDK untuk Python dan jalankanshadow.pycontoh aplikasi untuk mengedit dokumen Shadow dan mengontrol status bayangan.

Dalam tutorial ini, Anda akan belajar cara:

  • Gunakan perangkat lunak yang diinstal danAWS IoTPerangkat SDK untuk Python untuk menjalankan aplikasi sampel.

  • Pelajari cara memasukkan nilai menggunakan aplikasi sampel menerbitkan nilai yang diinginkan diAWS IoTkonsol.

  • Tinjaushadow.pycontoh aplikasi dan bagaimana menggunakan protokol MQTT untuk memperbarui status bayangan.

Sebelum Anda menjalankan tutorial ini:

Anda harus telah mengaturAkun AWS, mengkonfigurasi perangkat Raspberry Pi Anda, dan membuatAWS IoThal dan kebijakan yang memberikan izin perangkat untuk mempublikasikan dan berlangganan topik yang dipesan MQTT dari layanan Device Shadow. Untuk informasi selengkapnya, lihat Tutorial: Mempersiapkan Raspberry Pi Anda untuk menjalankan aplikasi bayangan.

Anda juga harus menginstal Git, Python, danAWS IoTSDK for Python. Tutorial ini dibangun di atas konsep-konsep yang disajikan dalam tutorialConnect Raspberry Pi atau perangkat lain. Jika Anda belum mencoba tutorial itu, kami sarankan Anda mengikuti langkah-langkah yang dijelaskan dalam tutorial itu untuk menginstal file sertifikat dan Device SDK dan kemudian kembali ke tutorial ini untuk menjalankanshadow.pyaplikasi sampel.

Tutorial ini memakan waktu sekitar 20 menit untuk menyelesaikannya.

Langkah 1: Jalankan aplikasi contoh shadow.py

Sebelum Anda menjalankanshadow.pycontoh aplikasi, Anda akan memerlukan informasi berikut selain nama dan lokasi file sertifikat yang Anda instal.

Nilai parameter aplikasi

Parameter

Dimana menemukan nilainya
your-iot-thing-nama

NamaAWS IoThal yang Anda buat sebelumnyaLangkah 2: Membuat sumber daya hal dan melampirkan kebijakan untuk hal.

Untuk menemukan nilai ini, diAWS IoTkonsol, pilihKelola, dan kemudian pilihThings.
your-iot-endpoint

Parameteryour-iot-endpointmemiliki format:endpoint_id-ats.iot.region.amazonaws.com, misalnya,a3qj468EXAMPLE-ats.iot.us-west-2.amazonaws.com. Untuk menemukan nilai ini:

  1. DiAWS IoTkonsol, pilihKelola, dan kemudian pilihThings.

  2. Pilih hal IoT yang Anda buat untuk perangkat Anda,MY_LIGHT_Bulb, yang Anda gunakan sebelumnya, dan kemudian pilihBerinteraksi. Pada halaman detail objek, titik akhir Anda ditampilkan di halamanHTTPSbagian.
Instal dan jalankan aplikasi sampel

  1. Buka direktori aplikasi sampel.

    cd ~/aws-iot-device-sdk-python-v2/samples

  2. Di jendela baris perintah, gantiyour-iot-endpointdanyour-iot-thing-namaseperti yang ditunjukkan dan jalankan perintah ini.

    python3 shadow.py --ca_file ~/certs/Amazon-root-CA-1.pem --cert ~/certs/device.pem.crt --key ~/certs/private.pem.key --endpoint your-iot-endpoint --thing_name your-iot-thing-name

  3. Amati bahwa aplikasi sampel:

    1. Terhubung keAWSLayanan IoT untuk akun Anda.

    2. BerlanggananDeltaperistiwa danUpdatedanGettanggapan.

    3. Meminta Anda untuk memasukkan nilai yang diinginkan di terminal.

    4. Menampilkan output yang serupa dengan yang berikut ini:

    Connecting to a3qEXAMPLEffp-ats.iot.us-west-2.amazonaws.com with client ID 'test-0c8ae2ff-cc87-49d2-a82a-ae7ba1d0ca5a'...
Connected!
Subscribing to Delta events...
Subscribing to Update responses...
Subscribing to Get responses...
Requesting current shadow state...
Launching thread to read user input...
Finished getting initial shadow state.
Shadow contains reported value 'off'.
Enter desired value:
catatan

Jika Anda mengalami kesulitan menjalankanshadow.pycontoh aplikasi, reviewLangkah 3: Memecahkan masalah denganshadow.pyaplikasi sampel. Untuk mendapatkan informasi tambahan yang dapat membantu Anda memperbaiki masalah, tambahkan--verbosity debugparameter ke baris perintah sehingga aplikasi sampel menampilkan pesan rinci tentang apa yang dilakukannya.

Masukkan nilai dan amati pembaruan dalam dokumen Shadow

Anda dapat memasukkan nilai di terminal untuk menentukandesirednilai, yang juga memperbaruireportednilai. Katakanlah Anda memasukkan warnayellowdi terminal. Parameterreportednilai juga diperbarui untuk warnayellow. Berikut ini menunjukkan pesan yang ditampilkan di terminal:

Enter desired value:
yellow
Changed local shadow value to 'yellow'.
Updating reported shadow value to 'yellow'...
Update request published.
Finished updating reported shadow value to 'yellow'.

Ketika Anda mempublikasikan permintaan pemutakhiran ini,AWS IoTmenciptakan default, bayangan klasik untuk sumber daya hal. Anda dapat mengamati permintaan pembaruan yang Anda publikasikan kereporteddandesirednilai-nilai dalamAWS IoTkonsol dengan melihat dokumen Shadow untuk sumber daya hal yang Anda buat (misalnya,My_light_bulb). Untuk melihat pembaruan dalam dokumen Shadow:

  1. DiAWS IoTkonsol, pilihKeloladan kemudian pilihThings.

  2. Dalam daftar hal-hal yang ditampilkan, pilih hal yang Anda buat, pilihBayangan, dan kemudian pilihBayangan klasik.

Dokumen Shadow akan serupa dengan yang berikut ini, menunjukkanreporteddandesirednilai diatur ke warnayellow. Anda melihat nilai-nilai ini diStatus bayanganbagian dari dokumen.

{
"desired": {
  "welcome": "aws-iot",
  "color": "yellow"
},
"reported": {
  "welcome": "aws-iot",
  "color": "yellow"
}
}

Anda juga melihatMetadatabagian yang berisi informasi timestamp dan nomor versi permintaan.

Anda dapat menggunakan versi dokumen negara untuk memastikan Anda memperbarui versi terbaru dari dokumen Shadow perangkat. Jika Anda mengirim permintaan pembaruan lain, nomor versi bertambah 1. Ketika Anda menyediakan versi dengan permintaan pembaruan, layanan menolak permintaan dengan kode respons konflik HTTP 409 jika versi dokumen status saat ini tidak cocok dengan versi yang disediakan. 

{
"metadata": {
  "desired": {
    "welcome": {
      "timestamp": 1620156892
    },
    "color": {
      "timestamp": 1620156893
    }
  },
  "reported": {
    "welcome": {
      "timestamp": 1620156892
    },
    "color": {
      "timestamp": 1620156893
    }
  }
},
"version": 10
}

Untuk mempelajari lebih lanjut tentang dokumen Shadow dan mengamati perubahan pada informasi negara, lanjutkan ke tutorial berikutnyaTutorial: Berinteraksi dengan Device Shadow menggunakan aplikasi sampel dan klien uji MQTTseperti yang dijelaskan dalamLangkah 4: Tinjau hasil dan langkah selanjutnyabagian dari tutorial ini. Opsional, Anda juga dapat mempelajari tentangshadow.pykode sampel dan bagaimana menggunakan protokol MQTT di bagian berikut.

Langkah 2: Tinjau aplikasi sampel shadow.py Device SDK

Bagian ini mengulasshadow.pycontoh aplikasi dariAWS IoTSDK v2 for Pythondigunakan dalam tutorial ini. Di sini, kami akan meninjau bagaimana menghubungkannyaAWS IoT Coredengan menggunakan MQTT dan MQTT lebih protokol WSS. ParameterAWSwaktu aktif umum (AWS-CRT)perpustakaan menyediakan dukungan protokol komunikasi tingkat rendah dan disertakan denganAWS IoTSDK v2 for Python.

Sementara tutorial ini menggunakan MQTT dan MQTT lebih WSS,AWS IoTmendukung perangkat yang mempublikasikan permintaan HTTPS. Untuk contoh program Python yang mengirimkan pesan HTTP dari perangkat, lihatContoh kode HTTPSmenggunakan Pythonrequestsperpustakaan.

Untuk informasi tentang bagaimana Anda dapat membuat keputusan berdasarkan informasi tentang protokol mana yang akan digunakan untuk komunikasi perangkat Anda, tinjauMemilih protokol untuk komunikasi perangkat Anda.

MQTT

Parametershadow.pypanggilan sampelmtls_from_path(ditampilkan di sini) dimqtt_connection_builderuntuk membangun koneksi denganAWS IoT Coredengan menggunakan protokol MQTT.mtls_from_pathmenggunakan sertifikat X.509 dan TLS v1.2 untuk mengotentikasi perangkat. ParameterAWSperpustakaan -CRT menangani rincian tingkat yang lebih rendah dari koneksi itu.

mqtt_connection = mqtt_connection_builder.mtls_from_path(
  endpoint=args.endpoint,
  cert_filepath=args.cert,
  pri_key_filepath=args.key,
  ca_filepath=args.ca_file,
  client_bootstrap=client_bootstrap,
  on_connection_interrupted=on_connection_interrupted,
  on_connection_resumed=on_connection_resumed,
  client_id=args.client_id,
  clean_session=False,
  keep_alive_secs=6
)

  • endpointadalahAWS IoTendpoint yang Anda lewatkan dari baris perintah danclient_idadalah ID yang mengidentifikasi perangkat ini secara unik diWilayah AWS.

  • cert_filepath,pri_key_filepath, danca_filepathadalah jalur ke sertifikat perangkat dan file kunci pribadi, dan file root CA.

  • client_bootstrapadalah objek runtime umum yang menangani kegiatan komunikasi soket, dan dipakai sebelum panggilan kemqtt_connection_builder.mtls_from_path.

  • on_connection_interrupteddanon_connection_resumedadalah fungsi callback untuk memanggil ketika koneksi perangkat terganggu dan dilanjutkan.

  • clean_sessionadalah apakah akan memulai sesi baru, persisten, atau jika ada, sambungkan kembali ke sesi yang sudah ada.keep_alive_secsadalah nilai tetap hidup, dalam hitungan detik, untuk mengirimCONNECTpermintaan. Ping akan secara otomatis dikirim pada interval ini. Server mengasumsikan bahwa koneksi hilang jika tidak menerima ping setelah 1,5 kali nilai ini.

Parametershadow.pysampel juga panggilanwebsockets_with_default_aws_signingdi dalammqtt_connection_builderuntuk membangun koneksi denganAWS IoT Coremenggunakan protokol MQTT lebih WSS. MQTT lebih WSS juga menggunakan parameter yang sama seperti MQTT dan mengambil parameter tambahan:

  • regionadalahAWSpenandatanganan Wilayah digunakan oleh otentikasi Signature V4,credentials_provideradalahAWSkredensi yang disediakan untuk digunakan untuk otentikasi. Wilayah dilewatkan dari baris perintah, dancredentials_providerobjek dipakai sesaat sebelum panggilan kemqtt_connection_builder.websockets_with_default_aws_signing.

  • websocket_proxy_optionsadalah opsi proxy HTTP, jika menggunakan host proxy. Dishadow.pycontoh aplikasi, nilai ini dipakai sesaat sebelum panggilan kemqtt_connection_builder.websockets_with_default_aws_signing.

Berlangganan topik dan acara Shadow

Parametershadow.pysampel mencoba untuk membangun koneksi dan menunggu untuk sepenuhnya terhubung. Jika tidak terhubung, perintah akan antri. Setelah terhubung, sampel berlangganan peristiwa delta dan memperbarui dan mendapatkan pesan, dan menerbitkan pesan dengan kualitas layanan (QoS) tingkat 1 (mqtt.QoS.AT_LEAST_ONCE).

Ketika perangkat berlangganan pesan dengan QoS level 1, broker pesan menyimpan pesan bahwa perangkat berlangganan sampai mereka dapat dikirim ke perangkat. Broker pesan mengirim ulang pesan sampai menerimaPUBACKrespon dari perangkat.

Untuk informasi selengkapnya tentang protokol MQTT, lihatTinjau protokol MQTTdanMQTT.

Untuk informasi lebih lanjut tentang bagaimana MQTT, MQTT lebih WSS, sesi persisten, dan tingkat QoS yang digunakan dalam tutorial ini, lihatMeninjau aplikasi sampel SDK Perangkat pubsub.py.

Langkah 3: Memecahkan masalah denganshadow.pyaplikasi sampel

Ketika Anda menjalankanshadow.pycontoh aplikasi, Anda akan melihat beberapa pesan yang ditampilkan di terminal dan prompt untuk memasukkandesirednilai. Jika program melempar kesalahan, maka untuk men-debug kesalahan, Anda dapat mulai dengan memeriksa apakah Anda menjalankan perintah yang benar untuk sistem Anda.

Dalam beberapa kasus, pesan kesalahan mungkin menunjukkan masalah koneksi dan terlihat mirip dengan:Host name was invalid for dns resolutionatauConnection was closed unexpectedly. Dalam kasus tersebut, berikut adalah beberapa hal yang dapat Anda periksa:

  • Periksa alamat endpoint dalam perintah

    Tinjauendpointargumen dalam perintah yang Anda masukkan untuk menjalankan aplikasi sampel, (misalnya,a3qEXAMPLEffp-ats.iot.us-west-2.amazonaws.com) dan periksa nilai ini diAWS IoTkonsol.

    Untuk memeriksa apakah Anda menggunakan nilai yang benar:

    1. DiAWS IoTkonsol, pilihKeloladan kemudian pilihThings.

    2. Pilih hal yang Anda buat untuk aplikasi sampel Anda (misalnya,MY_LIGHT_Bulb) dan kemudian pilihInteraksi.

    Pada halaman detail objek, titik akhir Anda ditampilkan di halamanHTTPSbagian. Anda juga harus melihat pesan yang mengatakan:This thing already appears to be connected.

  • Periksa aktivasi sertifikat

    Sertifikat mengautentikasi perangkat AndaAWS IoT Core.

    Untuk memeriksa apakah sertifikat Anda aktif:

    1. DiAWS IoTkonsol, pilihKeloladan kemudian pilihThings.

    2. Pilih hal yang Anda buat untuk aplikasi sampel Anda (misalnya,MY_LIGHT_Bulb) dan kemudian pilihKeamanan.

    3. Pilih sertifikat dan kemudian, dari halaman rincian sertifikat, pilih Pilih sertifikat dan kemudian, dari halaman rincian sertifikat, pilihTindakan.

    Jika dalam daftar dropdownAktifkantidak tersedia dan Anda hanya dapat memilihNonaktifkan, sertifikat Anda aktif. Jika tidak, pilihAktifkandan jalankan kembali program sampel.

    Jika program masih tidak berjalan, periksa nama berkas sertifikat dicertsfolder.

  • Periksa kebijakan yang dilampirkan pada sumber daya hal

    Sementara sertifikat mengautentikasi perangkat Anda,AWS IoTkebijakan mengizinkan perangkat untuk melakukanAWS IoToperasi, seperti berlangganan atau menerbitkan topik cadangan MQTT.

    Untuk memeriksa apakah kebijakan yang benar terlampir:

    1. Temukan sertifikat seperti yang dijelaskan sebelumnya, lalu pilihKebijakan.

    2. Pilih kebijakan yang ditampilkan dan periksa apakah kebijakan tersebut menjelaskanconnect,subscribe,receive, danpublishtindakan yang memberikan izin perangkat untuk mempublikasikan dan berlangganan topik yang dipesan MQTT.

      Untuk kebijakan contoh, lihatLangkah 1: MembuatAWS IoTkebijakan untuk Device Shadow.

    Jika Anda melihat pesan kesalahan yang menunjukkan masalah saat terhubung keAWS IoT, bisa jadi karena izin yang Anda gunakan untuk kebijakan. Jika demikian, kami menyarankan Anda untuk memulai dengan kebijakan yang menyediakan akses penuh keAWS IoTsumber daya dan kemudian menjalankan kembali program sampel. Anda dapat mengedit kebijakan saat ini, atau memilih kebijakan saat ini, pilihLepaskan, dan kemudian membuat kebijakan lain yang menyediakan akses penuh dan melampirkannya ke sumber daya hal Anda. Anda kemudian dapat membatasi kebijakan untuk hanya tindakan dan kebijakan yang Anda butuhkan untuk menjalankan program.

    {
  "Version": "2012-10-17",
  "Statement": [
      {
          "Effect": "Allow",
          "Action": [
              "iot:*"
          ],
          "Resource": "*"
      }
  ]
}
  • Periksa instalasi SDK Perangkat

    Jika program masih belum berjalan, Anda dapat menginstal ulang Device SDK untuk memastikan bahwa instalasi SDK Anda selesai dan benar.

Langkah 4: Tinjau hasil dan langkah selanjutnya

Dalam tutorial ini, Anda belajar bagaimana:

  • Menginstal perangkat lunak, alat, dan perangkat lunak yang diperlukanAWS IoTSDK for Python.

  • Memahami bagaimana aplikasi sampel,shadow.py, menggunakan protokol MQTT untuk mengambil dan memperbarui status bayangan saat ini.

  • Jalankan contoh aplikasi untuk Device Shadows dan amati pembaruan ke dokumen Shadow diAWS IoTkonsol. Anda juga belajar memecahkan masalah dan memperbaiki kesalahan saat menjalankan program.

Langkah selanjutnya

Sekarang Anda dapat menjalankanshadow.pycontoh aplikasi dan menggunakan Device Shadows untuk mengontrol negara. Anda dapat mengamati pembaruan pada dokumen Shadow diAWS IoTKonsol dan amati peristiwa delta yang merespons aplikasi sampel. Dengan menggunakan klien uji MQTT, Anda dapat berlangganan topik bayangan yang dipesan dan mengamati pesan yang diterima oleh topik saat menjalankan program sampel. Untuk informasi selengkapnya tentang cara menjalankan tutorial ini, lihatTutorial: Berinteraksi dengan Device Shadow menggunakan aplikasi sampel dan klien uji MQTT.