|
| 1 | +# Frequently Asked Questions |
| 2 | + |
| 3 | +### Where should I start? |
| 4 | + |
| 5 | +If you are just getting started make sure you [install this sdk](https://github.com/aws/aws-iot-device-sdk-java-v2#installation) and then build and run the [basic PubSub](https://github.com/aws/aws-iot-device-sdk-java-v2/tree/main/samples#pubsub) |
| 6 | + |
| 7 | +### How do I enable logging? |
| 8 | + |
| 9 | +To enable logging in the samples, you will need to set the following system properties when running the samples: |
| 10 | + |
| 11 | +```sh |
| 12 | +-Daws.crt.debugnative=true |
| 13 | +-Daws.crt.log.destination=File |
| 14 | +-Daws.crt.log.level=Trace |
| 15 | +-Daws.crt.log.filename=<path and filename> |
| 16 | +``` |
| 17 | + |
| 18 | +* `aws.crt.debugnative`: Whether to debug native (C/C++) code. Can be either `true` or `false`. |
| 19 | +* `aws.crt.log.destination`: Where the logs are outputted to. Can be `File`, `Stdout` or `Stderr`. Defaults to `Stderr`. |
| 20 | +* `aws.crt.log.level`: The level of logging shown. Can be `Trace`, `Debug`, `Info`, `Warn`, `Error`, `Fatal`, or `None`. Defaults to `Warn`. |
| 21 | +* `aws.crt.log.filename`: The path to save the log file. Only needed if `aws.crt.log.destination` is set to `File`. |
| 22 | + |
| 23 | +For example, to run `BasicPubSub` with logging you could use the following: |
| 24 | + |
| 25 | +```sh |
| 26 | +mvn compile exec:java -pl samples/BasicPubSub -Daws.crt.debugnative=true -Daws.crt.log.level=Debug -Daws.crt.log.destionation=Stdout -Dexec.mainClass=pubsub.PubSub -Dexec.args='--endpoint <endpoint> --cert <path to cert> --key <path to key> --ca_file <path to ca file>' |
| 27 | +``` |
| 28 | + |
| 29 | +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 avaible on the client side sdk. |
| 30 | + |
| 31 | +### I keep getting AWS_ERROR_MQTT_UNEXPECTED_HANGUP |
| 32 | + |
| 33 | +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: |
| 34 | + |
| 35 | +``` json |
| 36 | +{ |
| 37 | + "Version": "2012-10-17", |
| 38 | + "Statement": [ |
| 39 | + { |
| 40 | + "Effect": "Allow", |
| 41 | + "Action": [ |
| 42 | + "iot:*" |
| 43 | + ], |
| 44 | + "Resource": "*" |
| 45 | + } |
| 46 | + ] |
| 47 | +} |
| 48 | +``` |
| 49 | + |
| 50 | +After getting it working make sure to only allow the actions and resources that you need. More info about IoT IAM policies can be found [here](https://docs.aws.amazon.com/iot/latest/developerguide/security_iam_service-with-iam.html). |
| 51 | + |
| 52 | +### Mac-Only TLS Behavior |
| 53 | + |
| 54 | +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: |
| 55 | + |
| 56 | +``` |
| 57 | +static: certificate has an existing certificate-key pair that was previously imported into the Keychain. Using key from Keychain instead of the one provided. |
| 58 | +``` |
| 59 | + |
| 60 | +### How do debug in VSCode? |
| 61 | + |
| 62 | +Here is an example launch.json file to run the pubsub sample |
| 63 | + ``` json |
| 64 | + { |
| 65 | + // Use IntelliSense to learn about possible attributes. |
| 66 | + // Hover to view descriptions of existing attributes. |
| 67 | + // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387 |
| 68 | + "version": "0.2.0", |
| 69 | + "configurations": [ |
| 70 | + { |
| 71 | + "type": "java", |
| 72 | + "name": "PubSub", |
| 73 | + "request": "launch", |
| 74 | + "mainClass": "pubsub.PubSub", |
| 75 | + "projectName": "BasicPubSub", |
| 76 | + "args": "--endpoint <account-number>-ats.iot.<region>.amazonaws.com --ca_file <path to root-CA> --cert <path to cert> --key <path to key> --client-id test-client", |
| 77 | + "console": "externalTerminal" |
| 78 | + } |
| 79 | + ] |
| 80 | +} |
| 81 | +``` |
| 82 | + |
| 83 | +### What certificates do I need? |
| 84 | + |
| 85 | +* You can download pre-generated certificates from the AWS console (this is the simplest and is recommended for testing) |
| 86 | +* 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) |
| 87 | +* Certificates that you will need to run the samples |
| 88 | + * Root CA Certificates |
| 89 | + * 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) |
| 90 | + * 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 |
| 91 | + * When using samples it can look like this: `--ca_file root-CA.crt` |
| 92 | + * Device certificate |
| 93 | + * Intermediate device certificate that is used to generate the key below |
| 94 | + * When using samples it can look like this: `--cert abcde12345-certificate.pem.crt` |
| 95 | + * Key files |
| 96 | + * You should have generated/downloaded private and public keys that will be used to verify that communications are coming from you |
| 97 | + * When using samples you only need the private key and it will look like this: `--key abcde12345-private.pem.key` |
| 98 | + |
| 99 | +### I still have more questions about the this sdk? |
| 100 | + |
| 101 | +* [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 |
| 102 | +* [Here](https://docs.aws.amazon.com/greengrass/v2/developerguide/what-is-iot-greengrass.html) are the AWS IoT Greengrass v2 docs for more details about greengrass |
| 103 | +* [Discussion](https://github.com/aws/aws-iot-device-sdk-java-v2/discussions) questions are also a great way to ask other questions about this sdk. |
| 104 | +* [Open an issue](https://github.com/aws/aws-iot-device-sdk-java-v2/issues) if you find a bug or have a feature request |
0 commit comments