IoT Platform：Contoh

Informasi latar belakang

Untuk informasi lebih lanjut tentang koneksi perangkat melalui MQTT 5.0, lihat Ikhtisar.

Langkah 1: Inisialisasi SDK

1. Tambahkan file header.

   #include "aiot_state_api.h"
   #include "aiot_sysdep_api.h"
   #include "aiot_mqtt_api.h"

2. Tambahkan dependensi dasar dan konfigurasikan fitur output log.

       aiot_sysdep_set_portfile(&g_aiot_sysdep_portfile);
       aiot_state_set_logcb(demo_state_logcb);

3. Panggil operasi aiot_mqtt_init untuk membuat instance klien MQTT dan menginisialisasi parameter default.

       mqtt_handle = aiot_mqtt_init();
       if (mqtt_handle == NULL) {
           printf("aiot_mqtt_init gagal\n");
           return -1;
       }

Langkah 2: Konfigurasikan fitur yang diperlukan

Panggil operasi aiot_mqtt_setopt untuk mengonfigurasi item-item berikut: Untuk informasi lebih lanjut tentang parameter operasi, lihat aiot_mqtt_option_t.

1. Konfigurasikan parameter koneksi.

   • Kode sampel:

      char *product_key = "a18wP******";
      char *device_name = "LightSwitch";
      char *device_secret = "uwMTmVAMnGGHaAkqmeDY6cHxxB******";
      char *mqtt_host = "iot-06z00ax1o******.mqtt.iothub.aliyuncs.com";
      ...
      ...
      /* Tentukan versi MQTT. */
      protocol_version = AIOT_MQTT_VERSION_5_0;
      aiot_mqtt_setopt(mqtt_handle, AIOT_MQTTOPT_VERSION, (void *)&protocol_version);
      /* Tentukan titik akhir broker MQTT.  */
      aiot_mqtt_setopt(mqtt_handle, AIOT_MQTTOPT_HOST, (void *)url);
      /* Tentukan port broker MQTT.  */
      aiot_mqtt_setopt(mqtt_handle, AIOT_MQTTOPT_PORT, (void *)&port);
      /* Tentukan ProductKey produk tempat perangkat tersebut termasuk.  */
      aiot_mqtt_setopt(mqtt_handle, AIOT_MQTTOPT_PRODUCT_KEY, (void *)product_key);
      /* Tentukan DeviceName perangkat.  */
      aiot_mqtt_setopt(mqtt_handle, AIOT_MQTTOPT_DEVICE_NAME, (void *)device_name);
      /* Tentukan DeviceSecret perangkat.  */
      aiot_mqtt_setopt(mqtt_handle, AIOT_MQTTOPT_DEVICE_SECRET, (void *)device_secret);
      /* Tentukan kredensial keamanan koneksi.  */
      aiot_mqtt_setopt(mqtt_handle, AIOT_MQTTOPT_NETWORK_CRED, (void *)&cred);
      /* Jika Anda ingin menggunakan fitur Assigned Client Identifier dari MQTT 5.0, atur parameter use_assigned_clientid menjadi 1.*/
      uint8_t use_assigned_clientid = 0;
      aiot_mqtt_setopt(mqtt_handle, AIOT_MQTTOPT_ASSIGNED_CLIENTID, (void *)(&use_assigned_clientid));

   • Parameter:

     Parameter	Contoh	Deskripsi
     mqtt_host	iot-06z00ax1o******.mqtt.iothub.aliyuncs.com	Titik akhir yang ingin Anda hubungkan dengan perangkat. Untuk melihat titik akhir dari instance Enterprise Edition atau instance publik versi baru, buka panel Development Configurations pada halaman Instance Details di konsol IoT Platform. Jika Anda menggunakan instance publik versi sebelumnya, titik akhir dari instance publik berada dalam format ${YourProductKey}.iot-as-mqtt.${YourRegionId}.aliyuncs.com. Untuk informasi lebih lanjut tentang instance publik versi baru dan lama, instance Enterprise Edition, dan titik akhir, lihat Lihat titik akhir sebuah instance.
     product_key	a18wP******	Informasi verifikasi perangkat. Untuk informasi lebih lanjut, lihat Dapatkan informasi verifikasi perangkat. Dalam contoh ini, metode verifikasi sertifikat unik-per-perangkat digunakan.
     device_name	LightSwitch
     device_secret	uwMTmVAMnGGHaAkqmeDY6cHxxB******
     protocol_version	AIOT_MQTT_VERSION_5_0	Tentukan 5.0 sebagai nomor versi MQTT.
     use_assigned_clientid	1	Jika Anda ingin menggunakan fitur Assigned Client Identifier dari MQTT 5.0, atur parameter use_assigned_clientid menjadi 1.

   • Deskripsi mekanisme keep-alive MQTT:

     Penting

     • Selama periode keep-alive, perangkat harus mengirim setidaknya satu pesan, termasuk permintaan ping.

     • Timer dimulai ketika IoT Platform mengirim pesan CONNACK sebagai respons terhadap pesan CONNECT. Jika IoT Platform menerima pesan PUBLISH, SUBSCRIBE, PING, atau PUBACK, timer akan direset. IoT Platform memeriksa denyut jantung koneksi MQTT setiap 30 detik. Waktu tunggu untuk pemeriksaan denyut jantung adalah periode antara waktu perangkat terhubung ke IoT Platform dan waktu pemeriksaan denyut jantung berikutnya dilakukan. Maksimum waktu habis dihitung menggunakan rumus berikut: Interval denyut jantung × 1.5 + Waktu tunggu untuk pemeriksaan denyut jantung. Jika server tidak menerima pesan dari perangkat dalam periode maksimum waktu habis, server mengakhiri koneksi dengan perangkat.

     Link SDK for C menyediakan mekanisme keep-alive. Tabel berikut menjelaskan parameter yang dapat Anda konfigurasikan untuk menentukan nilai denyut jantung kustom untuk koneksi perangkat. Jika tidak, nilai default akan digunakan.

     Item	Nilai default	Deskripsi
     AIOT_MQTTOPT_HEARTBEAT_MAX_LOST	2	Jumlah maksimum denyut jantung yang dapat hilang. Jika batas terlampaui, sistem akan membentuk koneksi baru.
     AIOT_MQTTOPT_HEARTBEAT_INTERVAL_MS	25.000	Interval antara pemutusan dan koneksi baru yang dibentuk oleh sistem. Nilai valid: 1000 hingga 1200000. Unit: milidetik.
     AIOT_MQTTOPT_KEEPALIVE_SEC	1.200	Periode keep-alive. Setelah denyut jantung hilang, sistem dapat membentuk koneksi baru dalam periode tertentu. Nilai valid: 30 hingga 1200. Unit: detik. Kami sarankan Anda menentukan nilai yang lebih besar dari 300.

2. Konfigurasikan callback untuk memantau status dan menerima pesan.

   1. Konfigurasikan callback untuk memantau status.

      • Kode sampel:

         int main(int argc, char *argv[])
        {
         ...
         ...
        
         /* Tentukan callback default untuk menerima pesan MQTT.  */
         aiot_mqtt_setopt(mqtt_handle, AIOT_MQTTOPT_RECV_HANDLER, (void *)demo_mqtt_default_recv_handler);
         /* Tentukan callback untuk menangani event MQTT.  */
         aiot_mqtt_setopt(mqtt_handle, AIOT_MQTTOPT_EVENT_HANDLER, (void *)demo_mqtt_event_handler);
         ...
         ...
        }
         

      • Parameter:

        Item	Contoh	Deskripsi
        AIOT_MQTTOPT_RECV_HANDLER	demo_mqtt_default_recv_handler	Ketika pesan diterima, callback dipanggil untuk melakukan operasi yang diperlukan.
        AIOT_MQTTOPT_EVENT_HANDLER	demo_mqtt_event_handler	Ketika status koneksi perangkat berubah, callback dipanggil untuk melakukan operasi yang diperlukan.

   2. Definisikan callback untuk memantau status.

      Penting

      • Jangan tentukan logika yang memakan waktu untuk menangani event. Jika tidak, thread yang digunakan untuk menerima paket mungkin terblokir.

      • Status koneksi berubah karena beberapa penyebab, seperti pengecualian jaringan, rekoneksi otomatis, dan pemutusan koneksi.

      • Untuk menangani perubahan status koneksi, Anda dapat memodifikasi kode di bagian TODO berdasarkan kebutuhan bisnis Anda.

      /* Callback untuk menangani event MQTT. Ketika koneksi dibuat, dipulihkan, atau ditutup, callback dipanggil. Untuk informasi tentang definisi event, lihat core/aiot_mqtt_api.h.  */
      void demo_mqtt_event_handler(void *handle, const aiot_mqtt_event_t *event, void *userdata)
      {
       switch (event->type) {
       /* Panggil operasi aiot_mqtt_connect untuk membentuk koneksi ke broker MQTT.  */
       case AIOT_MQTTEVT_CONNECT: {
       printf("AIOT_MQTTEVT_CONNECT\n");
       /* TODO: Tentukan logika untuk membentuk koneksi. Jangan panggil fungsi yang memakan waktu yang dapat memblokir thread. */  */
       }
       break;
      
       /* Jika kesalahan pemutusan koneksi terjadi karena pengecualian jaringan, SDK secara otomatis memulai permintaan untuk menyambungkan ulang ke broker MQTT.  */
       case AIOT_MQTTEVT_RECONNECT: {
       printf("AIOT_MQTTEVT_RECONNECT\n");
       /* TODO: Tentukan logika untuk membentuk kembali koneksi. Jangan panggil fungsi yang memakan waktu yang dapat memblokir thread. */  */
       }
       break;
      
       /* Kesalahan pemutusan koneksi terjadi karena pengecualian jaringan. Operasi baca atau tulis tingkat rendah gagal. Tanggapan denyut jantung tidak diperoleh dari broker MQTT.  */
       case AIOT_MQTTEVT_DISCONNECT: {
       char *cause = (event->data.disconnect == AIOT_MQTTDISCONNEVT_NETWORK_DISCONNECT) ? ("network disconnect") :
       ("heartbeat disconnect");
       printf("AIOT_MQTTEVT_DISCONNECT: %s\n", cause);
       /* TODO: Tentukan logika untuk memproses masalah pemutusan koneksi. Jangan panggil fungsi yang memakan waktu yang dapat memblokir thread. */  */
       }
       break;
      
       default: {
      
       }
       }
      }
       

   3. Definisikan callback untuk menerima pesan.

      Penting

      • Jangan tentukan logika yang memakan waktu untuk memproses pesan. Jika tidak, thread yang digunakan untuk menerima paket mungkin terblokir.

      • Untuk memproses pesan yang diterima, Anda dapat memodifikasi kode di bagian TODO berdasarkan kebutuhan bisnis Anda.

      /* Fungsi callback default yang dapat dipanggil untuk menerima pesan MQTT. Fungsi ini dipanggil ketika SDK menerima pesan MQTT dari broker MQTT dan tidak ada callback kustom yang tersedia. */
      void demo_mqtt_default_recv_handler(void *handle, const aiot_mqtt_recv_t *packet, void *userdata)
      {
          switch (packet->type) {
              case AIOT_MQTTRECV_HEARTBEAT_RESPONSE: {
                  printf("heartbeat response\n");
                  /* TODO: Definisikan logika untuk mengirim tanggapan denyut jantung ke server. Dalam banyak kasus, tanggapan tidak dikirim. */
              }
              break;
      
      
              case AIOT_MQTTRECV_SUB_ACK: {
                  printf("suback, res: -0x%04X, packet id: %d, max qos: %d\n",
                         -packet->data.sub_ack.res, packet->data.sub_ack.packet_id, packet->data.sub_ack.max_qos);
                  /* TODO: Definisikan logika untuk mengirim tanggapan dari broker MQTT ke permintaan langganan. Dalam banyak kasus, tanggapan tidak dikirim. */
              }
              break;
              case AIOT_MQTTRECV_UNSUB_ACK: {
                  printf("unsuback, , packet id: %d\n",
                         packet->data.unsub_ack.packet_id);
                  /* TODO: Definisikan logika untuk mengirim tanggapan dari broker MQTT ke permintaan langganan. Dalam banyak kasus, tanggapan tidak dikirim. */
              }
              break;
              case AIOT_MQTTRECV_PUB: {
                  printf("pub, qos: %d, topic: %.*s\n", packet->data.pub.qos, packet->data.pub.topic_len, packet->data.pub.topic);
                  printf("pub, payload: %.*s\n", packet->data.pub.payload_len, packet->data.pub.payload);
                  printf("pub, payload len: %x\n", packet->data.pub.payload_len);
                  aiot_mqtt_props_print(packet->data.pub.props);
              }
              break;
      
      
              case AIOT_MQTTRECV_PUB_ACK: {
                  printf("puback, packet id: %d\n", packet->data.pub_ack.packet_id);
                  /* TODO: Definisikan logika untuk mengirim tanggapan dari broker MQTT ke pesan QoS 1 yang dilaporkan. Biasanya, tanggapan tidak dikirim. */
              }
              break;
      
              case AIOT_MQTTRECV_CON_ACK: {
                  aiot_mqtt_props_print(packet->data.con_ack.props);
              }
              break;
              case AIOT_MQTTRECV_DISCONNECT: {
                  printf("server disconnect, reason code: 0x%x\n", packet->data.server_disconnect.reason_code);
              }
              break;
       
              default: {
      
      
              }
          }
      }

Langkah 3: Bentuk koneksi

Panggil operasi aiot_mqtt_connect_v5 untuk mengirim permintaan koneksi dan autentikasi ke IoT Platform. Untuk informasi tentang cara mengonfigurasi parameter, lihat Konfigurasikan parameter koneksi.

mqtt_properties_t *conn_props = aiot_mqtt_props_init();
mqtt_property_t user_prop = {
    .id = MQTT_PROP_ID_USER_PROPERTY,
    .value.str_pair.key.len = strlen("demo_key"),
    .value.str_pair.key.value = (uint8_t *)"demo_key",
    .value.str_pair.value.len = strlen("demo_value"),
    .value.str_pair.value.value = (uint8_t *)"demo_value",
};
aiot_mqtt_props_add(conn_props, &user_prop);
/* Bentuk koneksi ke server melalui MQTT 5.0. */
res = aiot_mqtt_connect_v5(mqtt_handle, NULL, conn_props);
aiot_mqtt_props_deinit(&conn_props);
if (res < STATE_SUCCESS) {
    /* Jika koneksi MQTT gagal dibentuk, lepaskan sumber daya instance MQTT. */
    aiot_mqtt_deinit(&mqtt_handle);
    printf("aiot_mqtt_connect gagal: -0x%04X\n\r\n", -res);
    printf("silakan periksa variabel seperti mqtt_host, produt_key, device_name, device_secret dalam demo\r\n");
    return -1;
}

Langkah 4: Aktifkan thread keep-alive

Panggil operasi aiot_mqtt_process untuk mengirim pesan denyut jantung ke broker MQTT dan mengirim ulang pesan QoS 1 yang tidak menghasilkan tanggapan. Dengan cara ini, koneksi persisten diaktifkan.

1. Aktifkan thread keep-alive.

       res = pthread_create(&g_mqtt_process_thread, NULL, demo_mqtt_process_thread, mqtt_handle);
       if (res < 0) {
           printf("pthread_create demo_mqtt_process_thread gagal: %d\n", res);
           return -1;
       }

2. Untuk mengelola thread keep-alive, definisikan fungsi berikut:

   void *demo_mqtt_process_thread(void *args)
   {
       int32_t res = STATE_SUCCESS;
   
       while (g_mqtt_process_thread_running) {
           res = aiot_mqtt_process(args);
           if (res == STATE_USER_INPUT_EXEC_DISABLED) {
               break;
           }
           sleep(1);
       }
       return NULL;
   }

Langkah 5: Aktifkan thread untuk menerima pesan

Panggil operasi aiot_mqtt_recv untuk menerima pesan MQTT dari broker. Operasi yang diperlukan dilakukan menggunakan callback untuk menerima pesan. Jika terjadi pemutusan koneksi dan kemudian rekoneksi otomatis, operasi yang diperlukan dilakukan menggunakan callback untuk menangani event.

