Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# AWS IoT Aplikasi demo Device Shadow
**penting**
Demo ini di-host di Amazon-FreeRTOS repositori yang tidak digunakan lagi. Kami menyarankan Anda [mulai di sini](freertos-getting-started-modular.md) ketika Anda membuat proyek baru. Jika Anda sudah memiliki proyek FreeRTOS yang ada berdasarkan repositori yang sekarang tidak digunakan lagi, Amazon-FreeRTOS lihat. [Amazon-FreeRTOS Panduan Migrasi Repositori Github](github-repo-migration.md)
## Pengantar
Demo ini menunjukkan cara menggunakan pustaka AWS IoT Device Shadow untuk terhubung ke [layanan AWS Device Shadow](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html). Ini menggunakan [Perpustakaan CoreMQTT](coremqtt.md) untuk membuat koneksi MQTT dengan TLS (Mutual Authentication) ke Broker AWS IoT MQTT dan parser perpustakaan CoreJson untuk mengurai dokumen bayangan yang diterima dari layanan Shadow. AWS Demo menunjukkan operasi bayangan dasar, seperti cara memperbarui dokumen bayangan dan cara menghapus dokumen bayangan. Demo juga menunjukkan cara mendaftarkan fungsi callback dengan pustaka CoreMQTT untuk menangani pesan seperti bayangan `/update` dan `/update/delta` pesan yang dikirim dari layanan Device Shadow. AWS IoT
Demo ini dimaksudkan sebagai latihan pembelajaran hanya karena permintaan untuk memperbarui dokumen bayangan (status) dan respons pembaruan dilakukan oleh aplikasi yang sama. Dalam skenario produksi yang realistis, aplikasi eksternal akan meminta pembaruan status perangkat dari jarak jauh, bahkan jika perangkat saat ini tidak terhubung. Perangkat akan mengakui permintaan pembaruan saat terhubung.
**catatan**
Untuk mengatur dan menjalankan demo FreeRTOS, ikuti langkah-langkahnya. [Memulai dengan FreeRTOS](freertos-getting-started.md)
## Fungsionalitas
Demo membuat tugas aplikasi tunggal yang mengulang melalui serangkaian contoh yang mendemonstrasikan bayangan `/update` dan `/update/delta` panggilan balik untuk mensimulasikan pengalihan status perangkat jarak jauh. Ini mengirimkan pembaruan bayangan dengan `desired` status baru dan menunggu perangkat mengubah `reported` statusnya sebagai respons terhadap `desired` status baru. Selain itu, `/update` callback bayangan digunakan untuk mencetak status bayangan yang berubah. Demo ini juga menggunakan koneksi MQTT yang aman ke Broker AWS IoT MQTT, dan mengasumsikan ada status dalam bayangan perangkat. `powerOn`
Demo melakukan operasi berikut:
1. Buat koneksi MQTT dengan menggunakan fungsi pembantu di. `shadow_demo_helpers.c`
1. Merakit string topik MQTT untuk operasi bayangan perangkat, menggunakan makro yang ditentukan oleh pustaka Device Shadow. AWS IoT
1. Publikasikan ke topik MQTT yang digunakan untuk menghapus bayangan perangkat untuk menghapus bayangan perangkat yang ada.
1. Berlangganan topik MQTT untuk`/update/delta`, `/update/accepted` dan `/update/rejected` gunakan fungsi pembantu di. `shadow_demo_helpers.c`
1. Publikasikan status yang diinginkan `powerOn` menggunakan fungsi pembantu di`shadow_demo_helpers.c`. Ini akan menyebabkan `/update/delta` pesan dikirim ke perangkat.
1. Tangani pesan MQTT yang masuk`prvEventCallback`, dan tentukan apakah pesan tersebut terkait dengan bayangan perangkat menggunakan fungsi yang ditentukan oleh pustaka Device Shadow AWS IoT (). `Shadow_MatchTopic` Jika pesan adalah `/update/delta` pesan bayangan perangkat, maka fungsi demo utama akan mempublikasikan pesan kedua untuk memperbarui status yang dilaporkan ke`powerOn`. Jika `/update/accepted` pesan diterima, verifikasi bahwa pesan tersebut `clientToken` sama dengan yang dipublikasikan sebelumnya dalam pesan pembaruan. Itu akan menandai akhir dari demo.
Demo dapat ditemukan di file `{{freertos}}/demos/device_shadow_for_aws/shadow_demo_main.c` atau di [ GitHub](https://github.com/aws/amazon-freertos/blob/main/demos/device_shadow_for_aws/shadow_demo_main.c).
Tangkapan layar berikut menunjukkan output yang diharapkan ketika demo berhasil.
## Connect ke AWS IoT Pialang MQTT
Untuk terhubung ke broker AWS IoT MQTT, kami menggunakan metode yang sama seperti `MQTT_Connect()` di. [Demo otentikasi timbal balik CoreMQTT](mqtt-demo-ma.md)
## Hapus dokumen bayangan
Untuk menghapus dokumen bayangan, panggil `xPublishToTopic` dengan pesan kosong, menggunakan makro yang ditentukan oleh pustaka AWS IoT Device Shadow. Ini digunakan `MQTT_Publish` untuk mempublikasikan ke `/delete` topik. Bagian kode berikut menunjukkan bagaimana hal ini dilakukan dalam fungsi`prvShadowDemoTask`.
```
/* First of all, try to delete any Shadow document in the cloud. */
returnStatus = PublishToTopic( SHADOW_TOPIC_STRING_DELETE( THING_NAME ),
SHADOW_TOPIC_LENGTH_DELETE( THING_NAME_LENGTH ),
pcUpdateDocument,
0U );
```
## Berlangganan topik bayangan
Berlangganan topik Device Shadow untuk menerima pemberitahuan dari AWS IoT broker tentang perubahan bayangan. Topik Device Shadow dirakit oleh makro yang ditentukan di pustaka Device Shadow. Bagian kode berikut menunjukkan bagaimana hal ini dilakukan dalam `prvShadowDemoTask` fungsi.
```
/* Then try to subscribe shadow topics. */
if( returnStatus == EXIT_SUCCESS )
{
returnStatus = SubscribeToTopic(
SHADOW_TOPIC_STRING_UPDATE_DELTA( THING_NAME ),
SHADOW_TOPIC_LENGTH_UPDATE_DELTA( THING_NAME_LENGTH ) );
}
if( returnStatus == EXIT_SUCCESS )
{
returnStatus = SubscribeToTopic(
SHADOW_TOPIC_STRING_UPDATE_ACCEPTED( THING_NAME ),
SHADOW_TOPIC_LENGTH_UPDATE_ACCEPTED( THING_NAME_LENGTH ) );
}
if( returnStatus == EXIT_SUCCESS )
{
returnStatus = SubscribeToTopic(
SHADOW_TOPIC_STRING_UPDATE_REJECTED( THING_NAME ),
SHADOW_TOPIC_LENGTH_UPDATE_REJECTED( THING_NAME_LENGTH ) );
}
```
## Kirim Pembaruan Bayangan
Untuk mengirim pembaruan bayangan, demo memanggil `xPublishToTopic` dengan pesan dalam format JSON, menggunakan makro yang ditentukan oleh pustaka Device Shadow. Ini digunakan `MQTT_Publish` untuk mempublikasikan ke `/delete` topik. Bagian kode berikut menunjukkan bagaimana hal ini dilakukan dalam `prvShadowDemoTask` fungsi.
```
#define SHADOW_REPORTED_JSON \
"{" \
"\"state\":{" \
"\"reported\":{" \
"\"powerOn\":%01d" \
"}" \
"}," \
"\"clientToken\":\"%06lu\"" \
"}"
snprintf( pcUpdateDocument,
SHADOW_REPORTED_JSON_LENGTH + 1,
SHADOW_REPORTED_JSON,
( int ) ulCurrentPowerOnState,
( long unsigned ) ulClientToken );
xPublishToTopic( SHADOW_TOPIC_STRING_UPDATE( THING_NAME ),
SHADOW_TOPIC_LENGTH_UPDATE( THING_NAME_LENGTH ),
pcUpdateDocument,
( SHADOW_DESIRED_JSON_LENGTH + 1 ) );
```
## Menangani pesan delta bayangan dan pesan pembaruan bayangan
Fungsi callback pengguna, yang terdaftar ke [CoreMQTT Client Library](https://www.freertos.org/iot-device-shadow/device-shadow-demo.html#handle-shadow-messages) menggunakan `MQTT_Init` fungsi tersebut, akan memberi tahu kami tentang peristiwa paket yang masuk. Lihat fungsi callback [prv aktif EventCallback](https://github.com/aws/amazon-freertos/blob/main/demos/device_shadow_for_aws/shadow_demo_main.c#L671-L753). GitHub
Fungsi callback mengonfirmasi jenis paket yang masuk`MQTT_PACKET_TYPE_PUBLISH`, dan menggunakan Device Shadow Library API `Shadow_MatchTopic` untuk mengonfirmasi bahwa pesan yang masuk adalah pesan bayangan.
Jika pesan yang masuk adalah pesan bayangan dengan tipe`ShadowMessageTypeUpdateDelta`, maka kami memanggil [prv UpdateDeltaHandler](https://github.com/aws/amazon-freertos/blob/main/demos/device_shadow_for_aws/shadow_demo_main.c#L464-L580) untuk menangani pesan ini. Handler `prvUpdateDeltaHandler` menggunakan pustaka CoreJson untuk mengurai pesan guna mendapatkan nilai delta untuk `powerOn` status dan membandingkannya dengan status perangkat saat ini yang dikelola secara lokal. Jika berbeda, status perangkat lokal diperbarui untuk mencerminkan nilai baru `powerOn` status dari dokumen bayangan.
Jika pesan yang masuk adalah pesan bayangan dengan tipe`ShadowMessageTypeUpdateAccepted`, maka kami memanggil [prv UpdateAcceptedHandler](https://github.com/aws/amazon-freertos/blob/main/demos/device_shadow_for_aws/shadow_demo_main.c#L584-L667) untuk menangani pesan ini. Handler `prvUpdateAcceptedHandler` mem-parsing pesan menggunakan pustaka CoreJson untuk mendapatkan pesan dari `clientToken` pesan. Fungsi handler ini memeriksa apakah token klien dari pesan JSON cocok dengan token klien yang digunakan oleh aplikasi. Jika tidak cocok, fungsi mencatat pesan peringatan.