：Integrasi Link SDK ke dalam modul WAN berbasis TCP

Operasi di konsol IoT Platform

Untuk memeriksa apakah Link SDK yang diintegrasikan ke dalam modul bekerja sesuai harapan, Anda harus menghubungkan perangkat uji ke IoT Platform. Anda harus membuat produk di konsol IoT Platform dan kemudian membuat perangkat dalam produk untuk mendapatkan informasi identitas tentang perangkat.

1. Masuk ke konsol IoT Platform. Jika Anda masuk ke konsol sebagai penyedia modul, Anda harus membuat akun Alibaba Cloud. Anda dapat membuat akun Alibaba Cloud secara gratis.
2. Setelah Anda masuk ke IoT Platform, ikuti langkah-langkah yang dijelaskan dalam topik Buat Produk untuk membuat produk. Di halaman detail produk, Anda bisa mendapatkan ProductKey dan ProductSecret dari produk.
3. Buat perangkat uji. Di halaman detail perangkat, Anda bisa mendapatkan DeviceName dan DeviceSecret dari perangkat.

Proses integrasi Link SDK

Saat penyedia modul mengintegrasikan Link SDK ke dalam modul, proses tersebut mencakup beberapa tahap, seperti yang ditunjukkan pada gambar berikut.

Konfigurasikan Link SDK dan ekstrak kode

Konfigurasikan Link SDK

Link SDK menyediakan sejumlah besar fitur. Bagian berikut menjelaskan cara mengonfigurasi fitur yang diperlukan dalam contoh ini.

Jalankan perintah konfigurasi

• Linux

  Pergi ke direktori root Link SDK dan jalankan perintah berikut:

  make menuconfig
              

• Windows

  Pergi ke direktori root Link SDK dan jalankan perintah berikut:

  config.bat

Gunakan salah satu metode di atas untuk memulai alat konfigurasi Link SDK. Gambar berikut menunjukkan GUI dari alat tersebut.

Aktifkan fitur yang diperlukan

Di GUI, tekan tombol Spasi untuk memilih atau menghapus fitur dan tekan tombol Panah Atas atau Panah Bawah pada keypad untuk beralih antar opsi yang berbeda. Jika Anda ingin mendapatkan informasi tentang suatu opsi, tekan tombol panah untuk memindahkan kursor ke opsi tersebut dan tekan tombol H. Dalam hal ini, informasi yang menunjukkan tujuan opsi dan tindakan sistem yang dilakukan setelah Anda memilih atau menghapus opsi akan ditampilkan.

• Jika lingkungan kompilasi mencakup file header stdint.h, pilih opsi berikut.

  PLATFORM_HAS_STDINT

• Jika sistem operasi tertanam berjalan di lingkungan Anda, pilih opsi berikut.

  PLATFORM_HAS_OS

• Jika modul mendukung TCP bukan Message Queuing Telemetry Transport (MQTT), Anda harus mengaktifkan opsi berikut:
  • FEATURE_MQTT_COMM_ENABLED: menyediakan API MQTT dari Alibaba SDK untuk mengaktifkan komunikasi antara perangkat dan IoT Platform.
  • FEATURE_MQTT_DEFAULT_IMPL: menyediakan implementasi MQTT Client yang telah ditentukan sebelumnya di Alibaba SDK. Anda harus menulis kode untuk membuat dan membangun koneksi TCP, dan mengirimkan data melalui koneksi TCP berdasarkan implementasi MQTT Client.
  • FEATURE_MQTT_DIRECT: menyediakan titik akhir IoT Platform tempat perangkat dapat terhubung.

Kami merekomendasikan agar Anda memilih opsi FEATURE_SUPPORT_TLS. Anda dapat memilih opsi tersebut untuk mengenkripsi data yang dikirimkan antara perangkat dan IoT Platform. Dalam contoh ini, opsi ini tidak dipilih untuk mengurangi beban konfigurasi.

