IoT Platform:Contoh

Langkah 1: Inisialisasi klien

1. Tambahkan file header.

   ...
   ...
   
   #include "aiot_task_api.h"

2. Tambahkan dependensi dasar dan konfigurasikan fitur keluaran log.

       aiot_sysdep_set_portfile(&g_aiot_sysdep_portfile);
       aiot_state_set_logcb(demo_state_logcb);

3. Panggil operasi aiot_task_init() untuk membuat task.

       task_handle = aiot_task_init();
       if (task_handle == NULL) {
           demo_mqtt_stop(&mqtt_handle);
           printf("aiot_task_init gagal\n");
           return -1;
       }

Langkah 2: Konfigurasikan fitur

Panggil operasi aiot_task_setopt() untuk mengonfigurasi item berikut:

1. Hubungkan menggunakan penanganan koneksi MQTT.

   Penting

   Sebelum menyetel parameter spesifik tugas perangkat, pastikan informasi autentikasi perangkat telah ditentukan. Untuk informasi lebih lanjut, lihat Contoh.

   •     aiot_task_setopt(task_handle, AIOT_TASKOPT_MQTT_HANDLE, mqtt_handle);

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

2. Konfigurasikan callback pesan.

   •     aiot_task_setopt(task_handle, AIOT_TASKOPT_RECV_HANDLER, demo_task_recv_handler);

   • Parameter	Contoh	Deskripsi
     AIOT_TASKOPT_RECV_HANDLER	demo_task_recv_handler	Ketika pesan spesifik tugas perangkat diterima, fungsi ini dipanggil.

Langkah 3: Terima notifikasi tugas downstream

Jika IoT Platform mengirimkan notifikasi tugas ketika perangkat sedang online, lakukan langkah-langkah berikut untuk memproses notifikasi:

1. Masuk ke Konsol IoT Platform atau dan buat tugas perangkat.

