salesforce Dreamforce On-Demand
Contact Us 1-800-596-4880
  1. Homepage
  2. MQTT Connector (1.0)

  3. MQTT Connector Studio Configuration

All Connectors

Using Anypoint Studio to Configure MQTT Connector 1.0

Anypoint Studio (Studio) editors help you design and update your Mule applications, properties, and configuration files.

To add and configure a connector in Studio:

  1. Create a Mule project.

  2. Add the connector to your Mule project.

  3. Configure a source for the connector’s flow.

  4. Add a connector operation to the flow.

  5. Configure a global element for the connector.

  6. Configure a connection protocol.

  7. Configure credentials for authentication.

  8. Configure a fail-over server list.

  9. Enable file persistence.

  10. Configure advanced connection options.

When you run the connector, you can view the app log to check for problems, as described in View the App Log.

If you are new to configuring connectors in Studio, see Using Anypoint Studio to Configure a Connector. If, after reading this topic, you need additional information about the connector fields, see the MQTT Connector Reference.

Create a Mule Project

In Studio, create a new Mule project in which to add and configure the connector:

  1. In Studio, select File > New > Mule Project.

  2. Enter a name for your Mule project and click Finish.

Add the Connector to Your Mule Project

Add Anypoint Connector for MQTT (MQTT Connector) to your Mule project to automatically populate the XML code with the connector’s namespace and schema location and to add the required dependencies to the project’s pom.xml file:

  1. In the Mule Palette view, click (X) Search in Exchange.

  2. In the Add Dependencies to Project window, type mqtt in the search field.

  3. Click MQTT 3 Connector in Available modules.

  4. Click Add.

  5. Click Finish.

Adding a connector to a Mule project in Studio does not make that connector available to other projects in your Studio workspace.

Configure a Source

A source initiates a flow when a specified condition is met. You can configure one of these input sources to use with MQTT Connector:

  • MQTT3 > On New Message
    Initiates a flow by listening for incoming messages

  • HTTP > Listener
    Initiates a flow each time it receives a request on the configured host and port

  • Scheduler
    Initiates a flow when a time-based condition is met

For example, to configure an On New Message source, follow these steps:

  1. In the Mule Palette view, select MQTT3 > On New Message.

  2. Drag On New Message to the Studio canvas.

  3. In the On New Message configuration screen, optionally change the value of the Display Name field.

  4. Click the plus sign (+) next to the Connector configuration field to configure a global element that can be used by all instances of the source in the app.

  5. In the MQTT3 Config window, for Connection, select one of the connection types to provide to this configuration:

    • MQTT3 URL Connection

    • MQTT3 Fail-Over Connection

    • MQTT3 Form Connection

  1. Specify a unique and intuitive Client ID to identify an MQTT connection to a broker.

  2. On the General tab, also specify connection information such as required libraries for the broker.

  3. On the LWT tab, optionally specify the Last Will and Testament message.

  4. On the TLS/SSL tab, optionally specify a TLS configuration.

  5. On the Advanced tab, optionally specify advanced connection options and reconnection strategy.

  6. Click OK.

  7. In the On New Message configuration screen, in Topics, select Edit inline to list the topics that the listener subscribes to.

  8. Click the plus sign (+) to configure a topic.

  9. In the Topic configuration screen, set Topic filter, which represents a single or multilevel subscription to a topic.

  10. Set QoS to any of the following quality of service levels:

    • AT_MOST_ONCE

    • AT_LEAST_ONCE

    • EXACTLY_ONCE

  11. Click Finish.

Add a Connector Operation to the Flow

When you add a connector operation to your flow, you immediately define a specific operation for that connector to perform.

To add an operation for MQTT Connector, follow these steps:

  1. In the Mule Palette view, select MQTT3 and then select the desired operation.

  2. Drag the operation onto the Studio canvas and to the right of the input source.

Select any of the MQTT Connector or from the Mule Palette view on the right side of Anypoint Studio

Configure a Global Element for the Connector

