Contact Us 1-800-596-4880
  1. Homepage
  2. MQTT Connector (1.0)

  3. MQTT Connector Reference

All Connectors

MQTT Connector 1.0 Reference

Anypoint Connector for MQTT (MQTT Connector) is an MQTT (Message Queuing Telemetry Transport) v3.x protocol-compliant MuleSoft extension. MQTT is a lightweight publish/subscribe messaging protocol designed for connecting remote devices with a small code footprint and minimal network bandwidth. MQTT today is used in a wide variety of industries, such as automotive, manufacturing, telecommunications, and oil and gas.

The connector consumes and produces MQTT messages and supports all MQTT v3.x functionalities including message retention, LWT(LWT) messages, and persistent sessions.

Configurations

Config

Default configuration.

Parameters

Name Type Description Default Value Required

Name

String

The name for this configuration. Connectors reference the configuration with this name.

x

Connection

Connection types for this configuration.

x

Name

String

The identifier of this element used to reference it in other components

x

Expiration Policy

Expiration Policy

Configures an expiration policy for the configuration.

Connection Types

MQTT 3 URL Connection

Cached connection provider that creates MQTT connections. Enables you to specify a connection URL for the broker.

Parameters
Name Type Description Default Value Required

Client ID Generator

One of:

A Client ID generator that generates a Client ID to identify a connection to the MQTT broker.

x

Username

String

Username to authenticate credentials to the MQTT broker.

Password

String

Password authenticate credentials to the MQTT broker.

URL

String

URL that represents the broker to connect to.

TLS Context

TLS

Topic

String

Topic to publish the LWTmessage.

Body

String

Content of the LWTmessage.

QoS

Enumeration, one of:

  • AT_MOST_ONCE

  • AT_LEAST_ONCE

  • EXACTLY_ONCE

Quality of service (QoS) with which the LWTmessage is published. Defaults to AT_LEAST_ONCE.

AT_LEAST_ONCE

Is Retained

Boolean

If set to true, the broker retains the LWTmessage.

false

Connection Timeout

Number

The socket connection timeout value. This attribute works in tandem with timeoutUnit. If multiple fail-over URLs are provided, the timeout applies to each URL individually.

30

Timeout Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

Unit of time for the Connection Timeout field.

SECONDS

Keep Alive Interval

Number

The amount of time that the connection between the client and broker is kept alive without any messages exchanged. If the keep-alive interval is 0, then the keep-alive mechanism is disabled.

0

Keep Alive Interval Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

The unit of time that corresponds to the keepAliveInterval parameter. Defaults to SECONDS

SECONDS

Max In Flight

Number

Maximum number of messages that can be unacknowledged at a given time. If you set the parameter to 0, there can be unlimited in-flight messages.

10

Clean Session

Boolean

If set to true, the session is cleaned each time the client disconnects from the broker. Subscriptions are not saved and offline (QoS 1 and 2) messages for that client are lost.

true

Enable File Persistence

Boolean

If set to true, creates a file-based persistent data store, used to store outbound and inbound messages while they are in flight, enabling delivery to the QoS specified.

false

Data Store Path

String

The directory where the file-based persistent data store is created if enableFilePersistence is set to true.

Reconnection

Reconnection

When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment will fail if the test doesn’t pass after exhausting the associated reconnection strategy.
MQTT 3 Fail-Over Connection
Parameters
Name Type Description Default Value Required

Client ID Generator

One of: * Client ID Random Suffix Generator * Client ID Custom Expression Generator

A ClientIDGenerator that generates a Client ID to identify a connection to the MQTT broker.

x

Username

String

Username to authenticate credentials to the MQTT broker.

Password

String

Password to authenticate credentials to the MQTT broker.

Fail Over Servers

Array of Fail Over URL

The list of server URLs used to establish a connection to the broker.

x

TLS Context

TLS

Topic

String

Topic to publish the LWTmessage.

Body

String

Content of the LWTmessage.

QoS

Enumeration, one of:

  • AT_MOST_ONCE

  • AT_LEAST_ONCE

  • EXACTLY_ONCE

Quality of service (QoS) with which the LWTmessage is published. Defaults to AT_LEAST_ONCE

