Improved MQTT5 user guide and sample documentation

documents/MQTT5_Userguide.md

@@ -11,8 +11,8 @@
     * [How to create an MQTT5 Client based on desired connection method](#how-to-create-an-mqtt5-client-based-on-desired-connection-method)
         * [Direct MQTT with X509-based mutual TLS](#direct-mqtt-with-x509-based-mutual-tls)
         * [Direct MQTT with Custom Authentication](#direct-mqtt-with-custom-authentication)
-        * [Direct MQTT with PKCS11 Method](#direct-mqtt-with-pkcs11-method)
-        * [Direct MQTT with PKCS12 Method](#direct-mqtt-with-pkcs12-method)
+        * [Direct MQTT with PKCS11 Method (Unix Only)](#direct-mqtt-with-pkcs11-method-unix-only)
+        * [Direct MQTT with PKCS12 Method (macOS Only)](#direct-mqtt-with-pkcs12-method-macos-only)
         * [MQTT over Websockets with Sigv4 authentication](#mqtt-over-websockets-with-sigv4-authentication)
         * [MQTT over Websockets with Cognito authentication](#mqtt-over-websockets-with-cognito-authentication)
         * [Direct MQTT with Windows Certificate Store Method](#direct-mqtt-with-windows-certificate-store-method)
@@ -90,7 +90,7 @@ For X509 based mutual TLS, you can create a client where the certificate and pri
     client = mqtt5_client_builder.mtls_from_path(
         endpoint = "<account-specific endpoint>",
         cert_filepath=cert_filepath,
-        pri_key_filepath=pri_key_filepath))
+        pri_key_filepath=pri_key_filepath)
 ```
 
 #### **Direct MQTT with Custom Authentication**
@@ -123,7 +123,7 @@ If your custom authorizer uses signing, you must specify the three signed token
 
 In both cases, the builder will construct a final CONNECT packet username field value for you based on the values configured.  Do not add the token-signing fields to the value of the username that you assign within the custom authentication config structure.  Similarly, do not add any custom authentication related values to the username in the CONNECT configuration optionally attached to the client configuration. The builder will do everything for you.
 
-#### **Direct MQTT with PKCS11 Method**
+#### **Direct MQTT with PKCS11 Method (Unix Only)**
 
 An MQTT5 direct connection can be made using a PKCS11 device rather than using a PEM encoded private key, the private key for mutual TLS is stored on a PKCS#11 compatible smart card or Hardware Security Module (HSM). To create an MQTT5 builder configured for this connection, see the following code:
 
@@ -146,7 +146,7 @@ An MQTT5 direct connection can be made using a PKCS11 device rather than using a
 
 **Note**: Currently, TLS integration with PKCS#11 is only available on Unix devices.
 
-#### **Direct MQTT with PKCS12 Method**
+#### **Direct MQTT with PKCS12 Method (macOS Only)**
 
 An MQTT5 direct connection can be made using a PKCS12 file rather than using a PEM encoded private key. To create an MQTT5 builder configured for this connection, see the following code:
 
@@ -182,7 +182,7 @@ any additional configuration:
     client = mqtt5_client_builder.websockets_with_default_aws_signing(
         endpoint = "<account-specific endpoint>",
         region = signing_region,
-        credentials_provider=credentials_provider))
+        credentials_provider=credentials_provider)
 ```
 
 #### **MQTT over Websockets with Cognito authentication**
@@ -209,7 +209,7 @@ To create an MQTT5 builder configured for this connection, see the following cod
     client = mqtt5_client_builder.websockets_with_default_aws_signing(
         endpoint = "<account-specific endpoint>",
         region = signing_region,
-        credentials_provider=credentials_provider))
+        credentials_provider=credentials_provider)
 ```
 
 **Note**: A Cognito identity ID is different from a Cognito identity pool ID and trying to connect with a Cognito identity pool ID will not work. If you are unable to connect, make sure you are passing a Cognito identity ID rather than a Cognito identity pool ID.
@@ -241,7 +241,7 @@ by adding the http_proxy_options keyword argument to the builder:
         endpoint = "<account-specific endpoint>",
         cert_filepath = "<certificate file path>",
         pri_key_filepath = "<private key file path>",
-        http_proxy_options = http_proxy_options))
+        http_proxy_options = http_proxy_options)
 ```
 
 SDK Proxy support also includes support for basic authentication and TLS-to-proxy.  SDK proxy support does not include any additional

samples/mqtt/mqtt5_aws_websocket.md

@@ -64,6 +64,11 @@ Note that in a real application, you may want to avoid the use of wildcards in y
 
 </details>
 
+### Determining your signing region
+
+The `signing_region` parameter specifies the AWS region used to sign WebSocket connection requests via [SigV4 authentication](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html). It must match the region of your AWS IoT Core endpoint.
+For example, if your endpoint is `abcdef12345-ats.iot.us-west-2.amazonaws.com`, the signing region is `us-west-2`.
+
 ## How to run
 
 To Run this sample from the `samples\mqtt` folder, use the following command:

samples/mqtt/mqtt5_x509.md

@@ -66,6 +66,31 @@ Note that in a real application, you may want to avoid the use of wildcards in y
 
 </details>
 
+### Getting AWS IoT Endpoint
+Your AWS IoT endpoint is the address your devices use to connect to AWS IoT Core. You can retrieve it using either the AWS Console or the AWS CLI.
+
+#### Using the AWS Console
+
+1. Navigate to the [AWS IoT Core](https://console.aws.amazon.com/iot) console.
+2. In the left navigation pane, select **Domain configurations**.
+3. Copy the domain name listed — this is your AWS IoT endpoint.
+
+#### Using the AWS CLI
+
+Run the following command:
+
+```sh
+aws iot describe-endpoint --endpoint-type iot:Data-ATS
+```
+
+The output will contain your endpoint:
+
+```json
+{
+  "endpointAddress": "<AWS IoT endpoint>"
+}
+```
+
 ## How to run
 
 To Run this sample from the `samples\mqtt` folder, use the following command: