SDK参考

C SDK

快速接入

环境要求

操作系统：linux

交叉编译工具：gcc-5.40及以上

C SDK目录结构

| - certs（私钥，设备证书和根CA）
| - external_libs（外部库 - jsmn，mbedTLS）
| - include（IoT设备SDK的头文件）
| - src（IoT设备SDK的源文件）
| - platform（平台特定文件）
| - samples（包含用于在mbedTLS上构建的makefile的样本）

C SDK文件夹及其内容的说明

certs：该目录最初是空的，需要包含私钥，客户端证书和根CA.客户端证书和私钥可以从IoT控制台下载。

external_libs：mbedTLS和jsmn源文件。jsmn源文件始终存在。只有在下载SDK的tarball版本时才会包含mbedTLS源文件。

include ：该目录包含使用SDK的应用程序需要包含的头文件。

src ：该目录包含SDK源代码，包括MQTT库，设备影子代码和实用程序。

platform：定时器，TLS和线程层的平台特定文件。包含使用mbedTLS和pthread的Linux的参考实现。

samples：该目录包含示例应用程序以及它们的makefile。这些示例包括发布和订阅IoT服务的简单MQTT示例以及显示设备影子功能示例用法的设备影子示例。

C SDK参数配置

• 设置MQTT地址和端口，修改iot_config.h头文件

#define IOT_PROJECT_HOST "100.100.100.100"

#define IOT_PROJECT_PORT 30001

• 设置证书名称

#define IOT_ROOT_CA_FILENAME "IoTRootCA.crt"

#define IOT_CERTIFICATE_FILENAME "principal-hncnocro.crt"

#define IOT_PRIVATE_KEY_FILENAME "principal-hncnocro.key"

• 设置设备类型：网关：gateway 设备：device

#define IOT_DEVICE_TYPE "device"

• 设置项目ID

#define IOT_PROJECT_CODE "iotsbyjkiau"

• 设置产品ID

#define IOT_PRODUCT_CODE "hncnocro"

• 设置设备名称

#define IOT_DEVICE_CODE "devicetest"

• 设置证书路径，修改shadow_console_echo.c头文件

char certDirectory[PATH_MAX + 1] = "../../../certs";

编译运行

• 编译生成可执行文件shadow_console_echo

cd ./sdk_c/samples/linux/shadow_sample_console_echo
make clean
make

• 运行示例

./shadow_console_echo

C API接口

日志接口

MQTT接口

设备接口

通用接口

C SDK代码详解

设备连接

1. 设备初始化：用于设备初始化相关参数，包括目标IP、端口和证书信息等。

   参数：

   ​ pclient：mqtt client结构体变量指针

   ​ pParams：初始参数结构体变量指针

   返回值：

   ​ IoT_Error_t：枚举类型，返回操作结果

   注：pParams结构体成员变量包括：

   ​ pHost：mqtt地址

   ​ port：mqtt端口号

   ​ pRootCA：根证书

   ​ pClientCRT：crt证书

   ​ pClientKey：key证书

   ​ enableAutoReconnect：自动重连

   ​ disconnectHandler：连接中断回调函数

IoT_Error_t iot_shadow_init(IoT_Client *pClient, ShadowInitParameters_t *pParams) {
    IoT_Client_Init_Params mqttInitParams;
    IoT_Error_t rc;

    FUNC_ENTRY;
    if(NULL == pClient || NULL == pParams) {
        FUNC_EXIT_RC(NULL_VALUE_ERROR);
    }
    mqttInitParams.enableAutoReconnect = pParams->enableAutoReconnect;
    mqttInitParams.pHostURL = pParams->pHost;
    mqttInitParams.port = pParams->port;
    mqttInitParams.pRootCALocation = pParams->pRootCA;
    mqttInitParams.pDeviceCertLocation = pParams->pClientCRT;
    mqttInitParams.pDevicePrivateKeyLocation = pParams->pClientKey;
    mqttInitParams.mqttPacketTimeout_ms = 5000;
    mqttInitParams.mqttCommandTimeout_ms = 20000;
    mqttInitParams.tlsHandshakeTimeout_ms = 5000;
    mqttInitParams.isSSLHostnameVerify = true;
    mqttInitParams.disconnectHandler = pParams->disconnectHandler;
    rc = iot_mqtt_init(pClient, &mqttInitParams);
    if(SUCCESS != rc) {
        FUNC_EXIT_RC(rc);
    }
    resetClientTokenSequenceNum();
    iot_shadow_reset_last_received_version();
    initDeltaTokens();

    FUNC_EXIT_RC(SUCCESS);
}

