From 1957f30c5f84405ae82241a5806456eef1929c06 Mon Sep 17 00:00:00 2001 From: Vera Xia Date: Fri, 3 Oct 2025 13:36:38 -0700 Subject: [PATCH 1/4] update faq with crt classifiers --- documents/FAQ.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/documents/FAQ.md b/documents/FAQ.md index a91b66d8..dfa2c4e6 100644 --- a/documents/FAQ.md +++ b/documents/FAQ.md @@ -123,6 +123,39 @@ Instructions for building, installing, and use of the Android SDK can be found [ ### Where can I find MQTT 311 Samples? The MQTT 311 Samples can be found in the v1.27.2 samples folder [here](https://github.com/aws/aws-iot-device-sdk-java-v2/tree/v1.27.2/samples) +### The library size is large, can I improve it? +The SDK depends on aws-crt-java(CRT) library, which deploys native binaries for multiple platforms and results in a huge size. You can try the following options to reduce the package size. +1. Use platform-specific dependencies +Instead of including all platform binaries, specify only the platforms you need. +Sample to use classifier from aws-crt: + ``` + + software.amazon.awssdk.crt + aws-crt + 0.39.0 + linux-x86_64 + + ``` + Checkout aws-crt-java [available classifier](https://github.com/awslabs/aws-crt-java/tree/main?tab=readme-ov-file#available-classifiers) + +2. Build CRT and SDK from source +You can also build the CRT library and SDK from source + + a. [Build aws-crt library from source](https://github.com/awslabs/aws-crt-java/tree/main?tab=readme-ov-file#platform) + + b. Update SDK to use local CRT build. + Update the `sdk/pom.xml` dependencies: + + + software.amazon.awssdk.crt + aws-crt + 1.0.0-SNAPSHOT + + + + c. [Build the SDK from source](https://github.com/aws/aws-iot-device-sdk-java-v2/blob/main/documents/DEVELOPING.md#building-from-source) + + ### I still have more questions about this sdk? * [Here](https://docs.aws.amazon.com/iot/latest/developerguide/what-is-aws-iot.html) are the AWS IoT Core docs for more details about IoT Core From 6dfd49b2a81af3c8bc34e42986ee294f81393338 Mon Sep 17 00:00:00 2001 From: Vera Xia Date: Fri, 3 Oct 2025 13:45:20 -0700 Subject: [PATCH 2/4] update faq content table --- documents/FAQ.md | 65 +++++++++++++++++++++++++----------------------- 1 file changed, 34 insertions(+), 31 deletions(-) diff --git a/documents/FAQ.md b/documents/FAQ.md index dfa2c4e6..6ed6b3ed 100644 --- a/documents/FAQ.md +++ b/documents/FAQ.md @@ -11,6 +11,7 @@ * [How do I build and use the Android SDK?](#how-do-i-build-and-use-the-android-sdk) * [Where can I find MQTT 311 Samples?](#where-can-i-find-mqtt-311-samples) * [I still have more questions about this sdk?](#i-still-have-more-questions-about-this-sdk) +* [How can I improve the library size? ](#how-can-i-improve-the-library-size) ### Where should I start? @@ -123,37 +124,39 @@ Instructions for building, installing, and use of the Android SDK can be found [ ### Where can I find MQTT 311 Samples? The MQTT 311 Samples can be found in the v1.27.2 samples folder [here](https://github.com/aws/aws-iot-device-sdk-java-v2/tree/v1.27.2/samples) -### The library size is large, can I improve it? -The SDK depends on aws-crt-java(CRT) library, which deploys native binaries for multiple platforms and results in a huge size. You can try the following options to reduce the package size. -1. Use platform-specific dependencies -Instead of including all platform binaries, specify only the platforms you need. -Sample to use classifier from aws-crt: - ``` - - software.amazon.awssdk.crt - aws-crt - 0.39.0 - linux-x86_64 - - ``` - Checkout aws-crt-java [available classifier](https://github.com/awslabs/aws-crt-java/tree/main?tab=readme-ov-file#available-classifiers) - -2. Build CRT and SDK from source -You can also build the CRT library and SDK from source - - a. [Build aws-crt library from source](https://github.com/awslabs/aws-crt-java/tree/main?tab=readme-ov-file#platform) - - b. Update SDK to use local CRT build. - Update the `sdk/pom.xml` dependencies: - - - software.amazon.awssdk.crt - aws-crt - 1.0.0-SNAPSHOT - - - - c. [Build the SDK from source](https://github.com/aws/aws-iot-device-sdk-java-v2/blob/main/documents/DEVELOPING.md#building-from-source) +### How can I improve the library size? + +The SDK depends on aws-crt-java, which includes native binaries for multiple platforms (~50MB total). Here are two approaches to reduce size: + +#### Option 1: Use Platform-Specific Dependencies + +Use classifiers to include only your target platform's binaries: + +```xml + + software.amazon.awssdk.crt + aws-crt + 0.39.0 + linux-x86_64 + +``` + +See [all available classifiers](https://github.com/awslabs/aws-crt-java/tree/main?tab=readme-ov-file#available-classifiers). + +#### Option 2: Build from Source + +For maximum control, build both CRT and SDK locally: + +1. [Build aws-crt-java from source](https://github.com/awslabs/aws-crt-java/tree/main?tab=readme-ov-file#platform) +2. Update `sdk/pom.xml` to use local aws-crt build: + ```xml + + software.amazon.awssdk.crt + aws-crt + 1.0.0-SNAPSHOT + + ``` +3. [Build the SDK from source](./DEVELOPING.md#building-from-source) ### I still have more questions about this sdk? From 208ea26f3e2ec753df123f97019ff25f5adef0ea Mon Sep 17 00:00:00 2001 From: Vera Xia Date: Tue, 14 Oct 2025 10:23:37 -0700 Subject: [PATCH 3/4] typo and grammar in faq --- documents/FAQ.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/documents/FAQ.md b/documents/FAQ.md index 6ed6b3ed..0d37de50 100644 --- a/documents/FAQ.md +++ b/documents/FAQ.md @@ -29,14 +29,14 @@ To enable logging in the samples, you will need to set the following system prop ``` * `aws.crt.debugnative`: Whether to debug native (C/C++) code. Can be either `true` or `false`. -* `aws.crt.log.destination`: Where the logs are outputted to. Can be `File`, `Stdout` or `Stderr`. Defaults to `Stderr`. +* `aws.crt.log.destination`: Where the logs are output to. Can be `File`, `Stdout`, or `Stderr`. Defaults to `Stderr`. * `aws.crt.log.level`: The level of logging shown. Can be `Trace`, `Debug`, `Info`, `Warn`, `Error`, `Fatal`, or `None`. Defaults to `Warn`. * `aws.crt.log.filename`: The path to save the log file. Only needed if `aws.crt.log.destination` is set to `File`. For example, to run `BasicPubSub` with logging you could use the following: ```sh -mvn compile exec:java -pl samples/Mqtt/Mqtt5X509 -Daws.crt.debugnative=true -Daws.crt.log.level=Debug -Daws.crt.log.destionation=Stdout -Dexec.mainClass=pubsub.PubSub -Dexec.args='--endpoint --cert --key ' +mvn compile exec:java -pl samples/Mqtt/Mqtt5X509 -Daws.crt.debugnative=true -Daws.crt.log.level=Debug -Daws.crt.log.destination=Stdout -Dexec.mainClass=pubsub.PubSub -Dexec.args='--endpoint --cert --key ' ``` You can also enable [CloudWatch logging](https://docs.aws.amazon.com/iot/latest/developerguide/cloud-watch-logs.html) for IoT which will provide you with additional information that is not available on the client side sdk. @@ -56,7 +56,7 @@ System.out.println(CRT.awsErrorString(errorCode)); ### I keep getting AWS_ERROR_MQTT_UNEXPECTED_HANGUP -This could be many different things but it most likely is a policy issue. Start with using a super permissive IAM policy called AWSIOTFullAccess which looks like this: +This could be many different things, but it is most likely a policy issue. Start by using a super permissive IAM policy called AWSIOTFullAccess which looks like this: ``` json { From 0302f22c8226be04d2d2bfd831c29f0a914bcb3e Mon Sep 17 00:00:00 2001 From: Vera Xia Date: Wed, 15 Oct 2025 11:55:08 -0700 Subject: [PATCH 4/4] update cr comments --- documents/FAQ.md | 32 +++++++++++++++++++++++--------- 1 file changed, 23 insertions(+), 9 deletions(-) diff --git a/documents/FAQ.md b/documents/FAQ.md index 0d37de50..9583a61f 100644 --- a/documents/FAQ.md +++ b/documents/FAQ.md @@ -6,12 +6,13 @@ * [How do I get more information from an error code?](#how-do-i-get-more-information-from-an-error-code) * [I keep getting AWS_ERROR_MQTT_UNEXPECTED_HANGUP](#i-keep-getting-aws_error_mqtt_unexpected_hangup) * [I am experiencing deadlocks](#i-am-experiencing-deadlocks) -* [How do debug in VSCode?](#how-do-debug-in-vscode) +* [How to debug in VSCode?](#how-to-debug-in-vscode) * [What certificates do I need?](#what-certificates-do-i-need) +* [I am getting AWS_IO_TLS_ERROR_DEFAULT_TRUST_STORE_NOT_FOUND](#root-ca-file) * [How do I build and use the Android SDK?](#how-do-i-build-and-use-the-android-sdk) * [Where can I find MQTT 311 Samples?](#where-can-i-find-mqtt-311-samples) +* [How can I improve the library size?](#how-can-i-improve-the-library-size) * [I still have more questions about this sdk?](#i-still-have-more-questions-about-this-sdk) -* [How can I improve the library size? ](#how-can-i-improve-the-library-size) ### Where should I start? @@ -36,7 +37,7 @@ To enable logging in the samples, you will need to set the following system prop For example, to run `BasicPubSub` with logging you could use the following: ```sh -mvn compile exec:java -pl samples/Mqtt/Mqtt5X509 -Daws.crt.debugnative=true -Daws.crt.log.level=Debug -Daws.crt.log.destination=Stdout -Dexec.mainClass=pubsub.PubSub -Dexec.args='--endpoint --cert --key ' +mvn compile exec:java -pl samples/Mqtt/Mqtt5X509 -Daws.crt.debugnative=true -Daws.crt.log.level=Debug -Daws.crt.log.destination=Stdout -Dexec.args='--endpoint --cert --key ' ``` You can also enable [CloudWatch logging](https://docs.aws.amazon.com/iot/latest/developerguide/cloud-watch-logs.html) for IoT which will provide you with additional information that is not available on the client side sdk. @@ -79,9 +80,9 @@ After getting it working make sure to only allow the actions and resources that You MUST NOT perform blocking operations on any callback, or you will cause a deadlock. For example: in the on_publish_received callback, do not send a publish, and then wait for the future to complete within the callback. The Client cannot do work until your callback returns, so the thread will be stuck. -### How do debug in VSCode? +### How to debug in VSCode? -Here is an example launch.json file to run the pubsub sample +Here is an example `launch.json` file to run the X509 sample ``` json { // Use IntelliSense to learn about possible attributes. @@ -96,6 +97,7 @@ Here is an example launch.json file to run the pubsub sample "mainClass": "mqtt5x509.Mqtt5X509", "projectName": "Mqtt5X509", "args": "--endpoint -ats.iot..amazonaws.com --cert --key --client-id test-client", + "vmArgs": "-Daws.crt.debugnative=true -Daws.crt.log.destination=Stdout", "console": "externalTerminal" } ] @@ -107,10 +109,6 @@ Here is an example launch.json file to run the pubsub sample * You can download pre-generated certificates from the AWS console (this is the simplest and is recommended for testing) * You can also generate your own certificates to fit your specific use case. You can find documentation for that [here](https://docs.aws.amazon.com/iot/latest/developerguide/x509-client-certs.html) and [here](https://iot-device-management.workshop.aws/en/provisioning-options.html) * Certificates that you will need to run the samples - * Root CA Certificates - * Download the root CA certificate file that corresponds to the type of data endpoint and cipher suite you're using (You most likely want Amazon Root CA 1) - * Generated and provided by Amazon. You can download it [here](https://www.amazontrust.com/repository/) or download it when getting the other certificates from the AWS console - * When using samples it can look like this: `--ca_file root-CA.crt` * Device certificate * Intermediate device certificate that is used to generate the key below * When using samples it can look like this: `--cert abcde12345-certificate.pem.crt` @@ -118,6 +116,22 @@ Here is an example launch.json file to run the pubsub sample * You should have generated/downloaded private and public keys that will be used to verify that communications are coming from you * When using samples you only need the private key and it will look like this: `--key abcde12345-private.pem.key` +### I am getting AWS_IO_TLS_ERROR_DEFAULT_TRUST_STORE_NOT_FOUND + +This error usually occurs when the SDK cannot find or access the system's default trust store for TLS certificate validation. You can resolve this by downloading and specifying the Root CA certificate explicitly. + +**Root CA Certificate** +* Download the root CA certificate file that corresponds to the type of data endpoint and cipher suite you're using (you most likely want Amazon Root CA 1 if you are using the AWS IoT service) +* This certificate is generated and provided by Amazon. You can download it [here](https://www.amazontrust.com/repository/) or download it when getting the other certificates from the AWS Console + +**Set Root CA for the client builder** +```java +// When building your MQTT5 client, specify the CA file +// Mqtt5ClientBuilder builder = +builder.withCertificateAuthorityFromPath(null, ""); +``` + + ### How do I build and use the Android SDK? Instructions for building, installing, and use of the Android SDK can be found [here](../documents/ANDROID.md)