Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Demo CoreMQTT
**penting**
Demo ini di-host di repositori Amazon-Freertos 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 sudah ada berdasarkan repositori Amazon-Freertos yang sekarang tidak digunakan lagi, lihat. [Panduan Migrasi Repositori Github Amazon-freertos](github-repo-migration.md)
Demo ini dapat membantu Anda mempelajari cara menggunakan pustaka CoreMQTT.
**Topics**
+ [Demo otentikasi timbal balik CoreMQTT](mqtt-demo-ma.md)
+ [Demo berbagi koneksi Agen CoreMQTT](mqtt-demo-cs.md)
# Demo otentikasi timbal balik CoreMQTT
**penting**
Demo ini di-host di repositori Amazon-Freertos 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 sudah ada berdasarkan repositori Amazon-Freertos yang sekarang tidak digunakan lagi, lihat. [Panduan Migrasi Repositori Github Amazon-freertos](github-repo-migration.md)
## Pengantar
Proyek demo otentikasi timbal balik CoreMQTT menunjukkan kepada Anda cara membuat koneksi ke broker MQTT menggunakan TLS dengan otentikasi timbal balik antara klien dan server. [Demo ini menggunakan implementasi antarmuka transport berbasis MBEDTLS untuk membuat server dan koneksi TLS yang diautentikasi klien, dan menunjukkan alur kerja subscribe-publish MQTT pada tingkat QoS 1.](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/errata01/os/mqtt-v3.1.1-errata01-os-complete.html#_Toc442180914) Ini berlangganan filter topik, kemudian menerbitkan ke topik yang cocok dengan filter dan menunggu penerimaan pesan-pesan itu kembali dari server di tingkat QoS 1. Siklus penerbitan ke broker dan menerima pesan yang sama kembali dari broker diulang tanpa batas waktu. Pesan dalam demo ini dikirim di QoS 1, yang menjamin setidaknya satu pengiriman sesuai dengan spesifikasi MQTT.
**catatan**
Untuk mengatur dan menjalankan demo FreeRTOS, ikuti langkah-langkahnya. [Memulai dengan FreeRTOS](freertos-getting-started.md)
## Kode sumber
File sumber demo diberi nama `mqtt_demo_mutual_auth.c` dan dapat ditemukan di `freertos/demos/coreMQTT/` direktori dan [ GitHub](https://github.com/aws/amazon-freertos/blob/main/demos/coreMQTT/mqtt_demo_mutual_auth.c)situs web.
## Fungsionalitas
Demo menciptakan tugas aplikasi tunggal yang berputar melalui serangkaian contoh yang menunjukkan cara terhubung ke broker, berlangganan topik di broker, mempublikasikan ke topik di broker, lalu akhirnya, putuskan sambungan dari broker. Aplikasi demo berlangganan dan menerbitkan topik yang sama. Setiap kali demo menerbitkan pesan ke broker MQTT, broker mengirim pesan yang sama kembali ke aplikasi demo.
Penyelesaian demo yang berhasil akan menghasilkan output yang mirip dengan gambar berikut.
![\[Output terminal demo MQTT pada penyelesaian yang berhasil\]](http://docs.aws.amazon.com/id_id/freertos/latest/userguide/images/coremqtt-mad-output.png)
AWS IoT Konsol akan menghasilkan output yang mirip dengan gambar berikut.
![\[Output konsol demo MQTT pada penyelesaian yang berhasil\]](http://docs.aws.amazon.com/id_id/freertos/latest/userguide/images/coremqtt-mad-console.png)
## Coba lagi logika dengan backoff eksponensial dan jitter
Fungsi [ prvBackoffForCoba lagi](https://github.com/aws/amazon-freertos/blob/main/demos/coreMQTT/mqtt_demo_mutual_auth.c#L671-L717) menunjukkan bagaimana operasi jaringan yang gagal dengan server, misalnya, koneksi TLS atau permintaan berlangganan MQTT, dapat dicoba ulang dengan backoff eksponensial dan jitter. Fungsi menghitung periode backoff untuk upaya coba lagi berikutnya, dan melakukan penundaan backoff jika upaya coba lagi belum habis. Karena perhitungan periode backoff membutuhkan pembuatan angka acak, fungsi menggunakan PKCS11 modul untuk menghasilkan angka acak. Penggunaan PKCS11 modul memungkinkan akses ke True Random Number Generator (TRNG) jika platform vendor mendukungnya. Kami menyarankan Anda menyemai generator angka acak dengan sumber entropi khusus perangkat sehingga kemungkinan tabrakan dari perangkat selama percobaan ulang koneksi dikurangi.
## Menghubungkan ke broker MQTT
[ prvConnectToServerWithBackoffRetries](https://github.com/aws/amazon-freertos/blob/main/demos/coreMQTT/mqtt_demo_mutual_auth.c#L721-L782)Fungsi ini mencoba untuk membuat koneksi TLS yang saling diautentikasi ke broker MQTT. Jika koneksi gagal, ia mencoba lagi setelah periode backoff. Periode backoff akan meningkat secara eksponensial sampai jumlah upaya maksimum tercapai atau periode backoff maksimum tercapai. `BackoffAlgorithm_GetNextBackoff`Fungsi ini memberikan nilai backoff yang meningkat secara eksponensial dan pengembalian `RetryUtilsRetriesExhausted` ketika jumlah upaya maksimum telah tercapai. `prvConnectToServerWithBackoffRetries`Fungsi mengembalikan status kegagalan jika koneksi TLS ke broker tidak dapat dibuat setelah jumlah upaya yang dikonfigurasi.
MQTTConnectionWithBrokerFungsi [PRVCreate](https://github.com/aws/amazon-freertos/blob/main/demos/coreMQTT/mqtt_demo_mutual_auth.c#L785-L848) menunjukkan cara membuat koneksi MQTT ke broker MQTT dengan sesi bersih. Ini menggunakan antarmuka transportasi TLS, yang diimplementasikan dalam `FreeRTOS-Plus/Source/Application-Protocols/platform/freertos/transport/src/tls_freertos.c` file. Ingatlah bahwa kami sedang mengatur detik keep-alive untuk broker. `xConnectInfo`
Fungsi selanjutnya menunjukkan bagaimana antarmuka transport TLS dan fungsi waktu diatur dalam konteks MQTT menggunakan fungsi tersebut. `MQTT_Init` Hal ini juga menunjukkan bagaimana sebuah event callback function pointer (`prvEventCallback`) diatur. Callback ini digunakan untuk melaporkan pesan masuk.
## Berlangganan topik MQTT
MQTTSubscribeWithBackoffRetriesFungsi [prv](https://github.com/aws/amazon-freertos/blob/main/demos/coreMQTT/mqtt_demo_mutual_auth.c#L871-L969) menunjukkan cara berlangganan filter topik pada broker MQTT. Contoh ini menunjukkan cara berlangganan satu filter topik, tetapi dimungkinkan untuk meneruskan daftar filter topik dalam panggilan API berlangganan yang sama untuk berlangganan lebih dari satu filter topik. Juga, jika broker MQTT menolak permintaan berlangganan, langganan akan mencoba lagi, dengan dukungan eksponensial, untuk. `RETRY_MAX_ATTEMPTS`
## Menerbitkan ke topik
MQTTPublishToTopicFungsi [prv](https://github.com/aws/amazon-freertos/blob/main/demos/coreMQTT/mqtt_demo_mutual_auth.c#L972-L1004) menunjukkan cara mempublikasikan ke topik di broker MQTT.
## Menerima pesan masuk
Aplikasi mendaftarkan fungsi callback peristiwa sebelum terhubung ke broker, seperti yang dijelaskan sebelumnya. `prvMQTTDemoTask`Fungsi ini memanggil `MQTT_ProcessLoop` fungsi untuk menerima pesan masuk. Ketika pesan MQTT masuk diterima, ia memanggil fungsi callback acara yang terdaftar oleh aplikasi. [ prvEventCallback](https://github.com/aws/amazon-freertos/blob/main/demos/coreMQTT/mqtt_demo_mutual_auth.c#L1139-L1154)Fungsi ini adalah contoh dari fungsi callback peristiwa tersebut. `prvEventCallback`memeriksa jenis paket yang masuk dan memanggil handler yang sesuai. Dalam contoh di bawah ini, fungsi panggilan `prvMQTTProcessIncomingPublish()` untuk menangani pesan publikasi masuk atau `prvMQTTProcessResponse()` untuk menangani pengakuan (ACK).
## Memproses paket publikasi MQTT yang masuk
MQTTProcessIncomingPublishFungsi [prv](https://github.com/aws/amazon-freertos/blob/main/demos/coreMQTT/mqtt_demo_mutual_auth.c#L1108-L1135) menunjukkan cara memproses paket publikasi dari broker MQTT.
## Berhenti berlangganan dari suatu topik
Langkah terakhir dalam alur kerja adalah berhenti berlangganan dari topik sehingga broker tidak akan mengirim pesan yang dipublikasikan. `mqttexampleTOPIC` Berikut adalah definisi dari fungsi [prv MQTTUnsubscribe FromTopic](https://github.com/aws/amazon-freertos/blob/main/demos/coreMQTT/mqtt_demo_mutual_auth.c#L1007-L1043).
## Mengubah root CA yang digunakan dalam demo
Secara default, demo FreeRTOS menggunakan sertifikat Amazon Root CA 1 (kunci RSA 2048 bit) untuk mengautentikasi dengan server. AWS IoT Core Dimungkinkan untuk menggunakan [sertifikat CA lainnya untuk otentikasi server](https://docs.aws.amazon.com/iot/latest/developerguide/server-authentication.html#server-authentication-certs), termasuk sertifikat Amazon Root CA 3 (kunci ECC 256 bit). Untuk mengubah CA root untuk demo otentikasi timbal balik CoreMQTT:
1. Dalam editor teks, buka `freertos/vendors/vendor/boards/board/aws_demos/config_files/mqtt_demo_mutual_auth_config.h` file.
1. Dalam file, cari baris berikut.
```
* #define democonfigROOT_CA_PEM "...insert here..."
```
Hapus komentar baris ini dan, jika perlu, pindahkan melewati akhir ` */` blok komentar.
1. Salin sertifikat CA yang ingin Anda gunakan lalu tempel di `"...insert here..."` teks. Hasilnya akan terlihat seperti contoh berikut ini.
```
#define democonfigROOT_CA_PEM "-----BEGIN CERTIFICATE-----\n"\
"MIIBtjCCAVugAwIBAgITBmyf1XSXNmY/Owua2eiedgPySjAKBggqhkjOPQQDAjA5\n"\
"MQswCQYDVQQGEwJVUzEPMA0GA1UEChMGQW1hem9uMRkwFwYDVQQDExBBbWF6b24g\n"\
"Um9vdCBDQSAzMB4XDTE1MDUyNjAwMDAwMFoXDTQwMDUyNjAwMDAwMFowOTELMAkG\n"\
"A1UEBhMCVVMxDzANBgNVBAoTBkFtYXpvbjEZMBcGA1UEAxMQQW1hem9uIFJvb3Qg\n"\
"Q0EgMzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABCmXp8ZBf8ANm+gBG1bG8lKl\n"\
"ui2yEujSLtf6ycXYqm0fc4E7O5hrOXwzpcVOho6AF2hiRVd9RFgdszflZwjrZt6j\n"\
"QjBAMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgGGMB0GA1UdDgQWBBSr\n"\
"ttvXBp43rDCGB5Fwx5zEGbF4wDAKBggqhkjOPQQDAgNJADBGAiEA4IWSoxe3jfkr\n"\
"BqWTrBqYaGFy+uGh0PsceGCmQ5nFuMQCIQCcAu/xlJyzlvnrxir4tiz+OpAUFteM\n"\
"YyRIHN8wfdVoOw==\n"\
"-----END CERTIFICATE-----\n"
```
1. (Opsional) Anda dapat mengubah CA root untuk demo lainnya. Ulangi langkah 1 hingga 3 untuk setiap `freertos/vendors/vendor/boards/board/aws_demos/config_files/demo-name_config.h` file.
# Demo berbagi koneksi Agen CoreMQTT
**penting**
Demo ini di-host di repositori Amazon-Freertos 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 sudah ada berdasarkan repositori Amazon-Freertos yang sekarang tidak digunakan lagi, lihat. [Panduan Migrasi Repositori Github Amazon-freertos](github-repo-migration.md)
## Pengantar
Proyek demo berbagi koneksi CoreMQTT menunjukkan kepada Anda cara menggunakan aplikasi multithreaded untuk membuat koneksi ke broker AWS MQTT menggunakan TLS dengan otentikasi timbal balik antara klien dan server. [Demo ini menggunakan implementasi antarmuka transport berbasis MBEDTLS untuk membuat server dan koneksi TLS yang diautentikasi klien, dan menunjukkan alur kerja subscribe-publish MQTT pada tingkat QoS 1.](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/errata01/os/mqtt-v3.1.1-errata01-os-complete.html#_Toc442180914) Demo berlangganan filter topik, menerbitkan topik yang cocok dengan filter, dan kemudian menunggu untuk menerima pesan-pesan itu kembali dari server di tingkat QoS 1. Siklus penerbitan ke broker dan menerima pesan yang sama kembali dari broker diulang beberapa kali untuk setiap tugas yang dibuat. Pesan dalam demo ini dikirim di QoS 1, yang menjamin setidaknya satu pengiriman sesuai dengan spesifikasi MQTT.
**catatan**
Untuk mengatur dan menjalankan demo FreeRTOS, ikuti langkah-langkahnya. [Memulai dengan FreeRTOS](freertos-getting-started.md)
Demo ini menggunakan antrian aman utas untuk menahan perintah untuk berinteraksi dengan MQTT API. Ada dua tugas yang perlu diperhatikan dalam demo ini.
+ Tugas Agen MQTT (utama) memproses perintah dari antrian perintah sementara tugas lain mengantrekannya. Tugas ini memasuki loop, di mana ia memproses perintah dari antrian perintah. Jika perintah terminasi diterima, tugas ini akan keluar dari loop.
+ Tugas subpub demo membuat langganan ke topik MQTT, lalu membuat operasi publikasi dan mendorongnya ke antrian perintah. Operasi publikasi ini kemudian dijalankan oleh tugas Agen MQTT. Tugas subpub demo menunggu publikasi selesai, ditunjukkan dengan eksekusi callback penyelesaian perintah, kemudian memasuki penundaan singkat sebelum memulai publikasi berikutnya. Tugas ini menunjukkan contoh bagaimana tugas aplikasi akan menggunakan CoreMQTT Agent API.
Untuk pesan publikasi yang masuk, Agen CoreMQTT memanggil fungsi panggilan balik tunggal. Demo ini juga mencakup pengelola langganan yang memungkinkan tugas menentukan panggilan balik untuk memanggil pesan publikasi masuk tentang topik yang telah mereka langgani. Panggilan balik publikasi masuk agen dalam demo ini memanggil manajer berlangganan untuk menyebarkan publikasi ke tugas apa pun yang telah mendaftarkan langganan.
Demo ini menggunakan koneksi TLS dengan otentikasi timbal balik untuk terhubung. AWS Jika jaringan tiba-tiba terputus selama demo, maka klien mencoba untuk menyambung kembali menggunakan logika backoff eksponensial. Jika klien berhasil terhubung kembali, tetapi broker tidak dapat melanjutkan sesi sebelumnya, maka klien akan berlangganan kembali ke topik yang sama dengan sesi sebelumnya.
### Single threaded vs multithreaded
Ada dua model penggunaan CoreMQTT, single threaded dan multithreaded (multitasking). Model berulir tunggal menggunakan pustaka CoreMQTT hanya dari satu utas, dan mengharuskan Anda untuk membuat panggilan eksplisit berulang di pustaka MQTT. Kasus penggunaan multithreaded malah dapat menjalankan protokol MQTT di latar belakang dalam tugas agen (atau daemon), seperti yang ditunjukkan dalam demo yang didokumentasikan di sini. Saat Anda menjalankan protokol MQTT dalam tugas agen, Anda tidak perlu secara eksplisit mengelola status MQTT apa pun atau memanggil fungsi API. `MQTT_ProcessLoop` Selain itu, saat Anda menggunakan tugas agen, beberapa tugas aplikasi dapat berbagi satu koneksi MQTT tanpa perlu sinkronisasi primitif seperti mutex.
## Kode sumber
File sumber demo diberi nama `mqtt_agent_task.c` dan `simple_sub_pub_demo.c` dan dapat ditemukan di `freertos/demos/coreMQTT_Agent/` direktori dan [GitHub](https://github.com/aws/amazon-freertos/tree/main/demos/coreMQTT_Agent/)situs web.
## Fungsionalitas
Demo ini membuat setidaknya dua tugas: tugas utama yang memproses permintaan panggilan API MQTT, dan sejumlah subtugas yang dapat dikonfigurasi yang membuat permintaan tersebut. Dalam demo ini, tugas utama membuat subtugas, memanggil loop pemrosesan, dan membersihkan setelahnya. Tugas utama menciptakan koneksi MQTT tunggal ke broker yang dibagi di antara subtugas. Subtugas membuat langganan MQTT dengan broker dan kemudian mempublikasikan pesan ke sana. Setiap subtugas menggunakan topik unik untuk penerbitannya.
## Tugas utama
Tugas aplikasi utama, [ RunCoreMQTTAgentDemo](https://github.com/aws/amazon-freertos/blob/main/demos/coreMQTT_Agent/mqtt_agent_task.c#L435-L480), menetapkan sesi MQTT, membuat subtugas, dan menjalankan loop pemrosesan [ MQTTAgent\$1 CommandLoop](https://github.com/aws/amazon-freertos/blob/main/demos/coreMQTT_Agent/mqtt_agent_task.c#L856) hingga perintah terminasi diterima. Jika jaringan tiba-tiba terputus, demo akan terhubung kembali ke broker di latar belakang, dan membangun kembali langganan dengan broker. Setelah loop pemrosesan berakhir, ia terputus dari broker.
### Commands
Saat Anda menjalankan API Agen CoreMQTT, ia membuat perintah yang dikirim ke antrian tugas agen, yang diproses di. `MQTTAgent_CommandLoop()` Pada saat perintah dibuat, callback penyelesaian opsional dan parameter konteks dapat diteruskan. Setelah perintah yang sesuai selesai, callback penyelesaian akan dipanggil dengan konteks yang diteruskan dan nilai pengembalian apa pun yang dibuat sebagai hasil dari perintah. Tanda tangan untuk callback penyelesaian adalah sebagai berikut:
```
typedef void (* MQTTAgentCommandCallback_t )( void * pCmdCallbackContext,
MQTTAgentReturnInfo_t * pReturnInfo );
```
[Konteks penyelesaian perintah ditentukan pengguna; untuk demo ini, itu adalah: struct. MQTTAgent CommandContext](https://github.com/aws/amazon-freertos/blob/main/demos/coreMQTT_Agent/simple_sub_pub_demo.c#L105-L115)
Perintah dianggap selesai ketika:
+ Berlangganan, berhenti berlangganan, dan menerbitkan dengan QoS > 0: Setelah paket pengakuan yang sesuai telah diterima.
+ Semua operasi lainnya: Setelah API CoreMQTT yang sesuai telah dipanggil.
Setiap struktur yang digunakan oleh perintah, termasuk mempublikasikan informasi, informasi berlangganan, dan konteks penyelesaian, harus tetap dalam lingkup sampai perintah selesai. Tugas panggilan tidak boleh menggunakan kembali struktur perintah apa pun sebelum pemanggilan callback penyelesaian. Perhatikan bahwa karena callback penyelesaian dipanggil oleh Agen MQTT, callback akan berjalan dengan konteks thread tugas agen, bukan tugas yang membuat perintah. Mekanisme komunikasi antar-proses, seperti pemberitahuan tugas atau antrian, dapat digunakan untuk memberi sinyal tugas panggilan penyelesaian perintah.
### Menjalankan loop perintah
Perintah diproses terus menerus di`MQTTAgent_CommandLoop()`. Jika tidak ada perintah yang akan diproses, loop akan menunggu maksimum satu `MQTT_AGENT_MAX_EVENT_QUEUE_WAIT_TIME` untuk ditambahkan ke antrian, dan, jika tidak ada perintah yang ditambahkan, itu akan menjalankan satu iterasi. `MQTT_ProcessLoop()` Ini memastikan bahwa MQTT Keep-Alive dikelola, dan bahwa setiap publikasi yang masuk diterima bahkan ketika tidak ada perintah dalam antrian.
Fungsi loop perintah akan kembali karena alasan berikut:
+ Perintah mengembalikan kode status apa pun selain itu`MQTTSuccess`. Status kesalahan dikembalikan oleh loop perintah, sehingga Anda dapat memutuskan bagaimana menanganinya. Dalam demo ini, koneksi TCP dibangun kembali, dan upaya penyambungan kembali dilakukan. Jika ada kesalahan, koneksi ulang dapat terjadi di latar belakang tanpa intervensi dari tugas lain menggunakan MQTT.
+ Perintah putuskan sambungan (dari`MQTTAgent_Disconnect`) diproses. Loop perintah keluar sehingga TCP dapat terputus.
+ Perintah terminate (from`MQTTAgent_Terminate`) diproses. Perintah ini juga menandai perintah apa pun yang masih dalam antrian atau menunggu paket pengakuan sebagai kesalahan, dengan kode pengembalian. `MQTTRecvFailed`
### Manajer berlangganan
Karena demo menggunakan banyak topik, manajer berlangganan adalah cara mudah untuk mengaitkan topik berlangganan dengan panggilan balik atau tugas unik. Manajer berlangganan dalam demo ini adalah single-threaded, jadi tidak boleh digunakan oleh banyak tugas secara bersamaan. Dalam demo ini, fungsi pengelola langganan hanya dipanggil dari fungsi panggilan balik yang diteruskan ke agen MQTT, dan dijalankan hanya dengan konteks thread tugas agen.
## Tugas berlangganan-terbitkan sederhana
Setiap instance [ prvSimpleSubscribePublishTask](https://github.com/aws/amazon-freertos/blob/main/demos/coreMQTT_Agent/simple_sub_pub_demo.c#L447-L569)membuat langganan ke topik MQTT, dan membuat operasi publikasi untuk topik itu. Untuk mendemonstrasikan beberapa jenis publikasi, tugas bernomor genap menggunakan QoS 0 (yang selesai setelah paket publikasi dikirim) dan tugas ganjil menggunakan QoS 1 (yang selesai setelah menerima paket PUBACK).