MQTT API

FLX provides a MQTT API for implementing MQTT clients with or without a UI. The API implementation is based on the Eclipse’s Paho Android MQTT Service.

MQTT API Functions

Connects to the specified MQTT Broker.

  • brokerAddress – a String specifying the broker address. Address consists of a scheme, a broker host address, and a port number. E.g.: "tcp://broker.hivemq.com:1883"
  • clientId – a String specifying an arbitrary client ID of choice, e.g. "flx_client"
  • connectionCallback – the connect function is asynchronous, so a callback is needed. The callback is defined as a code block. Click the code block icon to open visual code editor for the callback code. The callback provides an input parameter event which has a type of one the subclasses of MqttConnectionEvent.

Returns: Null. The function is asynchronous.

Checks if the given connection is valid.

  • connection – a MqttConnection representing a connection to a broker

Returns: true if the connection is valid, otherwise false.

Disconnects the given connection.

  • connection – a MqttConnection representing a connection to a broker

Returns: Null. Disconnecting is notified asynchronously by a MqttConnectionLost event received by the connection callback.

Subscribes to one more topics. The format and structure for the topic strings is defined, e.g, in Understanding MQTT Topics.

  • connection – a MqttConnection representing a connection to a broker
  • subscriptionCallback – the subscribe function is asynchronous, so a callback is needed. The callback is defined as a code block. Click the code block icon to open visual code editor for the callback code. The callback provides an input parameter event which is of one the subclasses of MqttSubscriptionEvent
  • topics – a one or more topics. Each topic is defined as String.

Returns: Null. The success or failure of the subscribe is notified asynchronously either by MqttSubscribeSucceeded or MqttSubscribeFailed event received by the subscription callback.

Checks if the given subscription is valid.

  • subscription – a MqttSubscription representing a registered subscription

Returns: true if the subscription is valid, otherwise false.

Unsubscribes from receiving messages for the specified topic.

  • subscription – a MqttSubscription representing a registered subscription
  • topic – a String specifying a single topic to be unsubscribed

Returns: Either event MqttUnsubscribeSucceeded or MqttUnsubscribeFailed is received asynchronously via subscription callback.

Unsubscribes from all the currently subscribed topics.

  • subscription – a MqttSubscription representing a registered subscription

Returns: Either event MqttUnsubscribeSucceeded or MqttUnsubscribeFailed is received asynchronously via subscription callback.

Publishes a message under the specified topic.

  • connection – a MqttConnection representing a connection to a broker
  • topic – a topic as a String
  • message – a message to be published given as a String

Returns: Null. Either a MqttPublishSucceeded or MqttPublishFailed event is received asynchronously via the connection callback.

Checks if the given subscriptionEvent (MqttSubscriptionEvent) is actually of type MqttSubscribeSucceeded. An instance of MqttSubscribeSucceeded is received if subscribing to specified topic(s) succeeds. The instance contains a reference to MqttSubscription object which can be used for managing a subscription to a broker. The reference is obtained using function subscription (see below).

  • subscriptionEvent – a MqttSubscriptionEvent to be checked

Returns: true if the actual event type is MqttSubscribeSucceeded, otherwise false.

Gets the MqttSubscription object from the given subscriptionEvent (MqttSubscribeSucceeded).

  • subscriptionEvent – a MqttSubscriptionEvent (actually type MqttSubscribeSucceeded) containing the MqttSubscription object

Returns: a MqttSubscription.

Checks if the given subscriptionEvent (MqttSubscriptionEvent) is actually event MqttSubscribeFailed. An instance of MqttSubscribeSucceeded is received if subscribing to one or more topics fails.

  • subscriptionEvent – a MqttSubscriptionEvent to be checked

Returns: true if the actual event type is MqttSubscribeFailed, otherwise false.

Checks if the given subscriptionEvent (MqttSubscriptionEvent) is actually event MqttMessageReceived. An instance of MqttMessageReceived is received when a new message is received for a subscribed topic. An instance of MqttMessageReceived contains the topic and the received message as Strings. They can accessed using functions topic and message (see below).

  • subscriptionEvent – a MqttSubscriptionEvent to be checked