Anda tidak perlu mengaktifkan fitur lainnya.

Ekstrak kode sumber fitur yang dipilih

Di direktori root Link SDK, jalankan file extract.sh atau jalankan file extract.bat jika Anda menggunakan Windows. Kode fitur yang dipilih disalin ke direktori output.

Integrasikan file kode Link SDK ke dalam lingkungan kompilasi

Salin file kode yang Anda peroleh pada langkah sebelumnya dari direktori output ke direktori proyek Anda. Kemudian, ubah lingkungan kompilasi atau alat pengembangan Anda untuk mengintegrasikan file kode ke dalam lingkungan kompilasi.

Anda harus mengintegrasikan file kode dari direktori eng/dev_sign, eng/infra, eng/mqtt, dan eng/wrappers.

Implementasikan fungsi lapisan abstraksi perangkat keras (HAL)

Link SDK dirancang untuk berjalan di berbagai sistem operasi atau pada MCU yang tidak mendukung sistem operasi. Operasi yang terkait dengan sistem operasi didefinisikan sebagai fungsi HAL yang harus diimplementasikan. Sistem operasi bervariasi berdasarkan modul komunikasi. Operasi terkait TCP yang ingin Anda lakukan pada modul komunikasi juga didefinisikan sebagai fungsi HAL yang harus Anda implementasikan.

Semua fungsi HAL disimpan dalam file wrapper.c di direktori output/eng/wrappers/.

Fungsi HAL terkait OS

Tabel berikut menjelaskan fungsi HAL yang harus Anda implementasikan.

Direktori wrappers/os dari paket SDK terkompresi mencakup contoh tentang cara mengimplementasikan fungsi HAL. Jika contoh tertentu memenuhi persyaratan sistem operasi Anda, Anda dapat menggunakan contoh tersebut. Jika tidak ada contoh yang memenuhi syarat, Anda harus mengimplementasikan fungsi HAL berdasarkan skenario bisnis Anda.

Fungsi HAL yang dapat Anda implementasikan

Jika tidak ada sistem operasi yang berjalan di modul atau API MQTT dari Link SDK tidak dipanggil oleh beberapa thread, Anda tidak perlu mengubah definisi fungsi berikut di file wrapper.c. Jika sistem operasi berjalan di modul dan API MQTT dari Link SDK dipanggil oleh beberapa thread, Anda harus mengimplementasikan fungsi berikut.

Fungsi HAL terkait TCP

Koneksi MQTT dibentuk melalui TCP. Penyedia modul harus mengimplementasikan fungsi HAL terkait TCP berikut.

Fungsi HAL terkait produk

Fungsi HAL berikut dipanggil untuk mendapatkan informasi verifikasi identitas tentang produk. Produsen perangkat harus memberikan instruksi tentang cara membakar informasi identitas perangkat ke perangkat, mendapatkan informasi tersebut dengan menggunakan fungsi HAL berikut, dan kemudian menentukannya di Link SDK.

Saat Anda mengonfigurasi produk dalam skenario bisnis aktual, item data di atas harus dikirimkan oleh perintah AT dari produsen perangkat ke modul. Saat penyedia modul men-debug perangkat uji, penyedia dapat memperoleh ProductKey, DeviceName, dan DeviceSecret perangkat uji dengan memanggil fungsi di atas.

Implementasikan fitur produk berdasarkan kode contoh

Penyedia modul dapat men-debug fitur berdasarkan file mqtt_example.c di direktori output. Produsen perangkat dapat menyalin file tersebut ke proyeknya sendiri dan memodifikasi file untuk menggunakan fitur tersebut.

Kode contoh dalam file digunakan untuk menghubungkan perangkat ke IoT Platform, berlangganan topik, dan kemudian mengirimkan data ke topik. Dalam hal ini, IoT Platform mengirimkan data yang dikirimkan oleh perangkat ke perangkat yang berlangganan topik. Gambar berikut menjelaskan cara kerja kode contoh.

