Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
MQTT service

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.

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.

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_instInstance of MQTT module.
[in]hostURL 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_instInstance of MQTT module.
[in]clean_sessionIf this value set to 1, Broker server store the previous subscribed informations after disconnected.
[in]idID of user.
[in]passwordPassword of user.
[in]client_idClient ID of this connection.
[in]will_topicA MQTT topic that will be sent to subscribers when this connection is disconnected.
[in]will_msgA MQTT payload that will be sent to subscribers when this connection is disconnected.
[in]will_qosQOS level of will message.
[in]will_retainWhether 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]moduleModule 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_instInstance of MQTT module.
[in]force_closeIf 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]configPointer 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]moduleModule instance of MQTT.
[in]configPointer 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_instInstance of MQTT module.
[in]topicTopic of this MQTT message.
[in]msgPayload of this MQTT message.
[in]msg_lenPayload size of this MQTT message.
[in]qosQOS level of this MQTT message. (0 <= qos <= 2)
[in]retainWhether 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_instInstance of MQTT module.
[in]callbackCallback 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 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]sockSocket descriptor.
[in]msg_typeEvent type.
[in]msg_dataStructure 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_nameDomain name.
[in]server_ipServer 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_instInstance of MQTT module.
[in]topicA topic which will be received.
[in]qosQOS 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_instInstance 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_instInstance of MQTT module.
[in]topicA 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_instInstance of MQTT module.
[in]timeout_mstime 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.

Static Client Pool Allocation.

and its subsidiaries (Microchip). All rights reserved.

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().