search

aws / aws-iot-device-sdk-java

Java SDK for connecting to AWS IoT from a device.
https://aws.amazon.com/iot/sdk/
Apache License 2.0
211 stars 168 forks source link

readme

New Version Available

A new AWS IoT Device SDK is now available. It is a complete rework, built to improve reliability, performance, and security. We invite your feedback!

This SDK will no longer receive feature updates, but will receive security updates.

AWS IoT Device SDK for Java

The AWS IoT Device SDK for Java enables Java developers to access the AWS IoT Platform through MQTT or MQTT over the WebSocket protocol. The SDK is built with AWS IoT device shadow support, providing access to thing shadows (sometimes referred to as device shadows) using shadow methods, including GET, UPDATE, and DELETE. It also supports a simplified shadow access model, which allows developers to exchange data with their shadows by just using getter and setter methods without having to serialize or deserialize any JSON documents.

To get started, use the Maven repository or download the latest JAR file.

Overview

This document provides instructions for installing and configuring the AWS IoT device SDK for Java. It also includes some examples that demonstrate the use of different APIs.

MQTT Connection Types

The SDK is built on top of the Paho MQTT Java client library. Developers can choose from two types of connections to connect to the AWS IoT service:

For MQTT over TLS (port 8883), a valid certificate and private key are required for authentication. For MQTT over WebSocket (port 443), a valid AWS Identity and Access Management (IAM) access key ID and secret access key pair is required for authentication.

Thing Shadows

