MQTT Client

MQTT client v3.1.1 implementation, based on callback (non-netconn) connection API.

group LWGSM_APP_MQTT_CLIENT

MQTT client.

Typedefs

typedef struct lwgsm_mqtt_client *lwgsm_mqtt_client_p

Pointer to lwgsm_mqtt_client_t structure.

typedef void (*lwgsm_mqtt_evt_fn)(lwgsm_mqtt_client_p client, lwgsm_mqtt_evt_t *evt)

MQTT event callback function.

Param client

[in] MQTT client

Param evt

[in] MQTT event with type and related data

Enums

enum lwgsm_mqtt_qos_t

Quality of service enumeration.

Values:

enumerator LWGSM_MQTT_QOS_AT_MOST_ONCE = 0x00

Delivery is not guaranteed to arrive, but can arrive up to 1 time = non-critical packets where losses are allowed

enumerator LWGSM_MQTT_QOS_AT_LEAST_ONCE = 0x01

Delivery is quaranteed at least once, but it may be delivered multiple times with the same content

enumerator LWGSM_MQTT_QOS_EXACTLY_ONCE = 0x02

Delivery is quaranteed exactly once = very critical packets such as billing informations or similar

enum lwgsm_mqtt_state_t

State of MQTT client.

Values:

enumerator LWGSM_MQTT_CONN_DISCONNECTED = 0x00

Connection with server is not established

enumerator LWGSM_MQTT_CONN_CONNECTING

Client is connecting to server

enumerator LWGSM_MQTT_CONN_DISCONNECTING

Client connection is disconnecting from server

enumerator LWGSM_MQTT_CONNECTING

MQTT client is connecting… CONNECT command has been sent to server

enumerator LWGSM_MQTT_CONNECTED

MQTT is fully connected and ready to send data on topics

enum lwgsm_mqtt_evt_type_t

MQTT event types.

Values:

enumerator LWGSM_MQTT_EVT_CONNECT

MQTT client connect event

enumerator LWGSM_MQTT_EVT_SUBSCRIBE

MQTT client subscribed to specific topic

enumerator LWGSM_MQTT_EVT_UNSUBSCRIBE

MQTT client unsubscribed from specific topic

enumerator LWGSM_MQTT_EVT_PUBLISH

MQTT client publish message to server event.

Note

When publishing packet with quality of service LWGSM_MQTT_QOS_AT_MOST_ONCE, you may not receive event, even if packet was successfully sent, thus do not rely on this event for packet with qos = LWGSM_MQTT_QOS_AT_MOST_ONCE

enumerator LWGSM_MQTT_EVT_PUBLISH_RECV

MQTT client received a publish message from server

enumerator LWGSM_MQTT_EVT_DISCONNECT

MQTT client disconnected from MQTT server

enumerator LWGSM_MQTT_EVT_KEEP_ALIVE

MQTT keep-alive sent to server and reply received

enum lwgsm_mqtt_conn_status_t

List of possible results from MQTT server when executing connect command.

Values:

enumerator LWGSM_MQTT_CONN_STATUS_ACCEPTED = 0x00

Connection accepted and ready to use

enumerator LWGSM_MQTT_CONN_STATUS_REFUSED_PROTOCOL_VERSION = 0x01

Connection Refused, unacceptable protocol version

enumerator LWGSM_MQTT_CONN_STATUS_REFUSED_ID = 0x02

Connection refused, identifier rejected

enumerator LWGSM_MQTT_CONN_STATUS_REFUSED_SERVER = 0x03

Connection refused, server unavailable

enumerator LWGSM_MQTT_CONN_STATUS_REFUSED_USER_PASS = 0x04

Connection refused, bad user name or password

enumerator LWGSM_MQTT_CONN_STATUS_REFUSED_NOT_AUTHORIZED = 0x05

Connection refused, not authorized

enumerator LWGSM_MQTT_CONN_STATUS_TCP_FAILED = 0x100

TCP connection to server was not successful

Functions

lwgsm_mqtt_client_p lwgsm_mqtt_client_new(size_t tx_buff_len, size_t rx_buff_len)

Allocate a new MQTT client structure.

Parameters
  • tx_buff_len[in] Length of raw data output buffer

  • rx_buff_len[in] Length of raw data input buffer

Returns

Pointer to new allocated MQTT client structure or NULL on failure

void lwgsm_mqtt_client_delete(lwgsm_mqtt_client_p client)

Delete MQTT client structure.

Note

MQTT client must be disconnected first

Parameters

client[in] MQTT client

lwgsmr_t lwgsm_mqtt_client_connect(lwgsm_mqtt_client_p client, const char *host, lwgsm_port_t port, lwgsm_mqtt_evt_fn evt_fn, const lwgsm_mqtt_client_info_t *info)

