Integrasi Link SDK ke dalam modul berbasis MQTT -

Bagian ini menjelaskan cara mengintegrasikan IoT Platform Link SDK ke dalam modul berbasis Message Queuing Telemetry Transport (MQTT) dan menyelesaikan konfigurasi terkait. Kode contoh ditulis berdasarkan Link SDK v3.0.1.

Skenario

Link SDK dari IoT Platform digunakan untuk menghubungkan perangkat ke IoT Platform, memverifikasi perangkat, dan mengaktifkan komunikasi data. Dengan mengintegrasikan Link SDK ke dalam modul komunikasi, Anda dapat memperoleh manfaat berikut:

Produsen perangkat dapat menjalankan perintah AT dari modul pada perangkat untuk menghubungkan perangkat ke IoT Platform tanpa harus fokus pada bagaimana unit mikrokontroler (MCU) membentuk koneksi ke IoT Platform. Beban kerja MCU tetap tidak berubah.
Halaman Jaringan Mitra Alibaba Cloud menampilkan model modul bersertifikat, tautan pembelian, dan panduan pengembangan. Jika Anda adalah produsen perangkat atau penyedia layanan, Anda dapat menggunakan modul komunikasi bersertifikat untuk menghubungkan perangkat Anda ke IoT Platform.

Gambar berikut menunjukkan proses menghubungkan perangkat yang berisi modul komunikasi dengan Link SDK terintegrasi ke IoT Platform.

Berikut ini menjelaskan proses mengonfigurasi perangkat sebagai produsen perangkat.

Beli modul komunikasi dengan Link SDK terintegrasi.
Jalankan perintah AT pada MCU untuk menghubungkan perangkat ke IoT Platform, serta kirim dan terima data dari IoT Platform.
Terapkan layanan cloud di IoT Platform untuk mengelola perangkat.

Penyedia modul harus melakukan langkah-langkah berikut pada modul:

Integrasikan Link SDK ke dalam modul sesuai harapan.
Sediakan perintah AT yang dapat dijalankan oleh MCU untuk menghubungkan perangkat ke IoT Platform.

Catatan Penggunaan

Bagian ini menjelaskan cara mengintegrasikan Link SDK ke dalam modul berbasis MQTT. Ini membantu penyedia modul memahami proses integrasi Link SDK. Untuk mengurangi kompleksitas, bagian berikut menjelaskan cara mengintegrasikan modul tanda tangan perangkat dari Link SDK ke dalam modul perangkat. Dengan cara ini, Anda dapat menggunakan modul untuk menghubungkan perangkat ke IoT Platform.

Jika Anda adalah penyedia modul, kami sarankan Anda mengintegrasikan lebih banyak fitur dari Link SDK, seperti fitur terkait Thing Specification Language (TSL), fitur terkait over-the-air (OTA), dan fitur terkait bayangan perangkat. Dengan cara ini, produsen perangkat dapat menggunakan lebih banyak fitur saat perangkat terhubung ke IoT Platform.

Jika Anda menggunakan modul berbasis MQTT, Anda dapat memanggil operasi API dari Link SDK yang terintegrasi ke dalam modul untuk menghasilkan ID klien, nama pengguna, dan kata sandi yang diperlukan untuk terhubung ke broker MQTT IoT Platform berdasarkan modul fungsi MQTT dari modul tersebut. Kemudian, penyedia modul dapat menggunakan data tersebut untuk membentuk koneksi ke broker MQTT IoT Platform, berlangganan topik MQTT, dan mengirim data ke topik tersebut.

Buat produk Edisi Dasar di IoT Platform

Saat penyedia modul men-debug kode contoh, penyedia modul harus membuat produk uji dan perangkat uji untuk memeriksa apakah Link SDK bekerja sesuai harapan. Untuk membuat perangkat, lakukan langkah-langkah berikut:

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.
Buat perangkat uji. Di halaman detail perangkat, Anda bisa mendapatkan DeviceName dan DeviceSecret dari perangkat.

Berikut ini menjelaskan proses integrasi Link SDK.

