MQTT Client Integration

Use Java MQTT Client to Communicate with Your HDK and Sensors

Get the Itron Java MQTT Client App on GitHub

Learn how to use the Java MQTT Client to retrieve sensor data and push it to the to Itron Data Platform.


The Java MQTT client is a standalone utility that can be used to retrieve payloads generated by Itron based IoT devices generating MQTT "bubble-up" data. The MQTT client is packaged as a jar and accepts a property file that defines Itron network parameters and options. You can run the client on Linux, Windows, or MacOS.

The client is designed for extended runtime. It acts as a simple server that you can use to retrieve device payloads and consume them. The reference client is designed to work with the DHT-11 temperature sensor. It sends device payloads to the Starfish Data Platform where you can retrieve them using the Starfish Data Platform "observations" API. 

The MQTT client works especially well running in a virtual machine environment (such as an AWS EC2).


Task List

In addition to providing a reference on using the Java MQTT Client, you will be able to specifically confirm communication with your HDK and read sensor data. The following documentation outlines the steps required to achieve the following: 

  • Install the build prerequisites and build the Java MQTT Client (or download the pre-built all in one jar, available below)
  • Run the client
  • Determine your Starfish account Client ID and Client Secret
  • Determine the Starfish Tenant ID of your Itron IoT device
  • Set up the MQTT Client properties file
  • Use the MQTT Client


Software Needed 

This tutorial uses the pre-built Java MQTT Client, an all-in-one jar file. If you prefer to clone the source code and build the Java Client, detailed instructions are included in the file in the Java MQTT Client portion of the Itron GitHub Repository.

You will need to install Java 8 and either download or build the sdkcoapclient:


Hardware Needed

You will need a laptop or desktop computer to run the Java MQTT client and a working internet connection.


Milli Firmware Version

Ensure that you have the latest firmware flashed to your Milli device. 

Building the Java MQTT Client 

To build the MQTT Client use the following instructions. Alternatively, you can download and use the pre-built jar file.

  1. Navigate to the Java CoAP Client, available on GitHub as part of the developer_program repository.
  2. Clone the GitHub repository. Point your browser to the following URL: 
  3. Change your working directory to C:\<project base>\developer_program\SDK\Java MQTT Client, where <project base> is the location your cloned repository.
  4. Build the MQTT client using the following command:

mvn clean install

Note: If the build fails due to missing artifacts, you might need to adjust the maven settings.xml to access the appropriate remote maven repositories.


  1. The resultant jar can be found in the target subdirectory (using the example directory used above):

C:\<project base>\developer_program\SDK\Java MQTT Client\target\

  1. The jar is built as an all-in-one jar, and contains all libraries and dependencies required to use the client.


Running the MQTT Client

To run the client, use a command of the following form in a shell or command prompt window:

java -jar<path to properties file>


For example, if your properties file is named and is located in the same directory as the jar file:

java -jar


Determining the Starfish Client ID and Client Secret 

You can obtain your Starfish Client ID and Client Secret from your Starfish Developer Program account.

  1. Log in to the Devloper Program Portal.
  2. Click the Account Settings tab.
  3. Click the ClientID/Secret tab.
  4. Click Create New ClientID/Secret.
  5. Record/save your information for future reference. 
If you do not save these upon creating your account, you will need to create a new set, as Starfish does not store this information.


Determining your Starfish Tenant ID

Using the Starfish Data Platform tokens API, obtain a Starfish token.

  1. Navigate to
  2. Log in.
  3. Click the "View APIs" tab after you log on.
  4. Locate the /api/tokens API, and enter the required "body" with your Client ID and Client Secret.
  5. Click Try it out! The response returns a Starfish token.
  6. Copy the token. 
  7. Navigate to the JWT website:
  8. Locate the "Encoded" panel on the left of the page and replace the text in this panel with your token.
  9. The JWT (extracted from your token) displays in the "Decoded" panel on the right.
  10. The value of the sub property is your Tenant ID. Tenant IDs will always start with the prefix TN.


