Unduh Paket OTA melalui MQTT dengan Link SDK untuk C - IoT Platform - Alibaba Cloud - IoT Platform

File ./demos/mota_basic_demo.c menunjukkan cara perangkat menggunakan MQTT untuk mengunduh paket pembaruan OTA yang berisi satu file pembaruan dan melakukan pembaruan tersebut.

Informasi latar belakang

Untuk informasi lebih lanjut tentang fitur pembaruan OTA, lihat Ikhtisar pembaruan OTA.
Fitur pembaruan OTA didasarkan pada koneksi MQTT. Untuk informasi lebih lanjut tentang kode untuk koneksi MQTT, lihat Koneksi MQTT.

Langkah 1: Inisialisasi fitur OTA

Tambahkan file header.

……
……
#include "aiot_ota_api.h"
#include "aiot_mqtt_download_api.h"
……

/* Kumpulan fungsi adaptasi sistem di direktori portfiles/aiot_port */
extern aiot_sysdep_portfile_t g_aiot_sysdep_portfile;

/* TODO: Untuk menonaktifkan log, implementasikan fungsi ini sebagai fungsi kosong. Untuk mengurangi log, Anda dapat memilih untuk tidak mencetak log berdasarkan kode.
 * Contoh: [1578463098.611][LK-0309] pub: /ota/device/upgrade/a13FN******/ota_demo
 * Kode untuk log di atas adalah 0309 (heksadesimal). Untuk informasi lebih lanjut tentang nilai kode, lihat core/aiot_state_api.h.
 */

/* Ini adalah fungsi callback log. Log SDK dikeluarkan dari sini. */
int32_t demo_state_logcb(int32_t code, char *message)
{
    printf("%s", message);
    return 0;
}

Panggil aiot_ota_init untuk membuat handle OTA.

    ota_handle = aiot_ota_init();
    if (NULL == ota_handle) {
        goto exit;
    }

Langkah 2: Konfigurasikan fitur OTA

Panggil aiot_ota_setopt untuk mengonfigurasi opsi berikut.

Asosiasikan handle koneksi MQTT.
Penting Sebelum mengonfigurasi parameter OTA, Anda harus mengonfigurasi parameter seperti kredensial perangkat. Untuk informasi lebih lanjut, lihat Konfigurasikan parameter koneksi untuk MQTT.
- ```
    aiot_ota_setopt(ota_handle, AIOT_OTAOPT_MQTT_HANDLE, mqtt_handle);
```
- Item konfigurasi Contoh Deskripsi
  AIOT_OTAOPT_MQTT_HANDLE mqtt_handle Permintaan fitur OTA didasarkan pada koneksi MQTT. Item konfigurasi ini mengasosiasikan handle koneksi MQTT.
Konfigurasikan callback untuk pesan instruksi pembaruan OTA.
- ```
    aiot_ota_setopt(ota_handle, AIOT_OTAOPT_RECV_HANDLER, user_ota_recv_handler);
```
- Item konfigurasi Contoh Deskripsi
  
  AIOT_OTAOPT_MQTT_HANDLER
  user_ota_recv_handler
  Saat perangkat menerima instruksi pembaruan OTA dari IoT Platform, fungsi callback ini dipanggil.

Langkah 3: Laporkan versi perangkat saat ini

Setelah perangkat menjalin koneksi MQTT, panggil aiot_ota_report_version untuk melaporkan nomor versi perangkat saat ini. IoT Platform menentukan apakah pembaruan diperlukan berdasarkan nomor versi tersebut.

Dalam kode contoh berikut, nomor versi yang dilaporkan oleh perangkat sebelum pembaruan OTA adalah 1.0.0. Dalam aplikasi Anda, Anda harus mendapatkan nomor versi aktual dari area konfigurasi perangkat dan menyesuaikan kode tersebut.

Penting

Perangkat harus melaporkan nomor versinya setidaknya satu kali sebelum pembaruan OTA.

    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 instruksi pembaruan

Setelah Anda menambahkan paket pembaruan dan memulai tugas pembaruan di Konsol IoT Platform, IoT Platform mengirim instruksi pembaruan ke perangkat.
Untuk informasi lebih lanjut, lihat Tambahkan paket pembaruan.
Perangkat memanggil aiot_mqtt_recv untuk menerima pesan. Saat pesan diidentifikasi sebagai instruksi pembaruan OTA, callback user_ota_recv_handler dipanggil untuk memproses instruksi tersebut.
Tulis logika pemrosesan untuk fungsi callback.
Tulis logika pemrosesan untuk fungsi callback berdasarkan informasi berikut:
- IoT Platform mengirim instruksi paket pembaruan OTA ke perangkat melalui topik /ota/device/upgrade/${ProductKey}/${DeviceName}.
  Untuk informasi lebih lanjut tentang ${ProductKey} dan ${DeviceName}, lihat Dapatkan kredensial perangkat.