Proses Integrasi Link SDK

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

Konfigurasikan Link SDK dan ekstrak kode

Link SDK menyediakan sejumlah besar fitur. Untuk mencegah RAM dan memori flash berlebih dikonsumsi oleh Link SDK, Anda dapat menggunakan alat yang disediakan oleh Link SDK untuk mengonfigurasi dan mengekstrak hanya modul fungsi yang diperlukan.

Konfigurasikan Link SDK

Berikut ini menjelaskan cara mengonfigurasi fitur yang diperlukan sebagai penyedia modul.

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 file config.bat:

config.bat

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

Jika tanda asterisk (*) muncul sebelum opsi, fitur terkait diaktifkan. Jika tidak, fitur dinonaktifkan.
Alat menampilkan fitur yang dapat Anda konfigurasikan. Jika tidak ada opsi yang dipilih, fitur yang tidak dapat Anda konfigurasikan di Link SDK tetap berlaku.
Di GUI, tekan tombol Spasi untuk memilih atau menghapus opsi 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 mengaktifkan atau menonaktifkan opsi akan ditampilkan.

Anda dapat memilih opsi berikut berdasarkan skenario bisnis Anda:

Jika lingkungan pengembangan mendukung stdint.h, pilih PLATFORM_HAS_STDINT.
Jika lingkungan pengembangan mendukung malloc/free, pilih PLATFORM_HAS_DYNMEM.
Jika sistem operasi berjalan di lingkungan Anda, pilih PLATFORM_HAS_OS.

Jangan pilih opsi lain. Setelah Anda menyelesaikan konfigurasi, pindahkan kursor ke Exit dan tekan tombol Enter untuk keluar dari alat, lalu simpan konfigurasi sesuai petunjuk.

Ekstrak kode Link SDK

Berikut ini menjelaskan cara mengekstrak kode Link SDK.

Jalankan perintah ekstraksi

Linux

Pergi ke direktori root Link SDK dan jalankan perintah berikut:

sh ./extract.sh

Windows

Pergi ke direktori root Link SDK dan jalankan file extract.bat:

extract.bat

Gunakan salah satu metode di atas untuk memulai alat ekstraksi kode Link SDK. Alat ini membantu Anda mengekstrak file kode yang diperlukan dan menyalin file ke direktori output, seperti yang ditunjukkan pada gambar berikut.

Impor file Link SDK ke proyek Anda

Anda dapat menyalin direktori eng di direktori output ke direktori proyek Anda, lalu mengimpor file kode ke proyek Anda.

File kode disimpan di direktori eng/dev_sign, eng/infra, dan eng/wrappers. Saat Anda mengompilasi proyek, Anda harus menentukan jalur di atas dalam file header.

Implementasikan fungsi lapisan abstraksi perangkat keras (HAL)

Tidak ada.

Integrasikan Link SDK dengan modul fungsi MQTT yang ada

Hasilkan ID klien MQTT, nama pengguna, dan kata sandi.

Saat Anda menghubungkan klien MQTT ke broker MQTT, Anda harus menentukan ID klien, nama pengguna, dan kata sandi. Anda dapat memanggil fungsi IOT_Sign_MQTT() dari Link SDK untuk menghasilkan informasi tersebut.

int32_t IOT_Sign_MQTT(iotx_mqtt_region_types_t region, iotx_dev_meta_info_t *meta, iotx_sign_mqtt_t *signout)

Jika Anda ingin menggunakan fungsi tersebut, Anda harus menentukan file header dev_sign_internal.h dalam kode contoh.

#include "dev_sign_internal.h"

Parameter Input

region

Titik akhir IoT Platform yang ingin Anda hubungkan. Nilai valid parameter tersebut didefinisikan dalam file eng/infra/infra_defs.h.

