Modules
	Options

Data Structures
struct	mqtt_connect_client_info_t

Macros
#define	MQTT_PORT LWIP_IANA_PORT_MQTT

#define	MQTT_TLS_PORT LWIP_IANA_PORT_SECURE_MQTT

#define	mqtt_subscribe(client, topic, qos, cb, arg) mqtt_sub_unsub(client, topic, qos, cb, arg, 1)

#define	mqtt_unsubscribe(client, topic, cb, arg) mqtt_sub_unsub(client, topic, 0, cb, arg, 0)

Typedefs
typedef void(*	mqtt_connection_cb_t) (mqtt_client_t client, void arg, mqtt_connection_status_t status)

typedef void(*	mqtt_incoming_data_cb_t) (void arg, const u8_t data, u16_t len, u8_t flags)

typedef void(*	mqtt_incoming_publish_cb_t) (void arg, const char topic, u32_t tot_len)

typedef void(*	mqtt_request_cb_t) (void *arg, err_t err)

Enumerations
enum	mqtt_connection_status_t { MQTT_CONNECT_ACCEPTED = 0, MQTT_CONNECT_REFUSED_PROTOCOL_VERSION = 1, MQTT_CONNECT_REFUSED_IDENTIFIER = 2, MQTT_CONNECT_REFUSED_SERVER = 3, MQTT_CONNECT_REFUSED_USERNAME_PASS = 4, MQTT_CONNECT_REFUSED_NOT_AUTHORIZED_ = 5, MQTT_CONNECT_DISCONNECTED = 256, MQTT_CONNECT_TIMEOUT = 257 }

enum	{ MQTT_DATA_FLAG_LAST = 1 }

Functions
err_t	mqtt_publish (mqtt_client_t client, const char topic, const void payload, u16_t payload_length, u8_t qos, u8_t retain, mqtt_request_cb_t cb, void arg)

err_t	mqtt_sub_unsub (mqtt_client_t client, const char topic, u8_t qos, mqtt_request_cb_t cb, void *arg, u8_t sub)

void	mqtt_set_inpub_callback (mqtt_client_t client, mqtt_incoming_publish_cb_t pub_cb, mqtt_incoming_data_cb_t data_cb, void arg)

mqtt_client_t *	mqtt_client_new (void)

void	mqtt_client_free (mqtt_client_t *client)

err_t	mqtt_client_connect (mqtt_client_t client, const ip_addr_t ip_addr, u16_t port, mqtt_connection_cb_t cb, void arg, const struct mqtt_connect_client_info_t client_info)

void	mqtt_disconnect (mqtt_client_t *client)

u8_t	mqtt_client_is_connected (mqtt_client_t *client)

Detailed Description

MQTT client for lwIP

Author: Erik Andersson

Details of the MQTT protocol can be found at:
http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html 

-----------------------------------------------------------------
1. Initial steps, reserve memory and make connection to server:

1.1: Provide storage

Static allocation:
  mqtt_client_t static_client;
  example_do_connect(&static_client);

Dynamic allocation:
  mqtt_client_t *client = mqtt_client_new();
  if(client != NULL) {
    example_do_connect(&client);
  }
  
1.2: Establish Connection with server

void example_do_connect(mqtt_client_t *client)
{
  struct mqtt_connect_client_info_t ci;
  err_t err;
  
  /* Setup an empty client info structure */
  memset(&ci, 0, sizeof(ci));
  
  /* Minimal amount of information required is client identifier, so set it here */ 
  ci.client_id = "lwip_test";
  
  /* Initiate client and connect to server, if this fails immediately an error code is returned
     otherwise mqtt_connection_cb will be called with connection result after attempting 
     to establish a connection with the server. 
     For now MQTT version 3.1.1 is always used */
  
  err = mqtt_client_connect(client, ip_addr, MQTT_PORT, mqtt_connection_cb, 0, &ci);
  
  /* For now just print the result code if something goes wrong */
  if(err != ERR_OK) {
    printf("mqtt_connect return %d\n", err);
  }
}

