IoT Platform：Kode contoh

Langkah 1: Inisialisasi klien

1. Tambahkan file header.

   ...
   ……
   #include "aiot_ota_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_ota_init untuk membuat OTA.

       ota_handle = aiot_ota_init();
       if (NULL == ota_handle) {
           printf("aiot_ota_init failed\r\n");
           aiot_mqtt_deinit(&mqtt_handle);
           return -2;
       }

Langkah 2: Konfigurasikan fitur yang diperlukan

Panggil operasi aiot_ota_setopt untuk mengonfigurasi item berikut.

1. Asosiasikan dengan MQTT Connection Handler.

   Penting

   Sebelum Anda menyetel parameter pembaruan OTA, pastikan informasi autentikasi perangkat telah ditentukan. Untuk informasi lebih lanjut, lihat Contoh.

   •     aiot_ota_setopt(ota_handle, AIOT_OTAOPT_MQTT_HANDLE, mqtt_handle);

   • Parameter	Contoh	Deskripsi
     AIOT_OTAOPT_MQTT_HANDLE	mqtt_handle	Anda harus membangun koneksi MQTT. Parameter ini digunakan untuk mengasosiasikan dengan penanganan koneksi MQTT.

2. Konfigurasikan callback untuk memproses perintah pembaruan OTA.

   •     aiot_ota_setopt(ota_handle, AIOT_OTAOPT_RECV_HANDLER, demo_ota_recv_handler);

   • Parameter	Contoh	Deskripsi
     AIOT_OTAOPT_MQTT_HANDLER	demo_ota_recv_handler	Fungsi callback ini dipanggil ketika perangkat menerima perintah pembaruan OTA dari IoT Platform.

Langkah 3: Kirim nomor versi perangkat

Setelah perangkat membangun koneksi MQTT dengan IoT Platform, panggil operasi aiot_ota_report_version untuk mengirim nomor versi perangkat. IoT Platform menentukan apakah pembaruan diperlukan berdasarkan nomor versi.

Dalam contoh ini, nomor versi yang dikirim adalah 1.0.0. Dalam skenario bisnis sebenarnya, Anda harus mendapatkan nomor versi dari pengaturan perangkat dan menentukan logika untuk mengirim nomor versi.

    cur_version = "1.0.0";
    res = aiot_ota_report_version(ota_handle, cur_version);
    if (res < STATE_SUCCESS) {
        printf("aiot_ota_report_version failed: -0x%04X\r\n", -res);
    }

Langkah 4: Terima perintah pembaruan

1. Setelah menambahkan paket pembaruan ke IoT Platform dan memulai tugas pembaruan, IoT Platform mengirim perintah pembaruan ke perangkat.

   Untuk informasi lebih lanjut, lihat Tambahkan Paket Pembaruan.

2. Perangkat memanggil operasi aiot_mqtt_recv untuk menerima pesan. Setelah perangkat mengenali pesan sebagai perintah pembaruan OTA, callback demo_ota_recv_handler dipanggil.

