The MQ Telemetry Transport (MQTT) is a lightweight broker-based publish/subscribe messaging protocol designed to be open, simple, lightweight and easy to implement. These characteristics make it ideal for use in constrained environments, for example, but not limited to:

• Where the network is expensive, has low bandwidth or is unreliable such as mobile and vsat networks
• When run on an embedded or mobile device with limited processor, memory or battery

Features of the protocol include:

• The publish/subscribe message pattern to provide one-to-many message distribution and decoupling of applications
• A messaging transport that is agnostic to the content of the payload
• The use of TCP/IP to provide network connectivity
• The use of SSL/TLS to provide network security and trust
• Three qualities of service for message delivery which are maintained across network, client and server breaks.
  • "At most once", where messages are delivered according to the best efforts of the underlying TCP/IP network. Message loss or duplication 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", where messages are assured to arrive but duplicates may occur.
  • "Exactly once", 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.
  The quality of service for message delivery is met even if the network connection breaks, or the client or the server stop while a message is being delivered
• A small transport overhead (the fixed-length header is just 2 bytes), and protocol exchanges minimised to reduce network traffic
• A mechanism to notify interested parties to an abnormal disconnection of a client using the Last Will and Testament feature

The basic means of operating the client is:

1. Create an instance of {@link org.eclipse.paho.client.mqttv3.MqttClient} or {@link org.eclipse.paho.client.mqttv3.MqttAsyncClient}, providing the address of an MQTT server and a unique client identifier.
2. connect to the server
3. Exchange messages with the server:
   • publish messages to the server specifying a topic as the destination on the server
   • subscribe to one more topics. The server will send any messages it receives on those topics to the client. The client will be informed when a message arrives via a callback
4. disconnect from the server.

The programming model and concepts like the protocol are small and easy to use. Key concepts to use when creating MQTT application include:

• Every client instance that connects to an MQTT server must have a unique client identifier. If a second instance of a client with the same ID connects to a server the first instance will be disconnected.
• For message delivery to be reliable and withstand normal and abnormal network breaks together with client and server outages the client must use a persistent store to hold messages while they are being delivered. This is the default case where a file based persistent store {@link org.eclipse.paho.client.mqttv3.persist.MqttDefaultFilePersistence MqttDefaultFilePersistence} is used.
• When connecting the {@link org.eclipse.paho.client.mqttv3.MqttConnectOptions#setCleanSession(boolean) cleansession} option has a big impact on the operation of the client. If set to false:
  • Message delivery will match the quality of service specified when the message was published even across failures of the network, client or server
  • The server will store messages for active subscriptions on behalf of the client when the client is not connected. The server will deliver these messages to the client the next time it connects.
  If set to true:
  • Any state stored on the client and server related to the client will be cleansed before the connection is fully started. Subscriptions from earlier sessions will be unsubscribed and any messages still in-flight from previous sessions will be deleted.
  • When the client disconnects either as the result of the application requesting a disconnect or a network failure, state related to the client will be cleansed just as at connect time.
  • Messages will only be delivered to the quality of service requested at publish time if the connection is maintained while the message is being delivered
• When subscribing for messages the subscription can be for an absolute topic or a wildcarded topic.
• When unsubscribing the topic to be unsubscribed must match one specified on an earlier subscribe.
• There are two MQTT client libraries to choose from:
  1. {@link org.eclipse.paho.client.mqttv3.IMqttAsyncClient MqttAsyncClient} which provides a non-blocking interface where methods return before the requested operation has completed. The completion of the operation can be monitored by in several ways:
     • Use the {@link org.eclipse.paho.client.mqttv3.IMqttToken#waitForCompletion waitForCompletion} call on the token returned from the operation. This will block until the operation completes.
     • Pass a {@link org.eclipse.paho.client.mqttv3.IMqttActionListener IMqttActionListener} to the operation. The listener will then be called back when the operation completes.
     • Set a {@link org.eclipse.paho.client.mqttv3.MqttCallback MqttCallback} on the client. It will be notified when a message arrives, a message have been delivered to the server and when the connection to the server is lost.
  2. {@link org.eclipse.paho.client.mqttv3.IMqttClient MqttClient} where methods block until the operation has completed.
• For both the blocking and non-blocking clients some operations are asynchronous. This includes:
  • Notification that a new message has arrived: {@link org.eclipse.paho.client.mqttv3.MqttCallback#messageArrived messageArrived}.
  • Notification that the connection to the server has broken: {@link org.eclipse.paho.client.mqttv3.MqttCallback#connectionLost connectionLost}.
  • Notification that a message has been delivered to the server: {@link org.eclipse.paho.client.mqttv3.MqttCallback#deliveryComplete deliveryComplete}.
  A client registers interest in these notifications by registering a {@link org.eclipse.paho.client.mqttv3.MqttCallback MqttCallback} on the client
• There are a number of programs that demonstrate the different modes of writing MQTT applications
  • {@link org.eclipse.paho.sample.mqttv3app.Sample} uses the blocking client interface
  • {@link org.eclipse.paho.sample.mqttv3app.SampleAsyncCallBack} uses the asynchronous client with callbacks which are notified when an operation completes
  • {@link org.eclipse.paho.sample.mqttv3app.SampleAsyncWait} uses the asynchronous client and shows how to use the token returned from each operation to block until the operation completes.
• {@link org.eclipse.paho.client.mqttv3.MqttConnectOptions MqttConnectOptions} can be used to override the default connection options. This includes:
  • Setting the cleansession flag
  • Specifying a list of MQTT servers that the client can attempt to connect to
  • Set a keepalive interval
  • Setting the last will and testament
  • Setting security credentials