全部产品
Search

搜索本产品

    IoT Platform：Kode Contoh

    文档中心

    IoT Platform：Kode Contoh

    更新时间：Jul 06, 2025

    Unduh paket pembaruan over-the-air (OTA) yang berisi satu file melalui MQTT dan lakukan pembaruan pada perangkat. File kode contoh digunakan untuk tujuan ini.

    Informasi Latar Belakang

    • Untuk informasi lebih lanjut tentang fitur pembaruan OTA, lihat Ikhtisar.

    • Anda harus membangun koneksi MQTT. Ikhtisar.

    Langkah 1: Inisialisasi Klien

    1. Tambahkan file header
      ……
……
#include "aiot_ota_api.h"
#include "aiot_mqtt_download_api.h"
……

    2. /* Koleksi fungsi terkait sistem yang disimpan di folder portfiles/aiot_port. */
extern aiot_sysdep_portfile_t g_aiot_sysdep_portfile;

/* TODO: Jika Anda ingin menonaktifkan logging, jangan implementasikan fungsi berikut. Jika Anda ingin mengurangi entri log, Anda dapat menentukan logika pencetakan berdasarkan parameter code.
 * Contoh: [1578463098.611][LK-0309] pub: /ota/device/upgrade/a13FN******/ota_demo
 * Kode dalam entri log di atas adalah 0309 (heksadesimal). Untuk informasi lebih lanjut tentang nilai parameter code, lihat core/aiot_state_api.h.
 */