When you configure a connector, it’s best to configure a global element that all instances of that connector in the app can use. MQTT Connector comes with default values for both publishing and consuming messages. To use the connector, the only requirement is that you must configure which connection to use and that you specify a value for the client ID, which will uniquely identify that connection.

The client ID is mandatory because it identifies an MQTT connection to a broker. Define a meaningful name that uniquely identifies a client or device that connects to an MQTT broker and not a random string.

To configure the global element for MQTT Connector, follow these steps:

  1. Select the operation in the Studio canvas.

  2. In the configuration screen for the operation, click the plus sign (+) next to the Connector configuration field to access the global element configuration fields.

  3. In the MQTT3 Config window, for Connection, select one of the connection types to provide to this configuration:

    • MQTT3 URL Connection

    • MQTT3 Fail-Over Connection

    • MQTT3 Form Connection

  1. Specify a unique and intuitive Client ID to identify an MQTT connection to a broker, for example smart-bentley-123.

  2. Specify the URL to connect to a broker, for example tcp://127.0.0.1:1883.

  3. On the General tab, also specify connection information such as required libraries for the broker.

  4. On the LWT tab, optionally specify the Last Will and Testament message.

  5. On the SSL/TLS tab, optionally specify a TLS configuration.

  6. On the Advanced tab, optionally specify advanced connection options and reconnection strategy.

  7. Click OK to close the window.

MQTT 3 Connector Global Element Properties window

In the Configuration XML editor, the <mqtt3:connection>, clientId, and url configurations look like this:

<mqtt3:config name="MQTT_Config">
    <mqtt3:connection clientId="smart-bentley-123" url="tcp://127.0.0.1:1883" />
</mqtt3:config>

You can also specify each URL field separately for the connection by configuring the MQTT3 Form Connection, which enables you to specify a protocol, host, and port to establish a connection with the broker:

  1. In Studio, navigate to the Global Elements tab.

  2. Click Create.

  3. In the filter box, type mqtt and select MQTT3 Config.

  4. Click OK.

  5. In the MQTT3 Config window, for Connection, select MQTT3 Form Connection.

  6. Set the following fields:

    • Client id generator: Client id random suffix generator

    • Client ID: smart-bentley-123

    • Username: username

    • Protocol: TCP (Default)

    • URL: 127.0.0.1

    • Port: 1883

  7. Click OK.

MQTT 3 Form Connection configuration in Global Element Properties window

In the Configuration XML editor, the <mqtt3:form-connection>, protocol, host, port, and clientId configurations look like this:

<mqtt3:config name="MQTT3_Config">
    <mqtt3:form-connection username="username" password="testpass" host="127.0.0.1" >
        <mqtt3:client-id-generator >
            <mqtt3:client-id-random-suffix-generator clientId="smart-bentley-123" />
        </mqtt3:client-id-generator>
    </mqtt3:form-connection>
</mqtt3:config>

Configure a Connection Protocol

MQTT supports protocols that you can use to connect to and exchange MQTT messages with the broker. You can configure any of the following protocols in the connection string of the connector configuration:

  • LOCAL

  • SSL

  • TCP (Default)

  • WS

  • WSS

Configure Credentials for Authentication

Authentication credentials are optional, but you can provide a username and a password if required.

In the following example, you configure the authentication by providing a basic username and password:

  1. In Studio, navigate to the Global Elements tab.

  2. Click Create.

  3. In the filter box, type mqtt and select MQTT3 Config.

  4. Click OK.

  5. In the MQTT3 Config window, for Connection, select MQTT3 URL Connection.

  6. Set the following fields:

    • Client id generator: Client id random suffix generator

    • Client ID: smart-bentley-123

    • Username: username

    • Password: passtest

    • URL: tcp://127.0.0.1:1883"

  7. Click OK.

In the Configuration XML editor, the <mqtt3:connection>, username, and password configurations look like this:

<mqtt3:config name="MQTT_Config">
    <mqtt3:connection username="username" password="passtest" url='tcp://127.0.0.1:1883"' >
        <mqtt3:client-id-generator >
            <mqtt3:client-id-random-suffix-generator clientId="smart-bentley-123" />
        </mqtt3:client-id-generator>
    </mqtt3:connection>
