全部产品
弹性计算 会员服务 网络 安全 移动云 数加·大数据分析及展现 数加·大数据应用 管理与监控 云通信 阿里云办公 培训与认证 更多
存储与CDN 数据库 域名与网站(万网) 应用服务 数加·人工智能 数加·大数据基础服务 互联网中间件 视频服务 开发者工具 解决方案 物联网 智能硬件
阿里云物联网套件

C-SDK功能说明

更新时间:2018-04-17 18:04:16

详细技术说明文档, 请访问官方WiKi

编译配置项说明

请先下载最新版本设备端C语言SDK SDK下载

解压之后, 打开编译配置文件make.settings, 根据需要编辑配置项:

  1. FEATURE_MQTT_COMM_ENABLED = y # 是否打开MQTT通道的总开关
  2. FEATURE_MQTT_DIRECT = y # 是否打开MQTT直连的分开关
  3. FEATURE_MQTT_DIRECT_NOTLS = n # 是否打开MQTT直连无TLS的分开关
  4. FEATURE_COAP_COMM_ENABLED = y # 是否打开CoAP通道的总开关
  5. FEATURE_HTTP_COMM_ENABLED = y # 是否打开HTTP通道的总开关
  6. FEATURE_SUBDEVICE_ENABLED = n # 是否打开主子设备功能的总开关
  7. FEATURE_SUBDEVICE_STATUS = gateway # 主子设备功能所处的功能状态
  8. FEATURE_CMP_ENABLED = y # 是否打开CMP功能的总开关
  9. FEATURE_CMP_VIA_MQTT_DIRECT = y # CMP功能连云部分是否直接使用MQTT的开关
  10. FEATURE_MQTT_DIRECT_NOITLS = y # 是否打开MQTT直连无ITLS的分开关 目前itls只在id2模式支持
  11. FEATURE_DM_ENABLED = y # 是否打开DM功能的总开关
  12. FEATURE_SERVICE_OTA_ENABLED = y # 是否打开linkit中OTA功能的分开关
  13. FEATURE_SERVICE_COTA_ENABLED = y # 是否打开linkit中远程配置功能的分开关

具体含义参见下表:

配置选项 含义
FEATURE_MQTT_COMM_ENABLED 是否使能MQTT通道功能的总开关
FEATURE_MQTT_DIRECT 是否用MQTT直连模式代替HTTPS三方认证模式做设备认证
FEATURE_MQTT_DIRECT_NOTLS 使用MQTT直连模式做设备认证时, 是否要关闭MQTT over TLS
FEATURE_COAP_COMM_ENABLED 是否使能CoAP通道功能的总开关
FEATURE_HTTP_COMM_ENABLED 是否使能Https通道功能的总开关
FEATURE_SUBDEVICE_ENABLED 是否使能主子设备通道功能的总开关
FEATURE_SUBDEVICE_STATUS 主子设备功能所处的功能状态,取值有网关gateway(gw=1)和子设备subdevice(gw=0)
FEATURE_CMP_ENABLED 是否打开CMP功能的总开关,CMP: connectivity management platform
FEATURE_CMP_VIA_CLOUD_CONN CMP功能连云部分选择使用CLOUD_CONN,该开关选择具体协议:MQTT/CoAP/HTTP
FEATURE_MQTT_ID2_AUTH ID2功能需打开ITLS开关支持
FEATURE_SERVICE_OTA_ENABLED 是否打开linkit中OTA功能的分开关,需打开FEATURE_SERVICE_OTA_ENABLED支持
FEATURE_SERVICE_COTA_ENABLED 是否打开linkit中COTA功能的分开关,需打开FEATURE_SERVICE_OTA_ENABLED支持
FEATURE_SUPPORT_PRODUCT_SECRET 是否打开一型一密开关,与id2互斥
FEATURE_SERVICE_OTA_ENABLED FEATURE_SERVICE_COTA_ENABLED
y y 支持远程配置,不支持固件升级
y n 支持固件升级,不支持远程配置
n n/y 不支持service层级的ota,但是仍可以直接使用IOT_OTA_XXX来进行固件升级

编译 & 运行

请参考README.md

C-SDK提供的功能API说明

