Konfigurasi device shadow menggunakan Link SDK untuk C - IoT Platform

Konfigurasikan bayangan perangkat menggunakan file kode contoh ./demos/shadow_basic_demo.c.

Informasi latar belakang

Untuk informasi lebih lanjut tentang bayangan perangkat, lihat Ikhtisar.
Ikhtisar.

Langkah 1: Inisialisasi klien

Tambahkan file header.
```
...
...

#include "aiot_shadow_api.h"
```

Tambahkan dependensi dasar dan konfigurasikan fitur output log.

    aiot_sysdep_set_portfile(&g_aiot_sysdep_portfile);
    aiot_state_set_logcb(demo_state_logcb);

Panggil operasi aiot_shadow_init untuk membuat bayangan.

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

Langkah 2: Konfigurasikan fitur

Panggil operasi aiot_shadow_setopt untuk mengonfigurasi item berikut.

Penting Sebelum mengatur parameter spesifik bayangan perangkat,
- ```
    aiot_shadow_setopt(shadow_handle, AIOT_SHADOWOPT_MQTT_HANDLE, mqtt_handle);
```
- Parameter Contoh Deskripsi
  AIOT_SHADOWOPT_MQTT_HANDLE mqtt_handle Anda harus membangun koneksi MQTT. Parameter ini digunakan untuk mengasosiasikan dengan penanganan koneksi MQTT.
- ```
    aiot_shadow_setopt(shadow_handle, AIOT_SHADOWOPT_RECV_HANDLER, (void *)demo_shadow_recv_handler);
```
- Parameter Contoh Deskripsi
  AIOT_SHADOWOPT_RECV_HANDLER demo_shadow_recv_handler Fungsi ini dipanggil ketika pesan bayangan perangkat diterima.

Langkah 3: Kirim status perangkat

Jika perangkat online, perangkat dapat mengirimkan status ke bayangannya. Aplikasi mendapatkan status dari bayangan.

Perangkat memanggil operasi aiot_shadow_send untuk mengirimkan status terbaru ke bayangan perangkat di IoT Platform.
Ketika mengirimkan status, perhatikan hal-hal berikut:
- aiot_shadow_msg_t menunjukkan format data dan merupakan parameter input dari callback aiot_shadow_send(). menunjukkan format data. Parameter ini adalah parameter input dari callback .
- AIOT_SHADOWMSG_UPDATE menunjukkan tipe pesan.
```
int32_t demo_update_shadow(void *shadow_handle, char *reported_data, int64_t version)
{
    aiot_shadow_msg_t message;

    memset(&message, 0, sizeof(aiot_shadow_msg_t));
    message.type = AIOT_SHADOWMSG_UPDATE;
    message.data.update.reported = reported_data;
    message.data.update.version = version;

    return aiot_shadow_send(shadow_handle, &message);
}
```

Tentukan isi pesan.

        res = demo_update_shadow(shadow_handle, "{\"LightSwitch\":1}", 0);
        if (res < 0) {
            printf("demo_delete_shadow_report gagal, res = -0x%04x\r\n", -res);
        }

Contoh pesan:

Contoh pesan Format Alink Deskripsi

{
    "LightSwitch": 1
}

{
  "method": "update", 
  "state": {
    "reported": {
      "LightSwitch": 1
    }
  }, 
  "version": 0
}

Isi pesan dalam format JSON. Isi tersebut ditunjukkan oleh parameter state dalam data Alink. Untuk informasi lebih lanjut, lihat Perangkat mengirimkan status.

Item berikut menjelaskan isi pesan dalam contoh ini:

Tetapkan properti LightSwitch menjadi 1.
Tetapkan nomor versi menjadi 0.
Catatan
- Nomor versi operasi selanjutnya harus bertambah. Jika tidak, IoT Platform akan mengembalikan kesalahan.
- Jika Anda menetapkan nomor versi menjadi -1, IoT Platform akan menghapus data bayangan perangkat dan memperbarui nomor versi menjadi 0.