1. Aktifkan thread untuk menerima pesan.

       res = pthread_create(&g_mqtt_recv_thread, NULL, demo_mqtt_recv_thread, mqtt_handle);
       if (res < 0) {
           printf("pthread_create demo_mqtt_recv_thread gagal: %d\n", res);
           return -1;
       }
                                       

2. Untuk mengelola thread, definisikan fungsi berikut:

   void *demo_mqtt_recv_thread(void *args)
   {
       int32_t res = STATE_SUCCESS;
   
       while (g_mqtt_recv_thread_running) {
           res = aiot_mqtt_recv(args);
           if (res < STATE_SUCCESS) {
               if (res == STATE_USER_INPUT_EXEC_DISABLED) {
                   break;
               }
               sleep(1);
           }
       }
       return NULL;
   }

Langkah 6: Berlangganan topik

Panggil operasi aiot_mqtt_sub_v5 untuk berlangganan topik tertentu.

• Kode sampel:

      /* Gunakan kode sampel yang menunjukkan cara berlangganan topik melalui MQTT berdasarkan kebutuhan bisnis Anda. */
      {
          char *sub_topic = "/sys/${YourProductKey}/${YourDeviceName}/thing/event/property/post_reply";
          mqtt_properties_t *sub_props = aiot_mqtt_props_init();
          aiot_mqtt_props_add(sub_props, &user_prop);
          /* Opsi langganan. */
          sub_options_t opts = {
              .no_local = 1,
              .qos = 1,
              .retain_as_publish = 1,
              .retain_handling = 1,
          };
          res = aiot_mqtt_sub_v5(mqtt_handle, sub_topic, &opts, NULL, NULL, sub_props);
          aiot_mqtt_props_deinit(&sub_props);
          if (res < 0) {
              printf("aiot_mqtt_sub gagal, res: -0x%04X\n", -res);
              aiot_mqtt_deinit(&mqtt_handle);
              return -1;
          }
      }

  Catatan

  • Untuk informasi lebih lanjut tentang properti pengguna MQTT_PROP_ID_USER_PROPERTY yang ditentukan dalam kode berikut, lihat mqtt_property_identify_t.

  • Untuk informasi lebih lanjut tentang cara menentukan opsi langganan, lihat sub_options_t.

• Parameter:

  Parameter	Contoh	Deskripsi
  sub_topic	/a18wP******/LightSwitch/user/get	Topik di mana perangkat memiliki izin Subscribe. Deskripsi: a1oGs****** adalah ProductKey dari perangkat. LightSwitch adalah DeviceName dari perangkat. Dalam contoh ini, topik kustom default digunakan. Perangkat dapat menerima pesan dari IoT Platform melalui topik ini. Untuk informasi lebih lanjut, lihat Topik.
  sub_props	aiot_mqtt_props_init()	Properti tambahan yang ingin Anda tentukan untuk langganan.
  opts	.no_local = 1, .qos = 1, .retain_as_publish = 1, .retain_handling = 1,	Opsi langganan.

Langkah 7: Kirim pesan

Panggil operasi aiot_mqtt_pub_v5 untuk mengirim pesan ke topik tertentu.