Anda harus mengubah izin default pada topik dari Berlangganan menjadi Publikasi dan Berlangganan di konsol IoT Platform.

Kode contoh dimulai dari fungsi main(). Dalam definisi fungsi main(), fungsi HAL terkait produk dipanggil untuk mendapatkan informasi identitas tentang produk, seperti yang ditunjukkan dalam kode berikut.

int main(int argc, char *argv[])
{
    void                   *pclient = NULL;
    int                     res = 0;
    int                     loop_cnt = 0;
    iotx_mqtt_param_t       mqtt_params;

    HAL_GetProductKey(DEMO_PRODUCT_KEY);
    HAL_GetDeviceName(DEMO_DEVICE_NAME);
    HAL_GetDeviceSecret(DEMO_DEVICE_SECRET);

    EXAMPLE_TRACE("mqtt example");
            

• Fungsi HAL di atas yang dimulai dengan HAL_Get dipanggil untuk mendapatkan informasi sertifikat tentang perangkat. Penyedia modul dapat menentukan informasi sertifikat tentang perangkat uji.

Kode berikut menunjukkan cara mengonfigurasi parameter koneksi MQTT berdasarkan kebutuhan bisnis Anda.

/* Inisialisasi parameter MQTT */
    memset(&mqtt_params, 0x0, sizeof(mqtt_params));
    mqtt_params.port = sign_mqtt.port;
    mqtt_params.host = sign_mqtt.hostname;
    mqtt_params.client_id = sign_mqtt.clientid;
    mqtt_params.username = sign_mqtt.username;
    mqtt_params.password = sign_mqtt.password;
    mqtt_params.request_timeout_ms = 2000;
    mqtt_params.clean_session = 0;
    mqtt_params.keepalive_interval_ms = 60000;
    mqtt_params.read_buf_size = 1024;
    mqtt_params.write_buf_size = 1024;
    mqtt_params.handle_event.h_fp = example_event_handle;
    mqtt_params.handle_event.pcontext = NULL;
    pclient = IOT_MQTT_Construct(&mqtt_params);
            

Panggil fungsi IOT_MQTT_Construct() dari Link SDK untuk menghubungkan perangkat ke IoT Platform. Jika fungsi mengembalikan nilai non-null, koneksi ke IoT Platform terbentuk. Kemudian, panggil fungsi example_subscribe untuk berlangganan topik.

res = example_subscribe(pclient);
            

Gambar berikut menunjukkan isi dari fungsi example_subscribe.

• Produsen perangkat harus berlangganan topik dan mengimplementasikan fungsi pemrosesan berdasarkan desain produknya.
• Dalam kode contoh di atas, kode di kotak oranye pertama menentukan bahwa topik dalam format /$ProductKey/$DeviceName. Saat Anda membuat produk di konsol IoT Platform, sistem secara otomatis membuat topik dalam format tersebut.
• Kode di kotak oranye kedua menentukan informasi tentang topik.
• Kode di kotak oranye kedua menentukan cara berlangganan topik dan fungsi yang dipanggil untuk memproses data yang diterima dari topik.

Kode berikut menunjukkan cara menggunakan fitur publikasi MQTT untuk mengirimkan paket bisnis ke IoT Platform.

 while (1) {
        if (0 == loop_cnt % 20) {
            example_publish(pclient);
        }

        IOT_MQTT_Yield(pclient, 200);

        loop_cnt += 1;
    }
            

• Kode contoh di atas mengirimkan pesan tetap ke IoT Platform secara berkala. Kami merekomendasikan agar produsen perangkat hanya mengirimkan data yang diperlukan ke IoT Platform berdasarkan fitur produknya sendiri.
• Untuk mencegah data tidak valid dikirimkan ke IoT Platform secara berkala, Anda dapat menghapus pernyataan example_publish(pclient) di fungsi main().
• Fungsi IOT_MQTT_Yield dari Link SDK dipanggil untuk menerima data dari broker MQTT. Nilai 200 menunjukkan bahwa fungsi harus menunggu selama 200 milidetik sebelum fungsi menerima data. Jika Anda memiliki banyak pesan atau persyaratan tinggi untuk latensi, Anda dapat menentukan nilai yang lebih kecil.

Gambar berikut menunjukkan isi dari fungsi example_publish.

Dalam gambar di atas, kode di kotak oranye pertama menentukan isi pesan yang ingin Anda kirim. Kode di kotak oranye kedua memanggil fungsi dari Link SDK untuk mengirimkan pesan ke topik tertentu.

Unggah ID penyedia modul dan model modul

Jika penyedia modul ingin memverifikasi modul di IoT Platform, penyedia modul harus mengirimkan ID penyedia modul dan model modul. Dengan cara ini, IoT Platform dapat memperoleh jumlah perangkat yang terhubung ke IoT Platform berdasarkan ID penyedia modul atau model modul.

Sebelum Anda mengintegrasikan Link SDK, hubungi Alibaba Cloud untuk mendapatkan ID penyedia modul dan model modul dengan mengirimkan pesan berdasarkan template berikut. Untuk informasi lebih lanjut, kunjungi Hubungi Kami.

Subjek: Gunakan Link SDK untuk menghubungkan perangkat - Ajukan model modul atau chip

Setelah modul terhubung ke IoT Platform, salin kode berikut ke lingkungan Anda dan jalankan fungsi dalam kode untuk mengirimkan informasi. Parameter pid menentukan ID penyedia modul dan parameter mid menentukan ID model modul.

#define PID_STRING_LEN_MAX          32  /* Panjang maksimum nilai parameter pid. Nilainya adalah string.*/
#define MID_STRING_LEN_MAX          32  /* Panjang maksimum nilai parameter mid. Nilainya adalah string.*/


int example_report_pid_mid(void *pclient, const char *product_key, const char *device_name, const char *pid, const char *mid)
{
    int res = 0;
    iotx_mqtt_topic_info_t topic_msg;

    const char topic_frag1[] = "/sys/";
    const char topic_frag2[] = "/thing/deviceinfo/update";
    char topic[sizeof(topic_frag1) + sizeof(topic_frag2) + IOTX_PRODUCT_KEY_LEN + IOTX_DEVICE_NAME_LEN] = {0};

    const char payload_frag1[] = "{\"id\":\"0\",\"version\":\"1.0\",\"params\":[{\"attrKey\":\"SYS_MODULE_ID\",\"attrValue\":\"";
    const char payload_frag2[] = "\",\"domain\":\"SYSTEM\"},{\"attrKey\":\"SYS_PARTNER_ID\",\"attrValue\":\"";
    const char payload_frag3[] = "\",\"domain\":\"SYSTEM\"}],\"method\": \"thing.deviceinfo.update\"}";
    char payload[sizeof(payload_frag1) + sizeof(payload_frag2) + sizeof(payload_frag3) + PID_STRING_LEN_MAX + MID_STRING_LEN_MAX] = {0};

    if (strlen(pid) > PID_STRING_LEN_MAX || strlen(mid) > MID_STRING_LEN_MAX) {
        return -1;
    }

    /* Menggabungkan string untuk membuat topik MQTT. */
    memcpy(topic, topic_frag1, strlen(topic_frag1));
    memcpy(topic + strlen(topic), product_key, strlen(product_key));
    memcpy(topic + strlen(topic), "/", 1);
    memcpy(topic + strlen(topic), device_name, strlen(device_name));
    memcpy(topic + strlen(topic), topic_frag2, strlen(topic_frag2));

    /* Menggabungkan string untuk membuat payload topik MQTT. Payload mencakup nilai parameter pid dan mid. */
    memcpy(payload, payload_frag1, strlen(payload_frag1));
    memcpy(payload + strlen(payload), mid, strlen(mid));
    memcpy(payload + strlen(payload), payload_frag2, strlen(payload_frag2));
    memcpy(payload + strlen(payload), pid, strlen(pid));
    memcpy(payload + strlen(payload), payload_frag3, strlen(payload_frag3));

    topic_msg.qos = IOTX_MQTT_QOS0;
    topic_msg.retain = 0;
    topic_msg.dup = 0;
    topic_msg.payload = (void *)payload;
    topic_msg.payload_len = strlen(payload);

    /* Panggil MQTT IOT_MQTT_Publish untuk mengirim pesan yang mencakup nilai parameter pid dan mid.*/
    res = IOT_MQTT_Publish(pclient, topic, &topic_msg);
    if (res < 0) {
        return -1;
    }

    return 0;
}

            

Debug fitur

Tangkapan layar berikut disediakan berdasarkan hasil setelah Anda memodifikasi dan menjalankan file mqtt_example.c.

Periksa apakah perangkat terhubung ke IoT Platform

Secara default, perangkat diberikan izin Berlangganan pada topik /${productKey}/${deviceName}/get. Untuk mencegah pesan dijatuhkan setelah pesan dikirim ke IoT Platform, kami sarankan Anda mengubah izin pada topik menjadi Berlangganan dan Publikasi. Dengan cara ini, program contoh dapat berjalan sesuai harapan tanpa kegagalan.

Gambar berikut menunjukkan output setelah Anda menjalankan kode contoh. Output dicetak oleh fungsi HAL_Printf ke port serial. Program yang dikompilasi dari kode contoh mendapatkan output dan menampilkan output. Informasi dalam kotak oranye menunjukkan bahwa perangkat terhubung ke IoT Platform.

Periksa apakah data dikirim oleh perangkat ke IoT Platform

Masuk ke konsol IoT Platform dengan akun Alibaba Cloud Anda, buka halaman detail perangkat untuk memeriksa apakah pesan diterima dari perangkat, seperti yang ditunjukkan pada gambar berikut.

Gambar di atas menunjukkan topik ke mana pesan dikirim. Konten pesan tidak ditampilkan.

Periksa apakah data diterima oleh perangkat dari IoT Platform

Di tab Analisis Hilir, Anda dapat melihat pesan yang dikirim ke perangkat, seperti yang ditunjukkan pada gambar berikut.

Anda juga dapat memeriksa apakah data diterima dari IoT Platform di sisi perangkat. Gambar berikut menunjukkan output setelah Anda menjalankan kode contoh. Output menunjukkan bahwa data diterima dari IoT Platform.

Implementasikan perintah AT

Penyedia modul tidak menyediakan lingkungan pengembangan yang dapat digunakan untuk melakukan pengembangan kustom pada modul. Sebagai gantinya, penyedia modul menghubungkan MCU eksternal dan logika bisnis produk berjalan di MCU. Dalam hal ini, penyedia modul harus menyediakan perintah AT yang dapat dipanggil oleh MCU. Dalam banyak kasus, modul hanya mendukung TCP. Operasi API yang dapat dilakukan mengonfigurasi koneksi MQTT, membentuk koneksi, menutup koneksi, berlangganan pesan, dan mempublikasikan pesan harus disediakan.

Tabel berikut menjelaskan perintah AT yang direkomendasikan. Penyedia modul dapat menggabungkan beberapa perintah AT menjadi satu perintah AT atau membagi satu perintah AT menjadi beberapa perintah AT. Penyedia modul dapat mendefinisikan format kustom untuk perintah AT.

Saat MCU menjalankan perintah AT untuk mengirim informasi identitas perangkat ke modul, kami sarankan Anda menentukan informasi sebagai nilai variabel global. Dengan cara ini, HAL_GetProductKey, HAL_GetDeviceName, dan HAL_GetDeviceSecret dapat mengembalikan variabel global dan Anda tidak perlu memodifikasi kode contoh.