Connecting MQTT Clients Using Eclipse Paho Java Library and HiveMQ Cloud Broker
Written by The HiveMQ Team
Published: November 3, 2021
This is a getting started guide on connecting MQTT clients to HiveMQ Cloud MQTT Broker using the Eclipse Paho Java Client library. In this post, you will learn how to connect MQTT clients to a HiveMQ Cloud cluster, subscribe to topics, and publish data (sending and receiving messages) using the MQTT protocol.
The Eclipse Paho project provides open-source, mainly client-side, implementations of MQTT and MQTT-SN in a variety of programming languages. The Java client used here supports MQTT V3.1, MQTT V3.1.1, and MQTT V5.
For a completely finished code project, visit our GitHub repository. This example repository is easily and clearly structured to get you started quickly.
Getting Started with HiveMQ Cloud
To start connecting your MQTT clients, you need to set up HiveMQ Cloud. By signing up for HiveMQ Cloud, you will automatically get access to a HiveMQ Cloud Free cluster. HiveMQ Cloud Free is our smallest package that allows you to connect up to 100 MQTT clients for free and test the full MQTT functionality. After signing up, you have a running HiveMQ Cloud cluster, that you can use in this example.
The HiveMQ Cloud Quick Start Guide gives you step-by-step instructions on how to set up your HiveMQ Cloud account, create clusters, and connect MQTT clients.
Prerequisites to Using Eclipse Paho Java Client Library
Create a new project in your local IDE.
In the creation steps, select the Gradle project and make sure to activate Kotlin DSL build script, so that the
resulting build script will be build.gradle.kts.
The project builds automatically with this script and results in a
src folder with
test in it.
First, change the dependencies in the mentioned build.gradle.kts.
Change your file to look exactly like this, then the Paho Java library will be installed by building your project again.
Adding HiveMQ Cloud MQTT Broker Credentials
To connect your Paho Java client with your HiveMQ Cloud cluster, your host name, username and password are needed. These will be used in the code example in the next section. The host name can be found in the Details section of the Overview tab of your cluster.
After the cluster is created, add a set of credentials as shown in the picture below in the MQTT Credentials section of the Access Management tab of your cluster. You can use them in this example and future implementations. Use any secure username and password you desire. The client credentials that you just created are the values needed for the username and password variables.
Code Example on Securely Connecting an MQTT Client to HiveMQ Cloud
This example project covers the core functionality of an MQTT client interacting with HiveMQ Cloud. To securely connect the MQTT client with HiveMQ Cloud you need to enable TLS. Use your username and password to authenticate your MQTT client at HiveMQ Cloud. To connect the client, use the port 8883, which is standard for secure MQTT communication.
First open the
main folder, that was mentioned earlier, and create a new Java class in the
Name this file
Here the code snippets below will be added.
Now import the required libraries, including the Paho Client library, and an SSL library that is used for a secure
This is done by adding the following
import statements in your
After these import statements, put your
main method inside the public
Example class, that was created when making
the file earlier.
This method starts by creating the
When connecting to your HiveMQ Cloud cluster, you want to use a secure connection.
For that reason, SSL is used in the serverURI.
Exchange the placeholder for the hostname with your HiveMQ Cloud hostname to complete the address and connect to your cluster.
Add the credentials that you used for the cluster creation earlier into the placeholders for username and password. As mentioned, we want to use SSL, so it is activated here as well.
Now you can set a few callbacks, to make it easier to track certain events. In this example we set a callback for when the client lost the connection to the broker. Another callback we add is a callback for messages that are received by the client. We also register a callback for when an outgoing publish is complete. These are printed to the console.
The code subscribes to the topic filter ”#“.
This enables the MQTT client to receive all messages that are published to this topic filter. The so-called wildcard ("#"), that is used here as the topic filter, includes all topics.
Then the code publishes a message to the topic
"topic" with the content
It prints the content (payload) of the message due to the
messageArrived callback, that gets triggered when a message is received.
Other callbacks in this example are
deliveryComplete, that get called when their respective event occurs.
At the end, the client is disconnected.
In a real-world implementation for example, you could send temperature data with the messages and the
callback could print the temperature to an external display that may be connected through Wi-Fi.
When the connection is lost, you could set up a notification to your phone, so you can repair it quickly.
In this context
deliveryComplete could ensure that your system works normally and all message are actually published.
You can see that this kind of cloud-hosted MQTT is perfect for DIY home automation and smart home applications.
Finally, here is the whole code in one paragraph:
Get Started on MQTT and Eclipse Paho Java Client
If you want to learn more about MQTT, visit the MQTT Essentials guide. It explains the core MQTT concepts, features and other essential information. To learn more about Paho-Java, visit the official website of the eclipse foundation.