An implementation of MQTT v3.1

This application is an engine for MQTT v3.1. More...

Files
file	mqtt.c
	Implementation of the Contiki MQTT engine.
file	mqtt.h
	Header file for the Contiki MQTT engine.

Typedefs
typedef void(*	mqtt_event_callback_t) (struct mqtt_connection *m, mqtt_event_t event, void *data)
	MQTT event callback function. More...

Enumerations
enum	mqtt_event_t
	MQTT engine events.

Functions
mqtt_status_t	mqtt_register (struct mqtt_connection *conn, struct process *app_process, char *client_id, mqtt_event_callback_t event_callback, uint16_t max_segment_size)
	Initializes the MQTT engine. More...
mqtt_status_t	mqtt_connect (struct mqtt_connection *conn, char *host, uint16_t port, uint16_t keep_alive, uint8_t clean_session)
	Connects to a MQTT broker. More...
void	mqtt_disconnect (struct mqtt_connection *conn)
	Disconnects from a MQTT broker. More...
mqtt_status_t	mqtt_subscribe (struct mqtt_connection *conn, uint16_t *mid, char *topic, mqtt_qos_level_t qos_level)
	Subscribes to a MQTT topic. More...
mqtt_status_t	mqtt_unsubscribe (struct mqtt_connection *conn, uint16_t *mid, char *topic)
	Unsubscribes from a MQTT topic. More...
mqtt_status_t	mqtt_publish (struct mqtt_connection *conn, uint16_t *mid, char *topic, uint8_t *payload, uint32_t payload_size, mqtt_qos_level_t qos_level, mqtt_retain_t retain)
	Publish to a MQTT topic. More...
void	mqtt_set_username_password (struct mqtt_connection *conn, char *username, char *password)
	Set the user name and password for a MQTT client. More...
void	mqtt_set_last_will (struct mqtt_connection *conn, char *topic, char *message, mqtt_qos_level_t qos)
	Set the last will topic and message for a MQTT client. More...

Detailed Description

This application is an engine for MQTT v3.1.

It supports QoS Levels 0 and 1.

MQTT is a Client Server publish/subscribe messaging transport protocol. It is light weight, open, simple, and designed so as to be easy to implement. These characteristics make it ideal for use in many situations, including constrained environments such as for communication in Machine to Machine (M2M) and Internet of Things (IoT) contexts where a small code footprint is required and/or network bandwidth is at a premium.

The protocol runs over TCP/IP, more specifically tcp_socket. Its features include:

• Use of the publish/subscribe message pattern which provides one-to-many message distribution and decoupling of applications.
• A messaging transport that is agnostic to the content of the payload. Three qualities of service for message delivery: – "At most once" (0), where messages are delivered according to the best efforts of the operating environment. Message loss can occur. This level could be used, for example, with ambient sensor data where it does not matter if an individual reading is lost as the next one will be published soon after. –"At least once" (1), where messages are assured to arrive but duplicates can occur. – "Exactly once" (2), where message are assured to arrive exactly once. This level could be used, for example, with billing systems where duplicate or lost messages could lead to incorrect charges being applied. This QoS level is currently not supported in this implementation.
• A small transport overhead and protocol exchanges minimized to reduce network traffic.

• A mechanism, Last Will, to notify interested parties when an abnormal disconnection occurs.

  The protocol specification and other useful information can be found here: http://mqtt.org

Typedef Documentation

mqtt_event_callback_t

typedef void(* mqtt_event_callback_t) (struct mqtt_connection *m, mqtt_event_t event, void *data)

MQTT event callback function.

Parameters

m	A pointer to a MQTT connection
event	The event number
data	A user-defined pointer

The MQTT socket event callback function gets called whenever there is an event on a MQTT connection, such as the connection getting connected or closed.

Definition at line 346 of file mqtt.h.

Function Documentation

mqtt_connect()

mqtt_status_t mqtt_connect	(	struct mqtt_connection *	conn,
		char *	host,
		uint16_t	port,
		uint16_t	keep_alive,
		uint8_t	clean_session
	)

Connects to a MQTT broker.

Parameters

conn	A pointer to the MQTT connection.
host	IP address of the broker to connect to.
port	Port of the broker to connect to, default is MQTT port is 1883.
keep_alive	Keep alive timer in seconds. Used by broker to handle client disc. Defines the maximum time interval between two messages from the client. Shall be min 1.5 x report interval.
clean_session	Request a new session and discard pending messages with QoS > 0, as well as client subscriptions

Returns