• Kode sampel:

  	mqtt_properties_t *pub_props = aiot_mqtt_props_init();
    /* Gunakan kode sampel yang menunjukkan cara mengirim pesan melalui MQTT berdasarkan kebutuhan bisnis Anda.*/
    char *pub_topic = "/sys/${YourProductKey}/${YourDeviceName}/thing/event/property/post";
    char *pub_payload = "{\"id\":\"1\",\"version\":\"1.0\",\"params\":{\"LightSwitch\":0}}";
    mqtt_property_t response_prop = {
        .id = MQTT_PROP_ID_RESPONSE_TOPIC,
        .value.str.len = strlen(pub_topic),
        .value.str.value = (uint8_t *)pub_topic,
     };
     char *demo_data_str = "12345";
     mqtt_property_t correlation_prop = {
         .id = MQTT_PROP_ID_CORRELATION_DATA,
         .value.str.len = strlen(demo_data_str),
         .value.str.value = (uint8_t *)demo_data_str,
     };
     aiot_mqtt_props_add(pub_props, &response_prop);
     aiot_mqtt_props_add(pub_props, &correlation_prop);
     res = aiot_mqtt_pub_v5(mqtt_handle, pub_topic, (uint8_t *)pub_payload, (uint32_t)(strlen(pub_payload)), 1,0, pub_props);
     if (res < 0) {
         printf("aiot_mqtt pub gagal, res: -0x%04X\n", -res);
         aiot_mqtt_deinit(&mqtt_handle);
         return -1;
     }

  Catatan

  Untuk informasi lebih lanjut tentang properti pengguna MQTT_PROP_ID_USER_PROPERTY yang ditentukan dalam kode berikut, lihat mqtt_property_identify_t.

• Parameter:

  Parameter	Contoh	Deskripsi
  pub_topic	/a18wP******/LightSwitch/user/update	Topik di mana Anda memiliki izin Publish. Deskripsi: a1oGs****** menunjukkan ProductKey dari perangkat. LightSwitch menunjukkan DeviceName dari perangkat. Perangkat mengirim pesan ke IoT Platform melalui topik ini. Untuk informasi lebih lanjut, lihat Topik.
  pub_payload	{\"id\":\"1\",\"version\":\"1.0\",\"params\":{\"LightSwitch\":0}}	Konten pesan yang ingin Anda kirim ke IoT Platform. Dalam contoh ini, topik kustom digunakan. Oleh karena itu, Anda dapat menentukan format pesan kustom. Untuk informasi lebih lanjut, lihat Format data.
  pub_props	Untuk informasi lebih lanjut, lihat kode sampel.	Properti yang termasuk dalam pesan.

Langkah 8: Putuskan perangkat dari IoT Platform

Panggil operasi aiot_mqtt_disconnect_v5 untuk memutuskan perangkat dari IoT Platform.

Untuk informasi lebih lanjut tentang properti pengguna MQTT_PROP_ID_USER_PROPERTY yang ditentukan dalam kode sampel berikut, lihat mqtt_property_identify_t.

    {
        mqtt_properties_t *disconn_props = aiot_mqtt_props_init();
        /* Kode alasan 0x0 menunjukkan pemutusan normal. */
        int demo_reason_code = 0x0;
        char *demo_reason_string = "normal_exit";
        mqtt_property_t reason_prop = {.id = MQTT_PROP_ID_REASON_STRING, .value.str.len = strlen(demo_reason_string), .value.str.value = (uint8_t *)demo_reason_string};
        aiot_mqtt_props_add(disconn_props, &reason_prop);
        res = aiot_mqtt_disconnect_v5(mqtt_handle, demo_reason_code, disconn_props);
        aiot_mqtt_props_deinit(&disconn_props);
    }

Langkah 9: Keluar dari program

Panggil operasi aiot_mqtt_deinit untuk menghapus instance klien MQTT dan melepaskan sumber daya yang sesuai.

 res = aiot_mqtt_deinit(&mqtt_handle);
 if (res < STATE_SUCCESS) {
 printf("aiot_mqtt_deinit gagal: -0x%04X\n", -res);
 return -1;
 }

Apa yang harus dilakukan selanjutnya

• Setelah Anda mengonfigurasi file kode sampel, kompilasi file tersebut untuk menghasilkan file yang dapat dieksekusi. Dalam contoh ini, file yang dapat dieksekusi ./output/mqtt-v5-basic-demo dihasilkan.

  Untuk informasi lebih lanjut, lihat Siapkan Lingkungan.

• Untuk informasi lebih lanjut tentang hasil eksekusi, lihat Lihat Log.