AT_LEAST_ONCE

Is Retained

Boolean

If set to true, the broker retains the LWTmessage.

false

Connection Timeout

Number

The socket connection timeout value. This attribute works in tandem with timeoutUnit. If multiple fail-over URLs are provided, the timeout applies to each URL individually.

30

Timeout Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

Unit of time for the Connection Timeout field. Defaults to SECONDS

SECONDS

Keep Alive Interval

Number

The amount of time that the connection between the client and broker is kept alive without any messages being exchanged. If the keep-alive interval is 0, then the keep-alive mechanism is disabled.

0

Keep Alive Interval Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

The unit of time that corresponds to the keepAliveInterval parameter. Defaults to SECONDS

SECONDS

Max In Flight

Number

Maximum number of messages that can be unacknowledged at a given time. If you set the parameter to 0, there can be unlimited in-flight messages.

10

Clean Session

Boolean

If set to true, the session is cleaned each time the client disconnects from the broker. Subscriptions are not saved and offline (QoS 1 and 2) messages for that client are lost.

true

Enable File Persistence

Boolean

If set to true, creates a file-based persistent data store, used to store outbound and inbound messages while they are in flight, enabling delivery to the QoS specified.

false

Data Store Path

String

The directory where the file-based persistent data store is created if enableFilePersistence is set to true.

Reconnection

Reconnection

When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment will fail if the test doesn’t pass after exhausting the associated reconnection strategy.
MQTT 3 Form Connection

Cached connection provider that creates MQTT connections. Enables you to specify a protocol, host, and port to establish a connection with the broker.

Parameters
Name Type Description Default Value Required

Client ID Generator

One of: * Client ID Random Suffix Generator * Client ID Custom Expression Generator

A Client ID generator that generates a Client ID to identify a connection to the MQTT broker.

x

Username

String

Username to authenticate credentials to the MQTT broker.

Password

String

Password to authenticate credentials to the MQTT broker.

Protocol

Enumeration, one of:

  • TCP

  • WS

  • WSS

  • SSL

  • LOCAL

Transport level protocol to use when connecting to the broker.

TCP

URL

String

Broker’s host to connect to.

x

Port

String

Broker’s port to connect to

1883

TLS Context

TLS

Topic

String

Topic to publish the LWTmessage.

Body

String

Content of the LWTmessage.

QoS

Enumeration, one of:

  • AT_MOST_ONCE

  • AT_LEAST_ONCE

  • EXACTLY_ONCE

Quality of service (QoS) with which the LWTmessage is published. Defaults to AT_LEAST_ONCE

AT_LEAST_ONCE

Is Retained

Boolean

If set to true, the broker retains the LWTmessage.

false

Connection Timeout

Number

The socket connection timeout value. This attribute works in tandem with timeoutUnit. If multiple fail-over URLs are provided, the timeout applies to each URL individually.

30

Timeout Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

Unit of time for the Connection Timeout field. Defaults to SECONDS

SECONDS

Keep Alive Interval

Number

The amount of time that the connection between the client and broker is kept alive without any messages being exchanged. If the keep-alive interval is 0, then the keep-alive mechanism is disabled.

0

Keep Alive Interval Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

The unit of time that corresponds to the keepAliveInterval parameter.

SECONDS

Max In Flight

Number

Maximum number of messages that can be unacknowledged at a given time. If you set the parameter to 0, there can be unlimited in-flight messages.

10

Clean Session

Boolean

If set to true, the session is cleaned each time the client disconnects from the broker. Subscriptions are not saved and offline (QoS 1 and 2) messages for that client are lost.

true

Enable File Persistence

Boolean

If set to true, creates a file-based persistent data store, used to store outbound and inbound messages while they are in flight, enabling delivery to the QoS specified.

false

Data Store Path

String

The directory where the file-based persistent data store is created if enableFilePersistence is set to true.

Reconnection

Reconnection

When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment will fail if the test doesn’t pass after exhausting the associated reconnection strategy.

Associated Operations

Associated Sources

Operations

Publish

<mqtt3:publish>

Operation that enables you to publish a single MQTT 3 message to a given exchange.