1. 设备连接：配置client ID，进行mqtt连接。

   参数：

   ​ pclient：mqtt client结构体变量指针

   ​ pParams：连接参数结构体变量指针

   返回值：

   ​ IoT_Error_t：枚举类型，返回操作结果

IoT_Error_t iot_shadow_connect(IoT_Client *pClient, ShadowConnectParameters_t *pParams) {
    IoT_Error_t rc = SUCCESS;
    uint16_t deleteAcceptedTopicLen;
    IoT_Client_Connect_Params ConnectParams = iotClientConnectParamsDefault;

    FUNC_ENTRY;
    if(NULL == pClient || NULL == pParams || NULL == pParams->pMqttClientId) {
        FUNC_EXIT_RC(NULL_VALUE_ERROR);
    }

    snprintf(myThingName, MAX_SIZE_OF_THING_NAME, "%s", pParams->pMyThingName);
    snprintf(mqttClientID, MAX_SIZE_OF_UNIQUE_CLIENT_ID_BYTES, "%s", pParams->pMqttClientId);
    ConnectParams.isWillMsgPresent = false;
    ConnectParams.pClientID = pParams->pMqttClientId;
    ConnectParams.clientIDLen = pParams->mqttClientIdLen;

    rc = iot_mqtt_connect(pClient, &ConnectParams);
    if(SUCCESS != rc) {
        FUNC_EXIT_RC(rc);
    }
    IOT_INFO("iot_mqtt_connect finish");
    initializeRecords(pClient);
    if(NULL != pParams->deleteActionHandler) {
        snprintf(deleteAcceptedTopic, MAX_SHADOW_TOPIC_LENGTH_BYTES, "iot/things/%s/shadow/delete/accepted", myThingName);
        deleteAcceptedTopicLen = (uint16_t) strlen(deleteAcceptedTopic);
        rc = iot_mqtt_subscribe(pClient, deleteAcceptedTopic, deleteAcceptedTopicLen, QOS1,pParams->deleteActionHandler, (void *) myThingName);}

    FUNC_EXIT_RC(rc);
}

发布订阅

1. mqtt订阅主题：用户可自行调用该函数订阅自定义主题。

   参数：

   ​ pclient：mqtt client结构体变量指针

   ​ pTopicName：订阅的主题指针

   ​ topicNameLen：订阅主题长度变量

   ​ pApplicationHandler：回调函数指针

   返回值：

   ​ IoT_Error_t：枚举类型，返回操作结果

IoT_Error_t iot_mqtt_subscribe(IoT_Client *pClient, const char *pTopicName, uint16_t topicNameLen, QoS qos, pApplicationHandler_t pApplicationHandler, void *pApplicationHandlerData) {
    ClientState clientState;
    IoT_Error_t rc, subRc;

    FUNC_ENTRY;

    if(NULL == pClient || NULL == pTopicName || NULL == pApplicationHandler) {
        FUNC_EXIT_RC(NULL_VALUE_ERROR);
    }

    if(!iot_mqtt_is_client_connected(pClient)) {
        FUNC_EXIT_RC(NETWORK_DISCONNECTED_ERROR);
    }

    clientState = iot_mqtt_get_client_state(pClient);
    if(CLIENT_STATE_CONNECTED_IDLE != clientState && CLIENT_STATE_CONNECTED_WAIT_FOR_CB_RETURN != clientState) {
        FUNC_EXIT_RC(MQTT_CLIENT_NOT_IDLE_ERROR);
    }

    rc = iot_mqtt_set_client_state(pClient, clientState, CLIENT_STATE_CONNECTED_SUBSCRIBE_IN_PROGRESS);
    if(SUCCESS != rc) {
        FUNC_EXIT_RC(rc);
    }

    IOT_DEBUG("Sub Topic: %s", pTopicName);
    subRc = _iot_mqtt_internal_subscribe(pClient, pTopicName, topicNameLen, qos, pApplicationHandler, pApplicationHandlerData);

    rc = iot_mqtt_set_client_state(pClient, CLIENT_STATE_CONNECTED_SUBSCRIBE_IN_PROGRESS, clientState);
    if(SUCCESS == subRc && SUCCESS != rc) {
        subRc = rc;
    }

    FUNC_EXIT_RC(subRc);
}

