This module provides implementation of MQTT wrapper for Paho MQTT.

MQ Telemetry Transport (MQTT) is a lightweight broker-based publish/subscribe messaging protocol designed to be open, simple, lightweight and easy to implement.

Revision history 2014/10/07 : Initial draft. (v1.0)

Data Structures
struct	mqtt_client_pool

struct	mqtt_config
	MQTT configuration structure. More...

union	mqtt_data
	Structure of the MQTT callback. More...

struct	mqtt_data_connected
	Structure of the MQTT_CALLBACK_CONNECTED callback. More...

struct	mqtt_data_disconnected
	Structure of the MQTT_CALLBACK_DISCONNECTED callback. More...

struct	mqtt_data_ping
	Structure of the MQTT_CALLBACK_SENT_PING callback. More...

struct	mqtt_data_published
	Structure of the MQTT_CALLBACK_PUBLISHED callback. More...

struct	mqtt_data_sock_connected
	Structure of the MQTT_CALLBACK_SOCK_CONNECTED callback. More...

struct	mqtt_data_subscribed
	Structure of the MQTT_CALLBACK_SUBSCRIBED callback. More...

struct	mqtt_data_unsubscribed
	Structure of the MQTT_CALLBACK_UNSUBSCRIBED callback. More...

struct	mqtt_module
	Structure of MQTT connection instance. More...

Typedefs
typedef void(*	mqtt_callback_t )(struct mqtt_module module_inst, int type, union mqtt_data data)
	Callback interface of MQTT service. More...

Enumerations
enum	mqtt_callback_type { MQTT_CALLBACK_SOCK_CONNECTED, MQTT_CALLBACK_CONNECTED, MQTT_CALLBACK_PUBLISHED, MQTT_CALLBACK_SUBSCRIBED, MQTT_CALLBACK_UNSUBSCRIBED, MQTT_CALLBACK_DISCONNECTED, MQTT_CALLBACK_SENT_PING }
	A type of MQTT callback. More...

enum	mqtt_conn_result { MQTT_CONN_RESULT_ACCEPT = 0, MQTT_CONN_RESULT_UNACCEPTABLE_VERSION, MQTT_CONN_RESULT_ID_REJECTED, MQTT_CONN_RESULT_SERVER_UNAVAILABLE, MQTT_CONN_RESULT_BAD_USER_NAME, MQTT_CONN_RESULT_NOT_AUTHORIZED }
	Connect return code. More...

Functions
int	mqtt_connect (struct mqtt_module const module, const char host)
	Connect to specific MQTT broker server. More...

int	mqtt_connect_broker (struct mqtt_module const module, uint8_t clean_session, const char id, const char password, const char client_id, const char will_topic, const char will_msg, uint32_t will_msg_len, uint8_t will_qos, uint8_t will_retain)
	Send MQTT connect message to broker server with MQTT parameter. More...

int	mqtt_deinit (struct mqtt_module *const module)
	Termivate MQTT service. More...

int	mqtt_disconnect (struct mqtt_module *const module, int force_close)
	Send disconnect message to MQTT broker server and closing socket. More...

void	mqtt_get_config_defaults (struct mqtt_config *const config)
	Get default configuration of SW timer. More...

int	mqtt_init (struct mqtt_module module, struct mqtt_config config)
	Initialize MQTT service. More...

int	mqtt_publish (struct mqtt_module const module, const char topic, const char *msg, uint32_t msg_len, uint8_t qos, uint8_t retain)
	Send publish message to MQTT broker server. More...

int	mqtt_register_callback (struct mqtt_module *const module, mqtt_callback_t callback)
	Register and enable the callback. More...

void	mqtt_socket_event_handler (SOCKET sock, uint8_t msg_type, void *msg_data)
	Event handler of socket event. More...

void	mqtt_socket_resolve_handler (uint8_t *doamin_name, uint32_t server_ip)
	Event handler of gethostbyname. More...

int	mqtt_subscribe (struct mqtt_module const module, const char topic, uint8_t qos, messageHandler msgHandler)
	Send subscribe message to MQTT broker server. More...

int	mqtt_unregister_callback (struct mqtt_module *const module)
	Unregister callback. More...

int	mqtt_unsubscribe (struct mqtt_module const module, const char topic)
	Send unsubscribe message to MQTT broker server. More...

int	mqtt_yield (struct mqtt_module *module, int timeout_ms)
	Poll for published frames. More...

