Skip to content
Branch: master
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
src
.gitignore
README.md
changes.md
config.properties
pom.xml
testng.xml

README.md

Java MQTT Client

Itron Developer Program SDK

Current Version Info

Current version is 1.0.0. See the changes.md file for details.

Overview

A component of the Itron developer program reference SDK, 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 takes a property file that defines Itron network parameters and options. You can run the client on Linux, Windows, and 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 is very happy running in a VM environment (such as an AWS EC2).

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

java -jar sdkmqttclient-1.0.0.one-jar.jar -Dconfig.properties=<path to properties file>

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

java -jar sdkmqttclient-1.0.0.one-jar.jar -Dconfig.properties=./test.properties

Build Prerequisites

To build the MQTT Client you will need the following tools installed on your system:

  • Java 8
  • Maven (version 3+)

Checklist

The steps needed to build and prep the MQTT Client for use:

  • Install the build prerequisites
  • Build the Java MQTT Client
  • Determine your Starfish account Client Id and Client Secret
  • Determine your Starfish Tenant Id of your Silver Spring IoT device
  • Setup MQTT properties file
  • Use the MQTT Client

Build Java MQTT Client

You have probably already cloned the Itron developer program GitHub repository. If not, now's the time!

The Java CoAP Client is available on GitHub as part of the developer_program repository. First, clone the GitHub repository. Point your browser to the following URL: https://github.com/silverspringnetworks/developer_program.

Change your working directory to C:\<project base>\developer_program\SDK\Java MQTT Client. Note that you need to fill in the part of the path based on where you cloned the repository. Use this command to build the MQTT client:

mvn clean install

Note: If the build fails due to missing artifacts, you may need to change you maven settings.xml to access the appropriate remote maven repositories. The resultant jar can found in the target subdirectory (using the sample directory used above):

C:\<project base>\developer_program\SDK\Java MQTT Client\target\sdkmqttclient-1.0.0.one-jar.jar

The jar is built as an all in one jar, it contains all libraries and dependencies need to use the client.

Determine Starfish Client Id and Client Secret

Your Starfish Client Id and Client Secret can be obtained from your Starfish Developer Program account. Hopefully you captured these when you created your account. If not, you will need to create a new set as Starfish does not store your client Id and Secret. After you log into the developer program portal, select the "Account Settings" tab. Towards the middle of thee page, locate and click on the "ClientID/Secret" tab. Click on the "Create New ClientID/Secret" button. Make sure to write you Client Id and Client Secret down!

Determine your Starfish Tenant Id