Connect to MQTT server.

Note

After TCP connection is established, CONNECT packet is automatically sent to server

Parameters
  • client[in] MQTT client

  • host[in] Host address for server

  • port[in] Host port number

  • evt_fn[in] Callback function for all events on this MQTT client

  • info[in] Information structure for connection

Returns

lwgsmOK on success, member of lwgsmr_t enumeration otherwise

lwgsmr_t lwgsm_mqtt_client_disconnect(lwgsm_mqtt_client_p client)

Disconnect from MQTT server.

Parameters

client[in] MQTT client

Returns

lwgsmOK if request sent to queue or member of lwgsmr_t otherwise

uint8_t lwgsm_mqtt_client_is_connected(lwgsm_mqtt_client_p client)

Test if client is connected to server and accepted to MQTT protocol.

Note

Function will return error if TCP is connected but MQTT not accepted

Parameters

client[in] MQTT client

Returns

1 on success, 0 otherwise

lwgsmr_t lwgsm_mqtt_client_subscribe(lwgsm_mqtt_client_p client, const char *topic, lwgsm_mqtt_qos_t qos, void *arg)

Subscribe to MQTT topic.

Parameters
  • client[in] MQTT client

  • topic[in] Topic name to subscribe to

  • qos[in] Quality of service. This parameter can be a value of lwgsm_mqtt_qos_t

  • arg[in] User custom argument used in callback

Returns

lwgsmOK on success, member of lwgsmr_t enumeration otherwise

lwgsmr_t lwgsm_mqtt_client_unsubscribe(lwgsm_mqtt_client_p client, const char *topic, void *arg)

Unsubscribe from MQTT topic.

Parameters
  • client[in] MQTT client

  • topic[in] Topic name to unsubscribe from

  • arg[in] User custom argument used in callback

Returns

lwgsmOK on success, member of lwgsmr_t enumeration otherwise

lwgsmr_t lwgsm_mqtt_client_publish(lwgsm_mqtt_client_p client, const char *topic, const void *payload, uint16_t len, lwgsm_mqtt_qos_t qos, uint8_t retain, void *arg)

Publish a new message on specific topic.

Parameters
  • client[in] MQTT client

  • topic[in] Topic to send message to

  • payload[in] Message data

  • payload_len[in] Length of payload data

  • qos[in] Quality of service. This parameter can be a value of lwgsm_mqtt_qos_t enumeration

  • retain[in] Retian parameter value

  • arg[in] User custom argument used in callback

Returns

lwgsmOK on success, member of lwgsmr_t enumeration otherwise

void *lwgsm_mqtt_client_get_arg(lwgsm_mqtt_client_p client)

Get user argument on client.

Parameters

client[in] MQTT client handle

Returns

User argument

void lwgsm_mqtt_client_set_arg(lwgsm_mqtt_client_p client, void *arg)

Set user argument on client.

Parameters
  • client[in] MQTT client handle

  • arg[in] User argument

struct lwgsm_mqtt_client_info_t
#include <lwgsm_mqtt_client.h>

MQTT client information structure.

Public Members

const char *id

Client unique identifier. It is required and must be set by user

const char *user

Authentication username. Set to NULL if not required

const char *pass

Authentication password, set to NULL if not required

uint16_t keep_alive

Keep-alive parameter in units of seconds. When set to 0, functionality is disabled (not recommended)

const char *will_topic

Will topic

const char *will_message

Will message

lwgsm_mqtt_qos_t will_qos

Will topic quality of service

struct lwgsm_mqtt_request_t
#include <lwgsm_mqtt_client.h>

MQTT request object.

Public Members

uint8_t status

Entry status flag for in use or pending bit

uint16_t packet_id

Packet ID generated by client on publish

void *arg

User defined argument

uint32_t expected_sent_len

Number of total bytes which must be sent on connection before we can say “packet was sent”.

uint32_t timeout_start_time

Timeout start time in units of milliseconds

struct lwgsm_mqtt_evt_t
#include <lwgsm_mqtt_client.h>

MQTT event structure for callback function.

Public Members

lwgsm_mqtt_evt_type_t type

Event type

lwgsm_mqtt_conn_status_t status

Connection status with MQTT

struct lwgsm_mqtt_evt_t::[anonymous]::[anonymous] connect

Event for connecting to server

uint8_t is_accepted

Status if client was accepted to MQTT prior disconnect event

struct lwgsm_mqtt_evt_t::[anonymous]::[anonymous] disconnect

Event for disconnecting from server

void *arg

User argument for callback function

lwgsmr_t res

Response status

struct lwgsm_mqtt_evt_t::[anonymous]::[anonymous] sub_unsub_scribed

Event for (un)subscribe to/from topics

struct lwgsm_mqtt_evt_t::[anonymous]::[anonymous] publish

