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.7</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.7</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>.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.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>.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.// 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);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.keystore After 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");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, in the form of
<prefix>.iot.<region>.amazonaws.com - 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>.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>.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>.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.