Returns: true if the actual event type is MqttMessageReceived, otherwise false.

Gets the topic for the received message from the given subscriptionEvent (MqttMessageReceived).

  • subscriptionEvent – a MqttMessageReceived

Returns: the topic as a String.

Gets the received message from the given subscriptionEvent (MqttMessageReceived).

  • subscriptionEvent – a MqttMessageReceived

Returns: the message as a String.

Checks if the given subscriptionEvent (MqttSubscriptionEvent) is actually event MqttUnsubscribeSucceeded. An instance of MqttUnsubscribeSucceeded is received when a topic is successfully unsubscribed.

  • subscriptionEvent – a MqttSubscriptionEvent to be checked

Returns: true if the actual event type is MqttUnsubscribeSucceeded, otherwise false.

Checks if the given subscriptionEvent (MqttSubscriptionEvent) is actually event MqttUnsubscribeFailed. An instance of MqttUnsubscribeFailed is received when unsubscribing a topic fails.

  • subscriptionEvent – a MqttSubscriptionEvent to be checked

Returns: true if the actual event type is MqttUnsubscribeFailed, otherwise false.

Checks if the given connectionEvent (MqttConnectionEvent) is actually event MqttConnectSucceeded. An instance of MqttConnectSucceeded is received when connecting a broker succeeds and it contains MqttConnect object which is needed for managing a connection.

  • subscriptionEvent – a MqttConnectionEvent to be checked

Returns: true if the actual event type is MqttConnectSucceeded, otherwise false.

Checks if the given connectionEvent (MqttConnectionEvent) is actually event MqttConnectFailed. An instance of MqttConnectFailed is received when connecting a broker fails.

  • subscriptionEvent – a MqttConnectionEvent to be checked

Returns: true if the actual event type is MqttConnectFailed, otherwise false.

Checks if the given connectionEvent (MqttConnectionEvent) is actually event MqttConnectionLost. An instance of MqttConnectionLost is received when a connection to a broker is lost for some reason.

  • subscriptionEvent – a MqttConnectionEvent to be checked

Returns: true if the actual event type is MqttConnectionLost, otherwise false.

Checks if the given connectionEvent (MqttConnectionEvent) is actually event MqttPublishSucceeded. An instance of MqttPublishSucceeded is received when publishing a message succeeds.

  • subscriptionEvent – a MqttConnectionEvent to be checked

Returns: true if the actual event type is MqttPublishSucceeded, otherwise false.

Checks if the given connectionEvent (MqttConnectionEvent) is actually event MqttPublishFailed. An instance of MqttPublishFailed is received when publishing a message succeeds.

  • subscriptionEvent – a MqttConnectionEvent to be checked

Returns: true if the actual event type is MqttPublishFailed, otherwise false.

A Simple Example