2. Setelah Anda membuat tugas perangkat, IoT Platform mengirimkan notifikasi ke perangkat. Setelah perangkat menerima notifikasi, callback demo_task_recv_handler dipanggil.

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

   • aiot_task_recv_t merupakan parameter input callback yang menunjukkan format data.

   • AIOT_TASKRECV_NOTIFY menunjukkan tipe pesan.

   • Tabel berikut menjelaskan contoh notifikasi dan format data Alink dari notifikasi tersebut.

     Contoh	Format data Alink	Deskripsi
     { "task": { "taskId": "i5Ks6***pF010101", "status": "SENT", "jobDocument": { }, "jobFile": { "signMethod": "Md5", "sign": "wssxff56dhdsd***", "fileUrl": "https://iotx-***.aliyuncs.com/***.zip" } } }	{ "id": "7542940", "version": "1.0", "params": { "task": { "taskId": "i5Ks6***pF010101", "status": "SENT", "jobDocument": { }, "jobFile":{ "signMethod":"Md5", "sign":"wssxff56dhdsd***", "fileUrl": "https://iotx-***.aliyuncs.com/***.zip" } } } }	Isi pesan dalam format JSON. Isi tersebut merupakan nilai dari parameterparamsdalam data Alink.

   • Perangkat menyelesaikan tugas di bawah pekerjaan dan mengirimkan status tugas ke IoT Platform. Untuk detail lebih lanjut tentang cara memperbarui tugas, lihat Langkah 5: Perbarui status tugas di bawah pekerjaan.

   • Dalam contoh ini, logika untuk melaksanakan tugas tidak disediakan. Tentukan logika pemrosesan sesuai dengan kebutuhan bisnis Anda.

     void demo_task_recv_handler(void *handle, const aiot_task_recv_t *packet, void *userdata)
     {
         switch (packet->type) {
             case AIOT_TASKRECV_NOTIFY: {
                 const task_desc_t *in_desc = &(packet->data.notify);
     
                 printf("revice task notify, task_id:[%s],status:[%d],job_document[%s],document_file_url:[%s],\
                 sign_method:[%s],sign[%s]\r\n",
                        in_desc->task_id, in_desc->status, in_desc->job_document,
                        in_desc->document_file_url, in_desc->sign_method, in_desc->sign);
     
                 /* 1.Jika tidak ada catatan pekerjaan di handle, simpan pekerjaan yang dikirim oleh IoT Platform ke default_task_desc field di handle. */
                 if (NULL == g_local_task_desc) {
                     demo_copy_task_to_local_task(&g_local_task_desc, in_desc);
                     /* Mulai pekerjaan. Dalam contoh ini, informasi pekerjaan dicetak. Anda dapat menentukan logika berdasarkan kebutuhan bisnis Anda. */
                     int res = pthread_create(&g_task_thread, NULL, demo_task_thread, g_local_task_desc);
                     if (res != 0) {
                         printf("pthread_create demo_task_thread failed: %d\r\n", res);
                     } else {
                         /* Tetapkan jenis thread unduhan menjadi detach. Setelah firmware diperoleh, thread unduhan otomatis keluar. */
                         pthread_detach(g_task_thread);
                     }
                     /* Ubah status pekerjaan.TODO: Kode berikut hanya untuk referensi. Setelah pekerjaan selesai, Anda harus menetapkan status menjadi AIOT_TASK_STATUS_SUCCEEDED. */
                     g_local_task_desc->status = AIOT_TASK_STATUS_IN_PROGRESS;
                     aiot_task_update(handle, g_local_task_desc);
                     demo_free_local_task(&g_local_task_desc);
                     break;
                 }
     
                 /* 2.Jika status pekerjaan diatur ke status akhir oleh IoT Platform, pekerjaan lokal dibersihkan. */
                 if (in_desc->status == AIOT_TASK_STATUS_CANCELLED || in_desc->status == AIOT_TASK_STATUS_REMOVED
                     || in_desc->status == AIOT_TASK_STATUS_TIMED_OUT) {
                     /* TODO: Bersihkan pekerjaan lokal dan hentikan thread. */
                     /* Jika pekerjaan adalah pekerjaan default yang tercatat di handle, bersihkan memori pekerjaan. Jika tidak, Anda harus mempertahankan memori pekerjaan. */
                     if (NULL != g_local_task_desc && 0 == strcmp(in_desc->task_id, g_local_task_desc->task_id)) {
                         /* Lepaskan memori pekerjaan lokal. */
                         demo_free_local_task(&g_local_task_desc);
                     }
                     break;
                 }
     
                 /* 3.Jika pekerjaan lokal sudah ada, IoT Platform memperbarui deskripsi pekerjaan. Anda harus memeriksa deskripsi yang diperbarui. */
                 if (in_desc->status == AIOT_TASK_STATUS_IN_PROGRESS) {
                     if (NULL != g_local_task_desc && 0 == strcmp(in_desc->task_id, g_local_task_desc->task_id)) {
                         /* TODO: Perbarui deskripsi pekerjaan lokal. Anda dapat menangguhkan pekerjaan saat ini berdasarkan kebutuhan bisnis Anda. * /
                         break;
                     }
                 }
     
                 /* 4.Dalam kasus lain, pekerjaan yang diterima ditentukan sebagai pekerjaan baru. Jika pekerjaan sedang berjalan dan pekerjaan baru diterima, Anda dapat membuat daftar di fungsi main(). */
                 /* Masukkan daftar sebagai parameter userdata dan rekam semua pekerjaan dalam daftar ini untuk pemeliharaan. */
                 break;
             }
     ……
     ... 
     }

Langkah 4: Minta tugas perangkat

Setelah perangkat online, Anda dapat meminta tugas perangkat.

1. Panggil operasi aiot_task_get_task_detail untuk mengirim permintaan ke IoT Platform. Jika Anda menetapkan parameter ke NULL, Anda dapat memperoleh informasi tentang pekerjaan pertama yang belum dilaksanakan.

   Catatan

   Jika IoT Platform mendorong beberapa tugas perangkat ke perangkat, Anda dapat memanggil operasi aiot_task_get_task_list untuk memeriksa tugas perangkat sebelum Anda menerima notifikasi tugas. Kemudian, Anda dapat memeriksa informasi setiap tugas perangkat.

       res = aiot_task_get_task_detail(task_handle, NULL);
       if (res < STATE_SUCCESS) {
           aiot_task_deinit(&task_handle);
           demo_mqtt_stop(&mqtt_handle);
           return -1;
       }
                           

2. Setelah IoT Platform menerima permintaan, IoT Platform mengembalikan informasi tugas perangkat yang dibuat ke perangkat.

3. Setelah perangkat menerima notifikasi tugas, callback demo_task_recv_handler dipanggil.

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

   • aiot_task_recv_t merupakan parameter input callback yang menunjukkan format data.

   • AIOT_TASKRECV_GET_DETAIL_REPLY menunjukkan tipe pesan.

   • Tabel berikut menjelaskan contoh notifikasi dan format data Alink dari notifikasi tersebut.

     Contoh	Format data Alink	Deskripsi
     { "taskId": "i5Ks***F010101", "status": "IN_PROGRESS", "jobDocument": { }, "jobFile":{ "signMethod":"Md5", "sign":"wssxff56dhdsd***", "fileUrl": "https://iotx-***.aliyuncs.com/***.zip" } }	{ "id": "1234", "code": 200, "data": { "taskId": "$next", "task":{ "taskId": "i5Ks***F010101", "status": "IN_PROGRESS", "jobDocument": { }, "jobFile":{ "signMethod":"Md5", "sign":"wssxff56dhdsd***", "fileUrl": "https://iotx-***.aliyuncs.com/***.zip" } } } }	Isi pesan dalam format JSON. Isi tersebut merupakan nilai dari parameter params dalam data Alink.

   • Perangkat menyelesaikan tugas di bawah pekerjaan dan mengirimkan status tugas ke IoT Platform. Untuk detail lebih lanjut tentang cara memperbarui tugas, lihat Langkah 5: Perbarui status tugas di bawah pekerjaan.

   • Dalam contoh ini, logika untuk melaksanakan tugas tidak disertakan. Anda perlu menentukan logika pemrosesan sesuai dengan kebutuhan bisnis Anda.

     void demo_task_recv_handler(void *handle, const aiot_task_recv_t *packet, void *userdata)
     {
         switch (packet->type) {
     ...
     ... 
             case AIOT_TASKRECV_GET_DETAIL_REPLY: {
                 const task_get_detail_reply_t *in_reply = &(packet->data.get_detail_reply);
                 printf("revice task get detail, code:[%d]\r\n", in_reply->code);
                 if (200 == in_reply->code) {
                     printf("revice task get detail reply, task_id:[%s],status:[%d]\r\n",
                            in_reply->task.task_id, in_reply->task.status);
                     if (in_reply->task.status != AIOT_TASK_STATUS_NOT_FOUND) {
                         printf("job_document[%s],document_file_url:[%s], sign_method:[%s],sign[%s]\r\n",
                                in_reply->task.job_document, in_reply->task.document_file_url,
                                in_reply->task.sign_method, in_reply->task.sign);
                         task_desc_t task;
                         memset(&task, 0, sizeof(task));
                         memcpy(&task, &(in_reply->task), sizeof(task));
                         /* TODO: Implementasikan pekerjaan dengan memulai thread. */
     
                         /* Ubah status pekerjaan. TODO: Kode berikut hanya untuk referensi. Anda dapat menentukan logika berdasarkan kebutuhan bisnis Anda. Setelah tugas selesai, tetapkan status menjadi AIOT_TASK_STATUS_SUCCEEDED. */
                         task.status = AIOT_TASK_STATUS_IN_PROGRESS;
                         task.progress = 88;
                         aiot_task_update(handle, &task);
                     }
                 }
                 break;
             }
     ……
     ... 
     }

Langkah 5: Perbarui status tugas di bawah pekerjaan

Setelah perangkat mendapatkan informasi pekerjaan dan melaksanakan tugas di bawah pekerjaan, perangkat harus mengirimkan status tugas ke IoT Platform.

1. Panggil operasi aiot_task_update untuk mengirimkan status tugas ke IoT Platform.

   Saat mengirimkan status tugas, perhatikan hal-hal berikut:

   • task_desc_t menunjukkan format data.

   • aiot_task_update menunjukkan operasi API.

   • Contoh berikut menunjukkan pesan dalam format Alink.

     Catatan

     Isi pesan dalam format JSON. Isi tersebut merupakan nilai dari parameter params dalam data Alink.

     {
         "id": "123",
         "version": "1.0",
         "params": {
             "taskId": "i5Ks***F010101",
             "status": "IN_PROGRESS",
             "statusDetails": {
                 "key": "value"
             },
             "progress": 50
         }
     }

     Catatan: Isi pesan dalam format JSON. Isi tersebut merupakan nilai dari parameter params dalam data Alink.

   • Dalam contoh ini, status AIOT_TASK_STATUS_IN_PROGRESS dikirimkan. Anda harus memperoleh status tugas dalam skenario bisnis aktual dan mengirimkan status tersebut.

     • Kode contoh untuk Langkah 3

                       g_local_task_desc->status = AIOT_TASK_STATUS_IN_PROGRESS;
                       aiot_task_update(handle, g_local_task_desc);
                       demo_free_local_task(&g_local_task_desc);

     • Kode contoh untuk Langkah 4

                           task.status = AIOT_TASK_STATUS_IN_PROGRESS;
                           task.progress = 88;
                           aiot_task_update(handle, &task);

2. Setelah status tugas dikirimkan, IoT Platform mengembalikan pesan respons. Dalam hal ini, callback demo_task_recv_handler dipanggil.

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

   • aiot_task_recv_t merupakan parameter input callback yang menunjukkan format data.

   • AIOT_TASKRECV_UPDATE_REPLY menunjukkan tipe pesan.

   • Dalam contoh ini, logika untuk melaksanakan tugas tidak disediakan. Anda perlu menentukan logika pemrosesan sesuai dengan kebutuhan bisnis Anda.

     void demo_task_recv_handler(void *handle, const aiot_task_recv_t *packet, void *userdata)
     {
         switch (packet->type) {
     ...
     ... 
             case AIOT_TASKRECV_UPDATE_REPLY: {
                 const task_update_reply_t *update_reply = &(packet->data.update_reply);
                 printf("menerima balasan pembaruan tugas, kode:[%d]\r\n", update_reply->code);
     
                 if (200 == update_reply->code) {
                     printf("menerima balasan pembaruan tugas, task_id:[%s]\r\n", update_reply->task_id);
                 }
     
                 if (71012 == update_reply->code) {
                     printf("nilai status_details dari aiot_task_update harus dalam format json\r\n");
                 }
                 /* TODO */
                 break;
             }
     ……
     ... 
     }

Langkah 6: Keluar dari program

Panggil operasi aiot_task_deinit() untuk menghapus task

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

Langkah 7: Akhiri koneksi

Panggil operasi aiot_mqtt_disconnect untuk memutuskan sambungan 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;
    }