在支持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官方文档页面。

另外，在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：

对以上函数若需了解更多细节, 可直接访问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程序不用进行修改。