MQTT

Version 20.0.7580


MQTT


The MQTT Connector supports publishing MQTT messages and subscribing to MQTT topics.

Overview

Sending data through an MQTT Connector will publish the data to the configured topic, and messages received on any of the topics that the connector is subscribed to will be placed in the Output Folder.

Installing the Connector

The instructions for installing external connectors will vary depending on your installation.

Windows

In the Windows edition, simply running the installer should detect the installation directory and install to the appropriate path for it to be recognized within ArcESB.

Java

In the Java edition, the procedure will depend on the operating system and environment where ArcESB is running. In all cases, the MQTT Connector for ArcESB.zip folder containing the connector will need to be unzipped, and its contents copied into the “connectors” directory within the application directory. The location of this “connectors” directory will be one of the following, depending on how ArcESB is running:

  • Windows: C:\ProgramData\ArcESB\connectors\
  • Unix when deploying the WAR in your own Java Servlet container: ~/arcesb/connectors/
  • Using the embedded web server on Unix: /opt/arcesb/connectors/

Note that the ~/ directory will be the user’s home directory of the user running the Java Web server process.

Connector Configuration

This section contains all of the configurable connector properties.

Settings Tab

Host Configuration

Settings related to the remote MQTT server connection.

  • Remote Host The hostname or IP address of the remote MQTT server.
  • Remote Port The port on which to connect to the remote MQTT server.

Client Authentication

Settings related to authenticating against the remote MQTT server.

  • Username The username credential with which to authenticate.
  • Password The password for the specified username.

SSL Settings

Settings related to establishing a secure connection via SSL.

  • Use SSL/TLS Whether the connector will negotiate SSL when connecting to the remote server.
  • SSL Server Certificate The public certificate used to verify the identity of the remote server when establishing an SSL connection. This setting can be set to ‘Any Certificate’ to unconditionally trust the target server’s identity.

Publish

Settings related to publishing MQTT messages.

  • Topic The topic for the message to publish.
  • QoS Whether the delivery of messages should be non-guaranteed, guaranteed, or guaranteed without duplicates.

Subscribe

Settings related to subscribing to MQTT messages.

  • Enable MQTT Receiver Whether the connector should receive MQTT messages.
  • Topic Filters A comma-separate list of topics for the connector to subscribe to.
  • QoS Whether the delivery of messages should be non-guaranteed, guaranteed, or guaranteed without duplicates.

Automation Tab

Automation Settings

Settings related to the automatic processing of files by the connector.

  • Send Whether files arriving at the connector will automatically be sent as messages to the MQTT server.
  • Retry Interval The amount of time before a failed send is retried.
  • Retry Maximum Attempts The maximum number of times a failed send will be retried.

Advanced Tab

SSL Client Authentication

Settings related to client authentication when two-way SSL authentication is required.

  • Private Certificate The private certificate presented during SSL client authentication.
  • Certificate Password The password required to access the SSL client certificate.

Local Folders

Settings that determine where the connector will read files to upload, and where to write files after downloading.

  • Input Folder (Send) Files placed here will be sent by the connector. If Send Automation is enabled, the connector will automatically poll this location for files to process.
  • Output Folder (Receive) Files that the connector receives will be placed here. If the connector is connected to another connector in the flow, files will not remain here and will instead be passed along to the Input/Send folder for the connected connector.
  • Processed Folder (Sent) After sending, the connector will place a copy of the file here if Save to Sent Folder is enabled. This copy of the file will not be passed along to the next connector in the flow.

Performance

Settings related to the allocation of resources to the connector.

  • Max Workers The maximum number of worker threads that will be consumed from the threadpool to process files on this connector. If set, overrides the default setting from the Profile tab.
  • Max Files The maximum number of files that will be processed by the connector each time worker threads are assigned to the connector. If set, overrides the default setting from the Profile tab.

Other Settings

Settings not included in the previous categories.

  • Keep Alive Interval The maximum period of inactivity the connector will allow before sending a keep-alive packet.
  • Last Will Message The message that the server should publish in the event of an ungraceful disconnection.
  • Last Will Topic The topic of the Last Will Message.
  • Local File Scheme A filemask that determines how the connector will name files downloaded and pushed to the Output/Receive Folder. The following macros are supported:

    %ConnectorId%
    %Filename%
    %FilenameNoExt%
    %EXT%
    %ShortDate%
    %LongDate%
    %RegexFilename:%
    %DateFormat:%

    For example: %%FilenameNoExt%_%ShortDate%%EXT%
  • Republish Interval The interval that the connector will wait before republishing unacknowledged messages.
  • Timeout The duration that the connector will wait for a response from the server before throwing a timeout error.

Establishing a Connection

At a minimum, set Remote Host to the domain name or IP address of the MQTT server, as well as Remote Port if a non-standard port is used. If authentication is required, the Username and Password fields should also be set. If a secure connection is desired, check Use SSL/TLS, and optionally specify the SSL Server Certificate to the public certificate of the server, or Any Certificate in order to accept any certificate presented by the server. If used improperly, this value will create a security breach. Use it at your own risk.

Publishing

In order to publish data, set the Topic in the Publish section to the topic where the connector should publish messages. QoS value range from 0 to 2 and have the following meanings:

  • 0: At most once - The published message is sent once, and if it does not arrive it is lost.
  • 1: At least once - Guarantees that the published message arrives, but there may be duplicates.
  • 2: Exactly once - Guarantees that the publish message arrives and that there are no duplicates.

In the Advanced page, Republish Interval may be set to the number of seconds that the connector will wait for acknowledgements to messages that require them. If this time elapses without receiving an acknowledgement, the connector will republish the message. Republished messages reuse the packet Id from the original message, and will automatically set the Duplicate flag on the message. Specifying a value of 0 for Republish Interval will prevent the connector from automatically republishing messages.

Subscribing

In the Subscribe section of the settings page, the Enable MQTT Receiver option may be checked in order to indicate that the connector should also receive data. When checked, the connector will subscribe to the topics specified on a background thread, and incoming messages will automatically be placed in the Output Folder, named according to the value specified in Local File Scheme in the advanced tab. By default, the connector will name files with the topic and packet id of the message, using “%topic%_%packetid%.data” as the value for Local File Scheme.

Topic Filters may be set to a comma separated list of topic filters that the connector should subscribe to. Certain characters have special meanings in a topic filter:

  • / - The topic level separator
  • # - The multi-level wildcard (zero or more levels)
  • + - The single-level wildcard (exactly one level)
  • Leading $ - Denotes a “system topic”

In the advanced tab, Last Will Message and Last Will Topic may be set to the message that the server should publish, and the topic it should publish that message to, respectively, in the event of an ungraceful disconnection.