typedef enum {
    IOTX_CLOUD_REGION_SHANGHAI,   /* Shanghai */
    IOTX_CLOUD_REGION_SINGAPORE,  /* Singapore */
    IOTX_CLOUD_REGION_JAPAN,      /* Japan */
    IOTX_CLOUD_REGION_USA_WEST,   /* America */
    IOTX_CLOUD_REGION_GERMANY,    /* Germany */
    IOTX_CLOUD_REGION_CUSTOM,     /* Custom setting */
    IOTX_CLOUD_DOMAIN_MAX         /* Maximum number of domain */
} iotx_mqtt_region_types_t;

Jika modul tersedia untuk dibeli di daratan Tiongkok, atur parameter tersebut ke IOTX_CLOUD_REGION_SHANGHAI.
meta

Informasi identitas tentang perangkat. Kode berikut menunjukkan struktur data parameter tersebut:

typedef struct {
    char product_key[IOTX_PRODUCT_KEY_LEN + 1];
    char product_secret[IOTX_PRODUCT_SECRET_LEN + 1];
    char device_name[IOTX_DEVICE_NAME_LEN + 1];
    char device_secret[IOTX_DEVICE_SECRET_LEN + 1];
} iotx_dev_meta_info_t;

Setelah produk dibuat di konsol IoT Platform, nilai variabel di atas diminta oleh produsen perangkat untuk setiap perangkat. Dalam skenario pengembangan produk aktual, MCU mentransmisikan nilai variabel ke modul dengan menjalankan perintah AT.

Parameter Output

signout

Parameter tersebut berisi ID klien, nama pengguna, dan kata sandi yang diperlukan saat Anda menghubungkan klien ke broker MQTT. Kode berikut menunjukkan struktur data parameter tersebut:

typedef struct {
    char hostname[DEV_SIGN_HOSTNAME_MAXLEN];
    uint16_t port;
    char clientid[DEV_SIGN_CLIENT_ID_MAXLEN];
    char username[DEV_SIGN_USERNAME_MAXLEN];
    char password[DEV_SIGN_PASSWORD_MAXLEN];
} iotx_sign_mqtt_t;

Variabel hostname menentukan titik akhir broker MQTT Alibaba Cloud. Variabel port menentukan nomor port broker MQTT Alibaba Cloud.

Nilai Pengembalian

Jika pemanggilan berhasil, fungsi mengembalikan 0. Jika pemanggilan gagal, fungsi mengembalikan -1.

Contoh

Kode berikut dalam file eng\examples\dev_sign_example.c menunjukkan cara memanggil fungsi IOT_Sign_MQTT():

#define EXAMPLE_PRODUCT_KEY     "a1X2bEnP82z"
#define EXAMPLE_PRODUCT_SECRET  "7jluWm1zql7bt8qK"
#define EXAMPLE_DEVICE_NAME     "example1"
#define EXAMPLE_DEVICE_SECRET   "ga7XA6KdlEeiPXQPpRbAjOZXwG8ydgSe"

/* Implementasikan HAL ini atau gunakan "printf" sistem Anda sendiri jika Anda ingin mencetak sesuatu dalam contoh*/
void HAL_Printf(const char *fmt, ...);

int main(int argc, char *argv[])
{
    iotx_mqtt_region_types_t region = IOTX_CLOUD_REGION_SHANGHAI;
    iotx_dev_meta_info_t meta;
    iotx_sign_mqtt_t sign_mqtt;

    memset(&meta,0,sizeof(iotx_dev_meta_info_t));
    memcpy(meta.product_key,EXAMPLE_PRODUCT_KEY,strlen(EXAMPLE_PRODUCT_KEY));
    memcpy(meta.product_secret,EXAMPLE_PRODUCT_SECRET,strlen(EXAMPLE_PRODUCT_SECRET));
    memcpy(meta.device_name,EXAMPLE_DEVICE_NAME,strlen(EXAMPLE_DEVICE_NAME));
    memcpy(meta.device_secret,EXAMPLE_DEVICE_SECRET,strlen(EXAMPLE_DEVICE_SECRET));

    if (IOT_Sign_MQTT(region,&meta,&sign_mqtt) < 0) {
        return -1;
    }
    ...
}

Dalam contoh ini, nilai spesifik ditentukan untuk parameter product_key, product_secret, device_name, dan device_secret. Dalam skenario aktual, nilai-nilai tersebut harus ditransmisikan oleh MCU ke modul.

