Atmel Software Framework

MQTT service

This module provides implementation of MQTT 3.1 for WINC1500 board.

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_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_recv_publish
 Structure of the MQTT_CALLBACK_RECV_PUBLISH 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...
 

Macros

#define MQTT_PROTO_NAME   "MQIsdp"
 Protocol version string of MQTT. More...
 
#define MQTT_PROTO_VERSION   3
 Protocol version ID of MQTT. 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_RECV_PUBLISH,
  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 *const 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)
 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...
 

#define MQTT_PROTO_NAME   "MQIsdp"

Protocol version string of MQTT.

String of MQTT v3.1 is MQIsdp.

#define MQTT_PROTO_VERSION   3

Protocol version ID of MQTT.

ID of MQTT v3.1 is 3.

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_RECV_PUBLISH 

MQTT connection received publish message from the MQTT broker server.

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

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

Referenced by configure_mqtt().

int mqtt_init ( struct mqtt_module *const  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.

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

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.

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.

Referenced by socket_resolve_handler().

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

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