</mqtt3:config>

You can also provide a client certificate to authenticate the connection by setting a TLS context:

  1. In Studio, navigate to the Global Elements tab.

  2. Select your MQTT3 Config and click Edit.

  3. In MQTT3 Config, click SSL/TLS.

  4. For TLS Context, select Edit inline.

  5. In Trust Store Configuration, set the following fields:

    • Path: tls/truststore.jks

    • Password: racing

    • Type: jks

  6. Click OK.

MQTT TLS Context configuration in Global Element Properties window

In the Configuration XML editor, the <tls:context>,path, password, and type configurations look like this:

<mqtt3:config name="MQTT_TLS_Config">
    <mqtt3:connection username="username" password="passtest" url='tcp://127.0.0.1:1883"' >
        <tls:context >
            <tls:trust-store path="tls/truststore.jks" password="racing" type="jks" />
        </tls:context>
        <mqtt3:client-id-generator >
            <mqtt3:client-id-random-suffix-generator clientId="smart-bentley-123" />
        </mqtt3:client-id-generator>
    </mqtt3:connection>
</mqtt3:config>

Configure a Failover Server List

There are certain deployment schemas that consist of multiple brokers working together to provide clients with several connection endpoints. When there is more than one available server that the client can connect to, there are two possible scenarios: either each MQTT server operates separately, or they might work together and share a state (cluster mode), in which case you might want to specify how the MQTT client behaves in the event of a reconnection.

When you provide a failover server list, the connector can iterate over the list until it successfully establishes a connection with one of the provided endpoints.

In the following example, you configure the failover server list for an MQTT3 Fail-Over Connection:

  1. In Studio, navigate to the Global Elements tab.

  2. Click Create.

  3. In the filter box, type mqtt and select MQTT3 Config.

  4. Click OK.

  5. In the MQTT3 Config window, for Connection, select MQTT3 Fail-Over Connection.

  6. Set Client ID to smart-bentley-123.

  7. In Fail over servers, click the plus sign (+).

  8. Set the following fields:

    • Protocol: TCP (Default)

    • Host: 127.9.0.2

    • Port: 1883

  9. Click Finish.

  10. Repeat Steps 7 through 9 twice to add the other new host and port values.

MQTT 3 Fail-Over Server List configuration in Global Element Properties window

In the Configuration XML editor, the <mqtt3:fail-over-connection> and <mqtt3:fail-over-url configurations look like this:

<mqtt3:config name="MQTT_FailOver_Config">
    <mqtt3:fail-over-connection clientIDGenerator="smart-bentley-123" >
        <mqtt3:fail-over-servers >
            <mqtt3:fail-over-url host="127.9.0.2" />
            <mqtt3:fail-over-url host="127.0.0.3" port="1884" />
            <mqtt3:fail-over-url host="127.0.0.1" />
        </mqtt3:fail-over-servers>
    </mqtt3:fail-over-connection>
</mqtt3:config>

Configure the Clean Session Value

In the MQTT3 Config window, configure the Clean session field to False so the broker remembers the client the next time it connects. While the client is offline, all its subscriptions are saved, and Quality of Service (QoS) 1 and 2 messages that the client would want to receive are saved too, until the client reconnects.

Some brokers support the clustering of MQTT brokers in which the nodes share a state. In this case, setting the clean session flag to False is useful if the node the connector happens to go offline. This enables the client to reconnect to a different node that is aware of the client’s subscriptions so that any messages the connector might have missed while offline are delivered.

If the clean session is set to True (Default), then when the connector disconnects, for whatever reason, all its subscriptions are dropped and the connector has to resubscribe upon reconnection. All messages sent while offline are lost.

In the following example, you configure the clean session:

  1. In Studio, navigate to the Global Elements tab.

  2. Select your MQTT3 Config and click Edit.

  3. In the MQTT3 Config window, on the Advanced tab for Connection, select MQTT3 URL Connection.

  4. Set the following fields:

    • Clean session: False

  5. Click OK.

MQTT Clean session configuration in Global Element Properties window

