MQTT Client

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

group LWCELL_APP_MQTT_CLIENT

MQTT client.

Typedefs

typedef struct lwcell_mqtt_client *lwcell_mqtt_client_p: Pointer to lwcell_mqtt_client_t structure.

typedef void (*lwcell_mqtt_evt_fn)(lwcell_mqtt_client_p client, lwcell_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 lwcell_mqtt_qos_t

Quality of service enumeration.

Values:

enumerator LWCELL_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 LWCELL_MQTT_QOS_AT_LEAST_ONCE = 0x01: Delivery is quaranteed at least once, but it may be delivered multiple times with the same content

enumerator LWCELL_MQTT_QOS_EXACTLY_ONCE = 0x02: Delivery is quaranteed exactly once = very critical packets such as billing informations or similar

enum lwcell_mqtt_state_t

State of MQTT client.

Values:

enumerator LWCELL_MQTT_CONN_DISCONNECTED = 0x00: Connection with server is not established

enumerator LWCELL_MQTT_CONN_CONNECTING: Client is connecting to server

enumerator LWCELL_MQTT_CONN_DISCONNECTING: Client connection is disconnecting from server

enumerator LWCELL_MQTT_CONNECTING: MQTT client is connecting… CONNECT command has been sent to server

enumerator LWCELL_MQTT_CONNECTED: MQTT is fully connected and ready to send data on topics

enum lwcell_mqtt_evt_type_t

MQTT event types.

Values:

enumerator LWCELL_MQTT_EVT_CONNECT: MQTT client connect event

enumerator LWCELL_MQTT_EVT_SUBSCRIBE: MQTT client subscribed to specific topic

enumerator LWCELL_MQTT_EVT_UNSUBSCRIBE: MQTT client unsubscribed from specific topic

enumerator LWCELL_MQTT_EVT_PUBLISH: MQTT client publish message to server event.

Note

When publishing packet with quality of service LWCELL_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 = LWCELL_MQTT_QOS_AT_MOST_ONCE

enumerator LWCELL_MQTT_EVT_PUBLISH_RECV: MQTT client received a publish message from server

enumerator LWCELL_MQTT_EVT_DISCONNECT: MQTT client disconnected from MQTT server

enumerator LWCELL_MQTT_EVT_KEEP_ALIVE: MQTT keep-alive sent to server and reply received

enum lwcell_mqtt_conn_status_t

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

Values:

enumerator LWCELL_MQTT_CONN_STATUS_ACCEPTED = 0x00: Connection accepted and ready to use

enumerator LWCELL_MQTT_CONN_STATUS_REFUSED_PROTOCOL_VERSION = 0x01: Connection Refused, unacceptable protocol version

enumerator LWCELL_MQTT_CONN_STATUS_REFUSED_ID = 0x02: Connection refused, identifier rejected

enumerator LWCELL_MQTT_CONN_STATUS_REFUSED_SERVER = 0x03: Connection refused, server unavailable

enumerator LWCELL_MQTT_CONN_STATUS_REFUSED_USER_PASS = 0x04: Connection refused, bad user name or password

enumerator LWCELL_MQTT_CONN_STATUS_REFUSED_NOT_AUTHORIZED = 0x05: Connection refused, not authorized

enumerator LWCELL_MQTT_CONN_STATUS_TCP_FAILED = 0x100: TCP connection to server was not successful

Functions

lwcell_mqtt_client_p lwcell_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 lwcell_mqtt_client_delete(lwcell_mqtt_client_p client)

Delete MQTT client structure.

Note

MQTT client must be disconnected first

Parameters: client – [in] MQTT client

lwcellr_t lwcell_mqtt_client_connect(lwcell_mqtt_client_p client, const char *host, lwcell_port_t port, lwcell_mqtt_evt_fn evt_fn, const lwcell_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

lwcellOK on success, member of lwcellr_t enumeration otherwise

lwcellr_t lwcell_mqtt_client_disconnect(lwcell_mqtt_client_p client)

Disconnect from MQTT server.

Parameters: client – [in] MQTT client
Returns: lwcellOK if request sent to queue or member of lwcellr_t otherwise

uint8_t lwcell_mqtt_client_is_connected(lwcell_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

lwcellr_t lwcell_mqtt_client_subscribe(lwcell_mqtt_client_p client, const char *topic, lwcell_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 lwcell_mqtt_qos_t
arg – [in] User custom argument used in callback

Returns

lwcellOK on success, member of lwcellr_t enumeration otherwise

lwcellr_t lwcell_mqtt_client_unsubscribe(lwcell_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

lwcellOK on success, member of lwcellr_t enumeration otherwise

lwcellr_t lwcell_mqtt_client_publish(lwcell_mqtt_client_p client, const char *topic, const void *payload, uint16_t len, lwcell_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 lwcell_mqtt_qos_t enumeration
retain – [in] Retian parameter value
arg – [in] User custom argument used in callback

Returns

lwcellOK on success, member of lwcellr_t enumeration otherwise

void *lwcell_mqtt_client_get_arg(lwcell_mqtt_client_p client)

Get user argument on client.

Parameters: client – [in] MQTT client handle
Returns: User argument

void lwcell_mqtt_client_set_arg(lwcell_mqtt_client_p client, void *arg)

Set user argument on client.

Parameters

client – [in] MQTT client handle
arg – [in] User argument

struct lwcell_mqtt_client_info_t

#include <lwcell_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

lwcell_mqtt_qos_t will_qos: Will topic quality of service

struct lwcell_mqtt_request_t

#include <lwcell_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 lwcell_mqtt_evt_t

#include <lwcell_mqtt_client.h>

MQTT event structure for callback function.

Public Members

lwcell_mqtt_evt_type_t type: Event type

lwcell_mqtt_conn_status_t status: Connection status with MQTT

struct lwcell_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 lwcell_mqtt_evt_t::[anonymous]::[anonymous] disconnect: Event for disconnecting from server

void *arg: User argument for callback function

lwcellr_t res: Response status

struct lwcell_mqtt_evt_t::[anonymous]::[anonymous] sub_unsub_scribed: Event for (un)subscribe to/from topics

struct lwcell_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

lwcell_mqtt_qos_t qos: Received packet quality of service

uint8_t retain: Retain status of the received packet

struct lwcell_mqtt_evt_t::[anonymous]::[anonymous] publish_recv: Publish received event

union lwcell_mqtt_evt_t::[anonymous] evt: Event data parameters

group LWCELL_APP_MQTT_CLIENT_EVT

Event helper functions.

Connect event

Note

Use these functions on LWCELL_MQTT_EVT_CONNECT event

lwcell_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 lwcell_mqtt_conn_status_t

Disconnect event

Note

Use these functions on LWCELL_MQTT_EVT_DISCONNECT event

lwcell_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

Note

Use these functions on LWCELL_MQTT_EVT_SUBSCRIBE or LWCELL_MQTT_EVT_UNSUBSCRIBE events

lwcell_mqtt_client_evt_subscribe_get_argument(client, evt)

Get user argument used on lwcell_mqtt_client_subscribe.

Parameters

client – [in] MQTT client
evt – [in] Event handle

Returns

User argument

lwcell_mqtt_client_evt_subscribe_get_result(client, evt)

Get result of subscribe event.

Parameters

client – [in] MQTT client
evt – [in] Event handle

Returns

lwcellOK on success, member of lwcellr_t otherwise

lwcell_mqtt_client_evt_unsubscribe_get_argument(client, evt)

Get user argument used on lwcell_mqtt_client_unsubscribe.

Parameters

client – [in] MQTT client
evt – [in] Event handle

Returns

User argument

lwcell_mqtt_client_evt_unsubscribe_get_result(client, evt)

Get result of unsubscribe event.

Parameters

client – [in] MQTT client
evt – [in] Event handle

Returns

lwcellOK on success, member of lwcellr_t otherwise

Publish receive event

Note

Use these functions on LWCELL_MQTT_EVT_PUBLISH_RECV event

lwcell_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

lwcell_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

lwcell_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

lwcell_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

lwcell_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

lwcell_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 lwcell_mqtt_qos_t enumeration

lwcell_mqtt_client_evt_publish_recv_get_retain(client, evt)

Get received retain.

Parameters

client – [in] MQTT client
evt – [in] Event handle

Returns

1 if retained, 0 otherwise

Publish event

Note

Use these functions on LWCELL_MQTT_EVT_PUBLISH event

lwcell_mqtt_client_evt_publish_get_argument(client, evt)

Get user argument used on lwcell_mqtt_client_publish.

Parameters

client – [in] MQTT client
evt – [in] Event handle

Returns

User argument

lwcell_mqtt_client_evt_publish_get_result(client, evt)

Get result of publish event.

Parameters

client – [in] MQTT client
evt – [in] Event handle

Returns

lwcellOK on success, member of lwcellr_t otherwise

Defines

lwcell_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 lwcell_mqtt_evt_type_t enumeration