General Description

C APIs provided by the MQTT library.

All library API functions except cy_mqtt_init and cy_mqtt_deinit are thread safe.

Typedefs
typedef void(*	cy_mqtt_callback_t) (cy_mqtt_t mqtt_handle, cy_mqtt_event_t event, void *user_data)
	MQTT event callback functions type used to process the disconnect event and incoming MQTT publish packets received from the MQTT broker. More...

Functions
cy_rslt_t	cy_mqtt_init (void)
	Performs network sockets initialization required for the MQTT library. More...

cy_rslt_t	cy_mqtt_create (uint8_t buffer, uint32_t buff_len, cy_awsport_ssl_credentials_t security, cy_mqtt_broker_info_t broker_info, char descriptor, cy_mqtt_t *mqtt_handle)
	Creates an MQTT instance and initializes its members based on the supplied arguments. More...

cy_rslt_t	cy_mqtt_connect (cy_mqtt_t mqtt_handle, cy_mqtt_connect_info_t *connect_info)
	Connects to the given MQTT broker using a secured/non-secured TCP connection and establishes MQTT client session with the broker. More...

cy_rslt_t	cy_mqtt_get_handle (cy_mqtt_t mqtt_handle, char descriptor)
	Gets the MQTT handle associated with a user defined descriptor passed in cy_mqtt_create. More...

cy_rslt_t	cy_mqtt_publish (cy_mqtt_t mqtt_handle, cy_mqtt_publish_info_t *pub_msg)
	Publishes the MQTT message on given MQTT topic. More...

cy_rslt_t	cy_mqtt_subscribe (cy_mqtt_t mqtt_handle, cy_mqtt_subscribe_info_t *sub_info, uint8_t sub_count)
	Subscribes for MQTT message on the given MQTT topic or list of topics. More...

cy_rslt_t	cy_mqtt_register_event_callback (cy_mqtt_t mqtt_handle, cy_mqtt_callback_t event_callback, void *user_data)
	Registers an event callback for the given MQTT handle. More...

cy_rslt_t	cy_mqtt_deregister_event_callback (cy_mqtt_t mqtt_handle, cy_mqtt_callback_t event_callback)
	Deregisters an event callback for the given MQTT handle which was previously registered using cy_mqtt_register_event_callback API. More...

cy_rslt_t	cy_mqtt_unsubscribe (cy_mqtt_t mqtt_handle, cy_mqtt_unsubscribe_info_t *unsub_info, uint8_t unsub_count)
	Unsubscribes from a given MQTT topic. More...

cy_rslt_t	cy_mqtt_disconnect (cy_mqtt_t mqtt_handle)
	Initiates MQTT client disconnection from connected MQTT broker. More...

cy_rslt_t	cy_mqtt_delete (cy_mqtt_t mqtt_handle)
	Deletes the given MQTT instance and frees the resources allocated for the instance by the cy_mqtt_create function. More...

cy_rslt_t	cy_mqtt_deinit (void)
	One-time deinitialization function for network sockets implementation. More...

cy_rslt_t	cy_mqtt_stop_keepalive (cy_mqtt_t mqtt_handle)
	This API will stop monitoring the keep-alive intervals and does not send keep-alive request for the configured interval. More...

cy_rslt_t	cy_mqtt_start_keepalive (cy_mqtt_t mqtt_handle)
	This API will start monitoring the keep-alive intervals and start sending keep-alive request for the configured interval. More...

cy_rslt_t	cy_mqtt_get_socket (cy_mqtt_t mqtt_handle, cy_socket_t *socket)
	This API will return the socket handle for the given MQTT handle which is used to get socket info like local and peer IP address and port. More...

Typedef Documentation

◆ cy_mqtt_callback_t

typedef void(* cy_mqtt_callback_t) (cy_mqtt_t mqtt_handle, cy_mqtt_event_t event, void *user_data)

MQTT event callback functions type used to process the disconnect event and incoming MQTT publish packets received from the MQTT broker.

Note: MQTT library functions should not be invoked from this callback function.

Parameters

mqtt_handle	[in] : MQTT handle.
event	[in] : MQTT event information. For event values refer cy_mqtt_event_t .
user_data	[in] : Pointer to user data provided during cy_mqtt_create.

Returns: : void

Function Documentation

◆ cy_mqtt_init()

cy_rslt_t cy_mqtt_init ( void )

Performs network sockets initialization required for the MQTT library.

It must be called once (and only once) before calling any other function in this library.

This API is supported in multi-core environment and must be invoked on the secondary core application before calling any other virtual MQTT APIs.

Note: cy_mqtt_init and cy_mqtt_deinit API functions are not thread-safe. The caller must ensure that these two API functions are not invoked simultaneously from different threads.

Returns: cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.

◆ cy_mqtt_create()

cy_rslt_t cy_mqtt_create	(	uint8_t *	buffer,
		uint32_t	buff_len,
		cy_awsport_ssl_credentials_t *	security,
		cy_mqtt_broker_info_t *	broker_info,
		char *	descriptor,
		cy_mqtt_t *	mqtt_handle
	)

