：在支援TCP的廣域網路模組上整合SDK

在阿里雲物聯網平台上的操作

為了驗證模組上整合的SDK是否運行正確，需要將一個測試裝置串連到阿里雲物聯網平台。使用者需要在阿里雲物聯網平台上建立一個產品，並建立一個該產品的裝置執行個體以擷取到裝置的身份資訊。

1. 點擊阿里雲物聯網平台登入控制台，模組商需要註冊一個阿里雲帳號，註冊阿里雲帳號是免費的。
2. 登入阿里雲物聯網平台的控制台之後，按照建立產品描述的步驟建立一個產品。在產品頁面可以擷取到產品的ProductKey和ProductSecret。
3. 建立一個測試裝置，在裝置頁面可以擷取裝置的DeviceName和DeviceSecret。

整合SDK的開發過程

模組商在模組上整合SDK時，需要進行下面幾個開發過程。

SDK配置與代碼抽取

配置SDK

SDK包含的功能較多，下面講解如何配置本情境中需要的功能。

回合組態命令

• Linux系統

  進入SDK的根目錄下，運行命令

  make menuconfig
              

• Windows系統

  運行SDK根目錄下的config.bat

  config.bat

上面的兩種方式都會啟動SDK的組態工具，介面如下所示：

使能需要的SDK功能

在功能配置介面，按下空格鍵可以選中或者失效某個功能，使用小鍵盤的上下鍵來在不同功能之間切換；如果想知道每個選項的具體含義，先用方向鍵將高亮光條移到那個選項上，再按鍵盤上的“h”按鍵，將出現協助文本，說明選項是什麼含義，以及開啟了和關閉了意味著什麼。

• 如果編譯環境有內建標準標頭檔<stdint.h>，請使能選項：

  PLATFORM_HAS_STDINT

• 如果目標系統上運行有嵌入式作業系統，請使能選項：

  PLATFORM_HAS_OS

• 由於模組支援TCP但是不支援MQTT，因此必須使能下面三項配置：
  • FEATURE_MQTT_COMM_ENABLED，使用阿里SDK提供的MQTT API與雲端通訊。
  • FEATURE_MQTT_DEFAULT_IMPL，使用阿里SDK中內建的MQTT Client實現，使用者需要實現相關的TCP串連的建立、串連、資料收發過程。
  • FEATURE_MQTT_DIRECT，裝置端指定阿里雲物聯網雲端網站。

建議使能FEATURE_SUPPORT_TLS，讓資料與物聯網平台之間的資料通訊是加密的。本文檔中為了降低適配工作量，未使能該選項。

其它功能均無需使能。

抽取選中功能的原始碼

運行SDK根目錄下的extract.sh（windows下運行extract.bat），客戶選中的功能所對應的代碼將會被放置到檔案夾output。

將SDK代碼檔案加入客戶編譯環境

客戶將上一個步驟中得到的Link SDK的代碼檔案從output目錄複寫到自己的工程目錄中，並修改自己的編譯環境或者開發工具將這些代碼檔案整合到編譯環境。

客戶需要整合的檔案包括eng目錄下面的dev_sign、infra、mqtt、wrappers目錄下的代碼檔案。

實現HAL對接函數

Link SDK被設計為可以在不同的作業系統上運行，或者甚至在不支援作業系統的MCU上運行，因此與系統相關的操作被定義成一些HAL函數，需要客戶進行實現；另外，由於不同的通訊模組上的OS不同，所以與通訊模組上TCP相關的操作也被定義成HAL函數需要客戶進行實現。

所有HAL函數位於檔案為output/eng/wrappers/wrapper.c中。

系統相關HAL

必須實現函數：

另外，在SDK加壓後的目錄（非代碼抽取目錄）wrappers/os下有HAL的參考實現，使用者可以查看是否有自己需要的OS參考實現，若未提供則使用者需要自己進行實現。

可選實現函數

如果模組沒有運行OS，或者SDK的MQTT API並沒有在多個線程中被調用，以下函數可以不用修改wrapper.c中相關的函數實現；在有OS情境下並且MQTT API被APP在多個線程中調用，則需要使用者對接以下函數：

TCP相關HAL

MQTT基於TCP進行通訊，模組商需要實現下面四個TCP HAL函數。

產品相關HAL

下面的HAL用於擷取產品的身份認證資訊，裝置廠商需要設計如何在裝置上燒寫裝置身份資訊，並通過下面的HAL函數將其讀出後提供給SDK：

註：這幾個參數在實際產品開發時應該由裝置廠商通過AT指令告知模組，模組商調試時可以將自己建立的測試裝置的ProductKey、DeviceName、DeviceSecret直接通過上面這幾個函數返回。

參照example實現產品功能

模組商可參考output檔案夾中的 eng/examples/mqtt_example.c進行功能調試， 裝置廠商可以將該檔案複製到產品工程中，對其進行修改後使用。

該example將串連裝置到阿里雲，訂閱一個指定的topic並發送資料給該topic，即裝置上報的訊息會被物聯網平台發送給裝置，下面是example的大概過程說明：

