From aa3be968e284438da3a681a7c8e43be4925cf416 Mon Sep 17 00:00:00 2001
From: Bret Ambrose <bretambrose@gmail.com>
Date: Wed, 10 Jul 2024 09:25:46 -0700
Subject: [PATCH] Provisioning sample READMEs

---
 .../node/fleet_provisioning/basic/README.md   | 115 ++----------------
 samples/node/fleet_provisioning/csr/README.md | 114 ++---------------
 samples/node/shadow/README.md                 |   5 +-
 3 files changed, 20 insertions(+), 214 deletions(-)

diff --git a/samples/node/fleet_provisioning/basic/README.md b/samples/node/fleet_provisioning/basic/README.md
index 1372569f..deed5428 100644
--- a/samples/node/fleet_provisioning/basic/README.md
+++ b/samples/node/fleet_provisioning/basic/README.md
@@ -2,9 +2,7 @@
 
 [**Return to main sample list**](../../README.md)
 
-This sample uses the AWS IoT [Fleet provisioning](https://docs.aws.amazon.com/iot/latest/developerguide/provision-wo-cert.html) to provision devices using either a CSR or Keys-And-Certificate and subsequently calls RegisterThing. This allows you to create new AWS IoT Core things using a Fleet Provisioning Template.
-
-On startup, the script subscribes to topics based on the request type of either CSR or Keys topics, publishes the request to corresponding topic and calls RegisterThing.
+This sample uses the AWS IoT [Fleet provisioning service](https://docs.aws.amazon.com/iot/latest/developerguide/provision-wo-cert.html) to provision devices using the CreateKeysAndCertificate and RegisterThing APIs. This allows you to create new AWS IoT Core thing resources using a Fleet Provisioning Template.
 
 Your IoT Core Thing's [Policy](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html) must provide privileges for this sample to connect, subscribe, publish, and receive. Below is a sample policy that can be used on your IoT Core Thing that will allow this sample to run as intended.
 
@@ -19,7 +17,6 @@ Your IoT Core Thing's [Policy](https://docs.aws.amazon.com/iot/latest/developerg
       "Action": "iot:Publish",
       "Resource": [
         "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/certificates/create/json",
-        "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/certificates/create-from-csr/json",
         "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/provisioning-templates/<b>templatename</b>/provision/json"
       ]
     },
@@ -31,8 +28,6 @@ Your IoT Core Thing's [Policy](https://docs.aws.amazon.com/iot/latest/developerg
       "Resource": [
         "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/certificates/create/json/accepted",
         "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/certificates/create/json/rejected",
-        "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/certificates/create-from-csr/json/accepted",
-        "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/certificates/create-from-csr/json/rejected",
         "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/provisioning-templates/<b>templatename</b>/provision/json/accepted",
         "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/provisioning-templates/<b>templatename</b>/provision/json/rejected"
       ]
@@ -45,8 +40,6 @@ Your IoT Core Thing's [Policy](https://docs.aws.amazon.com/iot/latest/developerg
       "Resource": [
         "arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/certificates/create/json/accepted",
         "arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/certificates/create/json/rejected",
-        "arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/certificates/create-from-csr/json/accepted",
-        "arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/certificates/create-from-csr/json/rejected",
         "arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/provisioning-templates/<b>templatename</b>/provision/json/accepted",
         "arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/provisioning-templates/<b>templatename</b>/provision/json/rejected"
       ]
@@ -69,7 +62,7 @@ Note that in a real application, you may want to avoid the use of wildcards in y
 
 </details>
 
-## How to run
+### How to run
 
 There are many different ways to run the Fleet Provisioning sample because of how many different ways there are to setup a Fleet Provisioning template in AWS IoT Core. **The easiest and most common way is to run the sample with the following**:
 
@@ -79,23 +72,6 @@ npm install
 node ./index.js --endpoint <endpoint> --cert <file> --key <file> --template_name <template name> --template_parameters <template parameters>
 ```
 
-You can also run the sample with `--mqtt5` to run it with Mqtt5 Client
-``` sh
-# from the node/fleet_provisioning folder
-npm install
-node ./index.js --endpoint <endpoint> --cert <file> --key <file> --template_name <template name> --template_parameters <template parameters> --mqtt5
-```
-
-You can also pass a Certificate Authority file (CA) if your certificate and key combination requires it:
-
-``` sh
-# from the node/fleet_provisioning folder
-npm install
-node ./index.js --endpoint <endpoint> --cert <file> --key <file> --template_name <template name> --template_parameters <template parameters> --ca_file <file>
-```
-
-However, this is just one way using the `CreateKeysAndCertificate` workflow. Below are a detailed list of instructions with the different ways to connect. While the detailed instructions do not show it, you can pass `--ca_file` as needed no matter which way you connect via Fleet Provisioning.
-
 ### Fleet Provisioning Detailed Instructions
 
 #### Aws Resource Setup
@@ -260,13 +236,13 @@ We've included a script in the utils folder that creates certificate and key fil
 `create-provisioning-claim`. These dynamically sourced certificates are **only valid for five minutes**. When running the command,
 you'll need to substitute the name of the template you previously created. If on Windows, replace the paths with something appropriate.
 
-**Note**: The following assumes you are running this command from the `aws-iot-device-sdk-java-v2` folder, which is the main GitHub folder. If you are running this from another folder (like the `samples/Identity` folder), then you will need to adjust the filepaths accordingly.
+**Note**: The following assumes you are running this command from the `aws-iot-device-sdk-js-v2` folder, which is the main GitHub folder. If you are running this from another folder then you will need to adjust the filepaths accordingly.
 
 ```sh
 aws iot create-provisioning-claim \
     --template-name <TemplateName> \
     | python3 ./utils/parse_cert_set_result.py \
-    --path ./tmp \
+    --path /tmp \
     --filename provision
 ```
 * Replace `<TemplateName>` with the name of the Fleet Provisioning template you created earlier.
@@ -279,88 +255,11 @@ to perform the actual provisioning in the section below.
 To run the sample with your certificate and private key, use the following command:
 
 ``` sh
-# from the node/fleet_provisioning folder
+# from the node/fleet_provisioning/basic folder
 npm install
-node ./index.js --endpoint <endpoint> --cert <file> --key <file> --template_name <template name> --template_parameters '{\"SerialNumber\":\"1\",\"DeviceLocation\":\"Seattle\"}'
+node ./dist/index.js --endpoint <endpoint> --cert <file> --key <file> --template_name <template name> --template_parameters '{"SerialNumber":"1","DeviceLocation":"Seattle"}'
 ```
 
 As per normal, replace the `<>` parameters with the proper values. Notice that we provided substitution values for the two parameters in the template body, `DeviceLocation` and `SerialNumber`.
 
-With that, the sample should run and work as expected! You should then find your have a new AWS IoT Core thing!
-
-### Run the sample using the certificate signing request workflow
-
-To run the sample with this workflow, you'll need to create a certificate signing request in addition to the other steps above (creating the role, setting its policy, setting the template JSON, etc).
-
-First create a certificate-key pair:
-``` sh
-openssl genrsa -out /tmp/deviceCert.key 2048
-```
-
-Next create a certificate signing request from it:
-``` sh
-openssl req -new -key /tmp/deviceCert.key -out /tmp/deviceCert.csr
-```
-
-As in the previous workflow, you can [create a temporary certificate set from a provisioning claim](#creating-a-certificate-key-set-from-a-provisioning-claim). Again, this can be skipped if you have a policy and certificate with the proper permissions.
-
-```sh
-aws iot create-provisioning-claim \
-    --template-name <TemplateName> \
-    | python3 ./utils/parse_cert_set_result.py \
-    --path ./tmp \
-    --filename provision
-```
-* Replace `<TemplateName>` with the name of the Fleet Provisioning template you created earlier.
-
-Finally, you can also pass the certificate signing request while invoking the Fleet Provisioning sample.
-
-``` sh
-# from the node/fleet_provisioning folder
-npm install
-node ./index.js --endpoint <endpoint> --cert <file> --key <file> --template_name <template name> --template_parameters '{\"SerialNumber\":\"1\",\"DeviceLocation\":\"Seattle\"}' --csr <path to csr file>
-```
-
-## Service Client Notes
-### Differences between MQTT5 and MQTT311
-The service client with Mqtt5 client is almost identical to Mqtt3 one. The only difference is that you would need setup up a Mqtt5 Client and pass it to the service client.
-For how to setup a Mqtt5 Client, please refer to [MQTT5 User Guide](https://github.com/awslabs/aws-crt-nodejs/blob/main/MQTT5-UserGuide.md) and [MQTT5 PubSub Sample](../pub_sub_mqtt5/README.md)
-
-<table>
-<tr>
-<th>Create a IoTIdentityClient with Mqtt5</th>
-<th>Create a IoTIdentityClient with Mqtt311</th>
-</tr>
-<tr>
-<td>
-
-```js
-  // Create a Mqtt5 Client
-  config_builder = iot.AwsIotMqtt5ClientConfigBuilder.newDirectMqttBuilderWithMtlsFromPath(argv.endpoint, argv.cert, argv.key);
-  client = new mqtt5.Mqtt5Client(config_builder.build());
-
-  // Create the identity client from Mqtt5 Client
-  identity = iotidentity.IotIdentityClient.newFromMqtt5Client(client5);
-```
-
-</td>
-<td>
-
-```js
-    // Create a Mqtt311 Connection from the command line data
-    config_builder = iot.AwsIotMqttConnectionConfigBuilder.new_mtls_builder_from_path(argv.cert, argv.key);
-    config_builder.with_client_id(argv.client_id || "test-" + Math.floor(Math.random() * 100000000));
-    config_builder.with_endpoint(argv.endpoint);
-    client = new mqtt.MqttClient();
-    connection = client.new_connection(config);
-
-    // Create the shadow client from Mqtt311 Connection
-    identity = new iotidentity.IotIdentityClient(connection);
-```
-
-</td>
-</tr>
-</table>
-
-### mqtt5.QoS v.s. mqtt.QoS
-As the service client interface is unchanged for both Mqtt3 Connection and Mqtt5 Client,the service client will use mqtt.QoS instead of mqtt5.QoS even with a Mqtt5 Client.
+With that, the sample should run and work as expected! You should then find you have a new AWS IoT Core thing!
diff --git a/samples/node/fleet_provisioning/csr/README.md b/samples/node/fleet_provisioning/csr/README.md
index 1372569f..23bebcdc 100644
--- a/samples/node/fleet_provisioning/csr/README.md
+++ b/samples/node/fleet_provisioning/csr/README.md
@@ -2,9 +2,7 @@
 
 [**Return to main sample list**](../../README.md)
 
-This sample uses the AWS IoT [Fleet provisioning](https://docs.aws.amazon.com/iot/latest/developerguide/provision-wo-cert.html) to provision devices using either a CSR or Keys-And-Certificate and subsequently calls RegisterThing. This allows you to create new AWS IoT Core things using a Fleet Provisioning Template.
-
-On startup, the script subscribes to topics based on the request type of either CSR or Keys topics, publishes the request to corresponding topic and calls RegisterThing.
+This sample uses the AWS IoT [Fleet provisioning](https://docs.aws.amazon.com/iot/latest/developerguide/provision-wo-cert.html) to provision devices using a certificate signing request. This allows you to create new AWS IoT Core things using a Fleet Provisioning Template.
 
 Your IoT Core Thing's [Policy](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html) must provide privileges for this sample to connect, subscribe, publish, and receive. Below is a sample policy that can be used on your IoT Core Thing that will allow this sample to run as intended.
 
@@ -18,7 +16,6 @@ Your IoT Core Thing's [Policy](https://docs.aws.amazon.com/iot/latest/developerg
       "Effect": "Allow",
       "Action": "iot:Publish",
       "Resource": [
-        "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/certificates/create/json",
         "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/certificates/create-from-csr/json",
         "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/provisioning-templates/<b>templatename</b>/provision/json"
       ]
@@ -29,8 +26,6 @@ Your IoT Core Thing's [Policy](https://docs.aws.amazon.com/iot/latest/developerg
         "iot:Receive"
       ],
       "Resource": [
-        "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/certificates/create/json/accepted",
-        "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/certificates/create/json/rejected",
         "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/certificates/create-from-csr/json/accepted",
         "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/certificates/create-from-csr/json/rejected",
         "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/provisioning-templates/<b>templatename</b>/provision/json/accepted",
@@ -43,8 +38,6 @@ Your IoT Core Thing's [Policy](https://docs.aws.amazon.com/iot/latest/developerg
         "iot:Subscribe"
       ],
       "Resource": [
-        "arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/certificates/create/json/accepted",
-        "arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/certificates/create/json/rejected",
         "arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/certificates/create-from-csr/json/accepted",
         "arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/certificates/create-from-csr/json/rejected",
         "arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/provisioning-templates/<b>templatename</b>/provision/json/accepted",
@@ -76,26 +69,9 @@ There are many different ways to run the Fleet Provisioning sample because of ho
 ``` sh
 # from the node/fleet_provisioning folder
 npm install
-node ./index.js --endpoint <endpoint> --cert <file> --key <file> --template_name <template name> --template_parameters <template parameters>
-```
-
-You can also run the sample with `--mqtt5` to run it with Mqtt5 Client
-``` sh
-# from the node/fleet_provisioning folder
-npm install
-node ./index.js --endpoint <endpoint> --cert <file> --key <file> --template_name <template name> --template_parameters <template parameters> --mqtt5
-```
-
-You can also pass a Certificate Authority file (CA) if your certificate and key combination requires it:
-
-``` sh
-# from the node/fleet_provisioning folder
-npm install
-node ./index.js --endpoint <endpoint> --cert <file> --key <file> --template_name <template name> --template_parameters <template parameters> --ca_file <file>
+node ./index.js --endpoint <endpoint> --cert <file> --key <file> --template_name <template name> --template_parameters <template parameters> --csr <path to csr file>
 ```
 
-However, this is just one way using the `CreateKeysAndCertificate` workflow. Below are a detailed list of instructions with the different ways to connect. While the detailed instructions do not show it, you can pass `--ca_file` as needed no matter which way you connect via Fleet Provisioning.
-
 ### Fleet Provisioning Detailed Instructions
 
 #### Aws Resource Setup
@@ -252,7 +228,7 @@ You can use this JSON document as the `<TemplateJSON>` in the AWS CLI command. T
 
 #### Creating a certificate-key set from a provisioning claim
 
-To run the provisioning sample, you'll need a certificate and key set with sufficient permissions. Provisioning certificates are normally created ahead of time and placed on your device, but for this sample, we will just create them on the fly. This is primarily done for example purposes.
+To run the provisioning sample, you'll need a certificate and key set with permissions to perform the provisioning operations. Provisioning certificates are normally created ahead of time and placed on your device, but for this sample, we will just create them on the fly. This is primarily done for example purposes.
 
 You can also use any certificate set you've already created if it has sufficient IoT permissions. If you wish to do this, you can skip the step that calls `create-provisioning-claim` below and move right to the next step: [Running the sample using a certificate-key set](#running-the-sample-using-a-certificate-key-set)
 
@@ -260,37 +236,23 @@ We've included a script in the utils folder that creates certificate and key fil
 `create-provisioning-claim`. These dynamically sourced certificates are **only valid for five minutes**. When running the command,
 you'll need to substitute the name of the template you previously created. If on Windows, replace the paths with something appropriate.
 
-**Note**: The following assumes you are running this command from the `aws-iot-device-sdk-java-v2` folder, which is the main GitHub folder. If you are running this from another folder (like the `samples/Identity` folder), then you will need to adjust the filepaths accordingly.
+**Note**: The following assumes you are running this command from the `aws-iot-device-sdk-js-v2` folder, which is the main GitHub folder. If you are running this from another folder then you will need to adjust the filepaths accordingly.
 
 ```sh
 aws iot create-provisioning-claim \
     --template-name <TemplateName> \
     | python3 ./utils/parse_cert_set_result.py \
-    --path ./tmp \
+    --path /tmp \
     --filename provision
 ```
 * Replace `<TemplateName>` with the name of the Fleet Provisioning template you created earlier.
 
-This will create a certificate and key in the `tmp` folder with file names starting with `provision`. You can now use these temporary keys
+This will create a certificate and key in the `/tmp` folder with file names starting with `provision`. You can now use these temporary keys
 to perform the actual provisioning in the section below.
 
-#### Running the sample using a certificate-key set
-
-To run the sample with your certificate and private key, use the following command:
-
-``` sh
-# from the node/fleet_provisioning folder
-npm install
-node ./index.js --endpoint <endpoint> --cert <file> --key <file> --template_name <template name> --template_parameters '{\"SerialNumber\":\"1\",\"DeviceLocation\":\"Seattle\"}'
-```
-
-As per normal, replace the `<>` parameters with the proper values. Notice that we provided substitution values for the two parameters in the template body, `DeviceLocation` and `SerialNumber`.
+### Create a certificate signing request and run the sample
 
-With that, the sample should run and work as expected! You should then find your have a new AWS IoT Core thing!
-
-### Run the sample using the certificate signing request workflow
-
-To run the sample with this workflow, you'll need to create a certificate signing request in addition to the other steps above (creating the role, setting its policy, setting the template JSON, etc).
+You'll need to create a certificate signing request in addition to the other steps above (creating the role, setting its policy, setting the template JSON, etc).
 
 First create a certificate-key pair:
 ``` sh
@@ -302,65 +264,11 @@ Next create a certificate signing request from it:
 openssl req -new -key /tmp/deviceCert.key -out /tmp/deviceCert.csr
 ```
 
-As in the previous workflow, you can [create a temporary certificate set from a provisioning claim](#creating-a-certificate-key-set-from-a-provisioning-claim). Again, this can be skipped if you have a policy and certificate with the proper permissions.
-
-```sh
-aws iot create-provisioning-claim \
-    --template-name <TemplateName> \
-    | python3 ./utils/parse_cert_set_result.py \
-    --path ./tmp \
-    --filename provision
-```
-* Replace `<TemplateName>` with the name of the Fleet Provisioning template you created earlier.
-
-Finally, you can also pass the certificate signing request while invoking the Fleet Provisioning sample.
+Finally, you pass the certificate signing request while invoking the Fleet Provisioning sample.
 
 ``` sh
-# from the node/fleet_provisioning folder
+# from the node/fleet_provisioning/csr folder
 npm install
-node ./index.js --endpoint <endpoint> --cert <file> --key <file> --template_name <template name> --template_parameters '{\"SerialNumber\":\"1\",\"DeviceLocation\":\"Seattle\"}' --csr <path to csr file>
+node ./dist/index.js --endpoint <endpoint> --cert <file> --key <file> --template_name <template name> --template_parameters '{"SerialNumber":"1","DeviceLocation":"Seattle"}' --csr <path to csr file>
 ```
 
-## Service Client Notes
-### Differences between MQTT5 and MQTT311
-The service client with Mqtt5 client is almost identical to Mqtt3 one. The only difference is that you would need setup up a Mqtt5 Client and pass it to the service client.
-For how to setup a Mqtt5 Client, please refer to [MQTT5 User Guide](https://github.com/awslabs/aws-crt-nodejs/blob/main/MQTT5-UserGuide.md) and [MQTT5 PubSub Sample](../pub_sub_mqtt5/README.md)
-
-<table>
-<tr>
-<th>Create a IoTIdentityClient with Mqtt5</th>
-<th>Create a IoTIdentityClient with Mqtt311</th>
-</tr>
-<tr>
-<td>
-
-```js
-  // Create a Mqtt5 Client
-  config_builder = iot.AwsIotMqtt5ClientConfigBuilder.newDirectMqttBuilderWithMtlsFromPath(argv.endpoint, argv.cert, argv.key);
-  client = new mqtt5.Mqtt5Client(config_builder.build());
-
-  // Create the identity client from Mqtt5 Client
-  identity = iotidentity.IotIdentityClient.newFromMqtt5Client(client5);
-```
-
-</td>
-<td>
-
-```js
-    // Create a Mqtt311 Connection from the command line data
-    config_builder = iot.AwsIotMqttConnectionConfigBuilder.new_mtls_builder_from_path(argv.cert, argv.key);
-    config_builder.with_client_id(argv.client_id || "test-" + Math.floor(Math.random() * 100000000));
-    config_builder.with_endpoint(argv.endpoint);
-    client = new mqtt.MqttClient();
-    connection = client.new_connection(config);
-
-    // Create the shadow client from Mqtt311 Connection
-    identity = new iotidentity.IotIdentityClient(connection);
-```
-
-</td>
-</tr>
-</table>
-
-### mqtt5.QoS v.s. mqtt.QoS
-As the service client interface is unchanged for both Mqtt3 Connection and Mqtt5 Client,the service client will use mqtt.QoS instead of mqtt5.QoS even with a Mqtt5 Client.
diff --git a/samples/node/shadow/README.md b/samples/node/shadow/README.md
index a5035151..e8e1e870 100644
--- a/samples/node/shadow/README.md
+++ b/samples/node/shadow/README.md
@@ -190,8 +190,7 @@ Update Reported response: {"state":{"reported":{"Color":"red"}},"metadata":{"rep
 Received ShadowUpdated event: {"previous":{"state":{"desired":{"Color":"red"},"reported":{"Color":"green"}},"metadata":{"desired":{"Color":{"timestamp":1719855498}},"reported":{"Color":{"timestamp":1719853620}}},"version":5},"current":{"state":{"desired":{"Color":"red"},"reported":{"Color":"red"}},"metadata":{"desired":{"Color":{"timestamp":1719855498}},"reported":{"Color":{"timestamp":1719856038}}},"version":6},"timestamp":1719856038,"clientToken":"1317558e-0f69-40d7-8bdd-d3301a1cd6f7"}
 ```
 
-Notice that no ShadowDeltaUpdated event is generated because you just synced a reported and desired property value back together.  The "device" is
-now in sync with what the control application wanted.
+Notice that no ShadowDeltaUpdated event is generated because the reported and desired states are now back in sync.  
 
 ### Multiple Properties
 Not all shadow properties represent device configuration.  To illustrate several more aspects of the Shadow service, let's add a second property to our shadow document, 
@@ -235,7 +234,7 @@ Received ShadowDeltaUpdated event: {"version":9,"timestamp":1719857563,"state":{
 ```
 
 Similar to how updates are delta-based, notice how the ShadowDeltaUpdated event only includes the "Status" property, leaving the "Color" property out because it 
-hasn't changed.
+is still in sync between desired and reported.
 
 ### Removing properties
 Properties can be removed from a shadow by setting them to null.  Removing a property completely would require its removal from both the