The following simple example demonstrates how to connect to a broker (e.g. tcp//broker.hivemq.com:1883) to receive messages for a subscribed topic (e.g. sensor1/value):

  1. The scheme for the broker connection, e.g., tcp.
  2. The broker host address.
  3. The host port number. Of course, the complete, fully qualified broker address could be provided as a single string as well.
  4. The topic to be subscribed. In this example, we subscribe for receiving values from sensor1.
  5. The client ID. This is arbitrary, but should be unique among all clients of the broker.
  6. A variable for storing an instance MqttConnection object which is received when a connection to the broker succeeds.
  7. A variable for storing an instance of MqttSubscription object which is received when a subscribing to the topic succeeds. A client implementation can of course subscribe as many topics as needed.
  8. The function to connect to a broker specified by the address. Also the cliend ID and a connection callback needs to be provided.
  9. A connection callback code block. See below how the callback is implemented in this example.
  10. A user defined function onConnected which is invoked by the connection callback when a connection to the broker succeeds (see below).
  11. A user defined function onSubscribed which is invoked the subscription callback when a subscribing to a topic succeeds.
  12. A user defined function onMessageReceived which is invoked when ever a message to any subscribed topic is received.
Connection Callback

The contents of the code block defining the connection callback is depicted in the following screenshot:

  1. The contents of the code block that implements a connection callback.
  2. The callback receives an event which is any of the following subtypes of MqttConnectionEvent:
    • MqttConnectSucceeded
    • MqttConnectFailed
    • MqttConnectionLost
    • MqttPublishSucceeded
    • MqttPublicsFailed
  3. If the event is MqttConnectFailed ,the received event is simply printed to FLX console. In actual client implementation, we could implement a retry policy.
  4. If the event is MqttConnectSucceeded the function onConnected is called with the received event as a parameter. (See the implementation of this function below).
  5. If the event is MqttConnectionLost, the received event is simply printed to FLX console. In actual client implementation, we could implement a reconnect policy.
  6. If the event is MqttPublishFailed, the received event is simply printed to FLX console. In actual client implementation, we could implement a retry policy for publishing.
  7. If the event is MqttPublishSucceeded, the received event is simply printed to FLX console.
Function onConnected

Implementation of the function onConnected invoked by the connection callback is depicted below.

  1. User defined function onConnected receives a MqttConnectSucceeded event as a parameter.
  2. Function connection is used to get the MqttConnection object from the received event. The object is stored into the connection variable.
  3. The received connection can be then used to subscribe for desired topics.
  4. Variable topic defines the topic to be subscribed.
  5. A code block for defining a subscription callback which is needed for asynchronously receiving receiving subscription related events which are implemented as subtypes of MqttSubscription. (See the implementation of subscription callback below).

Subscription Callback

The contents of the code block defining the subscription callback is depicted in the following screenshot:

  1. A code block implementing the subscription callback.
  2. The callback receives an event which is of one of the following subtypes of MqttSubscriptionEvent:
    • MqttSubscribeSucceeded
    • MqttSubscribeFailed
    • MqttUnsubscribeSucceeded
    • MqttUnsubscribeFailed
    • MqttMessageReceived
  3. If a MqttMessageReceived is received, function onMessageReceived is invoked with the received event as a paremeter. (See below the implementation of this function).
  4. If a MqttSubscribeFailed is failed, then the event is simply printed. In an actual client, a retry policy could be implemented.
  5. If a MqttSubscribeSucceeded event is received, function onSubscribed is invoked with the received event as a paremeter. (See below the implementation of this function).
  6. if MqttUnsubscribeFailed is received, then the event is simply printed. In an actual client, a retry policy could be implemented.
  7. if MqttUnsubscribeSucceeded is received, then the event is simply printed. In an actual client, a retry policy could be implemented.
Function onSubscribed

The implementation of the function onSubscribed which is invoked when subscribing a topic succeeds is depicted below:

  1. User defined function onSubscribed.
  2. The function has a single parameter which has type MqttSubscribeSucceeded. The object contains a MqttSubscription object.
  3. The MqttSubscription object is obtained from the received event and is stored to variable subscription so that it can be used later on to manage the made subscription.
Function onMessageReceived

The implementation of the function onMessageReceived which is invoked when ever a message for the subscribed topic is received is depicted below:

  1. User defined function onMessageReceived.
  2. The function received a single input parameter of type MqttMessageReceived.
  3. The topic for the received message is obtained from the received event using function topic.
  4. The actual message is obtained from the received event using function message. Finally, the topic and message are displayed in this example to FLX Console.
  1. FLX Console displaying print traces.
  2. A list of received messages for topic sensor1/value.

MQTT Client Project Template

Starting from version 1.2.4, FLX includes a project template for a MQTT client applet with a UI that consists of three UI screens:

  1. Settings Screen: for establishing a connection to a MQTT Broker
  2. Messages Screen: for viewing the messages received for subscribed topics.
  3. Publish Screen: for publishing messages under defined topics.

Users can use the template as a starting point for creating a custom MQTT clients. Here are screenshots from the MQTT client applet: