You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+74-51Lines changed: 74 additions & 51 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,39 +1,54 @@
1
1
# AWS IoT Device SDK for Java v2
2
2
3
-
This document provides information about the AWS IoT device SDK for Java V2. This SDK is built on the [AWS Common Runtime](https://docs.aws.amazon.com/sdkref/latest/guide/common-runtime.html)
3
+
The AWS IoT Device SDK for Java v2 connects your Java applications and devices to the AWS IoT platform. It handles the complexities of secure communication, authentication, and device management so you can focus on your IoT solution. The SDK makes it easy to use AWS IoT services like Device Shadows, Jobs, Fleet Provisioning, and Commands.
4
4
5
-
*__Jump To:__*
5
+
**Supported Platforms**: Linux, Windows 11+, macOS 14+, Android API level 24+ (Android 7.0+)
6
6
7
+
> **Note**: The SDK is known to work on older platform versions, but we only guarantee compatibility for the platforms listed above.
*[MQTT5 User Guide](./documents/MQTT5_Userguide.md)
15
-
*[Migration Guide from the AWS IoT SDK for Java v1](./documents/MIGRATION_GUIDE.md)
17
+
*[Getting Help](#getting-help)
18
+
*[Resources](#resources)
19
+
20
+
## Features
21
+
22
+
The primary purpose of the AWS IoT Device SDK for Java v2 is to simplify the process of connecting devices to AWS IoT Core and interacting with AWS IoT services on various platforms. The SDK provides:
23
+
24
+
* Integrated service clients for AWS IoT Core services
25
+
* Secure device connections to AWS IoT Core using MQTT protocol including MQTT 5.0
26
+
* Support for [multiple authentication methods and connection types](./documents/MQTT5_Userguide.md#how-to-setup-mqtt5-builder-based-on-desired-connection-method)
27
+
* Android [support](./documents/ANDROID.md)
28
+
29
+
#### Supported AWS IoT Core services
30
+
31
+
* The [AWS IoT Device Shadow](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html) service manages device state information in the cloud.
32
+
* The [AWS IoT Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html) service sends remote operations to connected devices.
33
+
* The [AWS IoT fleet provisioning](https://docs.aws.amazon.com/iot/latest/developerguide/provision-wo-cert.html) service generates and delivers device certificates automatically.
34
+
* The [AWS IoT Device Management commands](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command.html) service sends instructions from the cloud to connected devices.
16
35
17
36
## Installation
18
37
38
+
The recommended way to use the AWS IoT Device SDK for Java v2 in your project is to consume it from Maven Central.
39
+
19
40
### Minimum Requirements
20
41
42
+
To develop applications that use AWS IoT Device SDK for Java v2, you need:
21
43
* Java 8+ ([Download and Install Java](https://www.java.com/en/download/help/download_options.html))
22
-
* Java JDK 8+ ([Download and Install JDK](https://docs.oracle.com/en/java/javase/18/install/overview-jdk-installation.html#GUID-8677A77F-231A-40F7-98B9-1FD0B48C346A))
See [detailed setup instructions](./documents/PREREQUISITES.md) for more information.
33
48
34
49
### Consuming IoT Device SDK from Maven in your application
35
50
36
-
Consuming this SDK via Maven is the preferred method of consuming it and using it within your application. To consume the Java V2 SDK in your application, add the following to your `pom.xml` dependencies:
51
+
Add the following to your `pom.xml` dependencies:
37
52
38
53
```xml
39
54
<dependency>
@@ -46,57 +61,65 @@ Consuming this SDK via Maven is the preferred method of consuming it and using i
46
61
Replace `1.27.4` in `<version>1.27.4</version>` with the latest release version for the SDK.
47
62
Look up the latest SDK version here: https://github.com/aws/aws-iot-device-sdk-java-v2/releases
48
63
49
-
### Build IoT Device SDK from source
64
+
### Building AWS IoT SDK from source
50
65
51
-
[Install Maven and Set PATH](https://maven.apache.org/install.html)
66
+
See the [Development Guide](./documents/DEVELOPING.md) for detailed instructions on building from source and using local builds.
52
67
53
-
```sh
54
-
# Create a workspace directory to hold all the SDK files
To get started with the AWS IoT Device SDK for Java v2:
71
+
72
+
1. Add the SDK to your project - See the [Installation](#installation) section for Maven dependency details
73
+
74
+
2. Choose your connection method - The SDK supports multiple authentication methods including X.509 certificates, AWS credentials, and custom authentication. [MQTT5 User Guide connection section](./documents/MQTT5_Userguide.md#how-to-setup-mqtt5-builder-based-on-desired-connection-method) and [MQTT5 X509 sample](./samples/Mqtt/Mqtt5X509/README.md) provide more guidance
63
75
64
-
If you wish to use the latest CRT release, rather than the latest tested with the IoT SDK, you can run the following before running `mvn clean install`:
76
+
3. Follow a complete example - Check out the [samples](samples) directory
The samples provide ready-to-run code with detailed setup instructions for each authentication method and use case.
90
+
91
+
## Getting Help
92
+
93
+
The best way to interact with our team is through GitHub.
94
+
* Open [discussion](https://github.com/aws/aws-iot-device-sdk-java-v2/discussions): Share ideas and solutions with the SDK community
95
+
* Search [issues](https://github.com/aws/aws-iot-device-sdk-java-v2/issues): Find created issues for answers based on a topic
96
+
* Create an [issue](https://github.com/aws/aws-iot-device-sdk-java-v2/issues/new/choose): New feature request or file a bug
97
+
98
+
If you have a support plan with [AWS Support](https://aws.amazon.com/premiumsupport/), you can also create a new support case.
74
99
75
-
### Mac-Only TLS Behavior
100
+
#### Mac-Only TLS Behavior
101
+
102
+
> [!NOTE]
103
+
> This SDK does not support TLS 1.3 on macOS. Support for TLS 1.3 on macOS is planned for a future release.
76
104
77
105
Please note that on Mac, once a private key is used with a certificate, that certificate-key pair is imported into the Mac Keychain. All subsequent uses of that certificate will use the stored private key and ignore anything passed in programmatically. Beginning in v1.7.3, when a stored private key from the Keychain is used, the following will be logged at the "info" log level:
78
106
79
107
```
80
-
static: certificate has an existing certificate-key pair that was previously imported into the Keychain. Using key from Keychain instead of the one provided.
108
+
static: certificate has an existing certificate-key pair that was previously imported into the Keychain.
109
+
Using key from Keychain instead of the one provided.
81
110
```
82
111
83
-
## Getting Help
112
+
## Resources
84
113
85
-
The best way to interact with our team is through GitHub. You can open a [discussion](https://github.com/aws/aws-iot-device-sdk-java-v2/discussions) for guidance questions or an [issue](https://github.com/aws/aws-iot-device-sdk-java-v2/issues/new/choose) for bug reports, or feature requests. You may also find help on community resources such as [StackOverFlow](https://stackoverflow.com/questions/tagged/aws-iot) with the tag [#aws-iot](https://stackoverflow.com/questions/tagged/aws-iot) or if you have a support plan with [AWS Support](https://aws.amazon.com/premiumsupport/), you can also create a new support case.
86
-
87
-
Please make sure to check out our resources too before opening an issue:
114
+
Check out our resources for additional guidance too before opening an issue:
0 commit comments