1. mqtt发布主题：用户可自行调用该函数发布自定义主题。

   参数：

   ​ pclient：mqtt client结构体变量指针

   ​ pTopicName：发布主题指针

   ​ topicNameLen：发布主题长度变量

   ​ pParams：发布消息结构体指针

   返回值：

   ​ IoT_Error_t：枚举类型，返回操作结果

IoT_Error_t iot_mqtt_publish(IoT_Client *pClient, const char *pTopicName, uint16_t topicNameLen, IoT_Publish_Message_Params *pParams) {
    IoT_Error_t rc, pubRc;
    ClientState clientState;

    FUNC_ENTRY;

    if(NULL == pClient || NULL == pTopicName || 0 == topicNameLen || NULL == pParams){
        FUNC_EXIT_RC(NULL_VALUE_ERROR);
    }

    if(!iot_mqtt_is_client_connected(pClient)) {
        FUNC_EXIT_RC(NETWORK_DISCONNECTED_ERROR);
    }

    clientState = iot_mqtt_get_client_state(pClient);
    if(CLIENT_STATE_CONNECTED_IDLE != clientState && CLIENT_STATE_CONNECTED_WAIT_FOR_CB_RETURN != clientState) {
        FUNC_EXIT_RC(MQTT_CLIENT_NOT_IDLE_ERROR);
    }

    rc = iot_mqtt_set_client_state(pClient, clientState, CLIENT_STATE_CONNECTED_PUBLISH_IN_PROGRESS);
    if(SUCCESS != rc) {
        FUNC_EXIT_RC(rc);
    }

    pubRc = _iot_mqtt_internal_publish(pClient, pTopicName, topicNameLen, pParams);

    rc = iot_mqtt_set_client_state(pClient, CLIENT_STATE_CONNECTED_PUBLISH_IN_PROGRESS, clientState);
    if(SUCCESS == pubRc && SUCCESS != rc) {
        pubRc = rc;
    }

    FUNC_EXIT_RC(pubRc);
}

拓扑关系

获取拓扑结构：由网关发起，用于获取该网关下绑定的子设备列表。

参数：

​ pclient：mqtt client结构体变量指针

​ callback：回调函数指针

返回值：

​ IoT_Error_t：枚举类型，返回操作结果

IoT_Error_t iot_shadow_topoGet(IoT_Client *pClient, void *callback){
    IoT_Error_t rc = SUCCESS;

    rc = iot_shadow_subscribe_topoReply(pClient, callback);

    if (strcmp(IOT_DEVICE_TYPE, IOT_TYPE_GATEWAY) == 0){    //网关
        int i;
        char topoPubTopic[MAX_SHADOW_TOPIC_LENGTH_BYTES] = {0};
        snprintf(topoPubTopic, sizeof(topoPubTopic), "iot/%s/%s/%s/thing/topo/get", IOT_PROJECT_CODE, IOT_PRODUCT_CODE, IOT_DEVICE_CODE);
        IOT_INFO("publish topoGet topic: %s", topoPubTopic);
        cJSON *json_topoGet = cJSON_CreateObject();
        cJSON_AddNumberToObject(json_topoGet, "id", 1);
        cJSON_AddStringToObject(json_topoGet, "version", "1.0");
        cJSON_AddStringToObject(json_topoGet, "params", "");
        cJSON_AddStringToObject(json_topoGet, "method", "");
        rc = iot_shadow_publishToTopic(pClient, topoPubTopic, cJSON_Print(json_topoGet), QOS0);
        if(SUCCESS != rc) {
            IOT_ERROR("publish To topoGet Topic Error  %d", rc);
        }
        IOT_DEBUG("topoGet payload: %s", cJSON_Print(json_topoGet));
        cJSON_Delete(json_topoGet);
    }
    return rc;
}

