:MQTT をサポートするモジュールへの SDK の統合

シナリオの説明

Link SDK は、デバイスを Alibaba Cloud IoT Platform に接続するためのデバイス側ソフトウェア開発キット (SDK) です。デバイス認証やデータ通信などの機能を処理します。Link SDK を通信モジュールに統合すると、次のメリットがあります。

• デバイスメーカーは、マイクロコントローラーユニット (MCU) 上で接続を管理する代わりに、モジュールが提供する AT コマンドを呼び出して Alibaba Cloud IoT Platform に接続できます。この方法により、MCU のリソース消費の増加を回避できます。

• Alibaba Cloud は、認定パートナーページで、認定済みモジュールのモデル、購入リンク、開発ガイドを掲載しています。これにより、デバイスメーカーとサービスプロバイダー (SP) は、認定済みの通信モジュールを購入して Alibaba Cloud IoT Platform に接続できます。

次の図は、SDK を統合したモジュールを使用してデバイスを開発する方法を示しています。

デバイスメーカーの開発フローは次のとおりです。

• Alibaba Cloud Link SDK が統合されたモジュールを購入します。

• MCU 上でモジュールが提供する AT コマンドを使用して Alibaba Cloud に接続し、Alibaba Cloud IoT Platform とデータを送受信します。

• Alibaba Cloud IoT Platform にクラウドサービスをデプロイして、デバイスを管理します。

モジュールメーカーは、モジュール上で次のタスクを完了する必要があります。

• Link SDK をモジュールに正しく統合します。

• MCU が呼び出して Alibaba Cloud IoT Platform に接続できる AT コマンドを提供します。

ドキュメントの目的

このトピックでは、Message Queuing Telemetry Transport (MQTT) プロトコルをすでにサポートしているモジュールに Link SDK を統合する方法について説明します。これにより、モジュールメーカーは SDK 統合の一般的なプロセスを理解できます。プロセスを簡素化するため、このトピックでは Link SDK のデバイス署名モジュールの統合方法のみを説明します。これにより、モジュールを Alibaba Cloud IoT Platform に接続できるようになります。

モジュールはすでに MQTT プロトコルをサポートしているため、SDK はモジュール上の既存の MQTT 機能モジュールを使用します。Link SDK は、Alibaba Cloud IoT Platform の MQTT ブローカーに接続するために必要な ClientID、UserName、Password などの情報を生成する API を提供します。モジュールメーカーはそのデータを使用して Alibaba Cloud IoT Platform ブローカーへの接続を確立します。これにより、モジュールは MQTT トピックをサブスクライブしたり、指定したトピックにデータを送信したりできます。

Alibaba Cloud IoT Platform での Basic Edition プロダクトの作成

モジュールをデバッグする際、テスト用のプロダクトとテスト用のデバイスを作成して、SDK が正しく動作することを確認できます。デバイスを作成するには、次の手順を実行します。

1. Alibaba Cloud IoT Platform コンソールにログインします。Alibaba Cloud アカウントを登録する必要があります。登録は無料です。

2. テストデバイスを作成します。デバイスページでデバイスの device_name と device_secret を取得できます。

次のセクションでは、モジュールに SDK を統合する開発プロセスについて説明します。

SDK 統合の開発プロセス

SDK を統合する際は、次の開発プロセスに従ってください。

SDK の設定とコード抽出

SDK には多数の機能が含まれています。SDK による RAM とフラッシュメモリの過剰な消費を防ぐため、設定ツールと抽出ツールを提供しています。これらのツールを使用すると、必要なコンポーネントのみを利用できます。

make menuconfig
            

config.bat
            

sh ./extract.sh
            

extract.bat
            

プロジェクトへの SDK ファイルの追加

output ディレクトリの eng フォルダーをプロジェクトディレクトリにコピーします。その後、コードファイルをプロジェクトに追加します。

追加するファイルは、eng/dev_sign、eng/infra、eng/wrappers ディレクトリにあります。コンパイル時には、これらのディレクトリをヘッダーファイル検索パスにも指定する必要があります。

HAL の実装

なし

既存の MQTT との Link SDK の統合

MQTT ClientID、UserName、Password の生成

MQTT クライアントが MQTT ブローカーに接続する際は、ClientID、UserName、Password などの情報を指定する必要があります。Link SDK は、これらのデータを生成する IOT_Sign_MQTT() API を提供します。

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

注意：この関数を使用するには、dev_sign_internal.h ヘッダーファイルをインクルードする必要があります。

#include "dev_sign_internal.h"
            

入力パラメータの説明

• region

接続先の Alibaba Cloud IoT Platform サイトを指定します。使用可能な値は eng/infra/infra_defs.h ファイルで定義されています。

typedef enum {
    IOTX_CLOUD_REGION_SHANGHAI,   /* 上海 */
    IOTX_CLOUD_REGION_SINGAPORE,  /* シンガポール */
    IOTX_CLOUD_REGION_JAPAN,      /* 日本 */
    IOTX_CLOUD_REGION_USA_WEST,   /* 米国 */
    IOTX_CLOUD_REGION_GERMANY,    /* ドイツ */
    IOTX_CLOUD_REGION_CUSTOM,     /* カスタム設定 */
    IOTX_CLOUD_DOMAIN_MAX         /* ドメインの最大数 */
} iotx_mqtt_region_types_t;
            