- Jenis instruksi pembaruan OTA adalah AIOT_OTARECV_FOTA.
```
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 tentang format data Alink dari pesan instruksi pembaruan OTA, lihat IoT Platform mendorong informasi paket pembaruan OTA.
- Jenis struktur data untuk pesan instruksi pembaruan OTA adalah aiot_ota_recv_t. Link SDK secara otomatis mengurai pesan instruksi pembaruan yang diterima.
- Untuk menulis logika pemrosesan fungsi callback, lihatLangkah 5.

Langkah 5: Unduh paket pembaruan dan lakukan pembaruan OTA

Penting Perangkat tidak secara otomatis mengunduh paket pembaruan setelah menerima pesan paket pembaruan dari IoT Platform. Anda harus memanggil API Link SDK untuk memulai pengunduhan.

Setelah user_ota_recv_handler dipicu, downloader mengirim permintaan unduh berbasis MQTT untuk menerima paket pembaruan dari IoT Platform dan melakukan pembaruan OTA.

Inisialisasi downloader.

Panggil aiot_mqtt_download_init untuk membuat download

void user_ota_recv_handler(void *ota_handle, aiot_ota_recv_t *ota_msg, void *userdata)
{
     ……
     ……

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

     ……
     ……

}

Konfigurasikan parameter unduh.

Panggil aiot_mqtt_download_setopt untuk mengonfigurasi parameter tugas unduh.

        aiot_mqtt_download_setopt(md_handler, AIOT_MDOPT_TASK_DESC, ota_msg->task_desc);
        /* Atur ukuran paket unduh. Anda dapat menyesuaikan nilai ini untuk perangkat dengan sumber daya terbatas. */
        aiot_mqtt_download_setopt(md_handler, AIOT_DLOPT_DATA_REQUEST_SIZE, &request_size);

        /* Nomor byte awal dan akhir untuk setiap segmen saat Anda mengunduh paket pembaruan secara bertahap atau hanya mengunduh fragmen tertentu dari paket.
         * Jika Anda menetapkan rentang untuk unduhan, data dalam satu pesan memiliki cyclic redundancy check (CRC), tetapi SDK tidak melakukan validasi MD5 penuh pada file.
         * Secara default, seluruh file diunduh. Data dalam satu pesan memiliki CRC, dan SDK melakukan validasi MD5 penuh pada file. 
         * Jika Anda menghapus komentar pada kode berikut, unduhan dimulai dari byte ke-10 file dan berakhir pada byte ke-10 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;

Item konfigurasi	Contoh	Deskripsi
AIOT_MDOPT_TASK_DESC	ota_msg->task_desc	Menentukan tugas unduh.
AIOT_DLOPT_DATA_REQUEST_SIZE	request_size	Ukuran setiap paket data yang diminta dari IoT Platform.
AIOT_MDOPT_RANGE_START	range_start	Nomor byte awal dan akhir untuk setiap segmen saat Anda mengunduh paket pembaruan secara bertahap atau hanya mengunduh fragmen tertentu dari paket. Jika tidak ditetapkan, seluruh file diunduh sekaligus. Contohnya, untuk mengunduh paket pembaruan berukuran 1024 byte dalam dua bagian, Anda dapat menetapkan parameter sebagai berikut: Bagian pertama: `AIOT_DLOPT_RANGE_START=0`, `AIOT_DLOPT_RANGE_END=511` Bagian kedua: `AIOT_DLOPT_RANGE_START=512`, `AIOT_DLOPT_RANGE_END=1023`
AIOT_MDOPT_RANGE_END	range_end
AIOT_MDOPT_RECV_HANDLE	user_download_recv_handler	Menentukan callback untuk menerima data paket pembaruan OTA. Callback ini dipicu saat IoT Platform mengembalikan pesan berisi konten paket pembaruan setelah perangkat menginisiasi permintaan unduh.

Panggil aiot_mqtt_download_process untuk mengirim permintaan unduh 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);
     ……
     ……

        }
    }

Setelah IoT Platform menerima permintaan unduh, platform tersebut mengembalikan paket pembaruan ke perangkat. Saat perangkat menerima data paket, callback user_download_recv_handler dipicu.

Tulis logika pemrosesan fungsi callback untuk menyimpan data paket pembaruan yang diunduh ke file lokal.

void user_download_recv_handler(void *handle, const aiot_mqtt_download_recv_t *packet, void *userdata)
{
    uint32_t data_buffer_len = 0;

    /* Saat ini, hanya kasus di mana packet->type adalah AIOT_MDRECV_DATA_RESP yang didukung. */
    if (!packet || AIOT_MDRECV_DATA_RESP != packet->type) {
        return;
    }

    /* Operasi untuk menyimpan file secara lokal harus diimplementasikan di sini. */
    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("download %03d%% done, +%d bytes\r\n", packet->data.data_resp.percent, data_buffer_len);
}

Setelah paket pembaruan diunduh, panggil aiot_mqtt_download_deinit untuk melepaskan sumber daya downloader.

    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 melaporkan nomor versi baru di sini. */
                printf("mqtt download ota success \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 failed \r\n");
                aiot_mqtt_download_deinit(&g_dl_handle);
                break;
            }
        }
    }

Langkah 6: Laporkan nomor versi setelah pembaruan

Untuk kode contoh tentang cara melaporkan nomor versi, lihat Langkah 3: Laporkan nomor versi perangkat saat ini.

Catatan

Setelah perangkat menyelesaikan pembaruan OTA, perangkat tersebut harus melaporkan nomor versi terbaru. Jika tidak, IoT Platform menganggap tugas pembaruan OTA gagal.
Jika perangkat perlu di-restart setelah pembaruan, perangkat tersebut harus melaporkan nomor versi terbaru setelah restart.
Kode contoh tidak menyertakan logika untuk melaporkan nomor versi setelah pembaruan selesai. Anda harus menambahkan logika ini ke kode Anda.

Langkah 7: Putuskan koneksi

Anda dapat memanggil aiot_mqtt_disconnect untuk mengirim pesan pemutusan koneksi ke IoT Platform dan memutuskan koneksi dari jaringan.

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

Langkah 8: Keluar dari program OTA

Panggil aiot_ota_deinit untuk menghapus instans OTA.

    aiot_ota_deinit(&ota_handle);

Langkah selanjutnya

./demos/mota-basic-demo demo.
Untuk informasi lebih lanjut, lihat Kompilasi dan jalankan.
Log operasional.