Creates an MQTT instance and initializes its members based on the supplied arguments.

Initializes the core AWS MQTT library and its components. The handle to the MQTT instance is returned via the handle pointer supplied by the user on success. This handle is used for creating MQTT connection with MQTT broker. Same handle is used for MQTT Publish, Subscribe, and Unsubscribing from MQTT topic. Note: To receive notification of events like availability of data for subscribed topic, or network disconnection, use cy_mqtt_register_event_callback.

Parameters

buffer	[in] : Network buffer for send and receive. Application needs to allocate memory for network buffer and should not be freed until MQTT object is deleted. The minimum buffer size is defined by CY_MQTT_MIN_NETWORK_BUFFER_SIZE. Please make sure the buffer allocated is larger than CY_MQTT_MIN_NETWORK_BUFFER_SIZE. This buffer is used for sending and receiving MQTT packets over the network. Hence, the buffer size should be sufficiently large enough to hold the MQTT packet header and payload. For example: To send/receive the MQTT payload of 4 kb, it's recommended to allocate 4.5 kb or more buffer.
buff_len	[in] : Network buffer length in bytes.
security	[in] : Credentials for TLS connection. Application needs to allocate memory for keys, certs, and sni/user names should not be freed until MQTT object is deleted.
broker_info	[in] : MQTT broker information. Refer cy_mqtt_broker_info_t for details.
descriptor	: A string that describes the MQTT handle that is being created in order to uniquely identify it.
mqtt_handle	[out] : Pointer to store the MQTT handle allocated by this function on successful return.

Returns: cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.

◆ cy_mqtt_connect()

cy_rslt_t cy_mqtt_connect	(	cy_mqtt_t	mqtt_handle,
		cy_mqtt_connect_info_t *	connect_info
	)

Connects to the given MQTT broker using a secured/non-secured TCP connection and establishes MQTT client session with the broker.

Parameters

mqtt_handle	[in] : MQTT handle created using cy_mqtt_create.
connect_info	[in] : MQTT connection parameters. Refer cy_mqtt_connect_info_t for details.

Returns: cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.

◆ cy_mqtt_get_handle()

cy_rslt_t cy_mqtt_get_handle	(	cy_mqtt_t *	mqtt_handle,
		char *	descriptor
	)

Gets the MQTT handle associated with a user defined descriptor passed in cy_mqtt_create.

This API is supported in multi-core environment and can be invoked from the secondary core application.

Parameters

mqtt_handle	[out] : Pointer to store the MQTT handle that corresponds to the descriptor.
descriptor	[in] : NULL terminated string that uniquely identifies the MQTT handle. Note: The maximum permissible length of the string is 20 characters (excluding the null character).

Returns: cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.

◆ cy_mqtt_publish()

cy_rslt_t cy_mqtt_publish	(	cy_mqtt_t	mqtt_handle,
		cy_mqtt_publish_info_t *	pub_msg
	)

Publishes the MQTT message on given MQTT topic.

This API is supported in multi-core environment and can be invoked from the secondary core application.

Parameters

mqtt_handle	[in] : MQTT handle created using cy_mqtt_create.
pub_msg	[in] : MQTT publish message information. Refer cy_mqtt_publish_info_t for details.

Returns: cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.

◆ cy_mqtt_subscribe()

cy_rslt_t cy_mqtt_subscribe	(	cy_mqtt_t	mqtt_handle,
		cy_mqtt_subscribe_info_t *	sub_info,
		uint8_t	sub_count
	)

Subscribes for MQTT message on the given MQTT topic or list of topics.

This API is supported in multi-core environment and can be invoked from the secondary core application.

Note

Single subscription request with multiple topics, this function returns success if at least one of the subscription is successful. If subscription fails for any of the topic in the list, the failure is indicated through 'allocated_qos' set to CY_MQTT_QOS_INVALID. Refer cy_mqtt_subscribe_info_t for more details. Upon return, the 'allocated_qos' indicate the QoS level allocated by the MQTT broker for the successfully subscribed topic.
Call cy_mqtt_register_event_callback before calling this API in order to be notified of data available for the subscribed topic(s).

Parameters

mqtt_handle	[in] : MQTT handle created using cy_mqtt_create.
sub_info	[in, out] : Pointer to array of MQTT subscription information structure. Refer cy_mqtt_subscribe_info_t for details.
sub_count	[in] : Number of subscription topics in the subscription array.

Returns: cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.

◆ cy_mqtt_register_event_callback()

cy_rslt_t cy_mqtt_register_event_callback	(	cy_mqtt_t	mqtt_handle,
		cy_mqtt_callback_t	event_callback,
		void *	user_data
	)

Registers an event callback for the given MQTT handle.

This API is supported in multi-core environment and can be invoked as a virtual API from the secondary core application.

Parameters

