docs: General documentation improvements

Signed-off-by: Ahmed Ismail <Ahmed.Ismail@arm.com>

docs/applications/aws_iot/aws_iot_cloud_connection.md

@@ -39,15 +39,15 @@ of the verification fails, then MCUBoot stops the booting process.
 
 To see messages being sent by the application:
 1. Login to your account and browse to the [AWS IoT console](https://console.aws.amazon.com/iotv2/).
-1. In the left navigation panel, choose **Manage**, and then choose **Things**.
+1. In the left navigation panel, choose **Manage**, followed by **All devices**, and then choose **Things**.
 1. Select the thing you created, and open the **Activity** tab. This will show
    the application connecting and subscribing to a topic.
 1. Click on the **MQTT test client** button. This will open a new page.
 1. Click on **Subscribe to a topic**.
 1. In the **Subscription topic** field enter the topic name
-   `pubsub/<mqtt-client-identifier>/task_0`
+   `<mqtt-client-identifier>/ml/inference.`
     > `mqtt-client-identifier` value is defined in
-      `configs/aws_configs/aws_clientcredential.h` as
+      `applications/<application_name>/configs/aws_configs/aws_clientcredential.h` as
       `clientcredentialIOT_THING_NAME`.
 1. In the **MQTT payload display** combo box select `Display payloads as
    strings (more accurate)`
@@ -90,8 +90,7 @@ in the next step.
    * For simplicity, use the same region for the bucket as where your Instance
     is located.
 1. Follow the instructions at: [Create an OTA Update service role](https://docs.aws.amazon.com/freertos/latest/userguide/create-service-role.html)
-1. Follow the instructions at: [Create an OTA user policy](https://docs.aws.amazon.com/freertos/latest/userguide/create-ota-user-policy.html)
-1. Go to AWS IoT web interface and choose **Manage** and then **Jobs**
+1. Go to AWS IoT web interface and choose **Manage** followed by **Remote actions**, and then **Jobs**
 1. Click the create job button and select **Create FreeRTOS OTA update job**
 1. Give it a name and click next
 1. Select the device to update (the Thing you created in earlier steps)
@@ -109,10 +108,8 @@ in the next step.
 1. For **Path name of file on device** put in `non_secure image`
 1. As the role, select the OTA role you created in step 2.
 1. Click next
-1. Create an ID for you Job
-1. Add a description
 1. **Job type**, select
    *Your job will complete after deploying to the selected devices/groups
    (snapshot).*
-1. Click next, your update job is ready and running - next time your
-   application connects it will perform the update.
+1. Click next, now your update job is ready and running
+   * If your application is connected to AWS, the update will begin immediately. If not, next time your application connects to AWS it will perform the update.

docs/applications/aws_iot/setting_up_aws_connectivity.md

@@ -23,7 +23,6 @@ via MQTT as well as enable an over-the-air update.
 1. Login to your account and browse to the [AWS IoT console](https://console.aws.amazon.com/iotv2/).
    * If this takes you to AWS Console, click on **Services** above and then
      click on **IoT Core**.
-   * Ensure your **Region** is correct.
 1. In the left navigation pane **Manage** section, expand **All devices** then
    select **Things**.
    * These instructions assume you do not have any IoT things registered in

docs/applications/blinky.md

@@ -19,19 +19,19 @@ setup correctly before proceeding.
 
 To build the blinky example, run the following command:
 ```bash
-./tools/scripts/build.sh blinky
+./tools/scripts/build.sh blinky --target <corstone300/corstone310/corstone315> --toolchain <ARMCLANG/GNU>
 ```
 
 Run the command below to perform a clean build:
 ```bash
-./tools/scripts/build.sh blinky -c
+./tools/scripts/build.sh blinky --target <corstone300/corstone310/corstone315> --toolchain <ARMCLANG/GNU> -c
 ```
 
 ## Running the application
 
 To run the blinky example, run the following command:
 ```bash
-./tools/scripts/run.sh blinky
+./tools/scripts/run.sh blinky --target <corstone300/corstone310/corstone315>
 ```
 
 ### Expected output

docs/applications/keyword_detection.md

@@ -47,7 +47,7 @@ Follow the instructions described in [Setting Up AWS Connectivity](./aws_iot/set
 To build the Keyword-Detection example, run the following command:
 
 ```bash
-./tools/scripts/build.sh keyword-detection --certificate_path <certificate pem's path> --private_key_path <private key pem's path> --target <corstone300/corstone310> --inference <ETHOS/SOFTWARE> --audio <ROM/VSI>
+./tools/scripts/build.sh keyword-detection --certificate_path <certificate pem's path> --private_key_path <private key pem's path> --target <corstone300/corstone310/corstone315> --inference <ETHOS/SOFTWARE> --audio <ROM/VSI> --toolchain <ARMCLANG/GNU>
 ```
 * The `certificate pem's path` and `private key pem's path` should be the downloaded key's and certificate's path if you chose the **Auto-generate a new certificate** during the Thing creation. If you chose **Skip creating a certificate at this time** then these paths should locate the generated credential files that were created by the `./tools/scripts/generate_credentials.py` script in the previous step.
 
@@ -58,7 +58,7 @@ To build the Keyword-Detection example, run the following command:
 Or, run the command below to perform a clean build:
 
 ```bash
-./tools/scripts/build.sh keyword-detection --certificate_path <certificate pem's path> --private_key_path <private key pem's path> --target <corstone300/corstone310> --inference <ETHOS/SOFTWARE> --audio <ROM/VSI> -c
+./tools/scripts/build.sh keyword-detection --certificate_path <certificate pem's path> --private_key_path <private key pem's path> --target <corstone300/corstone310/corstone315> --inference <ETHOS/SOFTWARE> --audio <ROM/VSI> --toolchain <ARMCLANG/GNU> -c
 ```
 
 ## Provisioning the device credentials into Protected Storage
@@ -68,12 +68,16 @@ Check [Device Provisioning](./device_provisioning/device_provisioning.md) for de
 ## Running the application
 
 ### Note:
-If you would like to run the keyword detection application using VSI configuration as the input audio source, you must run the [setup_python_vsi.sh](../../tools/scripts/setup_python_vsi.sh) script to setup the needed Python environment for VSI prior to running the application.
+If you would like to run the keyword detection application using VSI configuration as the input audio source, you must run the [setup_python_vsi.sh](../../tools/scripts/setup_python_vsi.sh) script to setup the needed Python environment for VSI prior to running the application:
+
+```bash
+./tools/scripts/setup_python_vsi.sh
+```
 
 To run the Keyword-Detection example, run the following command:
 
 ```bash
-./tools/scripts/run.sh keyword-detection --target <corstone300/corstone310> --audio <ROM/VSI>
+./tools/scripts/run.sh keyword-detection --target <corstone300/corstone310/corstone315> --audio <ROM/VSI>
 ```
 
 ### Expected output
@@ -131,16 +135,11 @@ Creating an empty PS flash layout.
 30 8376 [OTA Task ] [INFO]  Received: 0   Queued: 0   Processed: 0   Dropped: 0
 31 8388 [OTA Agent Task] [WARN] Index: 0. OTA event id: 0
 32 8397 [OTA Agent Task] [WARN] Index: 1. OTA event id: 2
-33 8446 [MQTT PUB SUB] [INFO] Subscribed to topic pubsub/<mqtt-client-identifier>/task_0.
-34 8464 [MQTT PUB SUB] [INFO] Successfully subscribed to topic: pubsub/<mqtt-client-identifier>/task_0
 35 9279 [OTA Agent Task] [INFO] Subscribed to topic $aws/things/<mqtt-client-identifier>/jobs/notify-next.
 36 9300 [OTA Agent Task] [INFO] Subscribed to MQTT topic: $aws/things/<mqtt-client-identifier>/jobs/notify-next
-37 10029 [MQTT Agent Task] [INFO] Publishing message to pubsub/<mqtt-client-identifier>/task_0.
-38 10084 [MQTT PUB SUB] [INFO] Sent PUBLISH packet to broker pubsub/<mqtt-client-identifier>/task_0 to broker.
 39 10105 [MQTT Agent Task] [INFO] De-serialized incoming PUBLISH packet: DeserializerResult=MQTTSuccess.
 40 10119 [MQTT Agent Task] [INFO] State record updated. New state=MQTTPublishDone.
 41 10131 [MQTT Agent Task] [INFO] Received incoming publish message Task 0 publishing message 0
-42 10145 [MQTT PUB SUB] [INFO] Successfully sent QoS 0 publish to topic: pubsub/<mqtt-client-identifier>/task_0 (PassCount:1, FailCount:0).
 43 10894 [MQTT Agent Task] [INFO] Publishing message to $aws/things/<mqtt-client-identifier>/jobs/$next/get.
 44 10986 [MQTT Agent Task] [INFO] Ack packet deserialized with result: MQTTSuccess.
 45 10998 [MQTT Agent Task] [INFO] State record updated. New state=MQTTPublishDone.

docs/applications/speech_recognition.md

@@ -27,7 +27,7 @@ Follow the instructions described in [Setting Up AWS Connectivity](./aws_iot/set
 To build the Speech-Recognition example, run the following command:
 
 ```bash
-./tools/scripts/build.sh speech-recognition --certificate_path <certificate pem's path> --private_key_path <private key pem's path> --target <corstone300/corstone310> --inference <ETHOS/SOFTWARE> --audio <ROM/VSI>
+./tools/scripts/build.sh speech-recognition --certificate_path <certificate pem's path> --private_key_path <private key pem's path> --target <corstone300/corstone310/corstone315> --inference ETHOS --audio <ROM/VSI> --toolchain <ARMCLANG/GNU>
 ```
 * The `certificate pem's path` and `private key pem's path` should be the downloaded key's and certificate's path if you chose the **Auto-generate a new certificate** during the Thing creation. If you chose **Skip creating a certificate at this time** then these paths should locate the generated credential files that were created by the `./tools/scripts/generate_credentials.py` script in the previous step.
 
@@ -36,7 +36,7 @@ To build the Speech-Recognition example, run the following command:
 Or, run the command below to perform a clean build:
 
 ```bash
-./tools/scripts/build.sh speech-recognition --certificate_path <certificate pem's path> --private_key_path <private key pem's path> --target <corstone300/corstone310> --inference <ETHOS/SOFTWARE> --audio <ROM/VSI> -c
+./tools/scripts/build.sh speech-recognition --certificate_path <certificate pem's path> --private_key_path <private key pem's path> --target <corstone300/corstone310/corstone315> --inference ETHOS --audio <ROM/VSI> --toolchain <ARMCLANG/GNU> -c
 ```
 
 ## Provisioning the device credentials into Protected Storage
@@ -46,12 +46,16 @@ Check [Device Provisioning](./device_provisioning/device_provisioning.md) for de
 ## Running the application
 
 ### Note:
-If you would like to run the speech recognition application using VSI configuration as the input audio source, you must run the [setup_python_vsi.sh](../../tools/scripts/setup_python_vsi.sh) script to setup the needed Python environment for VSI prior to running the application.
+If you would like to run the speech recognition application using VSI configuration as the input audio source, you must run the [setup_python_vsi.sh](../../tools/scripts/setup_python_vsi.sh) script to setup the needed Python environment for VSI prior to running the application:
+
+```bash
+./tools/scripts/setup_python_vsi.sh
+```
 
 To run the Speech-Recognition example, run the following command:
 
 ```bash
-./tools/scripts/run.sh speech-recognition --target <corstone300/corstone310> --audio <ROM/VSI>
+./tools/scripts/run.sh speech-recognition --target <corstone300/corstone310/corstone315> --audio <ROM/VSI>
 ```
 
 ### Expected output
@@ -110,16 +114,11 @@ Creating an empty PS flash layout.
 31 9281 [OTA Task ] [INFO]  Received: 0   Queued: 0   Processed: 0   Dropped: 0
 32 9292 [OTA Agent Task] [WARN] Index: 0. OTA event id: 0
 33 9300 [OTA Agent Task] [WARN] Index: 1. OTA event id: 2
-34 9663 [MQTT PUB SUB] [INFO] Subscribed to topic pubsub/<mqtt-client-identifier>/task_0.
-35 9680 [MQTT PUB SUB] [INFO] Successfully subscribed to topic: pubsub/<mqtt-client-identifier>/task_0
 36 10857 [OTA Agent Task] [INFO] Subscribed to topic $aws/things/<mqtt-client-identifier>/jobs/notify-next.
 37 10876 [OTA Agent Task] [INFO] Subscribed to MQTT topic: $aws/things/<mqtt-client-identifier>/jobs/notify-next
-38 11607 [MQTT Agent Task] [INFO] Publishing message to pubsub/<mqtt-client-identifier>/task_0.
-39 11824 [MQTT PUB SUB] [INFO] Sent PUBLISH packet to broker pubsub/<mqtt-client-identifier>/task_0 to broker.
 40 11844 [MQTT Agent Task] [INFO] De-serialized incoming PUBLISH packet: DeserializerResult=MQTTSuccess.
 41 11859 [MQTT Agent Task] [INFO] State record updated. New state=MQTTPublishDone.
 42 11870 [MQTT Agent Task] [INFO] Received incoming publish message Task 0 publishing message 0
-43 11884 [MQTT PUB SUB] [INFO] Successfully sent QoS 0 publish to topic: pubsub/<mqtt-client-identifier>/task_0 (PassCount:1, FailCount:0).
 44 12634 [MQTT Agent Task] [INFO] Publishing message to $aws/things/<mqtt-client-identifier>/jobs/$next/get.
 45 13021 [MQTT Agent Task] [INFO] Ack packet deserialized with result: MQTTSuccess.
 46 13032 [MQTT Agent Task] [INFO] State record updated. New state=MQTTPublishDone.
@@ -276,9 +275,7 @@ Creating an empty PS flash layout.
 ...
 
 8740 1522485 [MQTT Agent Task] [INFO] Received incoming publish message Task 0 publishing message 255
-8741 1522499 [MQTT PUB SUB] [INFO] Sent PUBLISH packet to broker pubsub/<mqtt-client-identifier>/task_0 to broker.
 8742 1522520 [OTA Agent Task] [WARN] Index: 9. OTA event id: 6
-8743 1522529 [MQTT PUB SUB] [INFO] Successfully sent QoS 0 publish to topic: pubsub/<mqtt-client-identifier>/task_0 (PassCount:256, FailCount:0).
 8744 1522554 [OTA Agent Task] [INFO] Received final block of the update.
 8745 1524214 [OTA Agent Task] [INFO] Received entire update and validated the signature.
 

docs/development_environment/linux_dev_env.md

@@ -76,7 +76,11 @@ Follow the intructions in the [document](./pre_commit_and_towncrier_setup.md)
 to setup pre-commit hooks and towncrier.
 
 Run the [setup_python_vsi.sh](../../tools/scripts/setup_python_vsi.sh) script
-to setup the needed Python environment for VSI to work.
+to setup the needed Python environment for VSI to work:
+
+```bash
+./tools/scripts/setup_python_vsi.sh
+```
 
 ## Cloning the Repository
 

docs/development_environment/vscode_dev_env_build_and_debug.md

@@ -87,7 +87,11 @@ Follow the intructions in the [document](./pre_commit_and_towncrier_setup.md)
 to setup pre-commit hooks and towncrier.
 
 Run the [setup_python_vsi.sh](../../tools/scripts/setup_python_vsi.sh) script
-to setup the needed python environment for VSI to work.
+to setup the needed python environment for VSI to work:
+
+```bash
+./tools/scripts/setup_python_vsi.sh
+```
 
 ## Building a reference application