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.
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.
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.
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:
- MQTT (over TLS 1.2) with X.509 certificate-based mutual authentication
- MQTT over WebSocket with AWS Signature Version 4 authentication
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.
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.
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.
To use the SDK, you will need Java 1.7+.
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>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:
- Jackson 2.x, including Jackson-corejackson-core and Jackson-databindjackson-databind
- Paho MQTT client for Java 1.1.x. download instructions
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=trueThe 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.
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.
- Initialize the Client with MQTT (over TLS 1.2): For this MQTT connection type (port 8883), the AWS IoT service requires TLS mutual authentication, so a valid client certificate (X.509) and RSA keys are required. You can use the AWS IoT console or the AWS command line tools to generate certificates and keys. For the SDK, only a certificate file and private key file are required.
StringclientEndpoint = "<prefix>-ats.iot.<region>.amazonaws.com"; // use value returned by describe-endpoint --endpoint-type "iot:Data-ATS"StringclientId = "<unique client id>"; // replace with your own client ID. Use unique client IDs for concurrent connections.StringcertificateFile = "<certificate file>"; // X.509 based certificate fileStringprivateKeyFile = "<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.KeyStorePasswordPairpair = SampleUtil.getKeyStorePasswordPair(certificateFile, privateKeyFile);
AWSIotMqttClientclient = newAWSIotMqttClient(clientEndpoint, clientId, pair.keyStore, pair.keyPassword);
// optional parameters can be set before connect()client.connect();- Initialize the Client with MQTT Over WebSocket: For this MQTT connection type (port 443), you will need valid IAM credentials to initialize the client. This includes an AWS access key ID and secret access key. There are a number of ways to get IAM credentials (for example, by creating permanent IAM users or by requesting temporary credentials through the Amazon Cognito service). For more information, see the developer guides for these services.
As a best practice for application security, do not embed credentials directly in the source code.
StringclientEndpoint = "<prefix>-ats.iot.<region>.amazonaws.com"; // use value returned by describe-endpoint --endpoint-type "iot:Data-ATS"StringclientId = "<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 sourcesAWSIotMqttClientclient = newAWSIotMqttClient(clientEndpoint, clientId, awsAccessKeyId, awsSecretAccessKey, sessionToken);
// optional parameters can be set before connect()client.connect();After the client is initialized and connected, you can publish messages and subscribe to topics.
To publish a message using a blocking API:
Stringtopic = "my/own/topic";
Stringpayload = "any payload";
client.publish(topic, AWSIotQos.QOS0, payload);To publish a message using a non-blocking API:
publicclassMyMessageextendsAWSIotMessage {
publicMyMessage(Stringtopic, AWSIotQosqos, Stringpayload) {
super(topic, qos, payload);
}
@OverridepublicvoidonSuccess() {
// called when message publishing succeeded
}
@OverridepublicvoidonFailure() {
// called when message publishing failed
}
@OverridepublicvoidonTimeout() {
// called when message publishing timed out
}
}
Stringtopic = "my/own/topic";
AWSIotQosqos = AWSIotQos.QOS0;
Stringpayload = "any payload";
longtimeout = 3000; // millisecondsMyMessagemessage = newMyMessage(topic, qos, payload);
client.publish(message, timeout);To subscribe to a topic:
publicclassMyTopicextendsAWSIotTopic {
publicMyTopic(Stringtopic, AWSIotQosqos) {
super(topic, qos);
}
@OverridepublicvoidonMessage(AWSIotMessagemessage) {
// called when a message is received
}
}
StringtopicName = "my/own/topic";
AWSIotQosqos = AWSIotQos.QOS0;
MyTopictopic = newMyTopic(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.
To access a shadow using a blocking API:
StringthingName = "<thing name>"; // replace with your AWS IoT Thing nameAWSIotDevicedevice = newAWSIotDevice(thingName);
client.attach(device);
client.connect();
// Delete existing shadow documentdevice.delete();
// Update shadow documentStatestate = "{\"state\":{\"reported\":{\"sensor\":3.0}}}";
device.update(state);
// Get the entire shadow documentStringstate = device.get();To access a shadow using a non-blocking API:
publicclassMyShadowMessageextendsAWSIotMessage {
publicMyShadowMessage() {
super(null, null);
}
@OverridepublicvoidonSuccess() {
// called when the shadow method succeeded// state (JSON document) received is available in the payload field
}
@OverridepublicvoidonFailure() {
// called when the shadow method failed
}
@OverridepublicvoidonTimeout() {
// called when the shadow method timed out
}
}
StringthingName = "<thing name>"; // replace with your AWS IoT Thing nameAWSIotDevicedevice = newAWSIotDevice(thingName);
client.attach(device);
client.connect();
MyShadowMessagemessage = newMyShadowMessage();
longtimeout = 3000; // millisecondsdevice.get(message, timeout);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.
publicclassMyDeviceextendsAWSIotDevice {
publicMyDevice(StringthingName) {
super(thingName);
}
@AWSIotDevicePropertyprivateStringsomeValue;
publicStringgetSomeValue() {
// read from the physical device
}
publicvoidsetSomeValue(StringnewValue) {
// write to the physical device
}
}
MyDevicedevice = newMyDevice(thingName);
longreportInterval = 5000; // milliseconds. Default interval is 3000.device.setReportInterval(reportInterval);
client.attach(device);
client.connect();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
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.keystoreAfter the keystore file my.keystore is created, you can use it to initialize the client like so:
StringkeyStoreFile = "<my.keystore>"; // replace with your own key store fileStringkeyStorePassword = "<keystore-password>"; // replace with your own key store passwordStringkeyPassword = "<key-password>"// replace with your own key passwordKeyStorekeyStore = KeyStore.getInstance(KeyStore.getDefaultType());
keyStore.load(newFileInputStream(keyStoreFile), keyStorePassword.toCharArray());
StringclientEndpoint = "<prefix>.iot.<region>.amazonaws.com"; // replace <prefix> and <region> with your ownStringclientId = "<unique client id>"; // replace with your own client ID. Use unique client IDs for concurrent connections.AWSIotMqttClientclient = newAWSIotMqttClient(clientEndpoint, clientId, keyStore, keyPassword);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.KeyStorePasswordPairpair = SampleUtil.getKeyStorePasswordPair(certificateFile, privateKeyFile, "EC");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.
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.
Publish/Subscribe sample: This sample consists of two publishers publishing one message per second to a topic. One subscriber subscribing to the same topic receives and prints the messages.
Shadow sample: This sample consists of a simple demo of the simplified shadow access model. The device contains two attributes: window state and room temperature. Window state can be modified (therefore, controlled) remotely through desired state. To demonstrate this control function, you can use the AWS IoT console to modify the desired window state, and then see its change from the sample output.
Shadow echo sample: This sample consists of a simple demo that uses Shadow methods to send a shadow update and then retrieve it back every second.
To run the samples, you will also need to provide the following arguments through the command line:
- clientEndpoint: client endpoint, obtained via calling describe-endpoint
- clientId: client ID
- thingName: AWS IoT thing name (not required for the Publish/Subscribe sample)
You will also need to provide either set of the following arguments for authentication. For an MQTT connection, provide these arguments:
- certificateFile: X.509 based certificate file (For Just-in-time registration, this is the concatenated file from both the device certificate and CA certificate. For more information about Just-in-Time Registration, please see this blog.
- privateKeyFile: private key file
- keyAlgorithm: (optional) RSA or EC. If not specified, RSA is used.
For an MQTT over WebSocket connection, provide these arguments:
- awsAccessKeyId: IAM access key ID
- awsSecretAccessKey: IAM secret access key
- sessionToken: (optional) if temporary credentials are used
You can use the following commands to execute the sample applications (assuming TLS mutual authentication is used).
- To run the Publish/Subscribe sample, use the following command:
$ mvn exec:java -pl aws-iot-device-sdk-java-samples -Dexec.mainClass="com.amazonaws.services.iot.client.sample.pubSub.PublishSubscribeSample" -Dexec.args="-clientEndpoint <prefix>-ats.iot.<region>.amazonaws.com -clientId <unique client id> -certificateFile <certificate file> -privateKeyFile <private key file>"- To run the Shadow sample, use the following command:
$ mvn exec:java -pl aws-iot-device-sdk-java-samples -Dexec.mainClass="com.amazonaws.services.iot.client.sample.shadow.ShadowSample" -Dexec.args="-clientEndpoint <prefix>-ats.iot.<region>.amazonaws.com -clientId <unique client id> -thingName <thing name> -certificateFile <certificate file> -privateKeyFile <private key file>"- To run the Shadow echo sample, use the following command:
$ mvn exec:java -pl aws-iot-device-sdk-java-samples -Dexec.mainClass="com.amazonaws.services.iot.client.sample.shadowEcho.ShadowEchoSample" -Dexec.args="-clientEndpoint <prefix>-ats.iot.<region>.amazonaws.com -clientId <unique client id> -thingName <thing name> -certificateFile <certificate file> -privateKeyFile <private key file>"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.
You'll find the API documentation for the SDK here.
This SDK is distributed under the Apache License, Version 2.0. For more information, see LICENSE.txt and NOTICE.txt.
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.