Variables
struct mqtt_client_pool	mqttClientPool [MQTT_MAX_CLIENTS]
	Static Client Pool Allocation. More...

typedef void(* mqtt_callback_t)(struct mqtt_module *module_inst, int type, union mqtt_data *data)

Callback interface of MQTT service.

enum mqtt_callback_type

A type of MQTT callback.

Enumerator
MQTT_CALLBACK_SOCK_CONNECTED	Socket was connected. After received this event, try connect to broker server using mqtt_connect_broker.
MQTT_CALLBACK_CONNECTED	MQTT connection was connected to broker server.
MQTT_CALLBACK_PUBLISHED	The publish operation is completed.
MQTT_CALLBACK_SUBSCRIBED	The subscribe operation is completed.
MQTT_CALLBACK_UNSUBSCRIBED	The unsubscribe operation is completed.
MQTT_CALLBACK_DISCONNECTED	The disconnection operation is completed.
MQTT_CALLBACK_SENT_PING	The PING operation is completed.

enum mqtt_conn_result

Connect return code.

The connect return code is sent in the variable header of a CONNACK message.

Enumerator
MQTT_CONN_RESULT_ACCEPT	Connection Accepted.
MQTT_CONN_RESULT_UNACCEPTABLE_VERSION	Connection Refused: unacceptable protocol version.
MQTT_CONN_RESULT_ID_REJECTED	Connection Refused: identifier rejected.
MQTT_CONN_RESULT_SERVER_UNAVAILABLE	Connection Refused: server unavailable.
MQTT_CONN_RESULT_BAD_USER_NAME	Connection Refused: bad user name or password.
MQTT_CONN_RESULT_NOT_AUTHORIZED	Connection Refused: not authorized.

int mqtt_connect	(	struct mqtt_module *const	module,
		const char *	host
	)

Connect to specific MQTT broker server.

This function is responsible only connect the socket. If operation of this function is complete, MQTT_CALLBACK_SOCK_CONNECTED event will be sent through MQTT callback.

Parameters

[in]	module_inst	Instance of MQTT module.
[in]	host	URL of MQTT broker server.

Returns: 0 Function succeeded; -ENOENT No such address.; -EINVAL Invalid argument.; -ENOSPC No space left on device.; -EIO Device was occurred error due to unknown exception.; -EDESTADDRREQ Destination address required.; -ECONNRESET Connection reset by peer.; -EAGAIN Try again.; -EBUSY Device or resource busy.; -EADDRINUSE Address already in use.; -EALREADY Socket already connected.; -ENOTCONN Service in bad state.; -ECONNREFUSED Connection refused.; -EOVERFLOW Value too large for defined data type.; -EBADMSG Not a data message.

References mqtt_module::callback, mqtt_module::config, ConnectNetwork(), MQTT_CALLBACK_SOCK_CONNECTED, mqtt_module::network, mqtt_config::port, mqtt_data_sock_connected::result, mqtt_data::sock_connected, and mqtt_config::tls.

Referenced by mqtt_callback(), and wifi_callback().

int mqtt_connect_broker	(	struct mqtt_module *const	module,
		uint8_t	clean_session,
		const char *	id,
		const char *	password,
		const char *	client_id,
		const char *	will_topic,
		const char *	will_msg,
		uint32_t	will_msg_len,
		uint8_t	will_qos,
		uint8_t	will_retain
	)

Send MQTT connect message to broker server with MQTT parameter.

If operation of this function is complete, MQTT_CALLBACK_CONNECTED event will be sent through MQTT callback.

Parameters

[in]	module_inst	Instance of MQTT module.
[in]	clean_session	If this value set to 1, Broker server store the previous subscribed informations after disconnected.
[in]	id	ID of user.
[in]	password	Password of user.
[in]	client_id	Client ID of this connection.
[in]	will_topic	A MQTT topic that will be sent to subscribers when this connection is disconnected.
[in]	will_msg	A MQTT payload that will be sent to subscribers when this connection is disconnected.
[in]	will_qos	QOS level of will message.
[in]	will_retain	Whether broker server will be store MQTT will message or not.

Returns: 0 Function succeeded; -ENOENT No such address.; -EINVAL Invalid argument.; -ENOSPC No space left on device.; -EIO Device was occurred error due to unknown exception.; -EDESTADDRREQ Destination address required.; -ECONNRESET Connection reset by peer.; -EAGAIN Try again.; -EBUSY Device or resource busy.; -EADDRINUSE Address already in use.; -EALREADY Socket already connected.; -ENOTCONN Service in bad state.; -ECONNREFUSED Connection refused.; -EOVERFLOW Value too large for defined data type.; -EBADMSG Not a data message.