Connection to server can also be probed by calling mqtt_client_is_connected(client) 

-----------------------------------------------------------------
2. Implementing the connection status callback


static void mqtt_connection_cb(mqtt_client_t *client, void *arg, mqtt_connection_status_t status)
{
  err_t err;
  if(status == MQTT_CONNECT_ACCEPTED) {
    printf("mqtt_connection_cb: Successfully connected\n");
    
    /* Setup callback for incoming publish requests */
    mqtt_set_inpub_callback(client, mqtt_incoming_publish_cb, mqtt_incoming_data_cb, arg);
    
    /* Subscribe to a topic named "subtopic" with QoS level 1, call mqtt_sub_request_cb with result */ 
    err = mqtt_subscribe(client, "subtopic", 1, mqtt_sub_request_cb, arg);

    if(err != ERR_OK) {
      printf("mqtt_subscribe return: %d\n", err);
    }
  } else {
    printf("mqtt_connection_cb: Disconnected, reason: %d\n", status);
    
    /* Its more nice to be connected, so try to reconnect */
    example_do_connect(client);
  }  
}

static void mqtt_sub_request_cb(void *arg, err_t result)
{
  /* Just print the result code here for simplicity, 
     normal behaviour would be to take some action if subscribe fails like 
     notifying user, retry subscribe or disconnect from server */
  printf("Subscribe result: %d\n", result);
}

-----------------------------------------------------------------
3. Implementing callbacks for incoming publish and data

/* The idea is to demultiplex topic and create some reference to be used in data callbacks
   Example here uses a global variable, better would be to use a member in arg
   If RAM and CPU budget allows it, the easiest implementation might be to just take a copy of
   the topic string and use it in mqtt_incoming_data_cb
*/
static int inpub_id;
static void mqtt_incoming_publish_cb(void *arg, const char *topic, u32_t tot_len)
{
  printf("Incoming publish at topic %s with total length %u\n", topic, (unsigned int)tot_len);

  /* Decode topic string into a user defined reference */
  if(strcmp(topic, "print_payload") == 0) {
    inpub_id = 0;
  } else if(topic[0] == 'A') {
    /* All topics starting with 'A' might be handled at the same way */
    inpub_id = 1;
  } else {
    /* For all other topics */
    inpub_id = 2;
  }
}

static void mqtt_incoming_data_cb(void *arg, const u8_t *data, u16_t len, u8_t flags)
{
  printf("Incoming publish payload with length %d, flags %u\n", len, (unsigned int)flags);

  if(flags & MQTT_DATA_FLAG_LAST) {
    /* Last fragment of payload received (or whole part if payload fits receive buffer
       See MQTT_VAR_HEADER_BUFFER_LEN)  */

    /* Call function or do action depending on reference, in this case inpub_id */
    if(inpub_id == 0) {
      /* Don't trust the publisher, check zero termination */
      if(data[len-1] == 0) {
        printf("mqtt_incoming_data_cb: %s\n", (const char *)data);
      }
    } else if(inpub_id == 1) {
      /* Call an 'A' function... */
    } else {
      printf("mqtt_incoming_data_cb: Ignoring payload...\n");
    }
  } else {
    /* Handle fragmented payload, store in buffer, write to file or whatever */
  }
}

-----------------------------------------------------------------
4. Using outgoing publish


void example_publish(mqtt_client_t *client, void *arg)
{
  const char *pub_payload= "PubSubHubLubJub";
  err_t err;
  u8_t qos = 2; /* 0 1 or 2, see MQTT specification */
  u8_t retain = 0; /* No don't retain such crappy payload... */
  err = mqtt_publish(client, "pub_topic", pub_payload, strlen(pub_payload), qos, retain, mqtt_pub_request_cb, arg);
  if(err != ERR_OK) {
    printf("Publish err: %d\n", err);
  }
}

