v3.2.3

1.增加从MQTT后台同步NTP时间的功能接口
2.增加网关子设备OTA示例
3.优化Log/HAL_Printf对字符串指针的处理
4.修复AT socket部分bug

Author: spikelin

docs/C-SDK_API及可变参数说明.md

@@ -141,6 +141,7 @@ MQTT构造时候除了提供设备信息，还需要提供一个回调函数，
 | 序号  | 函数名                      | 说明                                              |
 | ---- | ---------------------------- | ------------------------------------------------- |
 | 1    | IOT_Get_SysTime              | 获取 IoT hub 后台系统时间，目前仅支持 MQTT 通道对时功能 |
+| 2    | IOT_Sync_NTPTime             | 同步 IoT hub 后台时间戳并通过 NTP 算法设置设备系统时间，目前仅支持 MQTT 通道对时功能 |
 
 ### 网关功能接口
 关于网关功能介绍，可以参考SDK docs/IoT_Hub/网关功能文档
@@ -189,4 +190,4 @@ MQTT构造时候除了提供设备信息，还需要提供一个回调函数，
 | 序号 | 函数名                       | 说明                       |
 | ---- | ---------------------------- | -------------------------- |
 | 1    | IOT_Subscribe_Config         | 向云平台订阅远程配置 topic |
-| 2    | IOT_Get_Config               | 向云平台获取设备配置       |
+| 2    | IOT_Get_Config               | 向云平台获取设备配置       |

docs/IoT_Hub/mqtt_sample_快速入门.md