mqtt_handle	[in] : MQTT handle created using cy_mqtt_create.
event_callback	[in] : Application callback function which needs to be called on arrival of MQTT incoming publish packets and network disconnection notification from network layer.
user_data	[in] : Pointer to user data to be passed in the event callback.

Returns: cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.

◆ cy_mqtt_deregister_event_callback()

cy_rslt_t cy_mqtt_deregister_event_callback	(	cy_mqtt_t	mqtt_handle,
		cy_mqtt_callback_t	event_callback
	)

Deregisters an event callback for the given MQTT handle which was previously registered using cy_mqtt_register_event_callback API.

This API is supported in multi-core environment and can be invoked as a virtual API from the secondary core application.

Parameters

mqtt_handle	[in] : MQTT handle created using cy_mqtt_create.
event_callback	[in] : Callback function which needs to be deregistered.

Returns: cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.

◆ cy_mqtt_unsubscribe()

cy_rslt_t cy_mqtt_unsubscribe	(	cy_mqtt_t	mqtt_handle,
		cy_mqtt_unsubscribe_info_t *	unsub_info,
		uint8_t	unsub_count
	)

Unsubscribes from a given MQTT topic.

This API is supported in multi-core environment and can be invoked as a virtual API from the secondary core application.

Parameters

mqtt_handle	[in] : MQTT handle created using cy_mqtt_create.
unsub_info	[in] : Pointer to array of MQTT unsubscription information structure. Refer cy_mqtt_unsubscribe_info_t for details.
unsub_count	[in] : Number of unsubscription topics in the unsubscription array.

Returns: cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.

◆ cy_mqtt_disconnect()

cy_rslt_t cy_mqtt_disconnect ( cy_mqtt_t mqtt_handle )

Initiates MQTT client disconnection from connected MQTT broker.

Parameters

mqtt_handle [in] : MQTT handle created using cy_mqtt_create.

Returns: cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.

◆ cy_mqtt_delete()

cy_rslt_t cy_mqtt_delete ( cy_mqtt_t mqtt_handle )

Deletes the given MQTT instance and frees the resources allocated for the instance by the cy_mqtt_create function.

Before calling this API function, MQTT connection with broker must be disconnected. And the MQTT handle should not be used after delete.

Parameters

mqtt_handle [in] : MQTT handle created using cy_mqtt_create.

Returns: cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.

◆ cy_mqtt_deinit()

cy_rslt_t cy_mqtt_deinit ( void )

One-time deinitialization function for network sockets implementation.

It should be called after destroying all network socket connections.

This API is supported in multi-core environment and can be invoked on the secondary core application to clean up the MQTT virtual-only stack implementation. It should be called when the MQTT virtual APIs are no longer needed.

Note: cy_mqtt_init and cy_mqtt_deinit API functions are not thread-safe. The caller must ensure that these two API functions are not invoked simultaneously from different threads.

Returns: cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.

◆ cy_mqtt_stop_keepalive()

cy_rslt_t cy_mqtt_stop_keepalive ( cy_mqtt_t mqtt_handle )

This API will stop monitoring the keep-alive intervals and does not send keep-alive request for the configured interval.

This API can be used to stop sending keepalive request packets from host when MQTT keepalive is offloaded to WLAN FW.

Parameters

mqtt_handle [in] : MQTT handle created using cy_mqtt_create.

Returns: cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.

◆ cy_mqtt_start_keepalive()

cy_rslt_t cy_mqtt_start_keepalive ( cy_mqtt_t mqtt_handle )

This API will start monitoring the keep-alive intervals and start sending keep-alive request for the configured interval.

User need to invoke this API only if he has called cy_mqtt_stop_keepalive.

Parameters

mqtt_handle [in] : MQTT handle created using cy_mqtt_create.

Returns: cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.

◆ cy_mqtt_get_socket()

cy_rslt_t cy_mqtt_get_socket	(	cy_mqtt_t	mqtt_handle,
		cy_socket_t *	socket
	)

This API will return the socket handle for the given MQTT handle which is used to get socket info like local and peer IP address and port.

Parameters

mqtt_handle	[in] : MQTT handle created using cy_mqtt_create.
socket	[out] : Pointer to store the socket handle for given MQTT handle created using cy_mqtt_create.

Returns: cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.

General Description

Typedefs

Functions

Typedef Documentation

◆ cy_mqtt_callback_t

Function Documentation

◆ cy_mqtt_init()

◆ cy_mqtt_create()

◆ cy_mqtt_connect()

◆ cy_mqtt_get_handle()

◆ cy_mqtt_publish()

◆ cy_mqtt_subscribe()

◆ cy_mqtt_register_event_callback()

◆ cy_mqtt_deregister_event_callback()

◆ cy_mqtt_unsubscribe()

◆ cy_mqtt_disconnect()

◆ cy_mqtt_delete()

◆ cy_mqtt_deinit()

◆ cy_mqtt_stop_keepalive()

◆ cy_mqtt_start_keepalive()

◆ cy_mqtt_get_socket()