In the Configuration XML editor, the cleanSession configuration looks like this:

<mqtt3:config name="MQTT_Config">
    <mqtt3:connection username="username" password="passtest" url='tcp://127.0.0.1:1883' >
        <mqtt3:client-id-generator >
            <mqtt3:client-id-random-suffix-generator clientId="smart-bentley-123" />
        </mqtt3:client-id-generator>
        <mqtt3:connection-options cleanSession="false" />
    </mqtt3:connection>
</mqtt3:config>

Enable File Persistence

In the MQTT3 Config window, set the Enable file persistence field to True to enable the MQTT client to persist its state to a file that is used to store any outbound or inbound in-flight messages that the client might have with QoS ≥ 1. In contrast, if you set the field to False (Default), the client state is saved only in memory and in the event of a crash, the client cannot recover its state.

The enable file persistence feature does not use an object store. The file feature relies on the driver to use a file for persistent messages and can only be used in on-premise installations.

In the following example, you enable the file persistence:

  1. In Studio, navigate to the Global Elements tab.

  2. Select your MQTT3 Config and click Edit.

  3. In the MQTT3 Config window, for Connection, select MQTT3 URL Connection.

  4. On the Advanced tab, set the following fields:

    • Clean session: False

    • Enable file persistence: True

  5. Set Datastore to mqtt/store to specify where you want the persistent store to be generated.

  6. Click OK.

MQTT3 Enable File Persistence configuration in Global Element Properties window
Figure 1. MQTT3 Enable File Persistence configuration

In the Configuration XML editor, the enableFilePersistence and dataStorePath configurations look like this:

<mqtt3:config name="MQTT_Config">
    <mqtt3:connection username="username" password="passtest" url='tcp://127.0.0.1:1883' >
        <mqtt3:client-id-generator >
            <mqtt3:client-id-random-suffix-generator clientId="smart-bentley-123" />
        </mqtt3:client-id-generator>
        <mqtt3:connection-options cleanSession="false" />
        <mqtt3:file-persistence-options enableFilePersistence="true" />
    </mqtt3:connection>
</mqtt3:config>
If you set a dynamic client ID, MQTT Connector cannot recover the persisted files in the event of a crash. You must set a client ID that does not change in the event of an application restart after a crash.

Configure Advanced Connection Options

MQTT Connector enables you to define multiple default parameters while consuming or publishing messages. This way, you can define a global default behavior for all the operations associated with the configurations.

In the following example, you configure the Keep alive internal and Keep alive internal unit fields to set the maximum period of time that the connection is kept alive without any messages being exchanged between the client and broker. You also configure the Max in flight field to indicate the maximum number of in-flight messages allowed:

  1. In Studio, navigate to the Global Elements tab.

  2. Select your MQTT3 Config and click Edit.

  3. In the MQTT3 Config window, for Connection, select MQTT3 URL Connection.

  4. Select the Advanced tab, set the following fields:

    • Keep alive internal: 60

    • Keep alive internal unit: SECONDS (Default)

    • Max in flight: 60

  5. Click OK.

MQTT3 Connector Advanced Connection configuration in Global Element Properties window

In the Configuration XML editor, the keepAliveInterval, keepAliveIntervalUnit, and maxInFlight configurations look like this:

<mqtt3:config name="MQTT_Config">
    <mqtt3:connection username="username" password="passtest" url='tcp://127.0.0.1:1883' >
        <mqtt3:client-id-generator >
            <mqtt3:client-id-random-suffix-generator clientId="smart-bentley-123" />
        </mqtt3:client-id-generator>
        <mqtt3:connection-options keepAliveInterval="60" maxInFlight="60"/>
    </mqtt3:connection>
</mqtt3:config>

View the App Log

To check for problems, you can view the app log as follows:

  • If you’re running the app from Anypoint Platform, the output is visible in the Anypoint Studio console window.

  • If you’re running the app using Mule from the command line, the app log is visible in your OS console.

Unless the log file path is customized in the app’s log file (log4j2.xml), you can also view the app log in the default location MULE_HOME/logs/<app-name>.log.

See Also

Back to top
View on GitHub