Parameters

Name Type Description Default Value Required

Configuration

String

Name of the configuration to use.

x

Topic

String

Topic in which to publish the message.

x

Message

Any

Content of the message to publish.

#[payload]

QoS

Enumeration, one of:

  • AT_MOST_ONCE

  • AT_LEAST_ONCE

  • EXACTLY_ONCE

Quality of service (QoS) with which the message is published.

AT_LEAST_ONCE

Is Retained

Boolean

Whether the broker retains the message.

false

Config Ref

ConfigurationProvider

Name of the configuration to execute the component.

x

Reconnection Strategy

A retry strategy in case of connectivity errors.

For Configurations

Throws

  • MQTT3:CONNECTIVITY

    The client became disconnected from the broker while attempting to publish a message.

  • MQTT3:INVALID_TOPIC

    The topic is invalid because, for example, the name is too short, too long, or contains invalid characters.

  • MQTT3:PERSISTENCE

    When publishing a message, an error occurred while reading or writing persistent data for reliable messaging.

  • MQTT3:PUBLISH

    An error occurred while attempting to publish a message.

  • MQTT3:RETRY_EXHAUSTED

    All reconnection attempts failed.

  • MQTT3:WRITE_TIMEOUT

    An error occurred when the client timed out waiting to write messages to the server.

Sources

On New Message

<mqtt3:listener>

Source that listens for new incoming messages for one or more topic filters. Each topic filter has a specific QoS configured.

Parameters

Name Type Description Default Value Required

Configuration

String

Name of the configuration to use.

x

Topics

Array of Topic

List of topics that the listener subscribes to.

x

Config Ref

ConfigurationProvider

Name of the configuration to execute the component.

x

Primary Node Only

Boolean

Determines whether to execute the source only on the primary node when running Mule instances in a cluster.

Redelivery Policy

Redelivery Policy

Defines a policy for processing the redelivery of the same message.

Reconnection Strategy

A retry strategy in case of connectivity errors.

Output

Type

Any

Attributes Type

MQTT 3 Message Attributes

For Configurations

Types

TLS

Configures TLS to provide secure communications for the Mule app.

Field Type Description Default Value Required

Enabled Protocols

String

Comma-separated list of protocols enabled for this context.

Enabled Cipher Suites

String

Comma-separated list of cipher suites enabled for this context..

Trust Store

Trust Store

Key Store

Key Store

Revocation Check

Trust Store

Configures the truststore for TLS.

Field Type Description Default Value Required

Path

String

Path to the truststore. Mule resolves the path relative to the current classpath and file system, if possible.

Password

String

Password used to protect the trust store.

Type

String

Type of truststore.

Algorithm

String

Encryption algorithm that the trust store uses.

Insecure

Boolean

If true, no certificate validations will be performed, rendering connections vulnerable to attacks. Use at your own risk.

Key Store

Configures the keystore for the TLS protocol. The keystore you generate contains a private key and a public certificate.

Field Type Description Default Value Required

Path

String

Path to the keystore. Mule resolves the path relative to the current classpath and file system, if possible.

Type

String

Type of keystore.

Alias

String

Alias of the key to use when the keystore contains multiple private keys. By default, Mule uses the first key in the file.

Key Password

String

Password used to protect the private key.

Password

String

Password used to protect the keystore.

Algorithm

String

Encryption algorithm that the keystore uses.

Standard Revocation Check

Configures standard revocation checks for TLS certificates.

Field Type Description Default Value Required

Only End Entities

Boolean

Verify the last element of the certificate chain only.

Prefer Crls

Boolean

Try CRL instead of OCSP first.

No Fallback

Boolean

Do not use the secondary checking method, which is the method not specified in the Prefer Crls field.

Soft Fail

Boolean

Avoid verification failure when the revocation server cannot be reached or is busy.

Custom OCSP Responder

Configures a custom OCSP responder for certification revocation checks.

Field Type Description Default Value Required

Url

String

URL of the OCSP responder.

Cert Alias

String

Alias of the signing certificate for the OCSP response. If specified, the alias must be in the truststore.

CRL File