/* Called when publish is complete either with sucess or failure */
static void mqtt_pub_request_cb(void *arg, err_t result)
{
  if(result != ERR_OK) {
    printf("Publish result: %d\n", result);
  }
}

-----------------------------------------------------------------
5. Disconnecting

Simply call mqtt_disconnect(client)

Macro Definition Documentation

◆ MQTT_PORT

#define MQTT_PORT LWIP_IANA_PORT_MQTT

Default MQTT port (non-TLS)

◆ mqtt_subscribe

#define mqtt_subscribe	(	client,
		topic,
		qos,
		cb,
		arg
	)	mqtt_sub_unsub(client, topic, qos, cb, arg, 1)

Subscribe to topic

◆ MQTT_TLS_PORT

#define MQTT_TLS_PORT LWIP_IANA_PORT_SECURE_MQTT

Default MQTT TLS port

◆ mqtt_unsubscribe

#define mqtt_unsubscribe	(	client,
		topic,
		cb,
		arg
	)	mqtt_sub_unsub(client, topic, 0, cb, arg, 0)

Unsubscribe to topic

Typedef Documentation

◆ mqtt_connection_cb_t

typedef void(* mqtt_connection_cb_t) (mqtt_client_t *client, void *arg, mqtt_connection_status_t status)

Function prototype for mqtt connection status callback. Called when client has connected to the server after initiating a mqtt connection attempt by calling mqtt_client_connect() or when connection is closed by server or an error

Parameters

client	MQTT client itself
arg	Additional argument to pass to the callback function
status	Connect result code or disconnection notification

See also: mqtt_connection_status_t

◆ mqtt_incoming_data_cb_t

typedef void(* mqtt_incoming_data_cb_t) (void *arg, const u8_t *data, u16_t len, u8_t flags)

Function prototype for MQTT incoming publish data callback function. Called when data arrives to a subscribed topic

See also: mqtt_subscribe

Parameters

arg	Additional argument to pass to the callback function
data	User data, pointed object, data may not be referenced after callback return, NULL is passed when all publish data are delivered
len	Length of publish data fragment
flags	MQTT_DATA_FLAG_LAST set when this call contains the last part of data from publish message

◆ mqtt_incoming_publish_cb_t

typedef void(* mqtt_incoming_publish_cb_t) (void *arg, const char *topic, u32_t tot_len)

Function prototype for MQTT incoming publish function. Called when an incoming publish arrives to a subscribed topic

See also: mqtt_subscribe

Parameters

arg	Additional argument to pass to the callback function
topic	Zero terminated Topic text string, topic may not be referenced after callback return
tot_len	Total length of publish data, if set to 0 (no publish payload) data callback will not be invoked

◆ mqtt_request_cb_t

typedef void(* mqtt_request_cb_t) (void *arg, err_t err)

Function prototype for mqtt request callback. Called when a subscribe, unsubscribe or publish request has completed

Parameters

arg	Pointer to user data supplied when invoking request
err	ERR_OK on success ERR_TIMEOUT if no response was received within timeout, ERR_ABRT if (un)subscribe was denied

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Data callback flags

Enumerator
MQTT_DATA_FLAG_LAST	Flag set when last fragment of data arrives in data callback

◆ mqtt_connection_status_t

enum mqtt_connection_status_t

Connection status codes

Enumerator
MQTT_CONNECT_ACCEPTED	Accepted
MQTT_CONNECT_REFUSED_PROTOCOL_VERSION	Refused protocol version
MQTT_CONNECT_REFUSED_IDENTIFIER	Refused identifier
MQTT_CONNECT_REFUSED_SERVER	Refused server
MQTT_CONNECT_REFUSED_USERNAME_PASS	Refused user credentials
MQTT_CONNECT_REFUSED_NOT_AUTHORIZED_	Refused not authorized
MQTT_CONNECT_DISCONNECTED	Disconnected
MQTT_CONNECT_TIMEOUT	Timeout

Function Documentation