References mqtt_module::callback, mqtt_module::client, mqtt_data::connected, mqtt_module::isConnected, MQTT_CALLBACK_CONNECTED, MQTTConnect(), MQTTPacket_connectData_initializer, and mqtt_data_connected::result.

Referenced by mqtt_callback().

int mqtt_deinit ( struct mqtt_module *const module )

Termivate MQTT service.

Parameters

[in] module Module instance of MQTT.

Returns: 0 Function succeeded; -ENOENT No such address.; -EINVAL Invalid argument.; -ENOSPC No space left on device.; -EIO Device was occurred error due to unknown exception.; -EDESTADDRREQ Destination address required.; -ECONNRESET Connection reset by peer.; -EAGAIN Try again.; -EBUSY Device or resource busy.; -EADDRINUSE Address already in use.; -EALREADY Socket already connected.; -ENOTCONN Service in bad state.; -ECONNREFUSED Connection refused.; -EOVERFLOW Value too large for defined data type.; -EBADMSG Not a data message.; -ENOMEM Out of memory.

References deAllocateClient(), FAILURE, mqtt_module::isConnected, mqtt_disconnect(), and SUCCESS.

int mqtt_disconnect	(	struct mqtt_module *const	module,
		int	force_close
	)

Send disconnect message to MQTT broker server and closing socket.

If operation of this function is complete, MQTT_CALLBACK_DISCONNECTED event will be sent through MQTT callback.

Parameters

[in]	module_inst	Instance of MQTT module.
[in]	force_close	If this flag is set, MQTT service will be close the socket immediately.

Returns: 0 Function succeeded; -ENOENT No such address.; -EINVAL Invalid argument.; -ENOSPC No space left on device.; -EIO Device was occurred error due to unknown exception.; -EDESTADDRREQ Destination address required.; -ECONNRESET Connection reset by peer.; -EAGAIN Try again.; -EBUSY Device or resource busy.; -EADDRINUSE Address already in use.; -EALREADY Socket already connected.; -ENOTCONN Service in bad state.; -ECONNREFUSED Connection refused.; -EOVERFLOW Value too large for defined data type.; -EBADMSG Not a data message.

References mqtt_module::callback, mqtt_module::client, mqtt_data::disconnected, mqtt_module::isConnected, MQTT_CALLBACK_DISCONNECTED, MQTTDisconnect(), and mqtt_data_disconnected::reason.

Referenced by mqtt_deinit(), and wifi_callback().

void mqtt_get_config_defaults ( struct mqtt_config *const config )

Get default configuration of SW timer.

Parameters

[in] config Pointer of configuration structure which will be used in the module.

References mqtt_config::keep_alive, NULL, mqtt_config::port, mqtt_config::read_buffer, mqtt_config::read_buffer_size, mqtt_config::send_buffer, mqtt_config::send_buffer_size, and mqtt_config::tls.

Referenced by configure_mqtt().

int mqtt_init	(	struct mqtt_module *	module,
		struct mqtt_config *	config
	)

Initialize MQTT service.

Parameters

[in]	module	Module instance of MQTT.
[in]	config	Pointer of configuration structure which will be used in the module.

Returns: 0 Function succeeded; -ENOENT No such address.; -EINVAL Invalid argument.; -ENOSPC No space left on device.; -EIO Device was occurred error due to unknown exception.; -EDESTADDRREQ Destination address required.; -ECONNRESET Connection reset by peer.; -EAGAIN Try again.; -EBUSY Device or resource busy.; -EADDRINUSE Address already in use.; -EALREADY Socket already connected.; -ENOTCONN Service in bad state.; -ECONNREFUSED Connection refused.; -EOVERFLOW Value too large for defined data type.; -EBADMSG Not a data message.; -ENOMEM Out of memory.

References allocateClient(), mqtt_module::client, mqtt_module::config, FAILURE, mqtt_config::keep_alive, MQTTClientInit(), mqtt_module::network, NetworkInit(), NULL, mqtt_config::read_buffer, mqtt_config::read_buffer_size, mqtt_config::send_buffer, mqtt_config::send_buffer_size, and SUCCESS.

Referenced by configure_mqtt().

int mqtt_publish	(	struct mqtt_module *const	module,
		const char *	topic,
		const char *	msg,
		uint32_t	msg_len,
		uint8_t	qos,
		uint8_t	retain
	)