MQTT_STATUS_OK or an error status

This function connects to a MQTT broker.

Definition at line 1422 of file mqtt.c.

mqtt_disconnect()

void mqtt_disconnect

(

struct mqtt_connection *

conn

)

Disconnects from a MQTT broker.

Parameters

conn	A pointer to the MQTT connection.

This function disconnects from a MQTT broker.

Definition at line 1463 of file mqtt.c.

mqtt_publish()

mqtt_status_t mqtt_publish	(	struct mqtt_connection *	conn,
		uint16_t *	mid,
		char *	topic,
		uint8_t *	payload,
		uint32_t	payload_size,
		mqtt_qos_level_t	qos_level,
		mqtt_retain_t	retain
	)

Publish to a MQTT topic.

Parameters

conn	A pointer to the MQTT connection.
mid	A pointer to message ID.
topic	A pointer to the topic to subscribe to.
payload	A pointer to the topic payload.
payload_size	Payload size.
qos_level	Quality Of Service level to use. Currently supports 0, 1.
retain	If the RETAIN flag is set to 1, in a PUBLISH Packet sent by a Client to a Server, the Server MUST store the Application Message and its QoS, so that it can be delivered to future subscribers whose subscriptions match its topic name

Returns

MQTT_STATUS_OK or some error status

This function publishes to a topic on a MQTT broker.

Definition at line 1528 of file mqtt.c.

mqtt_register()

mqtt_status_t mqtt_register	(	struct mqtt_connection *	conn,
		struct process *	app_process,
		char *	client_id,
		mqtt_event_callback_t	event_callback,
		uint16_t	max_segment_size
	)

Initializes the MQTT engine.

Parameters

conn	A pointer to the MQTT connection.
app_process	A pointer to the application process handling the MQTT connection.
client_id	A pointer to the MQTT client ID.
event_callback	Callback function responsible for handling the callback from MQTT engine.
max_segment_size	The TCP segment size to use for this MQTT/TCP connection.

Returns

MQTT_STATUS_OK or MQTT_STATUS_INVALID_ARGS_ERROR

This function initializes the MQTT engine and shall be called before any other MQTT function.

Definition at line 1389 of file mqtt.c.

mqtt_set_last_will()

void mqtt_set_last_will	(	struct mqtt_connection *	conn,
		char *	topic,
		char *	message,
		mqtt_qos_level_t	qos
	)

Set the last will topic and message for a MQTT client.

Parameters

conn	A pointer to the MQTT connection.
topic	A pointer to the Last Will topic.
message	A pointer to the Last Will message (payload).
qos	The desired QoS level.

This function sets clients Last Will topic and message (payload). If the Will Flag is set to 1 (using the function) this indicates that, if the Connect request is accepted, a Will Message MUST be stored on the Server and associated with the Network Connection. The Will Message MUST be published when the Network Connection is subsequently closed.

This functionality can be used to get notified that a device has disconnected from the broker.

Definition at line 1581 of file mqtt.c.

mqtt_set_username_password()

void mqtt_set_username_password	(	struct mqtt_connection *	conn,
		char *	username,
		char *	password
	)

Set the user name and password for a MQTT client.

Parameters

conn	A pointer to the MQTT connection.
username	A pointer to the user name.
password	A pointer to the password.

This function sets clients user name and password to use when connecting to a MQTT broker.

Definition at line 1560 of file mqtt.c.

mqtt_subscribe()

mqtt_status_t mqtt_subscribe	(	struct mqtt_connection *	conn,
		uint16_t *	mid,
		char *	topic,
		mqtt_qos_level_t	qos_level
	)

Subscribes to a MQTT topic.

Parameters

conn	A pointer to the MQTT connection.
mid	A pointer to message ID.
topic	A pointer to the topic to subscribe to.
qos_level	Quality Of Service level to use. Currently supports 0, 1.

Returns

MQTT_STATUS_OK or some error status

This function subscribes to a topic on a MQTT broker.

Definition at line 1475 of file mqtt.c.

mqtt_unsubscribe()

mqtt_status_t mqtt_unsubscribe	(	struct mqtt_connection *	conn,
		uint16_t *	mid,
		char *	topic
	)

Unsubscribes from a MQTT topic.

Parameters

conn	A pointer to the MQTT connection.
mid	A pointer to message ID.
topic	A pointer to the topic to unsubscribe from.

Returns

MQTT_STATUS_OK or some error status

This function unsubscribes from a topic on a MQTT broker.

Definition at line 1503 of file mqtt.c.