Setelah IoT Platform menerima pesan, platform memperbarui file bayangan dan mengembalikan respons ke perangkat.

Setelah perangkat menerima respons, callback demo_shadow_recv_handler dipanggil.

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

aiot_shadow_recv_t menunjukkan format data dan merupakan parameter input dari callback. menunjukkan format data. Parameter ini adalah parameter input dari callback.
AIOT_SHADOWRECV_GENERIC_REPLY menunjukkan tipe pesan. menunjukkan tipe pesan.

Tabel berikut menjelaskan contoh respons dan format Alink dari respons.

Contoh	Format Alink	Deskripsi
`{ "status":"success", "version":0 }`	`{ "method": "reply", "payload": { "status": "success", "version": 0 }, "timestamp": 1626317187 }`	Respons ditunjukkan oleh parameter payload dalam data Alink. Contoh respons ini menunjukkan bahwa status telah dikirim.

Dalam contoh ini, pesan dicetak.

void demo_shadow_recv_handler(void *handle, const aiot_shadow_recv_t *recv, void *userdata)
{
    printf("demo_shadow_recv_handler, type = %d, productKey = %s, deviceName = %s\r\n",
            recv->type, recv->product_key, recv->device_name);

    switch (recv->type) {

        case AIOT_SHADOWRECV_GENERIC_REPLY: {
            const aiot_shadow_recv_generic_reply_t *generic_reply = &recv->data.generic_reply;

            printf("payload = \"%.*s\", status = %s, timestamp = %ld\r\n",
                   generic_reply->payload_len,
                   generic_reply->payload,
                   generic_reply->status,
                   (unsigned long)generic_reply->timestamp);
        }
……
...
        default:
            break;
    }
}

Langkah 4: Ubah status perangkat menggunakan properti yang diinginkan

Untuk mengubah status perangkat, Anda dapat menggunakan aplikasi untuk mengirimkan properti yang diinginkan ke bayangan perangkat atau masuk ke konsol IoT Platform untuk memodifikasi properti yang diinginkan dalam bayangan perangkat.

Perbarui properti yang diinginkan dalam bayangan perangkat menggunakan salah satu metode berikut:
- Kembangkan aplikasi cloud dan panggil operasi API untuk mengirimkan properti yang diinginkan ke bayangan perangkat. Untuk informasi lebih lanjut, lihat UpdateDeviceShadow.
- Di halaman Device Details IoT Platform, modifikasi properti yang diinginkan dalam bayangan perangkat. Untuk informasi lebih lanjut, lihat Lihat dan perbarui bayangan perangkat.
IoT Platform memperbarui file bayangan dan mengirimkannya ke perangkat.

Setelah perangkat menerima file bayangan, callback demo_shadow_recv_handler

Penting Jika perangkat offline, Anda dapat meminta bayangan perangkat setelah perangkat online. Untuk informasi lebih lanjut, lihat Langkah 5: Minta bayangan perangkat.

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

aiot_shadow_recv_t menunjukkan format data dan merupakan parameter input dari callback.
AIOT_SHADOWRECV_CONTROL menunjukkan tipe pesan.

Tabel berikut menjelaskan contoh pesan dan format Alink dari pesan.

Contoh Format Alink Deskripsi

{
    "state": {
        "desired": {
            "LightSwitch": 0
        }
    },
    "metadata": {
        "desired": {
            "LightSwitch": {
                "timestamp": 1626319658
            }
        }
    }
}

{
  "method": "control", 
  "payload": { 
   "state": {
        "desired": {
            "LightSwitch": 0
        }
    },
    "metadata": {
        "desired": {
            "LightSwitch": {
                "timestamp": 1626319658 
       }
      }
    }
  }, 
  "version": 2, 
  "timestamp": 1469564576
}

Respons ditunjukkan oleh parameter payload dalam data Alink.

Dalam contoh ini, properti yang diinginkan LightSwitch disetel menjadi 0.

Dalam contoh ini, pesan dicetak.