Send publish message to MQTT broker server.

If operation of this function is complete, MQTT_CALLBACK_PUBLISHED event will be sent through MQTT callback.

Parameters

[in]	module_inst	Instance of MQTT module.
[in]	topic	Topic of this MQTT message.
[in]	msg	Payload of this MQTT message.
[in]	msg_len	Payload size of this MQTT message.
[in]	qos	QOS level of this MQTT message. (0 <= qos <= 2)
[in]	retain	Whether broker server will be store this MQTT message or not.

Returns: 0 Function succeeded; -ENOENT No such address.; -EINVAL Invalid argument.; -ENOSPC No space left on device.; -EIO Device was occurred error due to unknown exception.; -EDESTADDRREQ Destination address required.; -ECONNRESET Connection reset by peer.; -EAGAIN Try again.; -EBUSY Device or resource busy.; -EADDRINUSE Address already in use.; -EALREADY Socket already connected.; -ENOTCONN Service in bad state.; -ECONNREFUSED Connection refused.; -EOVERFLOW Value too large for defined data type.; -EBADMSG Not a data message.

References mqtt_module::callback, mqtt_module::client, MQTT_CALLBACK_PUBLISHED, MQTTPublish(), NULL, MQTTMessage::payload, MQTTMessage::payloadlen, MQTTMessage::qos, and MQTTMessage::retained.

Referenced by check_usart_buffer().

int mqtt_register_callback	(	struct mqtt_module *const	module,
		mqtt_callback_t	callback
	)

Register and enable the callback.

Parameters

[in]	module_inst	Instance of MQTT module.
[in]	callback	Callback entry for the MQTT module.

Returns: 0 Function succeeded; -ENOENT No such address.; -EINVAL Invalid argument.; -ENOSPC No space left on device.; -EIO Device was occurred error due to unknown exception.; -EDESTADDRREQ Destination address required.; -ECONNRESET Connection reset by peer.; -EAGAIN Try again.; -EBUSY Device or resource busy.; -EADDRINUSE Address already in use.; -EALREADY Socket already connected.; -ENOTCONN Service in bad state.; -ECONNREFUSED Connection refused.; -EOVERFLOW Value too large for defined data type.; -EBADMSG Not a data message.

References callback, mqtt_module::callback, FAILURE, and SUCCESS.

Referenced by configure_mqtt().

void mqtt_socket_event_handler	(	SOCKET	sock,
		uint8_t	msg_type,
		void *	msg_data
	)

Event handler of socket event.

Parameters

[in]	sock	Socket descriptor.
[in]	msg_type	Event type.
[in]	msg_data	Structure of socket event.

References tcpClientSocketEventHandler().

Referenced by socket_event_handler().

void mqtt_socket_resolve_handler	(	uint8_t *	doamin_name,
		uint32_t	server_ip
	)

Event handler of gethostbyname.

Parameters

[in]	doamin_name	Domain name.
[in]	server_ip	Server IP.

References dnsResolveCallback().

Referenced by socket_resolve_handler().

int mqtt_subscribe	(	struct mqtt_module *const	module,
		const char *	topic,
		uint8_t	qos,
		messageHandler	msgHandler
	)

Send subscribe message to MQTT broker server.

If operation of this function is complete, MQTT_CALLBACK_SUBSCRIBED event will be sent through MQTT callback.

Parameters

[in]	module_inst	Instance of MQTT module.
[in]	topic	A topic which will be received.
[in]	qos	QOS level of received publish message.

Returns: 0 Function succeeded; -ENOENT No such address.; -EINVAL Invalid argument.; -ENOSPC No space left on device.; -EIO Device was occurred error due to unknown exception.; -EDESTADDRREQ Destination address required.; -ECONNRESET Connection reset by peer.; -EAGAIN Try again.; -EBUSY Device or resource busy.; -EADDRINUSE Address already in use.; -EALREADY Socket already connected.; -ENOTCONN Service in bad state.; -ECONNREFUSED Connection refused.; -EOVERFLOW Value too large for defined data type.; -EBADMSG Not a data message.

References mqtt_module::callback, mqtt_module::client, MQTT_CALLBACK_SUBSCRIBED, MQTTSubscribe(), and NULL.

Referenced by mqtt_callback().

int mqtt_unregister_callback ( struct mqtt_module *const module )

Unregister callback.

Parameters

[in] module_inst Instance of MQTT module.

