MQTT: MQTT communication

The MQTT functions implement the Message Queue Telemetry Transport (MQTT) protocol.

MQTT is a open message protocol for M2M communications that enables transfer of telemetry-style data in the form of messages.

The MQTT protocol is based on the principle of publishing messages and subscribing to topics, or "pub/sub". Multiple clients connect to a server and subscribe to topics that they are interested in. Clients also connect to the server and publish messages to topics. Many clients may subscribe to the same topics and do with the information as they please. The server and MQTT act as a simple, common interface for everything to connect to.

MQTT has been characterized as the protocol realizing the Internet of Things the same was as HTTP was the enabler for the Internet of People.

	•mqttOpen	Opens a connection to a MQTT server.
	•mqttClose	Closes a connection to a MQTT server.
	•mqttConnected	Queries if a connection to a MQTT server is active.
	•mqttConnectionLoss	Queries if a connection to a MQTT server has been interrupted.
	•mqttStatus	Get the status of a connection to a MQTT server.
	•mqttPublish	Sends a message to a MQTT server.
	•mqttPendingCount	Returns the number of messages, waiting to be sent.
	•mqttPendingClear	Clears the list of pending messages.
	•mqttSubscribe	Subscribe to a topic on a MQSS server.
	•mqttUnsubscribe	Unsubscribe to a topic on a MQTT server.
	•mqttWaiEvent	Wait for a received message or an optional timeout.
	•mqttReceive	Read a received message.
	•mqttCredentialsSet	Change the credentials used to connect to a MQTT server.

Support for Unicode strings are included in the MQTT API, which means that text (topics, username, etc.) can be in the local language rather than in English. For more information, please refer to mqttOpen.

Topics are treated as a hierarchy, using slash (/) as a separator. This allows sensible arrangement of common themes to be created, much in the same way as a file system.

For example, multiple RTCU devices may publish their temperature information on the following topic:

qos	name	description
0	Fire and forget	The message may not be delivered.
1	At least once	The message will be delivered, but may be delivered more than once in some circumstances.
2	Once and only	The message will be delivered exactly once.

When the RTCU connects to a server, it may inform the server that it has a will.

This is a message that it wishes the server to send when it disconnects unexpectedly.

•Maximum of 3 messages inflight from the server.This is the maximum number of QoS 2 messages that are not fully acknowledged.