aws · jmklix · May 31, 2022 · Mar 10, 2021 · Apr 12, 2021 · May 19, 2021
diff --git a/README.md b/README.md
@@ -22,19 +22,18 @@ to Python by the `awscrt` package ([PyPI](https://pypi.org/project/awscrt/)) ([G
 
 *__Jump To:__*
 * [Installation](#Installation)
-* [Mac-Only TLS Behavior](#Mac-Only-TLS-Behavior)
 * [Samples](samples)
 * [Getting Help](#Getting-Help)
+* [FAQ](./documents/FAQ.md)
 * [Giving Feedback and Contributions](#Giving-Feedback-and-Contributions)
-* [More Resources](#More-Resources)
 
 
 ## Installation
 
 ### Minimum Requirements
 * Python 3.6+
 
-[Step-by-step instructions](./PREREQUISITES.md)
+[Step-by-step instructions](./documents/PREREQUISITES.md)
 
 ### Install from PyPI
 ```
@@ -56,15 +55,7 @@ python3 -m pip install ./aws-iot-device-sdk-python-v2
 
 `awsiotsdk` depends on [awscrt](https://github.com/awslabs/aws-crt-python), which makes use of C extensions. Precompiled wheels are downloaded when installing on major platforms (Mac, Windows, Linux, Raspberry Pi OS). If wheels are unavailable for your platform, your machine must compile some C libraries.
 
-If you encounter issues, see [Installation Issues](./PREREQUISITES.md#installation-issues) and try again.
-
-## Mac-Only TLS Behavior
-
-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.3.2, when a stored private key from the Keychain is used, the following will be logged at the "info" log level:
-
-```
-static: certificate has an existing certificate-key pair that was previously imported into the Keychain.  Using key from Keychain instead of the one provided.
-```
+If you encounter issues, see [Installation Issues](./documents/PREREQUISITES.md#installation-issues) and try again.
 
 ## Samples
 
@@ -76,6 +67,7 @@ The best way to interact with our team is through GitHub. You can [open an issue
 
 Please make sure to check out our resources too before opening an issue:
 
+* Our [FAQ](./documents/FAQ.md)
 * [API documentation](https://aws.github.io/aws-iot-device-sdk-python-v2/)
 * Our [Developer Guide](https://docs.aws.amazon.com/iot/latest/developerguide/what-is-aws-iot.html) ([source](https://github.com/awsdocs/aws-iot-docs))
 * Check for similar [Issues](https://github.com/aws/aws-iot-device-sdk-python-v2/issues)
@@ -90,24 +82,11 @@ is provided by code that been generated from a model of the service.
 
 We need your help in making this SDK great. Please participate in the community and contribute to this effort by submitting issues, participating in discussion forums and submitting pull requests through the following channels.
 
-*   [Contributions Guidelines](/CONTRIBUTING.md)
-*   Articulate your feature request or upvote existing ones on our [Issues](https://github.com/aws/aws-iot-device-sdk-python-v2/issues?q=is%3Aissue+is%3Aopen+label%3Afeature-request) page.
-*   Submit [Issues](https://github.com/aws/aws-iot-device-sdk-python-v2/issues)
-
-
-## More Resources
-
-*   [AWS IoT Core Documentation](https://docs.aws.amazon.com/iot/)
-*   [Developer Guide](https://docs.aws.amazon.com/iot/latest/developerguide/what-is-aws-iot.html) ([source](https://github.com/awsdocs/aws-iot-docs))
-*   [Issues](https://github.com/aws/aws-iot-device-sdk-python-v2/issues)
-*   [Dev Blog](https://aws.amazon.com/blogs/?awsf.blog-master-iot=category-internet-of-things%23amazon-freertos%7Ccategory-internet-of-things%23aws-greengrass%7Ccategory-internet-of-things%23aws-iot-analytics%7Ccategory-internet-of-things%23aws-iot-button%7Ccategory-internet-of-things%23aws-iot-device-defender%7Ccategory-internet-of-things%23aws-iot-device-management%7Ccategory-internet-of-things%23aws-iot-platform)
-
-Integration with AWS IoT Services such as
-[Device Shadow](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html)
-and [Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html)
-is provided by code that been generated from a model of the service.
-
+* [Contributions Guidelines](./documents/CONTRIBUTING.md)
+* Articulate your feature request or upvote existing ones on our [Issues](https://github.com/aws/aws-iot-device-sdk-python-v2/issues?q=is%3Aissue+is%3Aopen+label%3Afeature-request) page.
+* Create discussion questions [here](https://github.com/aws/aws-iot-device-sdk-python-v2/discussions)
+* Find a bug open an [issue](https://github.com/aws/aws-iot-device-sdk-python-v2/issues)
 
 ## License
 
-This library is licensed under the Apache 2.0 License.
+This library is licensed under the [Apache 2.0 License](./documents/LICENSE).
diff --git a/CODE_OF_CONDUCT.md → documents/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md → documents/CODE_OF_CONDUCT.md
diff --git a/CONTRIBUTING.md → documents/CONTRIBUTING.md b/CONTRIBUTING.md → documents/CONTRIBUTING.md
diff --git a/documents/FAQ.md b/documents/FAQ.md
@@ -0,0 +1,91 @@
+# Frequently Asked Questions
+
+### Where should I start?
+
+If you are just getting started make sure you [install this sdk](https://github.com/aws/aws-iot-device-sdk-python-v2#installation) and then build and run the [basic PubSub](https://github.com/aws/aws-iot-device-sdk-python-v2/tree/main/samples#pubsub)
+
+### How do I enable logging?
+
+``` python
+io.init_logging(io.LogLevel.Error, 'stderr')
+```
+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.
+
+### 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:
+
+``` json
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Effect": "Allow",
+            "Action": [
+                "iot:*"
+            ],
+            "Resource": "*"
+        }
+    ]
+}
+```
+
+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).
+
+### Mac-Only TLS Behavior
+
+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:
+
+```
+static: certificate has an existing certificate-key pair that was previously imported into the Keychain.  Using key from Keychain instead of the one provided.
+```
+
+### How do debug in VSCode? 
+
+Here is an example launch.json file to run the pubsub sample
+ ``` json
+ {
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "PubSub",
+            "type": "python",
+            "request": "launch",
+            "program": "${workspaceFolder}/samples/pubsub.py",
+            "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"
+            ]
+        }
+    ]
+}
+```
+
+### What certificates do I need?
+
+* 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`
+    * Key files 
+        * 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 still have more questions about the 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
+* [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 
+* [Discussion](https://github.com/aws/aws-iot-device-sdk-python-v2/discussions) questions are also a great way to ask other questions about this sdk.
+* [Open an issue](https://github.com/aws/aws-iot-device-sdk-python-v2/issues) if you find a bug or have a feature request
diff --git a/LICENSE → documents/LICENSE b/LICENSE → documents/LICENSE
diff --git a/NOTICE → documents/NOTICE b/NOTICE → documents/NOTICE
diff --git a/PREREQUISITES.md → documents/PREREQUISITES.md b/PREREQUISITES.md → documents/PREREQUISITES.md