MQTT
Libraries > Cloud

MQTT is a machine-to-machine connectivity protocol. More...

Functions

zos_result_t mqtt_init (mqtt_connection_t *mqtt_connection)
 Initializes MQTT object. More...
 
zos_result_t mqtt_deinit (mqtt_connection_t *mqtt_connection)
 De-initializes MQTT object. More...
 
zos_result_t mqtt_open (mqtt_connection_t *mqtt_connection, const char *address, uint16_t port_number, zos_interface_t interface, mqtt_callback_t callback, zos_bool_t security)
 Opens a TCP/TLS connection with MQTT broker. More...
 
zos_result_t mqtt_connect (mqtt_connection_t *mqtt_connection, mqtt_pkt_connect_t *conninfo)
 Send connection frame to MQTT broker. More...
 
zos_result_t mqtt_disconnect (mqtt_connection_t *mqtt_connection)
 Disconnect from MQTT broker. More...
 
mqtt_msgid_t mqtt_publish (mqtt_connection_t *mqtt_connection, uint8_t *topic, uint8_t *message, uint32_t msg_len, uint8_t qos)
 Publish message to MQTT Broker on the given Topic. More...
 
mqtt_msgid_t mqtt_subscribe (mqtt_connection_t *mqtt_connection, uint8_t *topic, uint8_t qos)
 Subscribe for a topic with MQTT Broker. More...
 
mqtt_msgid_t mqtt_unsubscribe (mqtt_connection_t *mqtt_connection, uint8_t *topic)
 Unsubscribe the topic from MQTT Broker. More...
 

Detailed Description

MQTT is a machine-to-machine connectivity protocol.

MQTT is a machine-to-machine (M2M)/"Internet of Things" connectivity protocol. It was designed as an extremely lightweight publish/subscribe messaging transport. It is useful for connections with remote locations where a small code footprint is required and/or network bandwidth is at a premium. For example, it has been used in sensors communicating to a broker via satellite link, over occasional dial-up connections with healthcare providers, and in a range of home automation and small device scenarios. It is also ideal for mobile applications because of its small size, low power usage, minimised data packets, and efficient distribution of information to one or many receivers

See MQTT Website for more information.

Function Documentation

zos_result_t mqtt_connect ( mqtt_connection_t *  mqtt_connection,
mqtt_pkt_connect_t *  conninfo 
)

Send connection frame to MQTT broker.

NOTE: This is an asynchronous API. Connection status will be notified using callback function. MQTT_EVENT_TYPE_CONNECTED event will be sent using callback function

Parameters
[in]mqtt_connection: Contains address of a memory location which is passed during MQTT init
[in]conninfo: MQTT connect message related information
Returns
zos_result_t NOTE: Allocate memory for conninfo->client_id, conninfo->username, conninfo->password in non-stack area. And free/resuse them after getting event MQTT_EVENT_TYPE_CONNECT_REQ_STATUS or MQTT_EVENT_TYPE_DISCONNECTED
zos_result_t mqtt_deinit ( mqtt_connection_t *  mqtt_connection)

De-initializes MQTT object.

Parameters
[in]mqtt_connection: Contains address of a memory location which is passed during MQTT init
Returns
zos_result_t
zos_result_t mqtt_disconnect ( mqtt_connection_t *  mqtt_connection)

Disconnect from MQTT broker.

NOTE: This is an asynchronous API. Disconnect status will be notified using using callback function. MQTT_EVENT_TYPE_DISCONNECTED event will be sent using callback function

Parameters
[in]mqtt_connection: Contains address of a memory location which is passed during MQTT init
Returns
zos_result_t

NOTE: Allocate memory for conninfo->client_id, conninfo->username, conninfo->password in non-stack area. And free/resuse them after getting event MQTT_EVENT_TYPE_CONNECT_REQ_STATUS or MQTT_EVENT_TYPE_DISCONNECTED

zos_result_t mqtt_init ( mqtt_connection_t *  mqtt_connection)

Initializes MQTT object.

Parameters
[in]mqtt_connection: Contains address of a memory location, having size of MQTT_OBJECT_MEMORY_SIZE_REQUIREMENT bytes Application has to allocate it non stack memory area. And application has to free it after use
Returns
zos_result_t NOTE : The mqtt_connection memory here can be freed or reused by application after calling mqtt_deinit()
zos_result_t mqtt_open ( mqtt_connection_t *  mqtt_connection,
const char *  address,
uint16_t  port_number,
zos_interface_t  interface,
mqtt_callback_t  callback,
zos_bool_t  security 
)

Opens a TCP/TLS connection with MQTT broker.

Parameters
[in]mqtt_connection: Contains address of a memory location which is passed during MQTT init
[in]address: IP address of the Broker
[in]port_number: Port number broker is listening to
[in]interface: Network interface to be used for establishing connection with Broker
[in]callback: Event callback function which is used for notifying the events from library
[in]security: Security (TLS) is enabled (TRUE) or disabled (FALSE)
Returns
zos_result_t
mqtt_msgid_t mqtt_publish ( mqtt_connection_t *  mqtt_connection,
uint8_t *  topic,
uint8_t *  message,
uint32_t  msg_len,
uint8_t  qos 
)

Publish message to MQTT Broker on the given Topic.

NOTE: This is an asynchronous API. Publish status will be notified using using callback function. MQTT_EVENT_TYPE_PUBLISHED event will be sent using callback function

Parameters
[in]mqtt_connection: Contains address of a memory location which is passed during MQTT init
[in]topic: Contains the topic on which the message to be published
[in]message: Pointer to the message to be published
[in]msg_len: Length of the message pointed by 'message' pointer
[in]qos: QoS level to be used for publishing the given message
Returns
mqtt_msgid_t : ID for the message being published NOTE: Allocate memory for topic, data in non-stack area. And free/resuse them after getting event MQTT_EVENT_TYPE_PUBLISHED or MQTT_EVENT_TYPE_DISCONNECTED for given message ID (mqtt_msgid_t)
mqtt_msgid_t mqtt_subscribe ( mqtt_connection_t *  mqtt_connection,
uint8_t *  topic,
uint8_t  qos 
)

Subscribe for a topic with MQTT Broker.

NOTE: This is an asynchronous API. Subscribe status will be notified using using callback function. MQTT_EVENT_TYPE_SUBCRIBED event will be sent using callback function

Parameters
[in]mqtt_connection: Contains address of a memory location which is passed during MQTT init
[in]topic: Contains the topic to be subscribed to
[in]qos: QoS level to be used for receiving the message on the given topic
Returns
mqtt_msgid_t : ID for the message being subscribed NOTE: Allocate memory for topic in non-stack area. And free/resuse them after getting event MQTT_EVENT_TYPE_SUBCRIBED or MQTT_EVENT_TYPE_DISCONNECTED for given message ID (mqtt_msgid_t)
mqtt_msgid_t mqtt_unsubscribe ( mqtt_connection_t *  mqtt_connection,
uint8_t *  topic 
)

Unsubscribe the topic from MQTT Broker.

NOTE: This is an asynchronous API. Unsubscribe status will be notified using using callback function. MQTT_EVENT_TYPE_UNSUBCRIBED event will be sent using callback function

Parameters
[in]mqtt_connection: Contains address of a memory location which is passed during MQTT init
[in]topic: Contains the topic to be unsubscribed
Returns
mqtt_msgid_t : ID for the message being subscribed NOTE: Allocate memory for topic in non-stack area. And free/resuse them after getting event MQTT_EVENT_TYPE_UNSUBSCRIBED or MQTT_EVENT_TYPE_DISCONNECTED for given message ID (mqtt_msgid_t)