void demo_shadow_recv_handler(void *handle, const aiot_shadow_recv_t *recv, void *userdata)
{
    printf("demo_shadow_recv_handler, type = %d, productKey = %s, deviceName = %s\r\n",
            recv->type, recv->product_key, recv->device_name);

    switch (recv->type) {
...
...
        case AIOT_SHADOWRECV_CONTROL: {
            const aiot_shadow_recv_control_t *control = &recv->data.control;

            printf("payload = \"%.*s\", version = %ld\r\n",
                   control->payload_len,
                   control->payload,
                   (unsigned long)control->version);
        }
……
...
        default:
            break;
    }
}

Setelah perangkat memperbarui status lokal, perangkat mengirimkan status terbaru ke bayangan perangkat dan memproses respons.
Untuk informasi lebih lanjut, lihat Langkah 3: Kirim status perangkat.

Perangkat memanggil operasi aiot_shadow_send untuk menghapus properti yang diinginkan.

Ketika menghapus properti yang diinginkan, perhatikan hal-hal berikut:

aiot_shadow_msg_t menunjukkan format data dan merupakan parameter input dari callback aiot_shadow_send().
AIOT_SHADOWMSG_CLEAN_DESIRED menunjukkan tipe pesan.
Dalam contoh ini, semua properti yang diinginkan dihapus, dan nomor versi diatur menjadi 1.Dalam contoh ini, semua properti yang diinginkan dihapus dan nomor versi disetel menjadi .

int32_t demo_clean_shadow_desired(void *shadow_handle, int64_t version)
{
    aiot_shadow_msg_t message;

    memset(&message, 0, sizeof(aiot_shadow_msg_t));
    message.type = AIOT_SHADOWMSG_CLEAN_DESIRED;
    message.data.clean_desired.version = version;

    return aiot_shadow_send(shadow_handle, &message);
}
……
...
        res = demo_clean_shadow_desired(shadow_handle, 1);
        if (res < 0) {
            printf("demo_clean_shadow_desired gagal, res = -0x%04x\r\n", -res);
        }

Setelah platform IoT menerima permintaan untuk menghapus properti yang diinginkan, IoT Platform mengembalikan respons. Dalam hal ini, callback demo_shadow_recv_handler
Untuk informasi lebih lanjut, lihat Konfigurasikan callback untuk memproses respons.

Langkah 5: Minta bayangan perangkat

Ketika aplikasi mengirimkan perintah, perangkat mungkin offline. Setelah perangkat online, perangkat dapat meminta bayangan.

Perangkat memanggil operasi aiot_shadow_send untuk meminta konten bayangan perangkat dari IoT Platform.

menunjukkan tipe pesan.

int32_t demo_get_shadow(void *shadow_handle)
{
    aiot_shadow_msg_t message;

    memset(&message, 0, sizeof(aiot_shadow_msg_t));
    message.type = AIOT_SHADOWMSG_GET;

    return aiot_shadow_send(shadow_handle, &message);
}
……
...
        res = demo_get_shadow(shadow_handle);
        if (res < 0) {
            printf("demo_get_shadow gagal, res = -0x%04x\r\n", -res);
        }

Setelah IoT Platform menerima permintaan, platform mengembalikan respons. Setelah perangkat menerima respons, callback demo_shadow_recv_handler

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

aiot_shadow_recv_t menunjukkan format data dan merupakan parameter input dari callback.
AIOT_SHADOWRECV_GET_REPLY menunjukkan tipe pesan.

Tabel berikut menjelaskan contoh respons dan format Alink dari respons.

Contoh	Format Alink	Deskripsi
`{ "status": "success", "state": { "reported": { } }, "metadata": { "reported": { } } }`	`{ "method": "reply", "payload": { "status": "success", "state": { "reported": { } }, "metadata": { "reported": { } } }, "version": 5, "timestamp": 1626320690 }`	Respons ditunjukkan oleh parameter payload dalam data Alink. Contoh respons ini menunjukkan bahwa permintaan berhasil. Parameter reported tidak berisi data, yang menunjukkan bahwa tidak ada properti yang dikirimkan.