@@ -127,4 +127,19 @@ INF|2019-09-12 21:28:21|mqtt_sample.c|on_message_callback(195): Receive Message
 可以登录物联网通信控制台, 点击左边导航栏中的**云日志**, 查看刚才上报的消息
 ![](https://main.qcloudimg.com/raw/f589691c7e007b59a5426ede6dc17ddb.png)
 
+#### 7. 观察 NTP 时间日志
+如下日志信息显示 NTP 对时，设备 publish 获取 NTP 时间的报文，云平台记录接收到设备获取 NTP 时间报文的时间戳 ntptime1，记录给设备回复时的时间戳 ntptime2，将 ntptime1 和 ntptime2 回复给设备，设备接收到云平台的回复报文，通过算法计算出设备上真实的时间，并调用系统时间设置函数设置时间，通过例子程序日志可以看出时间被正确设置。
+windows / linux 平台已经适配时间设置，其他平台需要适配系统时间设置，执行例程时 windows 需要以管理员身份运行程序，linux 需要以超级用户身份运行程序。
+```
+sudo ./output/release/bin/mqtt_sample
+DBG|2020-10-22 10:48:26|mqtt_client_publish.c|qcloud_iot_mqtt_publish(340): publish packetID=0|topicName=$sys/
+operation/S3EUVBRJLB/test_device|payload={"type": "get", "resource": ["time"]}
+DBG|2020-10-22 10:48:27|system_mqtt.c|_system_mqtt_message_callback(47): Recv Msg Topic:$sys/operation/result/
+S3EUVBRJLB/test_device, payload:{"type":"get","time":1603334906,"ntptime1":1603334906594,"ntptime2":1603334906594}
+INF|2020-10-22 10:48:26|system_mqtt.c|IOT_Sync_NTPTime(294): set systime ms success, timestamp 1603334906644 ms
+INF|2020-10-22 10:48:26|mqtt_sample.c|main(325): sync ntp time success!
+
+```
+在 `HAL_Timer_freertos.c HAL_Timer_rtthread.c HAL_Timer_nonos.c` 文件中提供了 `timestamp_to_date` 函数将时间戳转换为年、月、日、时、分、秒、毫秒方便嵌入式设备设置 RTC 时钟。
+`HAL_Timer_set_systime_sec` 设置系统时间函数在 32bit 平台使用; `HAL_Timer_set_systime_ms` 设置系统时间函数在 64bit 平台使用。
 

docs/IoT_Hub/ota_mqtt_subdev_sample网关子设备升级.md

@@ -84,7 +84,7 @@ INF|2020-03-04 16:50:37|ota_mqtt_sample.c|process_ota(389): wait for ota upgrade
 ```
 INF|2020-03-04 16:50:38|ota_mqtt_sample.c|process_ota(389): wait for ota upgrade command...
 DBG|2020-03-04 16:50:39|ota_mqtt.c|_otamqtt_upgrage_cb(103): topic=$ota/update/S3EUVBRJLB/test_device
-INF|2020-03-04 16:50:39|ota_mqtt.c|_otamqtt_upgrage_cb(104): len=454, topic_msg={"file_size":175436,"md5sum":"ad4615b866c13afb8b293a679bfa5dc4","type":"update_firmware","url":"https://ota-1255858890.cos.ap-guangzhou.myqcloud.com/100008768029_S3EUVBRJLB_1.3.0?sign=q-sign-algorithm%3Dsha1%26q-ak%3DAKIDdO8ldrUa0Uts4H5Gzx6FZ9nfedjpiCd7%26q-sign-time%3D1583311839%3B1583398239%26q-key-time%3D1583311839%3B1583398239%26q-header-list%3D%26q-url-param-list%3D%26q-signature%3D1215yt303628f88f31c9a7734ead8a7fa32ed1b3%00","version":"1.3.0"}
+INF|2020-03-04 16:50:39|ota_mqtt.c|_otamqtt_upgrage_cb(104): len=454, topic_msg={"file_size":175436,"md5sum":"ad4615b866c13afb8b293a679bfa5dc4","type":"update_firmware","url":"https://ota-1255858890.cos.ap-guangzhou.myqcloud.com/","version":"1.3.0"}
 
 INF|2020-03-04 16:50:39|ota_mqtt_sample.c|process_ota(389): wait for ota upgrade command...
 ERR|2020-03-04 16:50:39|ota_mqtt_sample.c|_get_local_fw_info(251): open file ./FW_S3EUVBRJLBtest_device.json failed

docs/IoT_Hub/ota_sample_固件升级.md

@@ -185,23 +185,23 @@ void *IOT_Gateway_Get_Mqtt_Client(void *handle);
 
 /* The structure of subdevice bindinfo */
 typedef struct _SubdevBindInfo {
-    char                   product_id[MAX_SIZE_OF_PRODUCT_ID + 1];
-    char                   device_name[MAX_SIZE_OF_DEVICE_NAME + 1];
+    char                    product_id[MAX_SIZE_OF_PRODUCT_ID + 1];
+    char                    device_name[MAX_SIZE_OF_DEVICE_NAME + 1];
     struct _SubdevBindInfo *next;
 } SubdevBindInfo;
 
 /* The structure of subdevice bindlist */
 typedef struct _SubdevBindList {
     SubdevBindInfo *bindlist_head;
-    int bind_num;
+    int             bind_num;
 } SubdevBindList;
 
 /**
  * @brief get sub-device bind list from cloud platform
  *
  * @param client            handle to gateway client
  * @param param             gateway parameters
- * @param subdev_bindlist   output subdev bind list 
+ * @param subdev_bindlist   output subdev bind list
  *
  * @return QCLOUD_RET_SUCCESS for success, or err code for failure
  */
@@ -210,14 +210,13 @@ int IOT_Gateway_Subdev_GetBindList(void *client, GatewayParam *param, SubdevBind
 /**
  * @brief destory sub dev bind list
  *
- * @param subdev_bindlist  input subdev bind list pointer, ref IOT_Gateway_Subdev_GetBindList 
+ * @param subdev_bindlist  input subdev bind list pointer, ref IOT_Gateway_Subdev_GetBindList
  *        output param subdev_bindlist
  *
  * @return QCLOUD_RET_SUCCESS for success, or err code for failure
  */
 void IOT_Gateway_Subdev_DestoryBindList(SubdevBindList *subdev_bindlist);
 
-
 #ifdef __cplusplus
 }
 #endif

include/exports/qcloud_iot_export_gateway.h

@@ -157,6 +157,9 @@ void IOT_Log_Gen(const char *file, const char *func, const int line, const int l
 #define Log_w(fmt, ...) IOT_Log_Gen(__FILE__, __FUNCTION__, __LINE__, eLOG_WARN, fmt, ##__VA_ARGS__)
 #define Log_e(fmt, ...) IOT_Log_Gen(__FILE__, __FUNCTION__, __LINE__, eLOG_ERROR, fmt, ##__VA_ARGS__)
 
+/* check pointer before printf/snprintf */
+#define STRING_PTR_PRINT_SANITY_CHECK(s) ((s) ? (s) : "null")
+
 /* Macro for debug mode */
 #ifdef IOT_DEBUG
 #define IOT_FUNC_ENTRY                                              \

include/exports/qcloud_iot_export_log.h

@@ -23,25 +23,26 @@ extern "C" {
 #define REMOTE_CONFIG_ERRCODE_SUCCESS 0     // get config success
 #define REMOTE_CONFIG_ERRCODE_DISABLE 1001  // Cloud platform has been disabled remote config
 
-#define REMOTE_CONFIG_JSON_BUFFER_MIN_LEN 60 // config json buffer sys need len 
+#define REMOTE_CONFIG_JSON_BUFFER_MIN_LEN 60  // config json buffer sys need len
 
 /**
  * @brief proc config data, subscribe set struct ConfigSubscirbeUserData
  *
  * @param client               MQTTClient pointer
- * @param config_reply_errcode Config ErrCode; ERRCODE_REMOTE_CONFIG_SUCCESS can proc config_json other config_json is invalid
- * @param config_json          config json data string, format is {xxxx}; user config data at cloud platform, pointer is 
+ * @param config_reply_errcode Config ErrCode; ERRCODE_REMOTE_CONFIG_SUCCESS can proc config_json other config_json is
+ invalid
+ * @param config_json          config json data string, format is {xxxx}; user config data at cloud platform, pointer is
                                struct ConfigSubscirbeUserData json_buffer member
- * @param config_json_len      config json data length, 
+ * @param config_json_len      config json data length,
  * @return                     void
  */
 typedef void (*OnConfigProcHandler)(void *client, int config_reply_errcode, char *config_json, int config_json_len);
 
 typedef struct {
-    OnConfigProcHandler on_config_proc;  // config proc callback when message arrived
-    int                 json_buffer_len; // sys json data need 60 B + config json data max len 
-    char *				json_buffer;     // save json buffer [sys json data + config json data] ,sdk proc recv buff
-                                         // save config json data as OnConfigProcHandler functions config_json parameter
+    OnConfigProcHandler on_config_proc;   // config proc callback when message arrived
+    int                 json_buffer_len;  // sys json data need 60 B + config json data max len
+    char *              json_buffer;      // save json buffer [sys json data + config json data] ,sdk proc recv buff
+                        // save config json data as OnConfigProcHandler functions config_json parameter
 } ConfigSubscirbeUserData;
 
 /**

include/exports/qcloud_iot_export_remote_config.h

@@ -30,6 +30,15 @@ extern "C" {
  */
 int IOT_Get_SysTime(void* pClient, long* time);
 
+/**
+ * @brief sync ntp timestamp from MQTT server
+ *
+ * @param pClient           MQTTClient pointer
+ * @return                  QCLOUD_RET_SUCCESS for success
+ *                          otherwise, failure
+ */
+int IOT_Sync_NTPTime(void* pClient);
+
 #ifdef __cplusplus
 }
 #endif

include/exports/qcloud_iot_export_system.h

@@ -304,6 +304,20 @@ char *HAL_Timer_current(char *time_str);
  */
 long HAL_Timer_current_sec(void);
 
+/**
+ * @brief Set timestamp in second to systime/rtc
+ *
+ * @return   0 is success other failed
+ */
+int HAL_Timer_set_systime_sec(size_t timestamp_sec);
+
+/**
+ * @brief Set timestamp in millsecond to systime/rtc
+ *
+ * @return   0 is success other failed
+ */
+int HAL_Timer_set_systime_ms(size_t timestamp_ms);
+
 #ifdef AT_TCP_ENABLED
 int       HAL_AT_TCP_Init(void);
 uintptr_t HAL_AT_TCP_Connect(const char *host, uint16_t port);

include/qcloud_iot_import.h

@@ -57,7 +57,7 @@ uintptr_t HAL_TCP_Connect(const char *host, uint16_t port)
 
     ret = getaddrinfo(host, port_str, &hints, &addr_list);
     if (ret) {
-        Log_e("getaddrinfo(%s:%s) error", host, port_str);
+        Log_e("getaddrinfo(%s:%s) error", STRING_PTR_PRINT_SANITY_CHECK(host), port_str);
         return 0;
     }
 
@@ -78,13 +78,13 @@ uintptr_t HAL_TCP_Connect(const char *host, uint16_t port)
     }
 
     if (ret == 0) {
-        Log_e("failed to connect with TCP server: %s:%s", host, port_str);
+        Log_e("failed to connect with TCP server: %s:%s", STRING_PTR_PRINT_SANITY_CHECK(host), port_str);
     } else {
         /* reduce log print due to frequent log server connect/disconnect */
         if (0 == strncmp(host, LOG_UPLOAD_SERVER_DOMAIN, HOST_STR_LENGTH))
             UPLOAD_DBG("connected with TCP server: %s:%s", host, port_str);
         else
-            Log_i("connected with TCP server: %s:%s", host, port_str);
+            Log_i("connected with TCP server: %s:%s", STRING_PTR_PRINT_SANITY_CHECK(host), port_str);
     }
 
     freeaddrinfo(addr_list);

platform/os/freertos/HAL_TCP_lwip.c

@@ -23,6 +23,7 @@ extern "C" {
 #include <string.h>
 
 #include "qcloud_iot_import.h"
+#include "utils_timer.h"
 
 #define PLATFORM_HAS_TIME_FUNCS
 //#define PLATFORM_HAS_CMSIS
@@ -37,6 +38,45 @@ extern "C" {
 #include "stm32l4xx_hal.h"
 #endif
 
+int HAL_Timer_set_systime_sec(size_t timestamp_sec)
+{
+#if defined PLATFORM_HAS_TIME_FUNCS
+    struct timeval stime;
+    stime.tv_sec  = timestamp_sec;
+    stime.tv_usec = 0;
+    if (0 != settimeofday(&stime, NULL)) {
+        return -1;
+    }
+    return 0;
+#else
+    RTC_DATE_TIME date_time;
+    date_time.ms = 0;
+    timestamp_to_date(timestamp_sec, &date_time, 8);
+    // set RTC Time note hw rtc year base
+    return -1;
+#endif
+}
+
+int HAL_Timer_set_systime_ms(size_t timestamp_ms)
+{
+#if defined PLATFORM_HAS_TIME_FUNCS
+    struct timeval stime;
+    stime.tv_sec  = (timestamp_ms / 1000);
+    stime.tv_usec = ((timestamp_ms % 1000) * 1000);
+
+    if (0 != settimeofday(&stime, NULL)) {
+        return -1;
+    }
+    return 0;
+#else
+    RTC_DATE_TIME date_time;
+    date_time.ms = timestamp_ms % 1000;
+    timestamp_to_date(timestamp_ms / 1000, &date_time, 8);
+    // set RTC Time note hw rtc year base
+    return -1;
+#endif
+}
+
 uint32_t HAL_GetTimeMs(void)
 {
 #if defined PLATFORM_HAS_TIME_FUNCS

platform/os/freertos/HAL_Timer_freertos.c

@@ -46,7 +46,7 @@ uintptr_t HAL_UDP_Connect(const char *host, unsigned short port)
     hints.ai_family   = AF_INET;
     hints.ai_protocol = IPPROTO_UDP;
 
-    Log_d("establish tcp connection with server(host=%s port=%s)", host, port_str);
+    Log_d("establish tcp connection with server(host=%s port=%s)", STRING_PTR_PRINT_SANITY_CHECK(host), port_str);
 
     if (getaddrinfo(host, port_str, &hints, &addr_list) != 0) {
         Log_e("getaddrinfo error,errno:%s", strerror(errno));

platform/os/freertos/HAL_UDP_lwip.c

@@ -108,7 +108,7 @@ int HAL_SetDevInfoFile(const char *file_name)
 
     /* check if file exists */
     if (access(file_name, 0)) {
-        Log_e("device info file \"%s\" not existed", file_name);
+        Log_e("device info file \"%s\" not existed", STRING_PTR_PRINT_SANITY_CHECK(file_name));
         return QCLOUD_ERR_FAILURE;
     }
 
@@ -141,7 +141,7 @@ int HAL_GetDevInfoFromFile(const char *file_name, void *dev_info)
 
     fp = fopen(file_name, "r");
     if (NULL == fp) {
-        Log_e("open device info file \"%s\" failed", file_name);
+        Log_e("open device info file \"%s\" failed", STRING_PTR_PRINT_SANITY_CHECK(file_name));
         ret = QCLOUD_ERR_FAILURE;
         goto exit;
     }
@@ -329,29 +329,30 @@ static int iot_save_devinfo_to_json_file(DeviceInfo *pDevInfo)
 
     // product id, device name
     rc_of_snprintf = HAL_Snprintf(JsonDoc + strlen(JsonDoc), remain_size, "\"%s\":\"%s\",\n\"%s\":\"%s\",\n",
-                                  KEY_PRODUCT_ID, pDevInfo->product_id, KEY_DEV_NAME, pDevInfo->device_name);
+                                  KEY_PRODUCT_ID, STRING_PTR_PRINT_SANITY_CHECK(pDevInfo->product_id), KEY_DEV_NAME,
+                                  STRING_PTR_PRINT_SANITY_CHECK(pDevInfo->device_name));
     remain_size -= rc_of_snprintf;
 
     // product secret
 #ifdef DEV_DYN_REG_ENABLED
     rc_of_snprintf = HAL_Snprintf(JsonDoc + strlen(JsonDoc), remain_size, "\"%s\":\"%s\",\n", KEY_PRODUCT_SECRET,
-                                  pDevInfo->product_secret);
+                                  STRING_PTR_PRINT_SANITY_CHECK(pDevInfo->product_secret));
     remain_size -= rc_of_snprintf;
 #endif
 
     // key device info or cert device info
 #ifdef AUTH_MODE_CERT
     rc_of_snprintf = HAL_Snprintf(JsonDoc + strlen(JsonDoc), remain_size, "\"%s\":{\n", STR_DEV_CERT);
     remain_size -= rc_of_snprintf;
-    rc_of_snprintf =
-        HAL_Snprintf(JsonDoc + strlen(JsonDoc), remain_size, "\"%s\":\"%s\",\n\"%s\":\"%s\"\n}", STR_DEV_CERT_FILE,
-                     pDevInfo->dev_cert_file_name, STR_DEV_KEY_FILE, pDevInfo->dev_key_file_name);
+    rc_of_snprintf = HAL_Snprintf(JsonDoc + strlen(JsonDoc), remain_size, "\"%s\":\"%s\",\n\"%s\":\"%s\"\n}",
+                                  STR_DEV_CERT_FILE, STRING_PTR_PRINT_SANITY_CHECK(pDevInfo->dev_cert_file_name),
+                                  STR_DEV_KEY_FILE, STRING_PTR_PRINT_SANITY_CHECK(pDevInfo->dev_key_file_name));
     remain_size -= rc_of_snprintf;
 #else
     rc_of_snprintf = HAL_Snprintf(JsonDoc + strlen(JsonDoc), remain_size, "\"%s\":{\n", STR_DEV_INFO);
     remain_size -= rc_of_snprintf;
     rc_of_snprintf = HAL_Snprintf(JsonDoc + strlen(JsonDoc), remain_size, "\"%s\":\"%s\"\n}", STR_DEV_SECRET,
-                                  pDevInfo->device_secret);
+                                  STRING_PTR_PRINT_SANITY_CHECK(pDevInfo->device_secret));
     remain_size -= rc_of_snprintf;
 #endif
 

platform/os/linux/HAL_Device_linux.c

@@ -73,9 +73,9 @@ uintptr_t HAL_TCP_Connect(const char *host, uint16_t port)
     ret = getaddrinfo(host, port_str, &hints, &addr_list);
     if (ret) {
         if (ret == EAI_SYSTEM)
-            Log_e("getaddrinfo(%s:%s) error: %s", host, port_str, strerror(errno));
+            Log_e("getaddrinfo(%s:%s) error: %s", STRING_PTR_PRINT_SANITY_CHECK(host), port_str, strerror(errno));
         else
-            Log_e("getaddrinfo(%s:%s) error: %s", host, port_str, gai_strerror(ret));
+            Log_e("getaddrinfo(%s:%s) error: %s", STRING_PTR_PRINT_SANITY_CHECK(host), port_str, gai_strerror(ret));
         return 0;
     }
 
@@ -96,13 +96,13 @@ uintptr_t HAL_TCP_Connect(const char *host, uint16_t port)
     }
 
     if (0 == ret) {
-        Log_e("fail to connect with TCP server: %s:%s", host, port_str);
+        Log_e("fail to connect with TCP server: %s:%s", STRING_PTR_PRINT_SANITY_CHECK(host), port_str);
     } else {
         /* reduce log print due to frequent log server connect/disconnect */
         if (0 == strncmp(host, LOG_UPLOAD_SERVER_DOMAIN, HOST_STR_LENGTH))
             UPLOAD_DBG("connected with TCP server: %s:%s", host, port_str);
         else
-            Log_i("connected with TCP server: %s:%s", host, port_str);
+            Log_i("connected with TCP server: %s:%s", STRING_PTR_PRINT_SANITY_CHECK(host), port_str);
     }
 
     freeaddrinfo(addr_list);

platform/os/linux/HAL_TCP_linux.c

@@ -82,6 +82,30 @@ long HAL_Timer_current_sec(void)
     return tv.tv_sec;
 }
 
+int HAL_Timer_set_systime_sec(size_t timestamp_sec)
+{
+    struct timeval stime;
+    stime.tv_sec  = timestamp_sec;
+    stime.tv_usec = 0;
+
+    if (0 != settimeofday(&stime, NULL)) {
+        return -1;
+    }
+    return 0;
+}
+
+int HAL_Timer_set_systime_ms(size_t timestamp_ms)
+{
+    struct timeval stime;
+    stime.tv_sec  = (timestamp_ms / 1000);
+    stime.tv_usec = ((timestamp_ms % 1000) * 1000);
+
+    if (0 != settimeofday(&stime, NULL)) {
+        return -1;
+    }
+    return 0;
+}
+
 #ifdef __cplusplus
 }
 #endif

platform/os/linux/HAL_Timer_linux.c

@@ -47,7 +47,7 @@ uintptr_t HAL_UDP_Connect(const char *host, unsigned short port)
     hints.ai_family   = AF_INET;
     hints.ai_protocol = IPPROTO_UDP;
 
-    Log_d("establish tcp connection with server(host=%s port=%s)", host, port_str);
+    Log_d("establish tcp connection with server(host=%s port=%s)", STRING_PTR_PRINT_SANITY_CHECK(host), port_str);
 
     if (getaddrinfo(host, port_str, &hints, &addr_list) != 0) {
         Log_e("getaddrinfo error,errno:%s", strerror(errno));