Communicate with IoT Platform by using custom MQTT topics - IoT Platform

You can call the Message Queuing Telemetry Transport (MQTT) API operations of an IoT Platform SDK to communicate with IoT Platform. You can send data to IoT Platform by sending messages to specified topics or subscribe to specified topics to obtain data from IoT Platform. You must create the topics that are used to communicate with IoT Platform.

Communication process

The following figure shows how to communicate with IoT Platform by using MQTT topics.

Call the IOT_MQTT_Construct() operation to establish a persistent connection between a device and IoT Platform.
- The IOT_MQTT_Construct() operation is used to send connection requests to IoT Platform. You can call the IOT_Sign_MQTT() operation of the dev_sign feature to obtain the required signature information.
- After the connection is established, the handle parameter is returned. The value of the parameter is a connection handle. You can specify the handle as the value of a request parameter for all subsequent MQTT API operations.
Call the IOT_MQTT_Subscribe() operation to notify IoT Platform of the information about the topics whose messages are received by the device.
Go to the main business loop.
- Call the IOT_MQTT_Publish() or IOT_MQTT_Publish_Simple() operation to send messages to IoT Platform.
- Call the IOT_MQTT_Yield() operation to receive downstream messages from IoT Platform. Then, call the callback function that you specified in the IOT_MQTT_Subscribe() operation to process data.

API operations

Operation	Description
IOT_MQTT_CheckStateNormal	Checks whether a persistent connection is normal after the MQTT connection is established.
IOT_MQTT_Construct	Constructs an MQTT instance. The value of the request parameter is an `iotx_mqtt_param_t` struct that is required to connect to the MQTT server. The response is a handle that is linked to a created MQTT instance.
IOT_MQTT_Destroy	Destroys an MQTT instance. The value of the request parameter is a handle that is returned by the `IOT_MQTT_Construct()` operation.
IOT_MQTT_Publish	Creates a complete `MQTT Publish` packet and sends the packet to the server during an MQTT session.
IOT_MQTT_Publish_Simple	Creates a complete `MQTT Publish` packet and sends the packet to the server during an MQTT session. The value of the request parameter does not contain data of a complex data type, such as a struct.
IOT_MQTT_Subscribe	Creates a complete `MQTT Subscribe` packet and sends the packet to the server during an MQTT session.
IOT_MQTT_Subscribe_Sync	Creates a complete `MQTT Subscribe` packet and sends the packet to the server during an MQTT session and waits for the response.
IOT_MQTT_Unsubscribe	Creates a complete `MQTT UnSubscribe` packet and sends the packet to the server during an MQTT session.
IOT_MQTT_Yield	Provides a function that implements the main business logic in a loop. The function is used to check heartbeats and receive upstream packets from the server.

HAL functions

The following section describes optional functions. If you want an IoT Platform SDK to provide MQTT connections, you must implement these functions.

Function	Description
HAL_SSL_Destroy	Destroys a Transport Layer Security (TLS) connection. The function is required when you use MQTT features and encrypted connections.
HAL_SSL_Establish	Establishes a TLS connection. The function is required when you use MQTT features and encrypted connections.
HAL_SSL_Read	Reads data from a TLS connection. The function is required when you use MQTT features and encrypted connections.
HAL_SSL_Write	Writes data to a TLS connection. The function is required when you use MQTT features and encrypted connections.
HAL_TCP_Destroy	Destroys a TLS connection. The function is required when you use MQTT features.
HAL_TCP_Establish	Establishes a TCP connection and performs the domain name resolution.
HAL_TCP_Read	Reads data streams from a TCP connection and returns the number of bytes that are read during the specified time.
HAL_TCP_Write	Sends data streams to a TCP connection and returns the number of bytes that are sent during the specified time.

Note

The src/mqtt/mqtt_api.h file contains the API operations that you can call by using an IoT Platform SDK. The src/mqtt/mqtt_wrapper.h file contains the HAL functions that you may need to implement. For more information, see the code in the files.