物模型

获取物模型：用于获取设备模型数据。

参数：

​ pclient：mqtt client结构体变量指针

​ thingName：设备名称指针

​ callback：回调函数指针

返回值：

​ IoT_Error_t：枚举类型，返回操作结果

IoT_Error_t iot_shadow_dsltemplateGet(IoT_Client *pClient, char* thingName, void *clalback){
    IoT_Error_t rc = SUCCESS;
    int i;
    char dsltemplatePubTopic[MAX_SHADOW_TOPIC_LENGTH_BYTES] = {0};

    iot_shadow_subscribe_dsltemplateReply(pClient, thingName, clalback);

    snprintf(dsltemplatePubTopic, sizeof(dsltemplatePubTopic), "iot/%s/%s/%s/thing/dsltemplate/get", IOT_PROJECT_CODE, IOT_PRODUCT_CODE, thingName);
    IOT_INFO("publish dsltemplateGet topic: %s\n", dsltemplatePubTopic);
    cJSON *json_dsltemplateGet = cJSON_CreateObject();
    cJSON_AddNumberToObject(json_dsltemplateGet, "id", 1);
    cJSON_AddStringToObject(json_dsltemplateGet, "version", "1.0");
    cJSON_AddStringToObject(json_dsltemplateGet, "params", "");
    cJSON_AddStringToObject(json_dsltemplateGet, "method", "thing.dsltemplate.get");

    rc = iot_shadow_publishToTopic(pClient, dsltemplatePubTopic, cJSON_Print(json_dsltemplateGet), QOS0);
    if(SUCCESS != rc) {
        IOT_ERROR("publish To dsltemplateGet Topic Error  %d", rc);
    }
    IOT_DEBUG("dsltemplateGet payload: %s", cJSON_Print(json_dsltemplateGet));
    cJSON_Delete(json_dsltemplateGet);

    return rc;
}

Java SDK

环境要求

操作系统：Windows或linux

JDK版本： JDK 1.8.0及以上

Java SDK目录结构

sdk文件路径位于：src\main\java\com\iot\client

| - constant (常量类) | - core （核心基础类）
| - mqtt （MQTT相关类）
| - sample（ 示例demo）
| - shadow（shadow相关类）
| - util （公用工具类）

Java SDK文件夹及其内容的说明

constant：该目录包含常量和错误码常量。

core：该目录包含iot异常定义、iot回调接口等文件。

mqtt：MQTT相关类，包含MQTT连接和监听等。

sample ：示例dome，包括发布和订阅IoT服务的简单MQTT示例以及显示设备影子功能示例用法的设备影子示例等。

shadow ：shadow相关类，包含shadow规范格式代码、设备命令的监听和管理等。

util：SDK中使用到的工具类

Java SDK参数配置

参数配置文件位于src\main\resources\com\iot\client\sample\sampleUtil目录下的iot-sdk-device.properties（设备）和iot-sdk-gateway.properties（网关）中

• 设置客户端接入点（即MQTT访问地址）

ProjectAddr=XXX

• 指定根CA证书路径

IoTRootCaCrt=XXX

• 指定客户端证书路径

IotClientDevCrt=XXX

• 指定客户端私钥

IotClientDevKey=XXX

• 设置项目名称

ProjectCode=XXX

• 设置产品名称

ProductCode=XXX

• 设置设备名称

DeviceCode=XXX

• 设置用户名

mqttUserName=XXX

• 设置密码

mqttPassword=XXX

Java API接口

Java API接口

1. MQTT接口 - IotMqttClient

1. 设备影子接口 - IotDevice

Java SDK运行示例

1.将Java SDK导入Java运行环境

2.编辑SDK参数配置文件

3.运行示例：

设备示例位于src\main\java\com\iot\client\sample\device\MyDeviceMain.java

网关示例位于src\main\java\com\iot\client\sample\device\MyGatewayMain.java

MQTT Client SDK

物接入与Paho（即MQTT Client SDK）完全兼容，如果开发者需要开发MQTT客户端，可到Paho官方网站下载SDK并获取帮助文档，详情如下：