注意：需要在雲端將該topic從預設的許可權從”訂閱”修改為”發布和訂閱”，如下圖所示：

從程式入口的 main() 函數看起, 首先是調用模組提供的HAL函數擷取產品的身份資訊：

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");
            

註：

• 上面的三個HAL_GetXXX函數是擷取裝置的認證資訊，模組商可以在相應的HAL函數中填入測試裝置的認證資訊即可。

接下來對MQTT串連參數進行指定，客戶可以根據自己的需要對參數進行修改：

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

通過調用介面 IOT_MQTT_Construct() 觸發SDK串連雲平台, 若介面傳回值非NULL, 則連雲成功之後調用example_subscribe對一個指定的topic進行資料訂閱：

res = example_subscribe(pclient);
            

example_subscribe的函數內容如下：

註：

• 裝置商需要根據自己的產品設計，訂閱自己希望訂閱的TOPIC，以及註冊相應的處理函數。
• 上面例子程式中第一個橙色圈選的代碼是指定topic的格式：/$ProductKey/$DeviceName，這個topic是在物聯網平台建立一個產品時預設產生的。
• 第二個橙色圈選的代碼是產生topic的內容。
• 上圖的第三個框展示了如何訂閱一個指定的topic以及當通過該topic接收到資料時的處理函數。

以下段落示範MQTT的發布功能，即將業務報文上報到雲平台：

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

        IOT_MQTT_Yield(pclient, 200);

        loop_cnt += 1;
    }
            

註：

• 上面的代碼是周期性的將固定的訊息發送給雲端，裝置商需要根據自己的產品功能，在必要的時候才上傳資料給物聯網平台。
• 客戶可以刪除main函數中example_publish(pclient)語句，避免周期發送無效資料給到雲端。
• IOT_MQTT_Yield是讓SDK去接收來自MQTT Broker的資料，其中200毫秒是等待時間，如果使用者的訊息數量比較大、或者即時性要求較高，可以將時間改小。

下面是example_publish函數體的內容：

上面圖中第一個框是發送的訊息的內容，第二個框是調用SDK提給的API將訊息發送給指定的topic。

上傳模組商編碼和模組型號

如果模組商希望將模組送到阿里雲IoT進行模組認證，那麼模組商需要將模組商編碼和模組型號進行上報，這樣阿里雲物聯網平台可以統計通過指定模組商串連到平台的裝置數量，也可以統計通過模組商的某個型號模組串連裝置的數量。

模組商編碼和模組型號請在整合SDK前聯絡阿里進行擷取，請按如下模板發送訊息，聯絡我們。

主題：裝置接入Link SDK產品-模組/晶片型號申請

當模組與阿里雲物聯網平台建立串連之後，請複製並調用下面的函數進行資訊上報，其中參數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 topic字串 */
    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 payload字串, payload中包含了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 publish API發送PID，MID資訊報文 */
    res = IOT_MQTT_Publish(pclient, topic, &topic_msg);
    if (res < 0) {
        return -1;
    }

    return 0;
}

            

功能調試

下面的資訊截圖以mqtt_example.c為例編寫。

如何判斷裝置已串連到阿里雲

注意：/${productKey}/${deviceName}/get這個topic預設只有“訂閱”許可權，請在物聯網平台的控制台將其修改為“發布和訂閱”，避免訊息發送到雲端後被雲端丟棄； 把該topic修改為“發布和訂閱”，主要是為了讓example程式運行不出錯。

下面的列印是HAL_Printf函數將資訊列印到串口後運行example的輸出內容，其中使用橙色圈選的資訊表明裝置已成功串連到阿里雲物聯網平台：

如何判斷裝置已成功發送資料到雲端

登入阿里網物聯網平台的商家後台，選中指定的裝置，可以查看是否收到來自裝置的訊息，如下圖所示：

註：上圖中的內容只能看見訊息發送到了哪個topic，訊息的內容並不會顯示出來。

如何判斷裝置已可成功接收來自雲端資料

在商家背景“下行訊息分析”分析中可以看見由物聯網平台發送給裝置的訊息：

也可在裝置端查看是否已收到來自雲端的資料，exmaple代碼中收到雲端發送的資料的列印資訊如下所示：

AT指令實現

如果模組不提供開發環境給使用者進行二次開發，而是外接一個MCU並且產品的商務邏輯運行在MCU上，那麼模組商還需要提供AT指令給MCU調用，由於模組以前只支援TCP，所以需要提供MQTT串連配置、發起串連、中斷連線、訂閱、Publish等介面。

下面是推薦增加的AT指令（模組商也可以合并這些指令或者拆分指令），格式由模組商自行定義：

註：當MCU通過AT指令將裝置身份資訊傳遞到模組時，建議將裝置身份資訊儲存到全域變數中，並在HAL_GetProductKey、HAL_GetDeviceName、HAL_GetDeviceSecret等幾個HAL函數中將其進行返回，這樣example程式不用進行修改。