以下为华东2站点V2.0+版本的C-SDK提供的功能和对应的API, 用于让用户编写业务逻辑, 封装AT命令时, 也是基于这些API

更加准确详细和权威的描述, 以代码src/sdk-impl/iot_export.h, 以及src/sdk-impl/exports/*.h中的注释为准

如何使用这些API编写应用逻辑, 以代码sample/*/*.c的示例程序为准

API列表

用如下命令, 可以列出当前SDK代码提供的所有面向用户的API函数:

  1. $ cd src/sdk-impl
  2. $ grep -o "IOT_[A-Z][_a-zA-Z]*[^_]\> *(" iot_export.h exports/*.h|sed 's!.*:\(.*\)(!\1!'|cat -n
  3. 1 IOT_OpenLog
  4. 2 IOT_CloseLog
  5. 3 IOT_SetLogLevel
  6. 4 IOT_DumpMemoryStats
  7. 5 IOT_SetupConnInfo
  8. 6 IOT_SetupConnInfoSecure
  9. 7 IOT_Cloud_Connection_Init
  10. 8 IOT_Cloud_Connection_Deinit
  11. 9 IOT_Cloud_Connection_Send_Message
  12. 10 IOT_Cloud_Connection_Yield
  13. 11 IOT_CMP_Init
  14. 12 IOT_CMP_OTA_Start
  15. 13 IOT_CMP_OTA_Set_Callback
  16. 14 IOT_CMP_OTA_Get_Config
  17. 15 IOT_CMP_OTA_Request_Image
  18. 16 IOT_CMP_Register
  19. 17 IOT_CMP_Unregister
  20. 18 IOT_CMP_Send
  21. 19 IOT_CMP_Send_Sync
  22. 20 IOT_CMP_Yield
  23. 21 IOT_CMP_Deinit
  24. 22 IOT_CMP_OTA_Yield
  25. 23 IOT_CoAP_Init
  26. 24 IOT_CoAP_Deinit
  27. 25 IOT_CoAP_DeviceNameAuth
  28. 26 IOT_CoAP_Yield
  29. 27 IOT_CoAP_SendMessage
  30. 28 IOT_CoAP_GetMessagePayload
  31. 29 IOT_CoAP_GetMessageCode
  32. 30 IOT_HTTP_Init
  33. 31 IOT_HTTP_DeInit
  34. 32 IOT_HTTP_DeviceNameAuth
  35. 33 IOT_HTTP_SendMessage
  36. 34 IOT_HTTP_Disconnect
  37. 35 IOT_MQTT_Construct
  38. 36 IOT_MQTT_ConstructSecure
  39. 37 IOT_MQTT_Destroy
  40. 38 IOT_MQTT_Yield
  41. 39 IOT_MQTT_CheckStateNormal
  42. 40 IOT_MQTT_Disable_Reconnect
  43. 41 IOT_MQTT_Subscribe
  44. 42 IOT_MQTT_Unsubscribe
  45. 43 IOT_MQTT_Publish
  46. 44 IOT_OTA_Init
  47. 45 IOT_OTA_Deinit
  48. 46 IOT_OTA_ReportVersion
  49. 47 IOT_OTA_RequestImage
  50. 48 IOT_OTA_ReportProgress
  51. 49 IOT_OTA_GetConfig
  52. 50 IOT_OTA_IsFetching
  53. 51 IOT_OTA_IsFetchFinish
  54. 52 IOT_OTA_FetchYield
  55. 53 IOT_OTA_Ioctl
  56. 54 IOT_OTA_GetLastError
  57. 55 IOT_Shadow_Construct
  58. 56 IOT_Shadow_Destroy
  59. 57 IOT_Shadow_Yield
  60. 58 IOT_Shadow_RegisterAttribute
  61. 59 IOT_Shadow_DeleteAttribute
  62. 60 IOT_Shadow_PushFormat_Init
  63. 61 IOT_Shadow_PushFormat_Add
  64. 62 IOT_Shadow_PushFormat_Finalize
  65. 63 IOT_Shadow_Push
  66. 64 IOT_Shadow_Push_Async
  67. 65 IOT_Shadow_Pull
  68. 66 IOT_Gateway_Generate_Message_ID
  69. 67 IOT_Gateway_Construct
  70. 68 IOT_Gateway_Destroy
  71. 69 IOT_Subdevice_Register
  72. 70 IOT_Subdevice_Unregister
  73. 71 IOT_Subdevice_Login
  74. 72 IOT_Subdevice_Logout
  75. 73 IOT_Gateway_Get_TOPO
  76. 74 IOT_Gateway_Get_Config
  77. 75 IOT_Gateway_Publish_Found_List
  78. 76 IOT_Gateway_Yield
  79. 77 IOT_Gateway_Subscribe
  80. 78 IOT_Gateway_Unsubscribe
  81. 79 IOT_Gateway_Publish
  82. 80 IOT_Gateway_RRPC_Register
  83. 81 IOT_Gateway_RRPC_Response
  84. 82 linkkit_start
  85. 83 linkkit_end
  86. 84 linkkit_dispatch
  87. 85 linkkit_yield
  88. 86 linkkit_set_value
  89. 87 linkkit_get_value
  90. 88 linkkit_set_tsl
  91. 89 linkkit_answer_service
  92. 90 linkkit_invoke_raw_service
  93. 91 linkkit_trigger_event
  94. 92 linkkit_fota_init
  95. 93 linkkit_invoke_fota_service
  96. 94 linkkit_fota_init
  97. 95 linkkit_invoke_cota_get_config
  98. 96 linkkit_invoke_cota_service

必选API

序号 函数名 说明
1 IOT_OpenLog 开始打印日志信息(log), 接受一个const char *为入参, 表示模块名字
2 IOT_CloseLog 停止打印日志信息(log), 入参为空
3 IOT_SetLogLevel 设置打印的日志等级, 接受入参从1到5, 数字越大, 打印越详细
4 IOT_DumpMemoryStats 调试函数, 打印内存的使用统计情况, 入参为1-5, 数字越大, 打印越详细

CoAP功能相关

序号 函数名 说明
1 IOT_CoAP_Init CoAP实例的构造函数, 入参为iotx_coap_config_t结构体, 返回创建的CoAP会话句柄
2 IOT_CoAP_Deinit CoAP实例的摧毁函数, 入参为IOT_CoAP_Init()所创建的句柄
3 IOT_CoAP_DeviceNameAuth 基于控制台申请的DeviceName, DeviceSecret, ProductKey做设备认证
4 IOT_CoAP_GetMessageCode CoAP会话阶段, 从服务器的CoAP Response报文中获取Respond Code
5 IOT_CoAP_GetMessagePayload CoAP会话阶段, 从服务器的CoAP Response报文中获取报文负载
6 IOT_CoAP_SendMessage CoAP会话阶段, 连接已成功建立后调用, 组织一个完整的CoAP报文向服务器发送
7 IOT_CoAP_Yield CoAP会话阶段, 连接已成功建立后调用, 检查和收取服务器对CoAP Request的回复报文

云端连接Cloud Connection功能相关

序号 函数名 说明
1 IOT_Cloud_Connection_Init 云端连接实例的构造函数, 入参为iotx_cloud_connection_param_pt结构体, 返回创建的云端连接会话句柄
2 IOT_Cloud_Connection_Deinit 云端连接实例的摧毁函数, 入参为IOT_Cloud_Connection_Init()所创建的句柄
3 IOT_Cloud_Connection_Send_Message 发送数据给云端
4 IOT_Cloud_Connection_Yield 云端连接成功建立后,收取服务器发送的报文

CMP功能相关

序号 函数名 说明
1 IOT_CMP_Init CMP实例的构造函数, 入参为iotx_cmp_init_param_pt结构体,只存在一个CMP实例
2 IOT_CMP_Register 通过CMP订阅服务
3 IOT_CMP_Unregister 通过CMP取消服务订阅
4 IOT_CMP_Send 通过CMP发送数据,可以送给云端,也可以送给本地设备
5 IOT_CMP_Send_Sync 通过CMP同步发送数据 ,暂不支持
6 IOT_CMP_Yield 通过CMP接收数据,单线程情况下才支持
7 IOT_CMP_Deinit CMP示例的摧毁函数
8 IOT_CMP_OTA_Start 初始化ota功能,上报版本
9 IOT_CMP_OTA_Set_Callback 设置OTA回调函数
10 IOT_CMP_OTA_Get_Config 获取远程配置
11 IOT_CMP_OTA_Request_Image 获取固件
12 IOT_CMP_OTA_Yield 通过CMP完成OTA功能

MQTT功能相关

序号 函数名 说明
1 IOT_SetupConnInfo MQTT连接前的准备, 基于DeviceName + DeviceSecret + ProductKey产生MQTT连接的用户名和密码等
2 IOT_SetupConnInfoSecure MQTT连接前的准备, 基于ID2 + DeviceSecret + ProductKey产生MQTT连接的用户名和密码等,ID2模式启用
3 IOT_MQTT_CheckStateNormal MQTT连接后, 调用此函数检查长连接是否正常
4 IOT_MQTT_Construct MQTT实例的构造函数, 入参为iotx_mqtt_param_t结构体, 连接MQTT服务器, 并返回被创建句柄
5 IOT_MQTT_ConstructSecure MQTT实例的构造函数, 入参为iotx_mqtt_param_t结构体, 连接MQTT服务器, 并返回被创建句柄 ,ID2模式启用
6 IOT_MQTT_Destroy MQTT实例的摧毁函数, 入参为IOT_MQTT_Construct()创建的句柄
7 IOT_MQTT_Publish MQTT会话阶段, 组织一个完整的MQTT Publish报文, 向服务端发送消息发布报文
8 IOT_MQTT_Subscribe MQTT会话阶段, 组织一个完整的MQTT Subscribe报文, 向服务端发送订阅请求
9 IOT_MQTT_Unsubscribe MQTT会话阶段, 组织一个完整的MQTT UnSubscribe报文, 向服务端发送取消订阅请求
10 IOT_MQTT_Yield MQTT会话阶段, MQTT主循环函数, 内含了心跳的维持, 服务器下行报文的收取等

OTA功能相关(模组实现时的可选功能)

序号 函数名 说明
1 IOT_OTA_Init OTA实例的构造函数, 创建一个OTA会话的句柄并返回
2 IOT_OTA_Deinit OTA实例的摧毁函数, 销毁所有相关的数据结构
3 IOT_OTA_Ioctl OTA实例的输入输出函数, 根据不同的命令字可以设置OTA会话的属性, 或者获取OTA会话的状态
4 IOT_OTA_GetLastError OTA会话阶段, 若某个IOT_OTA_*()函数返回错误, 调用此接口可获得最近一次的详细错误码
5 IOT_OTA_ReportVersion OTA会话阶段, 向服务端汇报当前的固件版本号
6 IOT_OTA_FetchYield OTA下载阶段, 在指定的timeout时间内, 从固件服务器下载一段固件内容, 保存在入参buffer中
7 IOT_OTA_IsFetchFinish OTA下载阶段, 判断迭代调用IOT_OTA_FetchYield()是否已经下载完所有的固件内容
8 IOT_OTA_IsFetching OTA下载阶段, 判断固件下载是否仍在进行中, 尚未完成全部固件内容的下载
9 IOT_OTA_ReportProgress 可选API, OTA下载阶段, 调用此函数向服务端汇报已经下载了全部固件内容的百分之多少
10 IOT_OTA_RequestImage 可选API,向服务端请求固件下载
11 IOT_OTA_GetConfig 可选API,向服务端请求远程配置

HTTP功能相关

序号 函数名 说明
1 IOT_HTTP_Init Https实例的构造函数, 创建一个HTTP会话的句柄并返回
2 IOT_HTTP_DeInit Https实例的摧毁函数, 销毁所有相关的数据结构
3 IOT_HTTP_DeviceNameAuth 基于控制台申请的DeviceName, DeviceSecret, ProductKey做设备认证
4 IOT_HTTP_SendMessage Https会话阶段, 组织一个完整的HTTP报文向服务器发送,并同步获取HTTP回复报文
5 IOT_HTTP_Disconnect Https会话阶段, 关闭HTTP层面的连接, 但是仍然保持TLS层面的连接

设备影子相关(模组实现时的可选功能)

序号 函数名 说明
1 IOT_Shadow_Construct 建立一个设备影子的MQTT连接, 并返回被创建的会话句柄
2 IOT_Shadow_Destroy 摧毁一个设备影子的MQTT连接, 销毁所有相关的数据结构, 释放内存, 断开连接
3 IOT_Shadow_Pull 把服务器端被缓存的JSON数据下拉到本地, 更新本地的数据属性
4 IOT_Shadow_Push 把本地的数据属性上推到服务器缓存的JSON数据, 更新服务端的数据属性
5 IOT_Shadow_Push_Async IOT_Shadow_Push()接口类似, 但是异步的, 上推后便返回, 不等待服务端回应
6 IOT_Shadow_PushFormat_Add 向已创建的数据类型格式中增添成员属性
7 IOT_Shadow_PushFormat_Finalize 完成一个数据类型格式的构造过程
8 IOT_Shadow_PushFormat_Init 开始一个数据类型格式的构造过程
9 IOT_Shadow_RegisterAttribute 创建一个数据类型注册到服务端, 注册时需要*PushFormat*()接口创建的数据类型格式
10 IOT_Shadow_DeleteAttribute 删除一个已被成功注册的数据属性
11 IOT_Shadow_Yield MQTT的主循环函数, 调用后接受服务端的下推消息, 更新本地的数据属性

主子设备相关(模组实现时的可选功能)

序号 函数名 说明
1 IOT_Gateway_Construct 建立一个主设备,建立MQTT连接, 并返回被创建的会话句柄
2 IOT_Gateway_Destroy 摧毁一个主设备的MQTT连接, 销毁所有相关的数据结构, 释放内存, 断开连接
3 IOT_Subdevice_Login 子设备上线,通知云端建立子设备session
4 IOT_Subdevice_Logout 子设备下线,销毁云端建立子设备session及所有相关的数据结构, 释放内存
5 IOT_Gateway_Yield MQTT的主循环函数, 调用后接受服务端的下推消息
6 IOT_Gateway_Subscribe 通过MQTT连接向服务端发送订阅请求
7 IOT_Gateway_Unsubscribe 通过MQTT连接向服务端发送取消订阅请求
8 IOT_Gateway_Publish 通过MQTT连接服务端发送消息发布报文
9 IOT_Gateway_RRPC_Register 注册设备的RRPC回调函数,接收云端发起的RRPC请求
10 IOT_Gateway_RRPC_Response 对云端的RRPC请求进行应答
11 IOT_Gateway_Generate_Message_ID 生成消息id
12 IOT_Gateway_Get_TOPO 向topo/get topic发送包并等待回复(TOPIC_GET_REPLY 回复)
13 IOT_Gateway_Get_Config 向conifg/get topic发送包并等待回复(TOPIC_CONFIG_REPLY 回复)
14 IOT_Gateway_Publish_Found_List 发现设备列表上报

linkkit()

序号 函数名 说明
1 linkkit_start 启动 linkkit 服务,与云端建立连接并安装回调函数
2 linkkit_end 停止 linkkit 服务,与云端断开连接并回收资源
3 linkkit_dispatch 事件分发函数,触发 linkkit_start 安装的回调
4 linkkit_yield linkkit 主循环函数,内含了心跳的维持, 服务器下行报文的收取等;如果允许多线程,请不要调用此函数
5 linkkit_set_value 根据identifier设置物对象的 TSL 属性,如果标识符为struct类型、event output类型或者service output类型,使用点’.’分隔字段;例如”identifier1.identifier2”指向特定的项
6 linkkit_get_value 根据identifier获取物对象的 TSL 属性
7 linkkit_set_tsl 从本地读取 TSL 文件,生成物的对象并添加到 linkkit 中
8 linkkit_answer_service 对云端服务请求进行回应
9 linkkit_invoke_raw_service 向云端发送裸数据
10 linkkit_trigger_event 上报设备事件到云端
11 linkkit_fota_init 初始化 OTA-fota 服务,并安装回调函数(需编译设置宏 SERVICE_OTA_ENABLED )
12 linkkit_invoke_fota_service 执行fota服务
13 linkkit_fota_init 初始化 OTA-cota 服务,并安装回调函数(需编译设置宏 SERVICE_OTA_ENABLED SERVICE_COTA_ENABLED )
14 linkkit_invoke_cota_get_config 设备请求远程配置
15 linkkit_invoke_cota_service 执行cota服务
本文导读目录