Specifies the location of the certification revocation list (CRL) file.

Field Type Description Default Value Required

Path

String

Path to the CRL file.

Reconnection

Configures a reconnection strategy for an operation.

Field Type Description Default Value Required

Fails Deployment

Boolean

When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment fails if the test doesn’t pass after exhausting the associated reconnection strategy.

Reconnection Strategy

Reconnection strategy to use.

Reconnect

Configures a standard reconnection strategy, which specifies how often to reconnect and how many reconnection attempts the connector source or operation can make.

Field Type Description Default Value Required

Frequency

Number

How often in milliseconds to reconnect.

Blocking

Boolean

If false, the reconnection strategy runs in a separate, non-blocking thread.

Count

Number

How many reconnection attempts to make.

Reconnect Forever

Configures a forever reconnection strategy by which the connector operation source or operation attempts to reconnect at a specified frequency for as long as the Mule app runs.

Field Type Description Default Value Required

Frequency

Number

How often to attempt to reconnect, in milliseconds.

Blocking

Boolean

If false, the reconnection strategy runs in a separate, non-blocking thread.

Fail Over URL

Field Type Description Default Value Required

Protocol

Enumeration, one of:

  • TCP

  • WS

  • WSS

  • SSL

  • LOCAL

Transport level protocol to use when connecting to the broker.

TCP

Host

String

Broker’s host to connect to.

localhost

Port

String

Broker’s port to connect to.

1883

Expiration Policy

Configures the minimum amount of time that a dynamic configuration instance can remain idle before Mule considers it eligible for expiration.

Field Type Description Default Value Required

Max Idle Time

Number

A scalar time value for the maximum amount of time a dynamic configuration instance should be allowed to be idle before it’s considered eligible for expiration.

Time Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

Time unit for the Max Idle Time field.

MQTT 3 Message Attributes

Field Type Description Default Value Required

Topic

String

Topic to which the broker directed the message.

x

Message Id

Number

MQTT ID that identifies a message received from the broker.

x

QoS

Number

Quality of service of the message delivered by the broker.

x

Is Duplicate

Boolean

If set to true, the message can duplicate another received message.

false

Is Retained

Boolean

If set to true, the message was either sent from a current publisher, or was retained by the server as the last message published on the topic.

false

Topic

Field Type Description Default Value Required

Topic Filter

String

Topic filter that represents a single or multilevel subscription to a topic.

x

QoS

Enumeration, one of:

  • AT_MOST_ONCE

  • AT_LEAST_ONCE

  • EXACTLY_ONCE

Quality of service (QoS) with which messages destined to the topic’s Topic filter field should be sent by the broker.

AT_LEAST_ONCE

Redelivery Policy

Configures the redelivery policy for executing requests that generate errors. You can add a redelivery policy to any source in a flow.

Field Type Description Default Value Required

Max Redelivery Count

Number

Maximum number of times that a delivered request can be processed unsuccessfully before returning a REDELIVERY_EXHAUSTED error.

Message Digest Algorithm

String

Secure hashing algorithm to use if the Use Secure Hash field is true. If the payload of the message is a Java object, Mule ignores this value and returns the value that the payload’s hashCode() returned.

Message Identifier

Redelivery Policy Message Identifier

Defines which strategy to identify the messages.

Object Store

ObjectStore

Configures the object store that stores the redelivery counter for each message.

Redelivery Policy Message Identifier

Configures how to identify a redelivered message and how to find out when the message was redelivered.

Field Type Description Default Value Required

Use Secure Hash

Boolean

If true, Mule uses a secure hash algorithm to identify a redelivered message.

Id Expression

String

One or more expressions that determine when a message was redelivered. You can set this property only if the Use Secure Hash field is false.

Client ID Random Suffix Generator

Field Type Description Default Value Required

Client Id

String

Client ID to identify the connection to the MQTT broker.

Client ID Custom Expression Generator

Field Type Description Default Value Required

Client Id

String

Client ID to identify the connection to the MQTT broker.

Custom Client Id Suffix

String

Custom client ID suffix used to identify the connection to the MQTT broker.

See Also

MuleSoft Help Center

Back to top
View on GitHub