The header files for API function declarations, constants, and variable parameter definitions that are provided for user invocation in the device-side C SDK are located under the include directory. This document mainly describes the variable parameters and API functions under this directory.
Variable Parameter Configuration
The C SDK is based on the MQTT protocol. It can configure appropriate parameters according to specific scenario requirements to meet the needs of actual business operations. Variable access parameters include:
1. The timeout period for MQTT blocking calls (including connection, subscribe, publish, etc.), unit: millisecond. Recommend 5000 milliseconds.
2. The buffer size for sending and receiving messages of the MQTT protocol defaults to 2048 bytes, supports up to 16KB.
3. MQTT heartbeat message sending interval, maximum value: 690 seconds, unit: millisecond.
4. Maximum reconnection waiting time, unit: millisecond. When a device disconnects and attempts to reconnect, if it fails, the waiting time will double. If it exceeds this maximum waiting time, the reconnection will be exited.
Modify the
include/qcloud_iot_export_variables.h file. The macro definition can modify the parameter configuration of the corresponding access. After modification, the SDK needs to be recompiled. Sample code is as follows:/* default MQTT/CoAP timeout value when connect/pub/sub (unit: ms) */#define QCLOUD_IOT_MQTT_COMMAND_TIMEOUT (5 * 1000)/* default MQTT keep alive interval (unit: ms) */#define QCLOUD_IOT_MQTT_KEEP_ALIVE_INTERNAL (240 * 1000)/* default MQTT Tx buffer size, MAX: 16*1024 */#define QCLOUD_IOT_MQTT_TX_BUF_LEN (2048)/* default MQTT Rx buffer size, MAX: 16*1024 */#define QCLOUD_IOT_MQTT_RX_BUF_LEN (2048)/* default COAP Tx buffer size, MAX: 1*1024 */#define COAP_SENDMSG_MAX_BUFLEN (512)/* default COAP Rx buffer size, MAX: 1*1024 */#define COAP_RECVMSG_MAX_BUFLEN (512)/* MAX MQTT reconnect interval (unit: ms) */#define MAX_RECONNECT_WAIT_INTERVAL (60 * 1000)
API Function Description
The main features provided by C SDK v3.1.0 and the corresponding API descriptions are for customers to write business logic, with more detailed explanations. For example: API parameters and return values can be viewed in the comments of header files such as SDK code
include/exports/qcloud_iot_export_*.h.Thing Model API
No. | Function Name | Description |
1 | IOT_Template_Construct | Construct a Thing Model client Data_template_client and connect to the MQTT cloud service. |
2 | IOT_Template_Destroy | Close the Data_template MQTT connection and terminate the Data_template Client. |
3 | IOT_Template_Yield | Perform MQTT message reading, message processing, timeout request, heartbeat packet, and reconnection state management tasks in the current Thread Context. |
4 | IOT_Template_Publish | The Thing Model client publishes an MQTT message. |
5 | IOT_Template_Subscribe | The Thing Model client subscribes to an MQTT topic. |
6 | IOT_Template_Unsubscribe | The Thing Model client unsubscribes from the subscribed MQTT topic. |
7 | IOT_Template_IsConnected | View whether the MQTT of the current Thing Model client is connected. |
Model attribute API
No. | Function Name | Description |
1 | IOT_Template_Register_Property | Register the model attributes of the current device. |
2 | IOT_Template_UnRegister_Property | Delete the registered model attributes. |
3 | IOT_Template_Report | Submit Thing Model attribute data asynchronously. |
4 | IOT_Template_Report_Sync | Synchronously report the data of the device model attribute. |
5 | IOT_Template_GetStatus | Retrieve Thing Model attribute data asynchronously. |
6 | IOT_Template_GetStatus_sync | Synchronize and obtain device model attribute data. |
7 | IOT_Template_Report_SysInfo | Submit system information asynchronously. |
8 | IOT_Template_Report_SysInfo_Sync | Synchronize and submit system information. |
9 | IOT_Template_JSON_ConstructSysInfo | Construct the system information to be reported. |
10 | IOT_Template_ControlReply | Reply to the received device model attribute control messages. |
11 | IOT_Template_ClearControl | Delete the device model attribute control messages and cooperate with IOT_Template_GetStatus to obtain and use the control messages. |
Thing Model Event Interface
No. | Function Name | Description |
1 | IOT_Post_Event | Report device model events, import events, and the SDK completes the construction of event messages. |
2 | IOT_Post_Event_Raw | Report device model events, import data that meets the event message format, and the SDK completes the reporting. |
3 | IOT_Event_setFlag | Set event flag. The SDK supports 10 events by default and can be expanded. |
4 | IOT_Event_clearFlag | Clear event flags. |
5 | IOT_Event_getFlag | Retrieve event flags. |
Thing Model Behavior Interface
No. | Function Name | Description |
1 | IOT_ACTION_REPLY | Reply to the Thing Model behavior message. |
Multi-threaded environment usage instructions
SDK has the following precautions for use in a multi-threaded environment:
Multi-threaded calls to IOT_Template_Yield, IOT_Template_Construct and IOT_Template_Destroy are not allowed.
IOT_Template_Yield, as a function to read and process MQTT messages from the socket, should ensure a certain execution time and avoid being suspended or preempted for a long time.
OTA API
No. | Function Name | Description |
1 | IOT_OTA_Init | Initialize the OTA module. The client needs to initialize MQTT/COAP first before calling this API. |
2 | IOT_OTA_Destroy | Release resources related to the OTA module. |
3 | IOT_OTA_ReportVersion | Report local firmware version information to the OTA server. |
4 | IOT_OTA_IsFetching | Check if it is in the state of downloading firmware. |
5 | IOT_OTA_IsFetchFinish | Check if the firmware has been downloaded completely. |
6 | IOT_OTA_FetchYield | Retrieve firmware from a remote server with a specific timeout period. |
7 | IOT_OTA_Ioctl | Retrieve specified OTA information. |
8 | IOT_OTA_GetLastError | Retrieve the last error code. |
9 | IOT_OTA_StartDownload | Establish an HTTP connection with the firmware server based on the obtained firmware update address and the offset of the local firmware information (whether to resume from the breakpoint). |
10 | IOT_OTA_UpdateClientMd5 | Calculate the MD5 of the local firmware before resuming from the breakpoint. |
11 | IOT_OTA_ReportUpgradeBegin | Report the status of the upcoming upgrade to the server before performing the firmware upgrade. |
12 | IOT_OTA_ReportUpgradeSuccess | Report the successfully upgraded status to the server after the firmware upgrade is successful. |
13 | IOT_OTA_ReportUpgradeFail | Report the upgrade failure status to the server after the firmware upgrade fails. |
Log API
For a detailed description of the device log reporting functionality to the cloud, please refer to the device log reporting feature section in the IoT communication platform document under the SDK docs directory.
No. | Function Name | Description |
1 | IOT_Log_Set_Level | Set the print level of the SDK log. |
2 | IOT_Log_Get_Level | Return the print level of the SDK log. |
3 | IOT_Log_Set_MessageHandler | Set the log callback function and redirect the SDK log to other output methods. |
4 | IOT_Log_Init_Uploader | Enable the feature of SDK log reporting to the cloud and initialize resources. |
5 | IOT_Log_Fini_Uploader | Disable the feature of SDK log reporting to the cloud and release resources. |
6 | IOT_Log_Upload | Report the SDK running log to the cloud. |
7 | IOT_Log_Set_Upload_Level | Set the report level of the SDK log. |
8 | IOT_Log_Get_Upload_Level | Return the report level of the SDK log. |
9 | Log_d/i/w/e | Print the API for adding SDK logs by level. |
System Time API
No. | Function Name | Description |
1 | IOT_Get_SysTime | Retrieve the time of the IoT Hub backend system. Currently only support the synchronization feature via MQTT channel. |