Eclipse Paho Java Client

The Paho Java Client provides two distinct API styles:

1. MqttAsyncClient: A fully asynchronous API where the completion of activities (like connecting or publishing) is notified via registered callbacks.
2. MqttClient: A synchronous wrapper around MqttAsyncClient. It provides a simpler programming model where functions appear to block until the operation is complete, making it easier to use for simple synchronous applications.

The Paho Java Client provides two distinct API styles for interacting with MQTT brokers:

1. MqttAsyncClient: A fully asynchronous API. Completion of activities (like connecting or publishing) is notified via registered callbacks.
2. MqttClient: A synchronous wrapper around MqttAsyncClient. Functions in this API appear synchronous to the application, blocking execution until the operation completes.

The Paho Java MQTTv5 client provides two distinct API styles:

1. MqttAsyncClient: A fully asynchronous API. Completion of activities is notified via registered callbacks. This is the foundation for the v5 client.
2. MqttClient: A synchronous wrapper around MqttAsyncClient. It provides functions that appear synchronous to the application, making it easier to use for simple, blocking workflows.

Use the -sub flag to listen for messages on a topic. You can use wildcards (e.g., world/#) to subscribe to multiple topics.

To see which topic each incoming message originated from (useful when using wildcards), include the -V flag.

To use the MQTTv3 client, add the Eclipse Paho repository and the org.eclipse.paho.client.mqttv3 dependency to your pom.xml.

Replace %REPOURL% with https://repo.eclipse.org/content/repositories/paho-releases/ for stable releases or https://repo.eclipse.org/content/repositories/paho-snapshots/ for nightly builds. Replace %VERSION% with your desired version (e.g., 1.2.5).

<project ...>
<repositories>
    <repository>
        <id>Eclipse Paho Repo</id>
        <url>%REPOURL%</url>
    </repository>
</repositories>
...
<dependencies>
    <dependency>
        <groupId>org.eclipse.paho</groupId>
        <artifactId>org.eclipse.paho.client.mqttv3</artifactId>
        <version>%VERSION%</version>
    </dependency>
</dependencies>
</project>

To use the MQTTv5 client, add the Eclipse Paho repository and the org.eclipse.paho.mqttv5.client dependency to your pom.xml.

Use https://repo.eclipse.org/content/repositories/paho-releases/ for official releases (e.g., version 1.2.5) or https://repo.eclipse.org/content/repositories/paho-snapshots/ for nightly snapshots (e.g., version 1.2.6-SNAPSHOT).

<project ...>
<repositories>
    <repository>
        <id>Eclipse Paho Repo</id>
        <url>%REPOURL%</url>
    </repository>
</repositories>
...
<dependencies>
    <dependency>
        <groupId>org.eclipse.paho</groupId>
        <artifactId>org.eclipse.paho.mqttv5.client</artifactId>
        <version>%VERSION%</version>
    </dependency>
</dependencies>
</project>

The CLI app supports several ways to publish data to an MQTT broker:

1. Standard Message: Publish a string message with a specific QoS.
2. File Content: Publish the entire contents of a file to a topic.
3. Stdin (Single Shot): Pipe data into the command to publish the entire input at once.
4. Stdin (Line-by-Line): Pipe data into the command to publish each line from stdin as a separate message.
5. MQTTv5: Use the -v 5 flag to publish using the MQTT version 5 protocol (requires a compatible broker).

When connecting to a broker, you can define a 'Will Message' that the broker will automatically publish to a specific topic if the client's connection is unexpectedly lost (after the keepalive expires).

To use this, provide the following arguments:

• -wp or --will-payload: The content of the will message.
• -wt or --will-topic: The topic where the will message will be published.
• -wr or --will-retain: (Optional) Set to retain the will message.
• -wq or --will-qos: (Optional) Set the Quality of Service for the will message.

./mqtt-client -sub -h tcp://iot.eclipse.org:1883 -t world -q 0 -wt status -wp "I have disconnected"

To use the client in a Maven project, add the Eclipse Paho repository and the dependency to your pom.xml.

Use https://repo.eclipse.org/content/repositories/paho-releases/ for stable releases (current version 1.2.5) or https://repo.eclipse.org/content/repositories/paho-snapshots/ for nightly snapshots (current version 1.2.6-SNAPSHOT).

<project ...>
<repositories>
    <repository>
        <id>Eclipse Paho Repo</id>
        <url>%REPOURL%</url>
    </repository>
</repositories>
...
<dependencies>
    <dependency>
        <groupId>org.eclipse.paho</groupId>
        <artifactId>org.eclipse.paho.client.mqttv3</artifactId>
        <version>%VERSION%</version>
    </dependency>
</dependencies>
</project>

The Paho MQTT Utility is a lightweight tool used to test communication with an MQTT Broker, including publishing to and subscribing from topics for application testing.

Download Options

• Eclipse Repositories: Download the JAR directly from the Release Repository or the Snapshot Repository.
• Build from Source: You can build the JAR locally using Maven from the parent directory.

Running the Utility

Once you have obtained the JAR file, execute it using the java -jar command. Ensure you use the exact filename corresponding to your downloaded version.

To build the library from source using Maven:

1. Clone the repository.
2. If you want to build the development branch instead of the stable master branch, switch to it: git checkout -b develop remotes/origin/develop
3. Run the Maven package command: mvn package -DskipTests

The resulting JARs (library, source, and javadoc) will be located in the org.eclipse.paho.client.mqttv3/target directory.

To build the library from the source repository:

1. Switch to the development branch (optional, if you want the latest development code instead of the stable master branch):

   git checkout -b develop remotes/origin/develop

2. Build using Maven:

   mvn package -DskipTests

After building, the JAR files, source, and Javadoc can be found in the org.eclipse.paho.mqttv5.client/target directory.