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.

Parameters

  • [in] client: MQTT client

  • [in] evt: 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

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

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

enumerator LWGSM_MQTT_QOS_EXACTLY_ONCE

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

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

Connection accepted and ready to use

enumerator LWGSM_MQTT_CONN_STATUS_REFUSED_PROTOCOL_VERSION

Connection Refused, unacceptable protocol version

enumerator LWGSM_MQTT_CONN_STATUS_REFUSED_ID

Connection refused, identifier rejected

enumerator LWGSM_MQTT_CONN_STATUS_REFUSED_SERVER

Connection refused, server unavailable

enumerator LWGSM_MQTT_CONN_STATUS_REFUSED_USER_PASS

Connection refused, bad user name or password

enumerator LWGSM_MQTT_CONN_STATUS_REFUSED_NOT_AUTHORIZED

Connection refused, not authorized

enumerator LWGSM_MQTT_CONN_STATUS_TCP_FAILED

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.

Return

Pointer to new allocated MQTT client structure or NULL on failure

Parameters

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

  • [in] rx_buff_len: Length of raw data input buffer

void lwgsm_mqtt_client_delete(lwgsm_mqtt_client_p client)

Delete MQTT client structure.

Note

MQTT client must be disconnected first

Parameters

  • [in] client: 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

Return

lwgsmOK on success, member of lwgsmr_t enumeration otherwise

Parameters

  • [in] client: MQTT client

  • [in] host: Host address for server

  • [in] port: Host port number

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

  • [in] info: Information structure for connection

lwgsmr_t lwgsm_mqtt_client_disconnect(lwgsm_mqtt_client_p client)

Disconnect from MQTT server.

Return

lwgsmOK if request sent to queue or member of lwgsmr_t otherwise

Parameters

  • [in] client: MQTT client

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

Return

1 on success, 0 otherwise

Parameters

  • [in] client: MQTT client

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.

Return

lwgsmOK on success, member of lwgsmr_t enumeration otherwise

Parameters

  • [in] client: MQTT client

  • [in] topic: Topic name to subscribe to

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

  • [in] arg: User custom argument used in callback

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

Unsubscribe from MQTT topic.

Return

lwgsmOK on success, member of lwgsmr_t enumeration otherwise

Parameters

  • [in] client: MQTT client

  • [in] topic: Topic name to unsubscribe from

  • [in] arg: User custom argument used in callback

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.

Return

lwgsmOK on success, member of lwgsmr_t enumeration otherwise

Parameters

  • [in] client: MQTT client

  • [in] topic: Topic to send message to

  • [in] payload: Message data

  • [in] payload_len: Length of payload data

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

  • [in] retain: Retian parameter value

  • [in] arg: User custom argument used in callback

void *lwgsm_mqtt_client_get_arg(lwgsm_mqtt_client_p client)

Get user argument on client.

Return

User argument

Parameters

  • [in] client: MQTT client handle

void lwgsm_mqtt_client_set_arg(lwgsm_mqtt_client_p client, void *arg)

Set user argument on client.

Parameters

  • [in] client: MQTT client handle

  • [in] arg: 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.

Return

Connection status. Member of lwgsm_mqtt_conn_status_t

Parameters

  • [in] client: MQTT client

  • [in] evt: Event handle

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.

Return

1 on success, 0 otherwise

Parameters

  • [in] client: MQTT client

  • [in] evt: Event handle

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.

Return

User argument

Parameters

  • [in] client: MQTT client

  • [in] evt: Event handle

lwgsm_mqtt_client_evt_subscribe_get_result(client, evt)

Get result of subscribe event.

Return

lwgsmOK on success, member of lwgsmr_t otherwise

Parameters

  • [in] client: MQTT client

  • [in] evt: Event handle

lwgsm_mqtt_client_evt_unsubscribe_get_argument(client, evt)

Get user argument used on lwgsm_mqtt_client_unsubscribe.

Return

User argument

Parameters

  • [in] client: MQTT client

  • [in] evt: Event handle

lwgsm_mqtt_client_evt_unsubscribe_get_result(client, evt)

Get result of unsubscribe event.

Return

lwgsmOK on success, member of lwgsmr_t otherwise

Parameters

  • [in] client: MQTT client

  • [in] evt: Event handle

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.

Return

Topic name

Parameters

  • [in] client: MQTT client

  • [in] evt: Event handle

lwgsm_mqtt_client_evt_publish_recv_get_topic_len(client, evt)

Get topic length from received publish packet.

Return

Topic length

Parameters

  • [in] client: MQTT client

  • [in] evt: Event handle

lwgsm_mqtt_client_evt_publish_recv_get_payload(client, evt)

Get payload from received publish packet.

Return

Packet payload

Parameters

  • [in] client: MQTT client

  • [in] evt: Event handle

lwgsm_mqtt_client_evt_publish_recv_get_payload_len(client, evt)

Get payload length from received publish packet.

Return

Payload length

Parameters

  • [in] client: MQTT client

  • [in] evt: Event handle

lwgsm_mqtt_client_evt_publish_recv_is_duplicate(client, evt)

Check if packet is duplicated.

Return

1 if duplicated, 0 otherwise

Parameters

  • [in] client: MQTT client

  • [in] evt: Event handle

lwgsm_mqtt_client_evt_publish_recv_get_qos(client, evt)

Get received quality of service.

Return

Member of lwgsm_mqtt_qos_t enumeration

Parameters

  • [in] client: MQTT client

  • [in] evt: Event handle

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.

Return

User argument

Parameters

  • [in] client: MQTT client

  • [in] evt: Event handle

lwgsm_mqtt_client_evt_publish_get_result(client, evt)

Get result of publish event.

Return

lwgsmOK on success, member of lwgsmr_t otherwise

Parameters

  • [in] client: MQTT client

  • [in] evt: Event handle

Defines

lwgsm_mqtt_client_evt_get_type(client, evt)

Get MQTT event type.

Return

MQTT Event type, value of lwgsm_mqtt_evt_type_t enumeration

Parameters

  • [in] client: MQTT client

  • [in] evt: Event handle