The Internet of Things on AWS – Official Blog

Introducing AWS IoT Device SDKs for Java and Python

We are proud to announce two new device SDKs for AWS IoT – the AWS IoT SDK for Java and the AWS IoT SDK for Python. These SDKs add to those already available for AWS IoT:

The Java and Python SDKs help you easily and quickly connect your device or application to AWS IoT, send and receive messages using either MQTT or MQTT over the WebSocket protocol, and exchange state information with device shadows (sometimes referred to as thing shadows). All of the SDKs are open-sourced on GitHub, so you can use them as is or tweak them for your device or application.

Using the AWS IoT SDK for Java

You can get started with the SDK for Java by integrating it into an existing application or by trying the included sample applications. The SDK and samples are available both as source code in GitHub and binaries in Maven. For information about using the SDK, see the readme. In this post, we will show you how to load and run the samples from source code so you can step through and see the SDK in action.

Acquire and build the samples from source code

  1. Clone the aws-iot-device-sdk-java repository to your development machine. 
    $ git clone https://github.com/aws/aws-iot-device-sdk-java.git
$ cd aws-iot-device-sdk-java
  2. To build from the command line:
    a. Make sure you have Maven installed.
    b. Navigate to the aws-iot-device-sdk-java-samples folder.
    c. Run mvn clean install to build the project.
  3. To build from an IDE like Eclipse:
    a. Make sure you have installed Maven support for your IDE.
    b. Navigate to the aws-iot-device-sdk-java-samples folder and load the pom.xml file in your IDE. (In Eclipse, from the File menu, choose Import, choose Maven, and then choose Existing Maven Projects.
    c. Build the project. Eclipse is configured by default to build automatically.

Run the samples

There are three samples applications included with the SDK.

  • Publish/Subscribe sample: This sample consists of two publishers publishing one message per second to a test topic, sdkTest/sub. One subscriber subscribing to the same topic receives and prints the messages.
  • Device Shadow sample: This example demonstrates how to keep the device connected with its shadow in the cloud. This is the recommended way of accessing a shadow and keeping it synchronized with the device. To see this in action, you can use the AWS IoT console to update the shadow and observe the corresponding state change in this sample application.
  • Device Shadow Echo sample: This sample consists of a simple demo that uses shadow methods to send a shadow update and then retrieve it every second.

From the command line, use the following commands and parameters to execute the sample applications (assuming TLS mutual authentication is used) from the aws-iot-device-sdk-java-samples folder. If you are using Eclipse, specify the parameters in the Run/Debug Configurations of your project and then press F11 to launch it in debug mode. You can find the parameter values in the AWS IoT console by navigating to the thing and choosing Connect Device.

To run the Publish/Subscribe sample, use the following command:

$ mvn exec:java -Dexec.mainClass="com.amazonaws.services.iot.client.sample.pubSub.PublishSubscribeSample" -Dexec.args="-clientEndpoint .iot..amazonaws.com -clientId  -certificateFile  -privateKeyFile "

To run the Device Shadow sample, use the following command:

$ mvn exec:java -Dexec.mainClass="com.amazonaws.services.iot.client.sample.shadow.ShadowSample" -Dexec.args="-clientEndpoint .iot..amazonaws.com -clientId -thingName -certificateFile -privateKeyFile "

To run the Device Shadow Echo sample, use the following command:

$ mvn exec:java -Dexec.mainClass="com.amazonaws.services.iot.client.sample.shadowEcho.ShadowEchoSample" -Dexec.args="-clientEndpoint .iot..amazonaws.com -clientId -thingName -certificateFile -privateKeyFile "

Using the AWS IoT SDK for Python

You can get started with the SDK for Python by integrating it into an existing application or by trying the included sample applications. The SDK is available both as a package in PyPi and as source with samples on GitHub. For information about using the SDK, see the readme. In this post, we will show you how to load and run the samples.

Acquire the samples

Clone the aws-iot-device-sdk-python repository to your development machine.

$ git clone https://github.com/aws/aws-iot-device-sdk-python.git
$ cd aws-iot-device-sdk-python
$ python setup.py install

Run the samples

There are four samples applications included with the SDK:

  1. BasicPubSub sample: This example demonstrates a simple MQTT publish/subscribe operation using AWS IoT. It first subscribes to a topic and registers a callback to print new messages. It then publishes to the same topic in a loop.
  2. BasicPubSub with Amazon Cognito Session Token sample: This example builds on the first sample by using an Amazon Cognito Identity session token. Using the AWS SDK for Python (boto3), it first makes a request to Amazon Cognito to retrieve the access ID, the access key, and the session token for temporary authentication. Using the AWS IoT SDK for Python, it then uses these credentials to connect to AWS IoT and communicate data/messages using MQTT over the WebSocket protocol.
  3. ThingShadowEcho sample: This example demonstrates how a device communicates with AWS IoT, syncing data into the device shadow in the cloud and receiving commands from another app. When there is a new command from the app to change the desired state of the device, the device receives this request on a delta callback function and applies the change by publishing it as the reported state. To see this in action, you can use the AWS IoT console to update the shadow and observe the corresponding state change in this sample application.
  4. BasicShadow sample: This example demonstrates the use of basic shadow operations (update/delta). It has two scripts that perform shadow update operations and listen on delta topics, respectively. The example shows how a shadow update request triggers delta events.

From the command line, use the following commands and parameters to execute the sample applications. You can find the parameter values for the commands in the AWS IoT console by navigating to the thing and choosing Connect Device.

To run the BasicPubSub sample, use the command below that corresponds to your connection type:

$ # Certificate based mutual authentication
$ python basicPubSub.py -e -r -c -k
$ # MQTT over WebSocket
$ python basicPubSub.py -e -r -w

For the BasicPubSub with Amazon Cognito Session Token sample, you will need:

  • Your Amazon Cognito identity pool ID.
  • A role that allows unauthenticated identities to connect. Make sure that the policy attached to the unauthenticated role has permissions to access the required AWS IoT APIs. For more information about Amazon Cognito, see here.

To run the sample, use the following command:

$ python basicPubSub_CognitoSTS.py -e -r -C

To run the ThingShadowEcho sample, use the command below that corresponds to your connection type:

$ # Certificate based mutual authentication
$ python ThingShadowEcho.py -e -r -c -k
$ # MQTT over WebSocket
$ python ThingShadowEcho.py -e -r -w

To run the BasicShadow sample, first start the basicShadowDeltaListener. Use the command below that corresponds to your connection type:

$ # Certificate-based mutual authentication
$ python basicShadowDeltaListener.py -e -r -c -k
$ # MQTT over WebSocket
$ python basicShadowDeltaListener.py -e -r -w

Then, start the basicShadowUpdater. Use the command below that corresponds to your connection type:

$ # Certificate-based mutual authentication
$ python basicShadowUpdater.py -e -r -c -k
$ # MQTT over WebSockets
$ python basicShadowUpdater.py -e -r -w

Summary

We hope you found this blog post useful. We regularly update all of the SDKs as new features are added to AWS IoT. We will also be adding more SDKs in the coming months. Stay tuned to this blog and GitHub for updates. Feel free to leave your feedback in the comments.