Published event

const uint8_t *topic

Pointer to topic identifier

size_t topic_len

Length of topic

const void *payload

Topic payload

size_t payload_len

Length of topic payload

uint8_t dup

Duplicate flag if message was sent again

lwgsm_mqtt_qos_t qos

Received packet quality of service

struct lwgsm_mqtt_evt_t::[anonymous]::[anonymous] publish_recv

Publish received event

union lwgsm_mqtt_evt_t::[anonymous] evt

Event data parameters

group LWGSM_APP_MQTT_CLIENT_EVT

Event helper functions.

Connect event

Note

Use these functions on LWGSM_MQTT_EVT_CONNECT event

lwgsm_mqtt_client_evt_connect_get_status(client, evt)

Get connection status.

Parameters
  • client[in] MQTT client

  • evt[in] Event handle

Returns

Connection status. Member of lwgsm_mqtt_conn_status_t

Disconnect event

Note

Use these functions on LWGSM_MQTT_EVT_DISCONNECT event

lwgsm_mqtt_client_evt_disconnect_is_accepted(client, evt)

Check if MQTT client was accepted by server when disconnect event occurred.

Parameters
  • client[in] MQTT client

  • evt[in] Event handle

Returns

1 on success, 0 otherwise

Subscribe/unsubscribe event

Note

Use these functions on LWGSM_MQTT_EVT_SUBSCRIBE or LWGSM_MQTT_EVT_UNSUBSCRIBE events

lwgsm_mqtt_client_evt_subscribe_get_argument(client, evt)

Get user argument used on lwgsm_mqtt_client_subscribe.

Parameters
  • client[in] MQTT client

  • evt[in] Event handle

Returns

User argument

lwgsm_mqtt_client_evt_subscribe_get_result(client, evt)

Get result of subscribe event.

Parameters
  • client[in] MQTT client

  • evt[in] Event handle

Returns

lwgsmOK on success, member of lwgsmr_t otherwise

lwgsm_mqtt_client_evt_unsubscribe_get_argument(client, evt)

Get user argument used on lwgsm_mqtt_client_unsubscribe.

Parameters
  • client[in] MQTT client

  • evt[in] Event handle

Returns

User argument

lwgsm_mqtt_client_evt_unsubscribe_get_result(client, evt)

Get result of unsubscribe event.

Parameters
  • client[in] MQTT client

  • evt[in] Event handle

Returns

lwgsmOK on success, member of lwgsmr_t otherwise

Publish receive event

Note

Use these functions on LWGSM_MQTT_EVT_PUBLISH_RECV event

lwgsm_mqtt_client_evt_publish_recv_get_topic(client, evt)

Get topic from received publish packet.

Parameters
  • client[in] MQTT client

  • evt[in] Event handle

Returns

Topic name

lwgsm_mqtt_client_evt_publish_recv_get_topic_len(client, evt)

Get topic length from received publish packet.

Parameters
  • client[in] MQTT client

  • evt[in] Event handle

Returns

Topic length

lwgsm_mqtt_client_evt_publish_recv_get_payload(client, evt)

Get payload from received publish packet.

Parameters
  • client[in] MQTT client

  • evt[in] Event handle

Returns

Packet payload

lwgsm_mqtt_client_evt_publish_recv_get_payload_len(client, evt)

Get payload length from received publish packet.

Parameters
  • client[in] MQTT client

  • evt[in] Event handle

Returns

Payload length

lwgsm_mqtt_client_evt_publish_recv_is_duplicate(client, evt)

Check if packet is duplicated.

Parameters
  • client[in] MQTT client

  • evt[in] Event handle

Returns

1 if duplicated, 0 otherwise

lwgsm_mqtt_client_evt_publish_recv_get_qos(client, evt)

Get received quality of service.

Parameters
  • client[in] MQTT client

  • evt[in] Event handle

Returns

Member of lwgsm_mqtt_qos_t enumeration

Publish event

Note

Use these functions on LWGSM_MQTT_EVT_PUBLISH event

lwgsm_mqtt_client_evt_publish_get_argument(client, evt)

Get user argument used on lwgsm_mqtt_client_publish.

Parameters
  • client[in] MQTT client

  • evt[in] Event handle

Returns

User argument

lwgsm_mqtt_client_evt_publish_get_result(client, evt)

Get result of publish event.

Parameters
  • client[in] MQTT client

  • evt[in] Event handle

Returns

lwgsmOK on success, member of lwgsmr_t otherwise

Defines

lwgsm_mqtt_client_evt_get_type(client, evt)

Get MQTT event type.

Parameters
  • client[in] MQTT client

  • evt[in] Event handle

Returns

MQTT Event type, value of lwgsm_mqtt_evt_type_t enumeration