/* Callback untuk mencetak log SDK. */
int32_t demo_state_logcb(int32_t code, char *message)
{
    printf("%s", message);
    return 0;
}
    3. Panggil operasi aiot_ota_init untuk membuat OTA 
          ota_handle = aiot_ota_init();
    if (NULL == ota_handle) {
        goto exit;
    }

    Langkah 2: Konfigurasikan Fitur yang Diperlukan

    Panggil operasi aiot_ota_setopt untuk mengonfigurasi item berikut.

    1. Asosiasikan dengan handle koneksi MQTT.

      Penting

      Sebelum Anda mengatur parameter spesifik 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 handle koneksi MQTT.

    2. Konfigurasikan callback untuk memproses perintah pembaruan OTA.
      •     aiot_ota_setopt(ota_handle, AIOT_OTAOPT_RECV_HANDLER, user_ota_recv_handler);
      • ParameterContohDeskripsi

        AIOT_OTAOPT_MQTT_HANDLER

        		user_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.

    Penting

    Sebelum Anda melakukan pembaruan OTA, Anda harus mengirim nomor versi setidaknya sekali.

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

    Langkah 4: Terima perintah pembaruan

    1. Setelah Anda 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.
      Ketika Anda 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 jenis pesan.
        void user_ota_recv_handler(void *ota_handle, aiot_ota_recv_t *ota_msg, void *userdata)
{
    uint32_t request_size = 10 * 1024;
    switch (ota_msg->type) {
    case AIOT_OTARECV_FOTA: {
        if (NULL == ota_msg->task_desc || ota_msg->task_desc->protocol_type != AIOT_OTA_PROTOCOL_MQTT) {
            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. Link SDK secara otomatis mem-parsing pesan yang diterima.

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

    Langkah 5: Unduh paket pembaruan dan lakukan pembaruan OTA

    Penting

    Setelah perangkat menerima perintah pembaruan yang didorong oleh IoT Platform, perangkat tidak akan secara otomatis mengunduh paket pembaruan. Anda harus memanggil operasi API dari Link SDK untuk mengunduh paket tersebut.

    Setelah callback user_ota_recv_handler dipanggil, downloader memulai permintaan MQTT untuk menerima paket pembaruan OTA.

    1. Inisialisasi downloader.
      Panggil operasi aiot_mqtt_download_init untuk membuat download 
      void user_ota_recv_handler(void *ota_handle, aiot_ota_recv_t *ota_msg, void *userdata)
{
     ……
     ……

        printf("Versi firmware target OTA: %s, ukuran: %u Bytes\r\n", ota_msg->task_desc->version,
               ota_msg->task_desc->size_total);
        void *md_handler = aiot_mqtt_download_init();

     ……
     ……

}
    2. Atur parameter.
      Panggil operasi aiot_mqtt_download_setopt untuk mengatur parameter yang terkait dengan tugas unduhan.
      •         aiot_mqtt_download_setopt(md_handler, AIOT_MDOPT_TASK_DESC, ota_msg->task_desc);
        /* Ukuran maksimum setiap paket data yang dapat diunduh. Anda dapat menentukan nilai untuk perangkat dengan sumber daya terbatas. */
        aiot_mqtt_download_setopt(md_handler, AIOT_DLOPT_DATA_REQUEST_SIZE, &request_size);

        /* Nomor urutan byte posisi awal dan akhir untuk setiap segmen. Anda harus menentukan parameter ini jika Anda mengunduh paket pembaruan per segmen atau jika Anda perlu mengunduh segmen dari paket pembaruan. 
         * Jika Anda mengunduh paket pembaruan dalam segmen tertentu, pemeriksaan redundansi siklik (CRC) dilakukan untuk paket data. SDK tidak mengimplementasikan verifikasi MD5 untuk konten yang diunduh. 
         * Secara default, seluruh file diunduh. Dalam hal ini, CRC dilakukan untuk paket data dan SDK mengimplementasikan verifikasi MD5 untuk konten yang diunduh. 
         * Jika Anda menggunakan kode contoh berikut, unduhan dimulai dari byte ke-10 file dan berakhir pada byte ke-10 dari kilobyte ke-50. /
        // uint32_t range_start = 10, range_end = 50 * 1024 + 10;
        // aiot_mqtt_download_setopt(md_handler, AIOT_MDOPT_RANGE_START, &range_start);
        // aiot_mqtt_download_setopt(md_handler, AIOT_MDOPT_RANGE_END, &range_end);

        aiot_mqtt_download_setopt(md_handler, AIOT_MDOPT_RECV_HANDLE, user_download_recv_handler);
        g_dl_handle = md_handler;
      • ParameterContohDeskripsi
        AIOT_MDOPT_TASK_DESCota_msg->task_descParameter dasar yang terkait dengan tugas unduhan.
        AIOT_DLOPT_DATA_REQUEST_SIZErequest_sizeUkuran maksimum setiap paket data yang dapat diunduh dari IoT Platform.
        AIOT_MDOPT_RANGE_STARTrange_startNomor urutan byte posisi awal dan akhir untuk setiap segmen. Anda harus menentukan parameter ini jika Anda mengunduh paket pembaruan per segmen atau jika Anda perlu mengunduh segmen dari paket pembaruan.

        Jika Anda tidak menentukan parameter ini, seluruh file diunduh.

        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

        AIOT_MDOPT_RANGE_ENDrange_end
        AIOT_MDOPT_RECV_HANDLEuser_download_recv_handlerCallback untuk mengelola paket pembaruan OTA.

        Callback ini dipanggil ketika IoT Platform mengembalikan paket pembaruan setelah perangkat memulai permintaan unduhan.

    3. Panggil operasi aiot_mqtt_download_process untuk mengirim permintaan unduhan ke IoT Platform.
          while (1) {
        aiot_mqtt_process(mqtt_handle);
        aiot_mqtt_recv(mqtt_handle);
        if(g_dl_handle != NULL) {
            int32_t res = aiot_mqtt_download_process(g_dl_handle);
     ……
     ……

        }
    }
    4. IoT Platform menerima permintaan dan mengembalikan paket pembaruan ke perangkat. Setelah perangkat menerima pesan, callback user_download_recv_handler dipanggil.
      Anda harus menentukan logika callback untuk menyimpan paket pembaruan yang diunduh di perangkat.
      void user_download_recv_handler(void *handle, const aiot_mqtt_download_recv_t *packet, void *userdata)
{
    uint32_t data_buffer_len = 0;

    /* Anda hanya dapat menyetel packet->type ke AIOT_MDRECV_DATA_RESP. */
    if (!packet || AIOT_MDRECV_DATA_RESP != packet->type) {
        return;
    }

    /* Simpan file yang diunduh di perangkat. */
    FILE *file = fopen("mota_demo.bin", "ab");
    fwrite(packet->data.data_resp.data, packet->data.data_resp.data_size, sizeof(int8_t), file);
    fclose(file);

    data_buffer_len = packet->data.data_resp.data_size;

    printf("unduh %03d%% selesai, +%d bytes\r\n", packet->data.data_resp.percent, data_buffer_len);
}
    5. Setelah file paket pembaruan diunduh, panggil operasi aiot_mqtt_download_deinit untuk keluar dari program.
          while (1) {
        aiot_mqtt_process(mqtt_handle);
        aiot_mqtt_recv(mqtt_handle);
        if(g_dl_handle != NULL) {
            int32_t res = aiot_mqtt_download_process(g_dl_handle);

            if(STATE_MQTT_DOWNLOAD_SUCCESS == res) {
                /* Pembaruan berhasil. Anda dapat me-restart perangkat dan mengirim nomor versi baru. */
                printf("mqtt download ota berhasil \r\n");
                aiot_mqtt_download_deinit(&g_dl_handle);
                break;
            } else if(STATE_MQTT_DOWNLOAD_FAILED_RECVERROR == res
                      || STATE_MQTT_DOWNLOAD_FAILED_TIMEOUT == res
                      || STATE_MQTT_DOWNLOAD_FAILED_MISMATCH == res) {
                printf("mqtt download ota gagal \r\n");
                aiot_mqtt_download_deinit(&g_dl_handle);
                break;
            }
        }
    }

    Langkah 6: Kirim nomor versi setelah pembaruan

    Untuk informasi lebih lanjut tentang kode contoh untuk mengirim nomor versi, lihat Langkah 3: Kirim nomor versi perangkat.

    Catatan

    • Setelah perangkat diperbarui, Anda harus mengirim nomor versi terbaru. Jika tidak, IoT Platform menentukan bahwa tugas pembaruan OTA gagal.

    • Perangkat mungkin perlu direstart setelah pembaruan. Dalam hal ini, kirim nomor versi terbaru setelah perangkat direstart.

    • Dalam contoh ini, logika untuk mengirim nomor versi terbaru setelah pembaruan tidak ditentukan. Anda harus menentukan logika berdasarkan kebutuhan bisnis Anda.

    Langkah 7: Akhiri 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);

    Apa yang harus dilakukan selanjutnya