Saat penyedia modul men-debug Link SDK, penyedia modul harus membuat produk uji dan perangkat uji di konsol IoT Platform dan mendapatkan nilai parameter product_key, product_secret, device_name, dan device_secret. Nilai-nilai tersebut dihasilkan oleh IoT Platform untuk perangkat.

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 mengirim email dengan subjek "Aplikasi model modul atau chip" ke linkcertification@list.alibaba-inc.com. Jika Anda bukan penyedia modul, Anda tidak perlu mengajukan ID penyedia modul.

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;
    }

    /* Gabungkan 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));

    /* Gabungkan string untuk membuat payload topik MQTT. Payload tersebut 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 fungsi MQTT IOT_MQTT_Publish untuk mengirim pesan yang mencakup nilai parameter pid dan mid.
       Modifikasi fungsi MQTT IOT_MQTT_Publish berdasarkan skenario bisnis Anda.*/
    res = IOT_MQTT_Publish(pclient, topic, &topic_msg);
    if (res < 0) {
        return -1;
    }

    return 0;
}

Debugging

Hubungkan modul ke IoT Platform

Penyedia modul harus menulis kode yang dapat digunakan untuk menghubungkan modul ke IoT Platform. Modul fungsi MQTT dari modul menyediakan fungsi yang digunakan untuk terhubung ke broker MQTT. Tentukan titik akhir, nomor port, ID klien, nama pengguna, dan kata sandi yang dikembalikan setelah Anda memanggil fungsi IOT_Sign_MQTT() dari Link SDK untuk fungsi tersebut.

Kode contoh berikut mengintegrasikan Link SDK dan pustaka MQTT sumber terbuka bernama mosquitto.

        // Panggil fungsi IOT_Sign_MQTT() untuk mendapatkan nama pengguna, kata sandi, dan ID klien.
        IOT_Sign_MQTT(region,&meta,&sign_mqtt);

        mosquitto_lib_init();

        // Tentukan ID klien dan konfigurasikan parameter cleansession.
        mosq = mosquitto_new(sign_mqtt.clientid,0/*dont clean session*/,NULL);
        if(mosq==NULL){
                printf("Error:Failed creating mosquitto client\n\r");
                return(-1);
        }
        // Tentukan nama pengguna dan kata sandi yang diperlukan untuk terhubung ke broker MQTT.
        if(0 != mosquitto_username_pw_set(mosq, sign_mqtt.username, sign_mqtt.password)){
                printf("Error:Failed setting username or password\n\r");
                return(-1);
        }

        ...
        // Tentukan titik akhir dan nomor port untuk membentuk koneksi ke broker MQTT.
        if(mosquitto_connect(mosq, sign_mqtt.hostname, sign_mqtt.port, kaInterval)){
                printf("Error: Failed connecting cloud.\n\r");
                sleep(1);
                return -1;
        }

Saat Anda membentuk koneksi MQTT, Anda harus menentukan interval keepalive. Kami sarankan Anda menentukan interval 60 detik. Penyedia modul dapat mengimplementasikan perintah AT yang dapat dipanggil oleh MCU untuk menentukan interval. IoT Platform mendukung interval keepalive mulai dari 30 hingga 1.200 detik.

Jika koneksi MQTT tidak ditutup antara modul dan IoT Platform setelah modul terhubung ke IoT Platform, modul tetap dalam status Online. Anda dapat menemukan perangkat uji dan melihat status perangkat di IoT Platform. Gambar berikut menunjukkan perangkat yang berada dalam status Online.

Periksa apakah perangkat dapat mengirim data ke IoT Platform sesuai harapan

Setelah modul terhubung ke IoT Platform, perangkat dapat mengirim pesan ke topik /${productKey}/${deviceName}/get untuk memeriksa apakah data dapat dikirim ke IoT Platform sesuai harapan.

Secara default, perangkat memiliki 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.