◆ mqtt_client_connect()

err_t mqtt_client_connect	(	mqtt_client_t *	client,
		const ip_addr_t *	ip_addr,
		u16_t	port,
		mqtt_connection_cb_t	cb,
		void *	arg,
		const struct mqtt_connect_client_info_t *	client_info
	)

Connect to MQTT server

Parameters

client	MQTT client
ip_addr	Server IP
port	Server port
cb	Connection state change callback
arg	User supplied argument to connection callback
client_info	Client identification and connection options

Returns: ERR_OK if successful,

See also: err_t enum for other results

◆ mqtt_client_free()

void mqtt_client_free ( mqtt_client_t * client )

Free MQTT client instance

Parameters

client Pointer to instance to be freed

◆ mqtt_client_is_connected()

u8_t mqtt_client_is_connected ( mqtt_client_t * client )

Check connection with server

Parameters

client MQTT client

Returns: 1 if connected to server, 0 otherwise

◆ mqtt_client_new()

mqtt_client_t* mqtt_client_new ( void )

Create a new MQTT client instance

Returns: Pointer to instance on success, NULL otherwise

◆ mqtt_disconnect()

void mqtt_disconnect ( mqtt_client_t * client )

Disconnect from MQTT server

Parameters

client MQTT client

◆ mqtt_publish()

err_t mqtt_publish	(	mqtt_client_t *	client,
		const char *	topic,
		const void *	payload,
		u16_t	payload_length,
		u8_t	qos,
		u8_t	retain,
		mqtt_request_cb_t	cb,
		void *	arg
	)

MQTT publish function.

Parameters

client	MQTT client
topic	Publish topic string
payload	Data to publish (NULL is allowed)
payload_length	Length of payload (0 is allowed)
qos	Quality of service, 0 1 or 2
retain	MQTT retain flag
cb	Callback to call when publish is complete or has timed out
arg	User supplied argument to publish callback

Returns: ERR_OK if successful ERR_CONN if client is disconnected ERR_MEM if short on memory

◆ mqtt_set_inpub_callback()

void mqtt_set_inpub_callback	(	mqtt_client_t *	client,
		mqtt_incoming_publish_cb_t	pub_cb,
		mqtt_incoming_data_cb_t	data_cb,
		void *	arg
	)

Set callback to handle incoming publish requests from server

Parameters

client	MQTT client
pub_cb	Callback invoked when publish starts, contain topic and total length of payload
data_cb	Callback for each fragment of payload that arrives
arg	User supplied argument to both callbacks

◆ mqtt_sub_unsub()

err_t mqtt_sub_unsub	(	mqtt_client_t *	client,
		const char *	topic,
		u8_t	qos,
		mqtt_request_cb_t	cb,
		void *	arg,
		u8_t	sub
	)

MQTT subscribe/unsubscribe function.

Parameters

client	MQTT client
topic	topic to subscribe to
qos	Quality of service, 0 1 or 2 (only used for subscribe)
cb	Callback to call when subscribe/unsubscribe reponse is received
arg	User supplied argument to publish callback
sub	1 for subscribe, 0 for unsubscribe

Returns: ERR_OK if successful,

See also: err_t enum for other results

Modules

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ MQTT_PORT

◆ mqtt_subscribe

◆ MQTT_TLS_PORT

◆ mqtt_unsubscribe

Typedef Documentation

◆ mqtt_connection_cb_t

◆ mqtt_incoming_data_cb_t

◆ mqtt_incoming_publish_cb_t

◆ mqtt_request_cb_t

Enumeration Type Documentation

◆ anonymous enum

◆ mqtt_connection_status_t

Function Documentation

◆ mqtt_client_connect()

◆ mqtt_client_free()

◆ mqtt_client_is_connected()

◆ mqtt_client_new()

◆ mqtt_disconnect()

◆ mqtt_publish()

◆ mqtt_set_inpub_callback()

◆ mqtt_sub_unsub()