腾讯物联网通信 SDK
腾讯物联网通信 SDK 依靠安全且性能强大的数据通道，为物联网领域开发人员提供终端(如传感器, 执行器, 嵌入式设备或智能家电等等)和云端的双向通信能力。
快速开始
本节将讲述如何在腾讯物联网通信控制台申请设备, 并结合本 SDK 快速体验设备通过 MQTT+TLS/SSL 协议连接到腾讯云, 发送和接收消息；通过 CoAP+DTLS 协议连接到腾讯云，上报数据。
一. 控制台创建设备
1. 注册/登录腾讯云账号
访问腾讯云登录页面, 点击立即注册, 免费获取腾讯云账号，若您已有账号，可直接登录。
2. 访问物联网通信控制台
登录后点击右上角控制台，进入控制台后，鼠标悬停在云产品上，弹出层叠菜单，点击物联网通信。
或者直接访问物联网通信控制台
3. 创建产品和设备
点击页面创建新产品按钮, 创建一个产品。
在弹出的产品窗口中，选择节点类型和产品类型，输入产品名称，选择认证方式和数据格式，输入产品描述，然后点击确定创建。如果是普通直连设备，可按下图选择。
如果是普通网关设备，可按下图选择。
在生成的产品页面下，点击设备列表页面添加新设备。
如果产品认证方式为证书认证，输入设备名称成功后，切记点击弹窗中的下载按钮，下载所得包中的设备密钥文件和设备证书用于设备连接物联网通信的鉴权。
如果产品认证方式为密钥认证，输入设备名称成功后，会在弹窗中显示新添加设备的密钥
如果是网关产品，还需要按照普通产品的方式先创建子产品和子设备，并在网关产品页面添加子产品和子设备。需要注意的是子设备是无法直连物联网平台的产品，由网关设备代理连接，所以子设备的认证方式不影响连接，由网关设备来负责认证接入。 创建好子产品之后，先到网关产品页面的子产品栏目添加子产品
再到网关设备页面的子设备栏目添加子设备
4. 创建可订阅可发布的Topic
按照第三步中进入产品设置页面的方法进入页面后, 点击权限列表，再点击添加Topic权限。
在弹窗中输入 data, 并设置操作权限为发布和订阅，点击创建。
随后将会创建出 productID/${deviceName}/data 的 Topic，在产品页面的权限列表中可以查看该产品的所有权限。
对于网关产品，除了添加本产品的Topic权限，还需要为子产品添加Topic权限
二. 编译示例程序
1. 下载SDK
登录 Linux, 运行如下命令从 github 克隆代码, 或者访问最新下载地址, 将下载到的压缩包在 Linux 上解压缩
git clone https://github.com/tencentyun/qcloud-iot-sdk-embedded-c.git
2. 填入设备信息
编辑 samples/mqtt/mqtt_sample.c 文件和 samples/coap/coap_sample.c 文件中如下代码段, 填入之前创建产品和设备步骤中得到的 产品ID，设备名称：
- 若使用证书认证加密方式，填写 QCLOUD_IOT_CERT_FILENAME 和 QCLOUD_IOT_CERT_FILENAME 并将文件放置在根目录下 certs 目录中。将根目录下 make.settings 文件中的配置项 FEATURE_AUTH_MODE 设置为 CERT，FEATURE_AUTH_WITH_NOTLS 设置为 n。
FEATURE_AUTH_MODE = CERT # MQTT/CoAP接入认证方式，使用证书认证：CERT；使用密钥认证：KEY
FEATURE_AUTH_WITH_NOTLS = n # 接入认证是否不使用TLS，证书方式必须选择使用TLS，密钥认证可选择不使用TLS
- 若使用秘钥认证加密方式，填写 QCLOUD_IOT_DEVICE_SECRET。将根目录下 make.settings 文件中的配置项 FEATURE_AUTH_MODE 设置为 KEY，FEATURE_AUTH_WITH_NOTLS 设置为 n 时通过 TLS 密钥认证方式连接，设置为 y 时，则通过 HMAC-SHA1 加密算法连接。
/* 产品名称, 与云端同步设备状态时需要 */
#define QCLOUD_IOT_MY_PRODUCT_ID "YOUR_PRODUCT_ID"
/* 设备名称, 与云端同步设备状态时需要 */
#define QCLOUD_IOT_MY_DEVICE_NAME "YOUR_DEVICE_NAME"
#ifdef AUTH_MODE_CERT
/* 客户端证书文件名 非对称加密使用*/
#define QCLOUD_IOT_CERT_FILENAME "YOUR_DEVICE_NAME_cert.crt"
/* 客户端私钥文件名 非对称加密使用*/
#define QCLOUD_IOT_KEY_FILENAME "YOUR_DEVICE_NAME_private.key"
static char sg_cert_file[PATH_MAX + 1]; //客户端证书全路径
static char sg_key_file[PATH_MAX + 1]; //客户端密钥全路径
#else
#define QCLOUD_IOT_DEVICE_SECRET "YOUR_IOT_PSK"
#endif
- 若为网关产品，需要将根目录下 make.settings 文件中的配置项 FEATURE_GATEWAY_ENABLED 设置为 y。
FEATURE_GATEWAY_ENABLED = y # 是否打开网关功能
并编辑samples/gateway/gateway_sample.c 文件中如下代码段, 填入之前创建网关产品和子产品及设备步骤中得到的网关产品ID，网关设备名称，子产品ID，子设备名称：
/* 网关产品名称, 与云端同步设备状态时需要 */
#define QCLOUD_IOT_MY_PRODUCT_ID "YOUR_GW_PRODUCT_ID"
/* 网关设备名称, 与云端同步设备状态时需要 */
#define QCLOUD_IOT_MY_DEVICE_NAME "YOUR_GW_DEVICE_NAME"
#ifdef AUTH_MODE_CERT
/* 网关客户端证书文件名 非对称加密使用*/
#define QCLOUD_IOT_CERT_FILENAME "YOUR_GW_DEVICE_NAME_cert.crt"
/* 网关客户端私钥文件名 非对称加密使用*/
#define QCLOUD_IOT_KEY_FILENAME "YOUR_GW_DEVICE_NAME_private.key"
static char sg_cert_file[PATH_MAX + 1]; //客户端证书全路径
static char sg_key_file[PATH_MAX + 1]; //客户端密钥全路径
#else
#define QCLOUD_IOT_DEVICE_SECRET "YOUR_GW_IOT_PSK"
#endif
/* 子产品名称, 与云端同步设备状态时需要 */
#define QCLOUD_IOT_SUBDEV_PRODUCT_ID "YOUR_SUBDEV_PRODUCT_ID"
/* 子设备名称, 与云端同步设备状态时需要 */
#define QCLOUD_IOT_SUBDEV_DEVICE_NAME "YOUR_SUBDEV_DEVICE_NAME"
3. 编译 SDK 产生示例程序
在根目录执行
$make clean
$make
编译成功完成后, 生成的样例程序在当前目录的 output/release/bin 目录下:
output/release/bin/
├── aircond_shadow_sample
├── aircond_shadow_sample_v2
├── certs
│ ├── README.md
│ ├── TEST_CLIENT_cert.crt
│ └── TEST_CLIENT_private.key
├── coap_sample
├── door_coap_sample
├── door_mqtt_sample
├── gateway_sample
├── mqtt_sample
├── ota_mqtt_sample
└── shadow_sample
三. 运行示例程序
1. 执行 MQTT 示例程序
./mqtt_sample
INF|2018-04-27 17:39:35|device.c|iot_device_info_init(37): device info init success!
INF|2018-04-27 17:39:35|device.c|iot_device_info_set(42): start to set device info!
INF|2018-04-27 17:39:35|device.c|iot_device_info_set(66): device info set successfully!
DBG|2018-04-27 17:39:35|mqtt_client.c|qcloud_iot_mqtt_init(185): product_id: QICJYEM1T4
DBG|2018-04-27 17:39:35|mqtt_client.c|qcloud_iot_mqtt_init(186): device_name: Demo1
DBG|2018-04-27 17:39:35|mqtt_client.c|qcloud_iot_mqtt_init(259): cert file: /home/ubuntu/skyztmeng/v2_10_coap_ota/output/release/bin/certs/Demo1_cert.crt
DBG|2018-04-27 17:39:35|mqtt_client.c|qcloud_iot_mqtt_init(260): key file: /home/ubuntu/skyztmeng/v2_10_coap_ota/output/release/bin/certs/Demo1_private.key
DBG|2018-04-27 17:39:35|HAL_TLS_mbedtls.c|HAL_TLS_Connect(204): Connecting to /iotcloud-mqtt.gz.tencentdevices.com/8883...
DBG|2018-04-27 17:39:35|HAL_TLS_mbedtls.c|HAL_TLS_Connect(209): Setting up the SSL/TLS structure...
DBG|2018-04-27 17:39:35|HAL_TLS_mbedtls.c|HAL_TLS_Connect(251): Performing the SSL/TLS handshake...
INF|2018-04-27 17:39:35|mqtt_client.c|IOT_MQTT_Construct(107): mqtt connect with id: mgiO5 success
INF|2018-04-27 17:39:35|mqtt_sample.c|main(243): Cloud Device Construct Success
DBG|2018-04-27 17:39:35|mqtt_client_subscribe.c|qcloud_iot_mqtt_subscribe(123): topicName=$sys/operation/result/QICJYEM1T4/Demo1|packet_id=30134|pUserdata=(null)
INF|2018-04-27 17:39:35|system_mqtt.c|system_mqtt_event_handler(56): subscribe success, packet-id=30134
DBG|2018-04-27 17:39:35|system_mqtt.c|IOT_SYSTEM_GET_TIME(155): the count of subscribe is 0,
DBG|2018-04-27 17:39:35|mqtt_client_publish.c|qcloud_iot_mqtt_publish(325): publish packetID=0|topicName=$sys/operation/QICJYEM1T4/Demo1|payload={"type": "get", "resource": ["time"]}
INF|2018-04-27 17:39:35|system_mqtt.c|on_system_mqtt_message_callback(35): Receive Message With topicName:$sys/operation/result/QICJYEM1T4/Demo1, payload:{"type":"get","time":1524821975}
INF|2018-04-27 17:39:35|system_mqtt.c|on_system_mqtt_message_callback(44): the value of time is 1524821975
INF|2018-04-27 17:39:35|system_mqtt.c|IOT_SYSTEM_GET_TIME(181): receive time info success: 1, yield count is 1
INF|2018-04-27 17:39:35|system_mqtt.c|IOT_SYSTEM_GET_TIME(183): the time is 1524821975
INF|2018-04-27 17:39:35|mqtt_sample.c|main(254): the time is 1524821975
DBG|2018-04-27 17:39:35|mqtt_client_subscribe.c|qcloud_iot_mqtt_subscribe(123): topicName=QICJYEM1T4/Demo1/data|packet_id=30135|pUserdata=(null)
INF|2018-04-27 17:39:35|mqtt_sample.c|event_handler(80): subscribe success, packet-id=30135
DBG|2018-04-27 17:39:35|mqtt_client_publish.c|qcloud_iot_mqtt_publish(317): publish topic seq=30136|topicName=QICJYEM1T4/Demo1/data|payload={"action": "publish_test", "count": "0"}
INF|2018-04-27 17:39:35|mqtt_sample.c|event_handler(107): publish success, packet-id=30136
INF|2018-04-27 17:39:35|mqtt_sample.c|on_message_callback(137): Receive Message With topicName:QICJYEM1T4/Demo1/data, payload:{"action": "publish_test", "count": "0"}
INF|2018-04-27 17:39:36|mqtt_client_connect.c|qcloud_iot_mqtt_disconnect(472): mqtt disconnect!
INF|2018-04-27 17:39:36|mqtt_client.c|IOT_MQTT_Destroy(136): mqtt release!
2. 观察消息发送
如下日志信息显示示例程序通过 MQTT 的 Publish 类型消息, 上报数据到 /{productID}/{deviceName}/data 成功。
INF|2018-04-27 17:39:35|mqtt_sample.c|event_handler(107): publish success, packet-id=30136
3. 观察消息接收
如下日志信息显示该消息因为是到达已被订阅的 Topic, 所以又被服务器原样推送到示例程序, 并进入相应的回调函数
INF|2018-04-27 17:39:35|mqtt_sample.c|on_message_callback(137): Receive Message With topicName:QICJYEM1T4/Demo1/data, payload:{"action": "publish_test", "count": "0"}
4. 观察控制台日志
可以登录物联网通信控制台, 点击左边导航栏中的云日志, 查看刚才上报的消息
5. 执行 CoAP 示例程序
./coap_sample
INF|2018-04-27 17:54:17|device.c|iot_device_info_init(37): device info init success!
INF|2018-04-27 17:54:17|device.c|iot_device_info_set(42): start to set device info!
INF|2018-04-27 17:54:17|device.c|iot_device_info_set(66): device info set successfully!
DBG|2018-04-27 17:54:17|coap_client.c|qcloud_iot_coap_init(286): cert file: /home/ubuntu/skyztmeng/v2_10_coap_ota/output/release/bin/certs/Demo1_cert.crt
DBG|2018-04-27 17:54:17|coap_client.c|qcloud_iot_coap_init(287): key file: /home/ubuntu/skyztmeng/v2_10_coap_ota/output/release/bin/certs/Demo1_private.key
INF|2018-04-27 17:54:17|coap_client.c|IOT_COAP_Construct(83): coap connect success
INF|2018-04-27 17:54:17|coap_client_message.c|coap_message_send(404): add coap message id: 56647 into wait list ret: 0
DBG|2018-04-27 17:54:17|coap_client_message.c|_coap_message_handle(297): receive coap piggy ACK message, id 56647
INF|2018-04-27 17:54:17|coap_client_auth.c|_coap_client_auth_callback(42): auth token message success, code_class: 2 code_detail: 5
DBG|2018-04-27 17:54:17|coap_client_auth.c|_coap_client_auth_callback(52): auth_token_len = 11, auth_token = QEWMYSSYUYC
DBG|2018-04-27 17:54:17|coap_client_message.c|_coap_message_list_proc(148): remove the message id 56647 from list
INF|2018-04-27 17:54:17|coap_client_message.c|_coap_message_list_proc(87): remove node
INF|2018-04-27 17:54:17|coap_client.c|IOT_COAP_Construct(92): device auth successfully, connid: I75BN
ERR|2018-04-27 17:54:17|coap_sample.c|main(153): 0x25f0010
INF|2018-04-27 17:54:17|coap_sample.c|main(166): topic name is QICJYEM1T4/Demo1/data
INF|2018-04-27 17:54:17|coap_client_message.c|coap_message_send(404): add coap message id: 56648 into wait list ret: 0
DBG|2018-04-27 17:54:17|coap_sample.c|main(173): client topic has been sent, msg_id: 56648
DBG|2018-04-27 17:54:18|coap_client_message.c|_coap_message_handle(297): receive coap piggy ACK message, id 56648
INF|2018-04-27 17:54:18|coap_sample.c|event_handler(90): message received ACK, msgid: 56648
DBG|2018-04-27 17:54:18|coap_client_message.c|_coap_message_list_proc(148): remove the message id 56648 from list
INF|2018-04-27 17:54:18|coap_client_message.c|_coap_message_list_proc(87): remove node
INF|2018-04-27 17:54:18|coap_client.c|IOT_COAP_Destroy(126): coap release!
6. 观察消息发送
如下日志信息显示示例程序通过 CoAP 上报数据到 /{productID}/{deviceName}/data 成功。
DBG|2018-04-27 17:54:18|coap_client_message.c|_coap_message_handle(297): receive coap piggy ACK message, id 56648
INF|2018-04-27 17:54:18|coap_sample.c|event_handler(90): message received ACK, msgid: 56648
7. 执行网关实例程序
如下日志信息显示示例程序通过MQTT网关代理子设备上下线状态变化，发布和订阅消息成功。
./gateway_sample
INF|2019-01-23 16:35:56|mqtt_client.c|IOT_MQTT_Construct(64): SDK version: 2.3.0
INF|2019-01-23 16:35:56|device.c|iot_device_info_init(37): device info init success!
INF|2019-01-23 16:35:56|device.c|iot_device_info_set(42): start to set device info!
INF|2019-01-23 16:35:56|device.c|iot_device_info_set(66): device info set successfully!
DBG|2019-01-23 16:35:56|mqtt_client.c|qcloud_iot_mqtt_init(192): product_id: NINEPLMEB6
DBG|2019-01-23 16:35:56|mqtt_client.c|qcloud_iot_mqtt_init(193): device_name: Gateway-demo
DBG|2019-01-23 16:35:56|HAL_TLS_mbedtls.c|HAL_TLS_Connect(204): Connecting to /NINEPLMEB6.iotcloud.tencentdevices.com/8883...
DBG|2019-01-23 16:35:57|HAL_TLS_mbedtls.c|HAL_TLS_Connect(209): Setting up the SSL/TLS structure...
DBG|2019-01-23 16:35:57|HAL_TLS_mbedtls.c|HAL_TLS_Connect(251): Performing the SSL/TLS handshake...
INF|2019-01-23 16:35:57|mqtt_client.c|IOT_MQTT_Construct(114): mqtt connect with id: Ms237 success
DBG|2019-01-23 16:35:57|mqtt_client_subscribe.c|qcloud_iot_mqtt_subscribe(129): topicName=$gateway/operation/result/NINEPLMEB6/Gateway-demo|packet_id=25279|pUserdata=(null)
INF|2019-01-23 16:35:58|gateway_api.c|_gateway_event_handler(19): event type 3
DBG|2019-01-23 16:35:58|gateway_api.c|IOT_Gateway_Subdev_Online(126): there is no session, create a new session
DBG|2019-01-23 16:35:58|mqtt_client_publish.c|qcloud_iot_mqtt_publish(337): publish packetID=0|topicName=$gateway/operation/NINEPLMEB6/Gateway-demo|payload={"type":"online","payload":{"devices":[{"product_id":"S3EUVBRJLB","device_name":"test_dev_key"}]}}
DBG|2019-01-23 16:35:58|gateway_common.c|_gateway_message_handler(124): client_id(S3EUVBRJLB/test_dev_key), online success. result 0
DBG|2019-01-23 16:35:58|gateway_common.c|_gateway_message_handler(135): type(online),devices([{"product_id":"S3EUVBRJLB","device_name":"test_dev_key","result":0}]),product_id(S3EUVBRJLB),device_name(test_dev_key),result(0)
DBG|2019-01-23 16:35:58|mqtt_client_subscribe.c|qcloud_iot_mqtt_subscribe(129): topicName=S3EUVBRJLB/test_dev_key/data|packet_id=25280|pUserdata=(null)
INF|2019-01-23 16:35:58|gateway_api.c|_gateway_event_handler(19): event type 3
INF|2019-01-23 16:35:58|gateway_sample.c|_event_handler(103): subscribe success, packet-id=25280
DBG|2019-01-23 16:35:58|mqtt_client_publish.c|qcloud_iot_mqtt_publish(329): publish topic seq=25281|topicName=S3EUVBRJLB/test_dev_key/data|payload={"data":"test gateway"}
DBG|2019-01-23 16:35:58|gateway_sample.c|_message_handler(159): topic(S3EUVBRJLB/test_dev_key/data),len(28)
DBG|2019-01-23 16:35:58|gateway_sample.c|_message_handler(166): payload({"data":"test gateway"}),len(24)
DBG|2019-01-23 16:36:00|mqtt_client_publish.c|qcloud_iot_mqtt_publish(329): publish topic seq=25282|topicName=S3EUVBRJLB/test_dev_key/data|payload={"data":"test gateway"}
INF|2019-01-23 16:36:00|gateway_api.c|_gateway_event_handler(19): event type 9
INF|2019-01-23 16:36:00|gateway_sample.c|_event_handler(130): publish success, packet-id=25281
DBG|2019-01-23 16:36:00|gateway_sample.c|_message_handler(159): topic(S3EUVBRJLB/test_dev_key/data),len(28)
DBG|2019-01-23 16:36:00|gateway_sample.c|_message_handler(166): payload({"data":"test gateway"}),len(24)
DBG|2019-01-23 16:36:01|mqtt_client_publish.c|qcloud_iot_mqtt_publish(329): publish topic seq=25283|topicName=S3EUVBRJLB/test_dev_key/data|payload={"data":"test gateway"}
INF|2019-01-23 16:36:01|gateway_api.c|_gateway_event_handler(19): event type 9
INF|2019-01-23 16:36:01|gateway_sample.c|_event_handler(130): publish success, packet-id=25282
DBG|2019-01-23 16:36:01|gateway_sample.c|_message_handler(159): topic(S3EUVBRJLB/test_dev_key/data),len(28)
DBG|2019-01-23 16:36:01|gateway_sample.c|_message_handler(166): payload({"data":"test gateway"}),len(24)
DBG|2019-01-23 16:36:02|mqtt_client_publish.c|qcloud_iot_mqtt_publish(337): publish packetID=0|topicName=$gateway/operation/NINEPLMEB6/Gateway-demo|payload={"type":"offline","payload":{"devices":[{"product_id":"S3EUVBRJLB","device_name":"test_dev_key"}]}}
INF|2019-01-23 16:36:02|gateway_api.c|_gateway_event_handler(19): event type 9
INF|2019-01-23 16:36:02|gateway_sample.c|_event_handler(130): publish success, packet-id=25283
DBG|2019-01-23 16:36:02|gateway_common.c|_gateway_message_handler(129): client_id(S3EUVBRJLB/test_dev_key), offline success. result 0
DBG|2019-01-23 16:36:02|gateway_common.c|_gateway_message_handler(135): type(offline),devices([{"product_id":"S3EUVBRJLB","device_name":"test_dev_key","result":0}]),product_id(S3EUVBRJLB),device_name(test_dev_key),result(0)
INF|2019-01-23 16:36:03|mqtt_client_connect.c|qcloud_iot_mqtt_disconnect(441): mqtt disconnect!
INF|2019-01-23 16:36:03|mqtt_client.c|IOT_MQTT_Destroy(143): mqtt release!
8. 多线程环境实例程序
SDK对于多线程环境有注意事项，详细可以参考samples/mqtt/multi_thread_mqtt_sample.c
四. 可变接入参数配置
可变接入参数配置：SDK 的使用可以根据具体场景需求，配置相应的参数，满足实际业务的运行。可变接入参数包括：
- MQTT 心跳消息发送周期, 单位: ms
- MQTT 阻塞调用(包括连接, 订阅, 发布等)的超时时间, 单位:ms。 建议 5000 ms
- TLS 连接握手超时时间, 单位: ms
- MQTT 协议发送消息和接受消息的 buffer 大小默认是 512 字节，最大支持 256 KB
- CoAP 协议发送消息和接受消息的 buffer 大小默认是 512 字节，最大支持 64 KB
- 重连最大等待时间 修改 qcloud_iot_export.h 文件如下宏定义可以改变对应接入参数的配置。
/* MQTT心跳消息发送周期, 单位:ms */
#define QCLOUD_IOT_MQTT_KEEP_ALIVE_INTERNAL (240 * 1000)
/* MQTT 阻塞调用(包括连接, 订阅, 发布等)的超时时间, 单位:ms 建议5000ms */
#define QCLOUD_IOT_MQTT_COMMAND_TIMEOUT (5000)
/* TLS连接握手超时时间, 单位:ms */
#define QCLOUD_IOT_TLS_HANDSHAKE_TIMEOUT (5000)
/* MQTT消息发送buffer大小, 支持最大256*1024 */
#define QCLOUD_IOT_MQTT_TX_BUF_LEN (512)
/* MQTT消息接收buffer大小, 支持最大256*1024 */
#define QCLOUD_IOT_MQTT_RX_BUF_LEN (512)
/* COAP 发送消息buffer大小，最大支持64*1024字节 */
#define COAP_SENDMSG_MAX_BUFLEN (512)
/* COAP 接收消息buffer大小，最大支持64*1024字节 */
#define COAP_RECVMSG_MAX_BUFLEN (512)
/* 重连最大等待时间 */
#define MAX_RECONNECT_WAIT_INTERVAL (60000)
##关于 SDK 的更多使用方式及接口了解, 请访问官方 WiKi