• モジュールが中国で販売される場合、このパラメータを IOTX_CLOUD_REGION_SHANGHAI に設定します。

• meta

デバイス認証情報を指定します。データ構造は次のとおりです。

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;
            

デバイスメーカーは、Alibaba Cloud IoT Platform でプロダクトを定義した後、デバイスごとにこれら4つの変数を要求します。実際のプロダクト開発では、これらのパラメータを AT コマンドを介して MCU からモジュールに渡す必要があります。

出力パラメータの説明

• signout

このパラメータは、MQTT ブローカーに接続するために必要な ClientID、Username、Password などの情報を出力します。データ構造は次のとおりです。

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;
            

この構造体では、hostname は Alibaba Cloud IoT Platform サイトにおける MQTT ブローカーのドメイン名であり、port は MQTT ブローカーのポート番号です。

戻り値の説明

関数は、成功時に 0、失敗時に -1 を返します。

使用例

eng/examples/dev_sign_example.c ファイルは、IOT_Sign_MQTT() 関数の使用方法を示しています。次のスニペットは例です。

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

/* このHALを実装するか、サンプルで何かを出力したい場合は、お使いのシステムの "printf" を使用してください。 */
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;
    }
    ...
}

            

この例では、デバイスの product_key、product_secret、device_name、device_secret に固定値を使用しています。実際のプロダクトの実行時には、MCU がこれらの値をモジュールに提供する必要があります。

モジュールをデバッグする際は、Alibaba Cloud IoT Platform でプロダクトとテストデバイスを作成する必要があります。その後、プラットフォームがデバイス向けに生成する product_key、product_secret、device_name、device_secret を使用します。

モジュールプロバイダーコードとモジュールモデルのアップロード

モジュールを Alibaba Cloud IoT の認証に提出する場合は、モジュールプロバイダーコードとモジュールモデルを報告する必要があります。これにより、Alibaba Cloud IoT Platform は、特定のモジュールプロバイダーおよびモジュールモデルを使用してプラットフォームに接続するデバイス数を追跡できるようになります。

SDK を統合する前に、Alibaba Cloud に連絡してモジュールプロバイダーコードとモジュールモデルを取得してください。件名を 'Module/Chip Model Application' として、linkcertification@list.alibaba-inc.com 宛てにメールを送信してください。注意：モジュールプロバイダーでない場合、コードを申請する必要はありません。

モジュールが Alibaba Cloud IoT Platform への接続を確立した後、次の関数をコピーして呼び出し、情報を報告してください。pid パラメータはモジュールプロバイダーコードで、mid パラメータはモデルコードです。

#define PID_STRING_LEN_MAX          32  /* PID文字列の最大長 */
#define MID_STRING_LEN_MAX          32  /* MID文字列の最大長 */


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

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

    /* MQTTペイロードの文字列を組み立てます。ペイロードにはPIDと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);

    /* MQTT発行APIを使用して、PIDとMIDを含むメッセージを送信します。
       モジュールに組み込まれているMQTT機能を使用しているため、統合時には、次の発行関数を実際の発行関数に置き換えてください。*/
    res = IOT_MQTT_Publish(pclient, topic, &topic_msg);
    if (res < 0) {
        return -1;
    }

    return 0;
}

            

デバッグ

        // 署名関数を呼び出して、MQTTのusername、password、clientIDなどの情報を取得します。
        IOT_Sign_MQTT(region,&meta,&sign_mqtt);

        mosquitto_lib_init();

        // 以下のコードは、MQTTのclientIDとcleansessionパラメータを設定します。
        mosq = mosquitto_new(sign_mqtt.clientid, 0 /*セッションをクリーンアップしない*/, NULL);
        if(mosq==NULL){
                printf("Error:Failed creating mosquitto client\n\r");
                return(-1);
        }
        // 以下のコードは、MQTT接続のusernameとpasswordを設定します。
        if(0 != mosquitto_username_pw_set(mosq, sign_mqtt.username, sign_mqtt.password)){
                printf("Error:Failed setting username or password\n\r");
                return(-1);
        }

        ...
        // 以下のコードは、MQTTブローカーへの接続を確立します。ドメイン名とポートを使用します。
        if(mosquitto_connect(mosq, sign_mqtt.hostname, sign_mqtt.port, kaInterval)){
                printf("Error: Failed connecting cloud.\n\r");
                sleep(1);
                return -1;
        }
            

    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);
    // ここでトピックを生成します。
    HAL_Snprintf(topic, topic_len, fmt, product_key, device_name);

    // 以下のコードはメッセージを生成します。
    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);

    // 以下のコードは、指定されたトピックにメッセージを送信します。
    // 以下の送信関数を、お使いのモジュールのMQTT Publish関数に置き換えてください。
    res = IOT_MQTT_Publish(handle, topic, &topic_msg);
            

    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;
    }
    // 以下のコードはトピックを組み立てます。
    memset(topic, 0, topic_len);
    snprintf(topic, topic_len, fmt, product_key, device_name);

    /* 以下のコードはトピックをサブスクライブし、メッセージハンドラー関数を指定します。
      以下のコードを、お使いのモジュールの実際のMQTTサブスクライブ関数に置き換えてください。*/
    res = IOT_MQTT_Subscribe(handle, topic, IOTX_MQTT_QOS0, example_message_arrive, NULL);