The following sample describes a typical JWT:


  "iss": "/data",

  "sub": "TN0050f6aa53-0a1c-461f-a774-243f94ce9b21",

  "scope": "api",

  "accessPolicy": [


      "Action": "execute-api:Invoke",

      "Effect": "Allow",

      "Resource": "*/api/solutions/*"



      "Action": "execute-api:Invoke",

      "Effect": "Allow",

      "Resource": "GET/api/tenants/systemTenant/devicetemplates"



  "jti": "1d9bca68-754c-4702-a792-438086f5deaf",

  "iat": 1540584982,

  "exp": 1540588582



MQTT Authentication Methods

Itron provides the following authentication methods:

  • Token based 
  • CAAS based


When using Token based authentication, the MQTT Client will only receive payloads for devices that reside in your tenant (that is, devices that show up on Starfish Developer Portal account). The Token based method is the most commonly used. 

When using CAAS authentication, the MQTT Client will receive payloads for all devices. This is used specifically when the MQTT Client (or a client based on the MQTT Client code) is deployed into an Itron customer-specific network (not the Starfish network).


Token Based

The MQTT Client uses your Client ID and Client Secret to obtain a token when it establishes an MQTT broker session.

Note that the MQTTSDPBRIDGE_USE_TOKEN_AUTH property must be set to it's default value: 1.


CAAS Based

To use CAAS, include your CAAS username and password in the property file. The MQTT Client will use these credentials when it establishes an MQTT broker session.

Note that the MQTTSDPBRIDGE_USE_TOKEN_AUTH property must be set to 0 to use CAAS authentication.


MQTT Topic Naming Conventions

Itron uses a specific MQTT topic naming convention with the Starfish MQTT broker. Device payload data is published to the MQTT broker using topic naming that uses the following form:

<Tenant Id>/alert/<Mac Address>/<Sensor Type>

Topic Part
Tenant ID
Your Starfish Tenant ID.
String. Always use.
<Mac address>
IoT MAC address.
<Sensor Type>
Sensor type string. For example "temp".


You may use MQTT wildcards in the topic name. This allows users to craft one topic to cover all devices.

Following are several examples:

Retrieve payloads for all my temp sensors
Retrieve payloads for all my sensors
Retrieve payloads for a specific temp sensor


MQTT Client Property File

The client requires one command line option: the path to a property file (see above). This file contains properties that provide necessary information, such as your Client ID and Client Secret.

You are required to specify values for multiple properties. Other properties are determined by defaults which can be used to tune the MQTT Client.

A template property file called is provided. The following section describes the configuration/command line options available to you.

Itron reccommends that you change the non-required properties only if required for your solution.


Property Descriptions 

The following table summarizes the Java MQTT Client command line properties and corresponding descriptions.  

Property name
Required. Your Tenant ID.
Required. A Topic will have this form: \<Tenant Id\>/alert/+/+. For example: TN0050f6aa53-0a1c-461f-a774-243f94ce9b21/alert/+/+
Required. CAAS username or "notused" if using token authentication.
Required. CAAS password or blank if using token authentication.
Required. Your Starfish account Client ID.
Required. Your Starfish account Client Secret.
Required. A unique MQTT client ID. Can be up to 32 characters. Suggested form: mqtt-client-<20 char string of your choice>
Host name of the MQTT broker. Defaults to:
Set to 1 for token authentication. Set to 0 for CAAS authentication. Defaults to 1.
Protocol used with the MQTT broker. Defaults to ssl.
MQTT broker port. Defaults to 8883.
MQTT broker QoS. Defaults to 0
Starfish Data Platform tokens endpoint. Do not change.
Starfish Data Platform observations endpoint. Do not change.
Cache tenant device info. Set to 0 to avoid sending payloads to Starfish Data Platform. Defaults to 1. Change with caution.
Number of time to attempt a connection with MQTT broker. Defaults to 1440.
Time delay between connection attempts (ms). Defaults to 60000.
Idle loop delay (ms). Defaults to 100.
MQTT broker keep alive interval. Defaults to 3.