3. Tentukan logika pemrosesan callback.

   Saat menentukan logika pemrosesan callback, perhatikan hal-hal berikut:

   • IoT Platform menggunakan topik /ota/device/upgrade/${ProductKey}/${DeviceName} untuk mengirim perintah pembaruan OTA ke perangkat.

     Untuk informasi lebih lanjut tentang ${ProductKey} dan ${DeviceName}, lihat Dapatkan Informasi Verifikasi Perangkat.

   • AIOT_OTARECV_FOTA menunjukkan tipe pesan.

     void demo_ota_recv_handler(void *ota_handle, aiot_ota_recv_t *ota_msg, void *userdata)
     {
         switch (ota_msg->type) {
             case AIOT_OTARECV_FOTA: {
                 uint32_t res = 0;
                 uint16_t port = 443;
                 uint32_t max_buffer_len = (8 * 1024);
                 aiot_sysdep_network_cred_t cred;
                 void *dl_handle = NULL;
                 void *last_percent = NULL;
     
                 if (NULL == ota_msg->task_desc) {
                     break;
                 }
          ……
          ……
     
     }

   • Untuk informasi lebih lanjut tentang format data Alink dari perintah pembaruan OTA, lihat Dorong Informasi tentang Paket Pembaruan OTA ke Perangkat.

   • aiot_ota_recv_t menunjukkan format data, dan Link SDK secara otomatis mem-parsing pesan yang diterima.

   • Anda dapat menentukan logika pemrosesan callback berdasarkan kode contoh. Untuk informasi lebih lanjut, lihat Langkah 5: Unduh paket pembaruan dan lakukan pembaruan OTA.

Langkah 5: Unduh paket pembaruan dan lakukan pembaruan OTA

Setelah callback demo_ota_recv_handler dipanggil, downloader memulai Permintaan HTTPS untuk menerima paket pembaruan OTA.

1. Inisialisasi downloader.

   Panggil operasi aiot_download_init untuk membuat instance download.

               dl_handle = aiot_download_init();
               if (NULL == dl_handle) {
                   break;
               }
               printf("Versi firmware target OTA: %s, ukuran: %u Bytes \r\n", ota_msg->task_desc->version,
                      ota_msg->task_desc->size_total);
   
               if (NULL != ota_msg->task_desc->extra_data) {
                   printf("data tambahan: %s\r\n", ota_msg->task_desc->extra_data);
               }
   
               memset(&cred, 0, sizeof(aiot_sysdep_network_cred_t));
               cred.option = AIOT_SYSDEP_NETWORK_CRED_SVRCERT_CA;
               cred.max_tls_fragment = 16384;
               cred.x509_server_cert = ali_ca_cert;
               cred.x509_server_cert_len = strlen(ali_ca_cert);

2. Atur parameter.

   Panggil operasi aiot_download_setopt untuk menyetel parameter terkait tugas unduhan.

               /* Atur protokol TLS untuk mengunduh. */
               aiot_download_setopt(dl_handle, AIOT_DLOPT_NETWORK_CRED, (void *)(&cred));
               /* Atur nomor port server yang akan diakses. */
               aiot_download_setopt(dl_handle, AIOT_DLOPT_NETWORK_PORT, (void *)(&port));
               /* Tentukan informasi tugas unduhan, yang dapat diperoleh dari anggota task_desc dalam parameter input ota_msg. Informasi tersebut mencakup URL unduhan, ukuran firmware, dan tanda tangan firmware. */
               aiot_download_setopt(dl_handle, AIOT_DLOPT_TASK_DESC, (void *)(ota_msg->task_desc));
               /* Atur callback yang dipanggil SDK saat konten yang diunduh diterima. */
               aiot_download_setopt(dl_handle, AIOT_DLOPT_RECV_HANDLER, (void *)(demo_download_recv_handler));
               /* Atur panjang buffer maksimum untuk unduhan tunggal. Pengguna diberitahu jika batas tercapai. */
               aiot_download_setopt(dl_handle, AIOT_DLOPT_BODY_BUFFER_MAX_LEN, (void *)(&max_buffer_len));
               /* Tentukan informasi yang dibagi di antara panggilan berbeda dari AIOT_DLOPT_RECV_HANDLER. Dalam contoh ini, informasi kemajuan disimpan. */
               last_percent = malloc(sizeof(uint32_t));
               if (NULL == last_percent) {
                   aiot_download_deinit(&dl_handle);
                   break;
               }
               memset(last_percent, 0, sizeof(uint32_t));
               aiot_download_setopt(dl_handle, AIOT_DLOPT_USERDATA, (void *)last_percent);

3. Mulai permintaan unduhan.

   1. Mulai thread unduhan demo_ota_download_thread.

                  res = pthread_create(&g_download_thread, NULL, demo_ota_download_thread, dl_handle);
                  if (res != 0) {
                      printf("pthread_create demo_ota_download_thread gagal: %d\r\n", res);
                      aiot_download_deinit(&dl_handle);
                      free(last_percent);
                  } else {
                      /* Tetapkan jenis thread pengunduhan menjadi detach. Setelah firmware diperoleh, thread pengunduhan otomatis keluar. */
                      pthread_detach(g_download_thread);
                  }

   2. Setelah thread demo_ota_download_thread diaktifkan, panggil operasi aiot_download_send_request untuk memulai Permintaan HTTPS GET untuk mengunduh paket pembaruan dari server penyimpanan.

      • void *demo_ota_download_thread(void *dl_handle)
        {
            int32_t     ret = 0;
        
            printf("memulai thread unduhan dalam 2 detik ......\n");
            sleep(2);
        
            /* Mulai permintaan untuk mengunduh paket pembaruan dari server penyimpanan.  */
            /*
             * TODO: Dalam contoh ini, satu permintaan dimulai untuk mendapatkan semua konten paket pembaruan. 
             *       Jika perangkat memiliki sumber daya terbatas atau koneksi jaringan buruk, Anda dapat mengimplementasikan unduhan tersegmentasi.
             *
             *       aiot_download_setopt(dl_handle, AIOT_DLOPT_RANGE_START, ...);
             *       aiot_download_setopt(dl_handle, AIOT_DLOPT_RANGE_END, ...);
             *       aiot_download_send_request(dl_handle);
             *
             *      Jika Anda mengimplementasikan unduhan tersegmentasi, tentukan tiga pernyataan di atas dalam loop. Dalam kasus ini, beberapa permintaan dikirim dan beberapa respons diterima.
             *
             */
        
             ……
             ……
        
        }

      • Untuk mengimplementasikan unduhan tersegmentasi, atur parameter AIOT_DLOPT_RANGE_START dan AIOT_DLOPT_RANGE_END.

        Sebagai contoh, jika Anda ingin mengunduh paket pembaruan 1.024 byte menggunakan dua segmen, tentukan nilai berikut untuk parameter:

        • Segmen pertama: AIOT_DLOPT_RANGE_START=0, AIOT_DLOPT_RANGE_END=511

        • Segmen kedua: AIOT_DLOPT_RANGE_START=512, AIOT_DLOPT_RANGE_END=1023

4. Terima paket pembaruan.

   1. Setelah permintaan unduhan dikirim, panggil operasi aiot_download_recv untuk menerima paket pembaruan menggunakan thread unduhan demo_ota_download_thread. Setelah perangkat menerima paket, callback demo_download_recv_handler dipanggil. Anda harus menyimpan paket pembaruan yang diunduh ke penyimpanan lokal atau sistem file perangkat.

      void *demo_ota_download_thread(void *dl_handle)
      {
           ……
           ……
      
           while (1) {
              /* Terima firmware yang dikirim dari server. */
              ret = aiot_download_recv(dl_handle);
      
              /* Setelah firmware diunduh, nilai kembali dari aiot_download_recv() adalah STATE_DOWNLOAD_FINISHED. Jika tidak, nilainya adalah jumlah byte yang diperoleh. */  */
              if (STATE_DOWNLOAD_FINISHED == ret) {
                  printf("unduhan selesai\n");
                  break;
              }
          }
           ……
           ……
      }

   2. Tentukan callback demo_download_recv_handler untuk menyimpan paket pembaruan yang diunduh dan lakukan pembaruan.

      Catatan

      Dalam contoh ini, respons dicetak. Logika untuk menyimpan dan menerapkan paket pembaruan tidak ditentukan. Dalam skenario bisnis nyata, Anda harus menyimpan paket pembaruan dan menginstalnya untuk menyelesaikan pembaruan OTA.

      void demo_download_recv_handler(void *handle, const aiot_download_recv_t *packet, void *userdata)
      {
          uint32_t data_buffer_len = 0;
          uint32_t last_percent = 0;
          int32_t  percent = 0;
      
          /* Anda dapat menyetel packet->type hanya ke AIOT_DLRECV_HTTPBODY. */
          if (!packet || AIOT_DLRECV_HTTPBODY != packet->type) {
              return;
          }
          percent = packet->data.percent;
      
          /* userdata dapat menyimpan data yang perlu dibagikan antara panggilan berbeda dari demo_download_recv_handler(). */
          /* Dalam contoh ini, persentase kemajuan unduhan firmware disimpan. */
          if (userdata) {
              last_percent = *((uint32_t *)(userdata));
          }
      
          data_buffer_len = packet->data.len;
      
          /* Nilai negatif dari percent menunjukkan bahwa terjadi pengecualian selama penerimaan data atau otentikasi digest gagal. */
          if (percent < 0) {
              printf("pengecualian: percent = %d\r\n", percent);
              if (userdata) {
                  free(userdata);
              }
              return;
          }
           ……
           ……
      
      }

5. Kirim kemajuan unduhan.

   Setelah callback demo_download_recv_handler dipanggil, panggil operasi aiot_download_report_progress untuk mengirim kemajuan unduhan dan kesalahan pembaruan ke IoT Platform. Kesalahan pembaruan mencakup kegagalan pembakaran dan pemutusan jaringan.

   • Lihat kemajuan yang dikirim:

     Kemajuan ditampilkan di konsol IoT Platform. Untuk informasi lebih lanjut, lihat Lihat Status Pembaruan.

   • Kirim kemajuan dalam kondisi normal atau abnormal:

     • Jika unduhan berhasil, bilangan bulat yang menunjukkan kemajuan dikirim ke IoT Platform. Link SDK secara otomatis menghitung nilai parameter percent dan mengirimkannya ke IoT Platform menggunakan callback.

     • Jika terjadi kesalahan selama unduhan atau firmware yang diunduh gagal dibakar, kesalahan tersebut dikirim ke IoT Platform. Untuk informasi lebih lanjut tentang kode kesalahan, lihat aiot_ota_protocol_errcode_t.

   void demo_download_recv_handler(void *handle, const aiot_download_recv_t *packet, void *userdata)
   {
        ……
        ……
       /*
        * TODO:
        *       Setelah Anda mengunduh paket pembaruan, simpan memori yang posisi awalnya adalah packet->data.buffer dan panjangnya adalah packet->data.len ke lokasi penyimpanan lokal atau sistem file perangkat. 
        *
        *      Jika pembakaran gagal, Anda harus memanggil operasi aiot_download_report_progress(handle, -4) untuk mengirim pesan kesalahan ke IoT Platform. 
        */
       /* Jika nilai percent adalah 100, semua konten paket pembaruan telah diunduh.  */
       if (percent == 100) {
           /*
            * TODO: Bakar firmware, simpan konfigurasi, mulai ulang perangkat, lalu beralih ke firmware baru untuk mem-boot perangkat. 
                    Perangkat harus mengirim nomor versi firmware baru ke IoT Platform setelah pembaruan.
   
                    aiot_ota_report_version(ota_handle, new_version);
   
                    Sebagai contoh, jika versi diperbarui dari 1.0.0 menjadi 1.1.0, nilai new_version adalah 1.1.0 harus dikirim ke IoT Platform. 
                    IoT Platform menentukan bahwa pembaruan berhasil setelah menerima nomor versi firmware baru. Jika tidak, IoT Platform menentukan bahwa pembaruan gagal. 
            */
       }
   
       /* Sederhanakan output. Setiap kali kemajuan unduhan meningkat setidaknya 5%, kemajuan dicetak dan dikirim ke IoT Platform. */
       if (percent - last_percent >= 5 || percent == 100) {
           printf("unduhan %03d%% selesai, +%d byte\n", percent, data_buffer_len);
           aiot_download_report_progress(handle, percent);
           if (userdata) {
               *((uint32_t *)(userdata)) = percent;
           }
       }
   }

6. Keluar dari downloader.

   Setelah paket pembaruan diunduh, panggil operasi aiot_download_deinit untuk menghapus sesi download. Kemudian, thread unduhan ditutup.

       aiot_download_deinit(&dl_handle);
       printf("thread unduhan keluar\n");

Langkah 6: Kirim nomor versi setelah pembaruan

Untuk informasi lebih lanjut, lihat Langkah 3: Kirim Nomor Versi Perangkat.

Langkah 7: Tutup koneksi

Panggil operasi aiot_mqtt_disconnect untuk memutuskan koneksi perangkat dari IoT Platform.

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

Langkah 8: Keluar dari program

Panggil operasi aiot_ota_deinit untuk menghapus OTA

    aiot_ota_deinit(&ota_handle);