Kode contoh:

    int res = 0;
    iotx_mqtt_topic_info_t topic_msg;
    const char *fmt = "/%s/%s/get";
    char *topic = NULL;
    int topic_len = 0;
    char *payload = "hello,world";

    topic_len = strlen(fmt) + strlen(product_key) + strlen(device_name) + 1;
    topic = HAL_Malloc(topic_len);
    if (topic == NULL) {
        HAL_Printf("memory not enough\n");
        return -1;
    }
    memset(topic, 0, topic_len);
    // Hasilkan topik.
    HAL_Snprintf(topic, topic_len, fmt, product_key, device_name);

        // Hasilkan pesan.
    memset(&topic_msg, 0x0, sizeof(iotx_mqtt_topic_info_t));
    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);

        // Kirim pesan ke topik. Ganti fungsi berikut dengan fungsi publikasi MQTT yang spesifik untuk modul Anda.
    res = IOT_MQTT_Publish(handle, topic, &topic_msg);

Di konsol IoT Platform, periksa apakah data diterima di tab Log Perangkat perangkat.

Tab tersebut menampilkan waktu ketika pesan diterima dari perangkat dan nama topik dari mana pesan diterima. Kontennya tidak ditampilkan.
IoT Platform tidak mendukung pesan tingkat layanan (QoS) 2.

Periksa apakah perangkat telah berlangganan topik

Penyedia modul dapat berlangganan data topik /{productKey}/${deviceName}/get untuk perangkat. Setelah perangkat mengirimkan data ke IoT Platform, IoT Platform mengirimkan data ke perangkat. Dengan cara ini, penyedia modul dapat memeriksa apakah perangkat telah berlangganan topik. Kode contoh:

    int res = 0;
    const char *fmt = "/%s/%s/get";
    char *topic = NULL;
    int topic_len = 0;

    topic_len = strlen(fmt) + strlen(product_key) + strlen(device_name) + 1;
    topic = HAL_Malloc(topic_len);
    if (topic == NULL) {
        HAL_Printf("memory not enough\n");
        return -1;
    }
    // Buat topik
    memset(topic, 0, topic_len);
    snprintf(topic, topic_len, fmt, product_key, device_name);

    /* Berlangganan topik dan tentukan fungsi untuk memproses pesan.
      Ganti fungsi berikut dengan fungsi berlangganan MQTT yang spesifik untuk modul Anda. */
    res = IOT_MQTT_Subscribe(handle, topic, IOTX_MQTT_QOS0, example_message_arrive, NULL);

Di konsol IoT Platform, penyedia modul dapat memeriksa apakah data telah dikirim ke perangkat.

Tab Log Perangkat menampilkan waktu pengiriman pesan dari IoT Platform ke perangkat, tetapi tidak mencakup konten pesan tersebut.
Penyedia modul harus memverifikasi bahwa data yang diterima sesuai dengan data yang dikirimkan pada modul untuk memastikan penerimaan data sesuai harapan.

Implementasikan perintah AT

Penyedia modul harus menyediakan perintah AT yang dapat dipanggil oleh MCU. Jika menggunakan modul berbasis MQTT, operasi API untuk mengonfigurasi koneksi MQTT, membentuk koneksi, menutup koneksi, berlangganan pesan, dan mempublikasikan pesan harus tersedia. Setelah penyedia modul mengintegrasikan Link SDK, mereka dapat mengimplementasikan lebih banyak perintah AT spesifik untuk Alibaba Cloud atau memodifikasi perintah AT yang sudah ada.

Tabel berikut menjelaskan perintah AT yang direkomendasikan.

Perintah	Deskripsi
Tentukan informasi identitas untuk perangkat	Tentukan ProductKey, ProductSecret, DeviceName, dan DeviceSecret untuk perangkat.
Tentukan titik akhir IoT Platform	IoT Platform tersedia di beberapa wilayah, seperti daratan Tiongkok, AS, dan Jepang. Anda dapat menentukan informasi tentang titik akhir IoT Platform yang ingin Anda hubungkan ke MCU.

Anda dapat tetap menggunakan perintah AT lain yang disediakan oleh penyedia modul.