Returns: 0 Function succeeded; -ENOENT No such address.; -EINVAL Invalid argument.; -ENOSPC No space left on device.; -EIO Device was occurred error due to unknown exception.; -EDESTADDRREQ Destination address required.; -ECONNRESET Connection reset by peer.; -EAGAIN Try again.; -EBUSY Device or resource busy.; -EADDRINUSE Address already in use.; -EALREADY Socket already connected.; -ENOTCONN Service in bad state.; -ECONNREFUSED Connection refused.; -EOVERFLOW Value too large for defined data type.; -EBADMSG Not a data message.

References mqtt_module::callback, FAILURE, NULL, and SUCCESS.

int mqtt_unsubscribe	(	struct mqtt_module *const	module,
		const char *	topic
	)

Send unsubscribe message to MQTT broker server.

If operation of this function is complete, MQTT_CALLBACK_UNSUBSCRIBED event will be sent through MQTT callback.

Parameters

[in]	module_inst	Instance of MQTT module.
[in]	topic	A topic that want to be removed.

Returns: 0 Function succeeded; -ENOENT No such address.; -EINVAL Invalid argument.; -ENOSPC No space left on device.; -EIO Device was occurred error due to unknown exception.; -EDESTADDRREQ Destination address required.; -ECONNRESET Connection reset by peer.; -EAGAIN Try again.; -EBUSY Device or resource busy.; -EADDRINUSE Address already in use.; -EALREADY Socket already connected.; -ENOTCONN Service in bad state.; -ECONNREFUSED Connection refused.; -EOVERFLOW Value too large for defined data type.; -EBADMSG Not a data message.

References mqtt_module::callback, mqtt_module::client, MQTT_CALLBACK_SUBSCRIBED, MQTTUnsubscribe(), and NULL.

int mqtt_yield	(	struct mqtt_module *	module,
		int	timeout_ms
	)

Poll for published frames.

Parameters

[in]	module_inst	Instance of MQTT module.
[in]	timeout_ms	time limit for polling.

Returns: 0 Function succeeded; -ENOENT No such address.; -EINVAL Invalid argument.; -ENOSPC No space left on device.; -EIO Device was occurred error due to unknown exception.; -EDESTADDRREQ Destination address required.; -ECONNRESET Connection reset by peer.; -EAGAIN Try again.; -EBUSY Device or resource busy.; -EADDRINUSE Address already in use.; -EALREADY Socket already connected.; -ENOTCONN Service in bad state.; -ECONNREFUSED Connection refused.; -EOVERFLOW Value too large for defined data type.; -EBADMSG Not a data message.

References mqtt_module::client, and MQTTYield().

Referenced by main().

struct mqtt_client_pool mqttClientPool[MQTT_MAX_CLIENTS]

Static Client Pool Allocation.

You are permitted to use the software and its derivatives with Microchip products.

SOFTWARE AND DOCUMENTATION ARE PROVIDED �AS IS� WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY, TITLE, NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROCHIP OR ITS LICENSORS BE LIABLE OR OBLIGATED UNDER CONTRACT, NEGLIGENCE, STRICT LIABILITY, CONTRIBUTION, BREACH OF WARRANTY, OR OTHER LEGAL OR EQUITABLE THEORY FOR ANY DIRECT OR INDIRECT DAMAGES OR EXPENSES INCLUDING BUT NOT LIMITED TO ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, OR OTHER SIMILAR COSTS. TO THE FULLEST EXTENT ALLOWED BY LAW, MICROCHIP AND ITS LICENSORS LIABILITY WILL NOT EXCEED THE AMOUNT OF FEES, IF ANY, THAT YOU PAID DIRECTLY TO MICROCHIP TO USE THIS SOFTWARE. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS.

THIRD PARTY SOFTWARE: Notwithstanding anything to the contrary, any third party software accompanying this software is subject to the terms and conditions of the third party�s license agreement or open source software license. To the extent required by third party or open source licenses covering such third party software, the terms of such license will apply in lieu of the terms provided herein. To the extent the terms of such third party licenses prohibit any of the restrictions described herein, such restrictions will not apply to such third party software. THIRD PARTY SOFTWARE IS SUBJECT TO THE FOREGOING WARRANTY DISCLAIMER AND LIMIT ON LIABILITY PROVIDED IN THE PARAGRAPH ABOVE.

Referenced by isMQTTSocket().

Microchip® Advanced Software Framework

Data Structures

Typedefs

Enumerations

Functions

Variables