Dalam contoh ini, pesan dicetak.

void demo_shadow_recv_handler(void *handle, const aiot_shadow_recv_t *recv, void *userdata)
{
    printf("demo_shadow_recv_handler, type = %d, productKey = %s, deviceName = %s\r\n",
            recv->type, recv->product_key, recv->device_name);

    switch (recv->type) {
...
...
        case AIOT_SHADOWRECV_GET_REPLY: {
            const aiot_shadow_recv_get_reply_t *get_reply = &recv->data.get_reply;

            printf("payload = \"%.*s\", version = %ld\r\n",
                   get_reply->payload_len,
                   get_reply->payload,
                   (unsigned long)get_reply->version);
        }
        default:
            break;
    }
}

Langkah 6: Hapus properti dalam bayangan perangkat

Jika perangkat dalam status terbaru, perangkat dapat mengirimkan perintah untuk menghapus properti dalam bayangan perangkat.

Perangkat memanggil operasi aiot_shadow_send untuk menghapus properti tertentu dalam bayangan perangkat.

Ketika mengirimkan permintaan, perhatikan hal-hal berikut:

aiot_shadow_msg_t menunjukkan format data dan merupakan parameter input dari callback aiot_shadow_send().
AIOT_SHADOWMSG_DELETE_REPORTED menunjukkan tipe pesan.

int32_t demo_delete_shadow_report(void *shadow_handle, char *reported, int64_t version)
{
    aiot_shadow_msg_t message;

    memset(&message, 0, sizeof(aiot_shadow_msg_t));
    message.type = AIOT_SHADOWMSG_DELETE_REPORTED;
    message.data.delete_reporte.reported = reported;
    message.data.delete_reporte.version = version;

    return aiot_shadow_send(shadow_handle, &message);
}

        res = demo_delete_shadow_report(shadow_handle, "{\"LightSwitch\":\"null\"}", 2);
        if (res < 0) {
            printf("demo_delete_shadow_report gagal, res = -0x%04x\r\n", -res);
        }

Contoh pesan:

Contoh Format Alink Deskripsi

"{\"LightSwitch\":\"null\"}", 2

{
  "method": "delete", 
  "state": {
    "reported": {
      "LightSwitch": "null", 
    }
  }, 
  "version": 2
}

Isi pesan dalam format JSON. Isi tersebut ditunjukkan oleh parameter state dalam data Alink. Untuk informasi lebih lanjut, lihat Perangkat menghapus properti bayangan.

Item berikut menjelaskan isi pesan dalam contoh ini:

Tetapkan properti LightSwitch menjadi null. Nilai ini menunjukkan bahwa semua data dalam bayangan perangkat dihapus.
Tetapkan nomor versi menjadi 2.

Setelah IoT Platform menerima permintaan, platform mengembalikan respons. Setelah perangkat menerima respons, callback demo_shadow_recv_handler
Untuk informasi lebih lanjut, lihat Konfigurasikan callback untuk memproses respons.

Langkah 7: Keluar dari program

Panggil operasi aiot_shadow_deinit untuk menghapus bayangan

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

Apa yang harus dilakukan selanjutnya

Dalam contoh ini, file eksekusi ./demos/shadow-basic-demo telah dibuat.
Untuk informasi lebih lanjut, lihat Siapkan lingkungan.
Penting
- Ketika mengonfigurasi file kode contoh, hapus simbol komentar (/* dan */) di kedua sisi kode dan ubah nomor versi sesuai skenario aktual.
- Ketika mengubah nomor versi, perhatikan hal-hal berikut:
  - Nomor versi operasi selanjutnya harus bertambah. Jika tidak, IoT Platform akan mengembalikan kesalahan.
  - Jika Anda menetapkan nomor versi menjadi -1, IoT Platform akan menghapus data bayangan perangkat dan memperbarui nomor versi menjadi 0.
Lihat log.

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