A thing shadow represents the cloud counterpart of a physical device or thing. Although a device is not always online, its thing shadow is. A thing shadow stores data in and out of the device in a JSON based document. When the device is offline, its shadow document is still accessible to the application. When the device comes back online, the thing shadow publishes the delta to the device (which the device didn't see while it was offline).

The SDK implements the protocol for applications to retrieve, update, and delete shadow documents mentioned here. When you use the simplified access model, you have the option to enable strict document versioning. To reduce the overhead of subscribing to shadow topics for each method requested, the SDK automatically subscribes to all of the method topics when a connection is established.

Simplified Shadow Access Model

Unlike the shadow methods, which operate on JSON documents, the simplified shadow access model allows developers to access their shadows with getter and setter methods.

To use this feature, you must extend the device class AWSIotDevice, use the annotation AWSIotDeviceProperty to mark class member variables to be managed by the SDK, and provide getter and setter methods for accessing these variables. The getter methods will be used by the SDK to report to the shadow periodically. The setter methods will be invoked whenever there is a change to the desired state of the shadow document. For more information, see Use the SDK later in this document.

Install the SDK

Minimum Requirements

To use the SDK, you will need Java 1.7+.

Install the SDK Using Maven

The recommended way to use the AWS IoT Device SDK for Java in your project is to consume it from Maven. Simply add the following dependency to the POM file of your Maven project.

<dependencies>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-iot-device-sdk-java</artifactId>
    <version>1.3.9</version>
  </dependency>
</dependencies>

The sample applications included with the SDK can also be installed using the following dependency definition.

<dependencies>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-iot-device-sdk-java-samples</artifactId>
    <version>1.3.9</version>
  </dependency>
</dependencies>

Install the SDK Using the Latest JAR

The latest JAR files can be downloaded here. You can simply extract and copy the JAR files to your project's library directory, and then update your IDE to include them to your library build path.

You will also need to add two libraries the SDK depends on:

Build the SDK from the GitHub Source

You can build both the SDK and its sample applications from the source hosted at GitHub.

$ git clone https://github.com/aws/aws-iot-device-sdk-java.git
$ cd aws-iot-device-sdk-java
$ mvn clean install -Dgpg.skip=true

Use the SDK

The following sections provide some basic examples of using the SDK to access the AWS IoT service over MQTT. For more information about each API, see the API documentation.

Initialize the Client

To access the AWS IoT service, you must initialize AWSIotMqttClient. The way in which you initialize the client depends on the connection type (MQTT or MQTT over WebSocket) you choose. In both cases, a valid client endpoint and client ID are required for setting up the connection.

String clientEndpoint = "<prefix>-ats.iot.<region>.amazonaws.com";   // use value returned by describe-endpoint --endpoint-type "iot:Data-ATS"
String clientId = "<unique client id>";                              // replace with your own client ID. Use unique client IDs for concurrent connections.
String certificateFile = "<certificate file>";                       // X.509 based certificate file
String privateKeyFile = "<private key file>";                        // PKCS#1 or PKCS#8 PEM encoded private key file

// SampleUtil.java and its dependency PrivateKeyReader.java can be copied from the sample source code.
// Alternatively, you could load key store directly from a file - see the example included in this README.
KeyStorePasswordPair pair = SampleUtil.getKeyStorePasswordPair(certificateFile, privateKeyFile);
AWSIotMqttClient client = new AWSIotMqttClient(clientEndpoint, clientId, pair.keyStore, pair.keyPassword);

// optional parameters can be set before connect()
client.connect();

As a best practice for application security, do not embed credentials directly in the source code.

String clientEndpoint = "<prefix>-ats.iot.<region>.amazonaws.com";   // use value returned by describe-endpoint --endpoint-type "iot:Data-ATS"
String clientId = "<unique client id>";                              // replace with your own client ID. Use unique client IDs for concurrent connections.

// AWS IAM credentials could be retrieved from AWS Cognito, STS, or other secure sources
AWSIotMqttClient client = new AWSIotMqttClient(clientEndpoint, clientId, awsAccessKeyId, awsSecretAccessKey, sessionToken);

// optional parameters can be set before connect()
client.connect();

Publish and Subscribe

After the client is initialized and connected, you can publish messages and subscribe to topics.

To publish a message using a blocking API:

String topic = "my/own/topic";
String payload = "any payload";

client.publish(topic, AWSIotQos.QOS0, payload);

To publish a message using a non-blocking API:

public class MyMessage extends AWSIotMessage {
    public MyMessage(String topic, AWSIotQos qos, String payload) {
        super(topic, qos, payload);
    }

    @Override
    public void onSuccess() {
        // called when message publishing succeeded
    }

    @Override
    public void onFailure() {
        // called when message publishing failed
    }

    @Override
    public void onTimeout() {
        // called when message publishing timed out
    }
}

String topic = "my/own/topic";
AWSIotQos qos = AWSIotQos.QOS0;
String payload = "any payload";
long timeout = 3000;                    // milliseconds

MyMessage message = new MyMessage(topic, qos, payload);
client.publish(message, timeout);

To subscribe to a topic:

public class MyTopic extends AWSIotTopic {
    public MyTopic(String topic, AWSIotQos qos) {
        super(topic, qos);
    }

    @Override
    public void onMessage(AWSIotMessage message) {
        // called when a message is received
    }
}

String topicName = "my/own/topic";
AWSIotQos qos = AWSIotQos.QOS0;

MyTopic topic = new MyTopic(topicName, qos);
client.subscribe(topic);

Note: all operations (publish, subscribe, unsubscribe) will not timeout unless you define a timeout when performing the operation. If no timeout is defined, then a value of 0 is used, meaning the operation will never timeout and, in rare cases, wait forever for the server to respond and block the calling thread indefinitely. It is recommended to set a timeout for QoS1 operations if your application expects responses within a fixed duration or if there is the possibility the server you are communicating with may not respond.

Shadow Methods

To access a shadow using a blocking API:

String thingName = "<thing name>";                    // replace with your AWS IoT Thing name

AWSIotDevice device = new AWSIotDevice(thingName);

client.attach(device);
client.connect();

// Delete existing shadow document
device.delete();

// Update shadow document
State state = "{\"state\":{\"reported\":{\"sensor\":3.0}}}";
device.update(state);

// Get the entire shadow document
String state = device.get();

To access a shadow using a non-blocking API:

public class MyShadowMessage extends AWSIotMessage {
    public MyShadowMessage() {
        super(null, null);
    }

    @Override
    public void onSuccess() {
        // called when the shadow method succeeded
        // state (JSON document) received is available in the payload field
    }

    @Override
    public void onFailure() {
        // called when the shadow method failed
    }

    @Override
    public void onTimeout() {
        // called when the shadow method timed out
    }
}

String thingName = "<thing name>";      // replace with your AWS IoT Thing name

AWSIotDevice device = new AWSIotDevice(thingName);

client.attach(device);
client.connect();

MyShadowMessage message = new MyShadowMessage();
long timeout = 3000;                    // milliseconds
device.get(message, timeout);

Simplified Shadow Access Model

To use the simplified shadow access model, you need to extend the device class AWSIotDevice, and then use the annotation class AWSIotDeviceProperty to mark the device attributes and provide getter and setter methods for them. The following very simple example has one attribute, someValue, defined. The code will report the attribute to the shadow, identified by thingName every 5 seconds, in the reported section of the shadow document. The SDK will call the setter method setSomeValue() whenever there's a change to the desired section of the shadow document.

public class MyDevice extends AWSIotDevice {
    public MyDevice(String thingName) {
        super(thingName);
    }

    @AWSIotDeviceProperty
    private String someValue;

    public String getSomeValue() {
        // read from the physical device
    }

    public void setSomeValue(String newValue) {
        // write to the physical device
    }
}

MyDevice device = new MyDevice(thingName);

long reportInterval = 5000;            // milliseconds. Default interval is 3000.
device.setReportInterval(reportInterval);

client.attach(device);
client.connect();

Other Topics

Enable Logging

The SDK uses java.util.logging for logging. To change the logging behavior (for example, to change the logging level or logging destination), you can specify a property file using the JVM property java.util.logging.config.file. It can be provided through JVM arguments like so:

-Djava.util.logging.config.file="logging.properties"

To change the console logging level, the property file logging.properties should contain the following lines:

# Override of console logging level
java.util.logging.ConsoleHandler.level=INFO

Load KeyStore from File to Initialize the Client

You can load a KeyStore object directly from JKS-based keystore files. You will first need to import X.509 certificate and the private key into the keystore file like so:

$ openssl pkcs12 -export -in <certificate-file> -inkey <private-key-file> -out p12.keystore -name alias
(type in the export password)

$ keytool -importkeystore -srckeystore p12.keystore -srcstoretype PKCS12 -srcstorepass <export-password> -alias alias -deststorepass <keystore-password> -destkeypass <key-password> -destkeystore my.keystore

After the keystore file my.keystore is created, you can use it to initialize the client like so:

String keyStoreFile = "<my.keystore>";                               // replace with your own key store file
String keyStorePassword = "<keystore-password>";                     // replace with your own key store password
String keyPassword = "<key-password>"                                // replace with your own key password

KeyStore keyStore = KeyStore.getInstance(KeyStore.getDefaultType());
keyStore.load(new FileInputStream(keyStoreFile), keyStorePassword.toCharArray());

String clientEndpoint = "<prefix>.iot.<region>.amazonaws.com";       // replace <prefix> and <region> with your own
String clientId = "<unique client id>";                              // replace with your own client ID. Use unique client IDs for concurrent connections.

AWSIotMqttClient client = new AWSIotMqttClient(clientEndpoint, clientId, keyStore, keyPassword);

Use ECC-Based Certificates

You can use Elliptic Curve Cryptography (ECC)-based certificates to initialize the client. To create an ECC key and certificate, see this blog post. After you have created and registered the key and certificate, use the following command to convert the ECC key file to PKCK#8 format.

$ openssl pkcs8 -topk8 -nocrypt -in ecckey.key -out ecckey-pk8.key
(type in the key password)

You can then use the instruction described in this section to initialize the client with just this one change.

// SampleUtil.java and its dependency PrivateKeyReader.java can be copied from the sample source code.
// Alternatively, you could load key store directly from a file - see the example included in this README.
KeyStorePasswordPair pair = SampleUtil.getKeyStorePasswordPair(certificateFile, privateKeyFile, "EC");

Increase in-flight publish limit (too many publishes in Progress error)

If you are getting a too many publishes in Progress error this means that your application has more operations in-flight (meaning they have not succeeded or failed, but they are waiting for a response from the server) than Paho supports by default. By default, the Paho client supports a maximum of 10 in-flight operations.

The recommended way to resolve this issue is to track how many QoS1 operations you have sent that are in-flight and when you reach the limit of 10, you add any further operations into a queue. Then as the QoS1 operations are no longer in-flight you grab QoS1 operations from the queue until it is empty or until you have hit the maximum of 10 in-flight operations. You then repeat this process until all the operations are sent. This will prevent your application from ever trying to send too many operations at once and exceeding the maximum in-flight limit of the Paho client.

Another way to help reduce this issue is to increase the maximum number of in-flight operations that the Paho client can process. To do this, you will need to modify the source code to increase this limit. Download the source code from GitHub, navigate to the AwsIotMqttConnection.java file, and add the following line of code in the buildMqttConnectOptions function just under the line options.setKeepAliveInterval(client.getKeepAliveInterval() / 1000); (around line 151):

options.setMaxInflight(100);

Then compile the source code and use the compiled Jar in your application.

This will increase Paho's in-flight limit to 100 and allow you to have more in-flight at the same time, giving additional room for sending larger volumes of QoS1 operations. Note that these in-flight operations still need to be acknowledged by the server or timeout before they are no longer in-flight, you can just have up to 100 in-flight rather than the default of 10.

For AWS IoT Core, you can only send a maximum of 100 QoS1 operations per second. Any operations sent after the first 100 per second will be ignored by AWS IoT Core. For this reason, it is highly recommended you perform all operations with a timeout if you increase the maximum in-flight limit, to prevent a situation where you send more than 100 QoS1 operations per second and are waiting on an operation to get an acknowledgement from the sever that will never come.

Sample Applications

There are three samples applications included with the SDK. The easiest way to run these samples is through Maven, which will take care of getting the dependencies.

Arguments for the Sample Applications

To run the samples, you will also need to provide the following arguments through the command line:

You will also need to provide either set of the following arguments for authentication. For an MQTT connection, provide these arguments:

For an MQTT over WebSocket connection, provide these arguments:

Run the Sample Applications

You can use the following commands to execute the sample applications (assuming TLS mutual authentication is used).

Sample Source Code

You can get the sample source code either from the GitHub repository as described here or from the latest SDK binary. They both provide you with Maven project files that you can use to build and run the samples from the command line or import them into an IDE, such as Eclipse.

The sample source code included with the latest SDK binary is shipped with a modified Maven project file (pom.xml) that allows you to build the sample source indepedently, without the need to reference the parent POM file as with the GitHub source tree.

API Documentation

You'll find the API documentation for the SDK here.

License

This SDK is distributed under the Apache License, Version 2.0. For more information, see LICENSE.txt and NOTICE.txt.

Support

If you have technical questions about the AWS IoT Device SDK, use the AWS IoT Forum. For any other questions about AWS IoT, contact AWS Support.