To determine your Starfish Tenant Id, follow this procedure:

  • Using the Starfish Data Platform tokens API, obtain a Starfish token. The easiest way to do this is to use the Starfish Studio API sandbox: (https://studio.developer.ssni.com/studio.html) and click on the "View APIs" tab after you logon. Locate the /api/tokens API, fill in the required "body" with your Client Id and Client Secret, and click the "try it out!" button. Look at the response and you will find a token.
  • Copy the token (it's a long string).
  • Next, visit the JWT web site (https://jwt.io)
  • Locate the "Encoded" panel on the left hand side of the page. Replace the text in this panel with your token.
  • You will see your JWT (extracted from your token) in the "Decoded" panel on the right hand side.
  • locate the "sub" property. The assocaited value is your Tenant Id. Tenant ID's will always start with a "TN".

A typical JWT will look something like this:

{
  "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

Two authentication methods are provided: token based and CAAS based.

Token based authentication is typically the method you will use. If you have not worked with Itron and been given CAAS account credentials, than you will use the token based method.

When using Token based authentication, the MQTT Client will only receive payloads for devices that live in your tenant (that is, devices that show up on Starfish Developer Portal account). When using CAAS authentication, the MQTT Client will receive payloads for all devices. This is specifically used when the MQTT Client (or your client which can be based on the MQTT Client code) is deployed into a 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 1 (the default).

CAAS Based

To use CAAS, include your CAAS username and password in the property file. The MQTT Client will use these credentials when it established 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

We use 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 this form:

<Tenant Id>/alert/<Mac Address>/<Sensor Type>
Topic Part Description
<Tenant Id> Your Starfish Tenant Id (see above).
alert String. Always use.
<Mac Address> mac address of an IoT device.
<Sensor Type> Sensor type string. For example "temp"

You may use MQTT wildcards in the topic name. This makes it easy to craft one topic to cover all your devices. Here are a few examples.

Topic Description
TN0050f6aa53-0a1c-461f-a774-243f94ce9b21/alert/+/temp Retrieve payloads for all my temp sensors
TN0050f6aa53-0a1c-461f-a774-243f94ce9b21/alert/+/+ Retrieve payloads for all my sensors
TN0050f6aa53-0a1c-461f-a774-243f94ce9b21/alert/001350050047dd92/temp 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 a number of properties that provide needed information such as your Client Id and Client Secret.

There are a number of properties where you are required to specify the values. The rest are defaults that can be used to tune the MQTT Client. It is suggested that you change the non-required properties only if required for you solution. A template property file is provided for your use called config.properties.

The following section describes the configuration/command line options available to you.

Property Descriptions

All property configuration options are described in this section.

Property Name Description
MQTTSDPBRIDGE_TENANT_ID Required. Your Tenant Id.
MQTTSDPBRIDGE_TOPIC Required. A Topic will have this form: <Tenant Id>/alert/+/+. For example: TN0050f6aa53-0a1c-461f-a774-243f94ce9b21/alert/+/+
MQTTSDPBRIDGE_USERNAME Required. CAAS username or "notused" if using token authentication.
MQTTSDPBRIDGE_PASSWORD Required. CAAS password or blank if using token authentication.
MQTTSDPBRIDGE_SDP_CLIENT_ID Required. Your Starfish account Client Id.
MQTTSDPBRIDGE_SDP_CLIENT_SECRET Required. Your Starfish account Client Secret.
MQTTSDPBRIDGE_CLIENT_ID Required. A unique MQTT client id. Up to 32 characters. Suggested form: mqtt-client-<20 char string of your choice>
MQTTSDPBRIDGE_BROKER_HOST Host name of the MQTT broker. Defaults to: api.mqtt-staging.developer.ssni.com
MQTTSDPBRIDGE_USE_TOKEN_AUTH Set to 1 for token authentication. Set to 0 for CAAS authentication. Defaults to 1.
MQTTSDPBRIDGE_BROKER_PROTOCOL Protocol used with the MQTT broker. Defaults to ssl.
MQTTSDPBRIDGE_BROKER_PORT MQTT broker port. Defaults to 8883.
MQTTSDPBRIDGE_QOS MQTT broker QoS. Defaults to 0.
MQTTSDPBRIDGE_SDP_TOKEN_ENDPOINT Starfish Data Platform tokens endpoint. Do not change.
MQTTSDPBRIDGE_SDP_OBSERVATION_ENDPOINT Starfish Data Platform observations endpoint. Do not change.
MQTTSDPBRIDGE_SDP_GET_DEVICE_INFO Cache tenant device info. Set to 0 to avoid sending payloads to Starfish Data Platform. Defaults to 1. Change carefully.
MQTTSDPBRIDGE_CONNECTION_ATTEMPTS Number of time to attempt a connection with MQTT broker. Defaults to 1440.
MQTTSDPBRIDGE_CONNECTION_DELAY Time delay between connection attempts (ms). Defaults to 60000.
MQTTSDPBRIDGE_IDLE_LOOP_DELAY Idle loop delay (ms). Defaults to 100.
MQTTSDPBRIDGE_KEEP_ALIVE_INTERVAL MQTT broker keep alive interval. Defaults to 3.
You can’t perform that action at this time.