/**
@page building Building and Running Demos
@brief Instructions for building and running demos.

<p>
The libraries in this SDK are not dependent on any operating systems.
However, the demos for the libraries in this SDK are built and tested on a
Linux platform. This SDK builds with [CMake](https://cmake.org/), a cross-platform build tool.
</p>

@section build_prerequisites Prerequisites
@brief Prerequisites needed to run the demos.

@pre
- CMake 3.2.0 or later and a C90 compiler.

@pre
- A supported operating system. The ports provided with this repo are expected to work with all recent versions of the following operating systems, although we cannot guarantee the behavior on all systems.
    - Linux system with POSIX sockets and timer APIs. (CI tests on Ubuntu 18.04).<br>
        - On Linux systems, installation of OpenSSL development libraries and header files, <i>version 1.1.0</i> or later, are required. The OpenSSL development libraries are usually called something like `libssl-dev` or `openssl-devel` when installed through a package manager.
        - Although not a part of the C90 standard, stdint.h is required for fixed-width integer types (e.g int32_t).

@section aws_iot_setup AWS IoT Account Setup
@brief Setting up AWS IoT to run demos.

You need to setup an AWS account and access the AWS IoT console for running the AWS IoT Device Shadow library, AWS IoT Device Defender library, AWS IoT Jobs library,
AWS IoT OTA library and coreHTTP S3 download demos.
Also, the AWS account can be used for running the MQTT mutual auth demo against AWS IoT broker.
Note that running the AWS IoT Device Defender, AWS IoT Jobs and AWS IoT Device Shadow library demos require the setup of a Thing resource for the device running the demo.
-  [Setup an AWS account](https://portal.aws.amazon.com/billing/signup#/start).
-  [Sign-in to the AWS IoT Console](https://console.aws.amazon.com/iot/home) after setting up the AWS account.
-  [Create a Thing resource](https://docs.aws.amazon.com/iot/latest/developerguide/iot-moisture-create-thing.html).

@section configuring_mutual_auth_demo Configuring the Mutual Auth Demo
@brief Passing configuration settings to run the mutual auth demo.

- You can pass the following configuration settings as command line options in order to run the mutual auth demos:
@code{sh}
cmake .. -DAWS_IOT_ENDPOINT="aws-iot-endpoint" -DROOT_CA_CERT_PATH="root-ca-path" -DCLIENT_CERT_PATH="certificate-path" -DCLIENT_PRIVATE_KEY_PATH="private-key-path"
@endcode

- In order to set these configurations manually, edit `demo_config.h` in `demos/mqtt/mqtt_demo_mutual_auth/` to `#define` the following:

	- Set `AWS_IOT_ENDPOINT` to your custom endpoint. This is found on the *Settings* page of the AWS IoT Console and has a format of `ABCDEFG1234567.iot.us-east-2.amazonaws.com`.

	- Set `ROOT_CA_CERT_PATH` to the path of the root CA certificate downloaded when setting up the device certificate in [AWS IoT Account Setup](https://github.com/aws/aws-iot-device-sdk-embedded-C/tree/main#aws-iot-account-setup).

	- Set `CLIENT_CERT_PATH` to the path of the client certificate downloaded when setting up the device certificate in [AWS IoT Account Setup](https://github.com/aws/aws-iot-device-sdk-embedded-C/tree/main#aws-iot-account-setup).

	- Set `CLIENT_PRIVATE_KEY_PATH` to the path of the private key downloaded when setting up the device certificate in [AWS IoT Account Setup](https://github.com/aws/aws-iot-device-sdk-embedded-C/tree/main#aws-iot-account-setup).

@section configuring_s3_demos Configuring the HTTP S3 Demos
@brief Generating pre-signed URLs and passing configuration settings to run the S3 upload, download, and multi-threaded download demos.

The S3 upload, download, and multi-threaded download demos require user-generated pre-signed URLs to be configured. A python script `presigned_url_gen.py` (located in `demos/http/common/src/`) is provided to easily generate pre-signed PUT and GET URLs.

## Using the Pre-signed URL Generator

### Dependencies
	- Python 3+
	- boto3
	- argparse

### Pre-requisites
<ol>
<li>Install the dependencies.</li>
@code{sh}
pip install boto3 argparse
@endcode

<li>You will need an AWS Account with S3 access before beginning. You must install and configure the AWS CLI in order to use this script.</li>
@code{sh}
aws configure
@endcode
	- For information on AWS S3, please see: https://docs.aws.amazon.com/AmazonS3/latest/dev/Welcome.html
	- For AWS CLI installation information, please see: https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html
	- For AWS CLI configuration information, please see: https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html
</ol>

### Usage
<ol>
<li>Run presigned_url_gen.py with your S3 **bucket-name**, S3 **object-key**, and optionally, your S3 bucket's **region-name** (if not specified, the region configured in AWS CLI will be used).</li>
@code{sh}
python presigned_urls_gen.py --bucket <YOUR BUCKET NAME> --key <YOUR OBJECT KEY> --region <YOUR BUCKET'S REGION NAME>
@endcode

An example expected output:
@code{sh}
#define S3_PRESIGNED_GET_URL    "https://aws-s3-endpoint/object-key.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ABABABABABABABABABAB%2F20201027%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20201027T194726Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=SomeHash12345UrlABcdEFgfIjK"

#define S3_PRESIGNED_PUT_URL    "https://aws-s3-endpoint/object-key.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ABABABABABABABABABAB%2F20201027%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20201027T194726Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=SomeHash12345UrlLMnmOPqrStUvW"
@endcode

<li>Copy and paste the output into **demo_config.h** for macro **S3_PRESIGNED_GET_URL** and **S3_PRESIGNED_PUT_URL**.</li>
@code{c}
#define S3_PRESIGNED_GET_URL    "https://aws-s3-endpoint/object-key.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ABABABABABABABABABAB%2F20201027%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20201027T194726Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=SomeHash12345UrlABcdEFgfIjK"

#define S3_PRESIGNED_PUT_URL    "https://aws-s3-endpoint/object-key.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ABABABABABABABABABAB%2F20201027%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20201027T194726Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=SomeHash12345UrlLMnmOPqrStUvW"
@endcode

You may also pass any or all of the following configuration settings as command line options in order to run the demos:
@code{sh}
cmake .. -DS3_PRESIGNED_GET_URL="your-get-url" -DS3_PRESIGNED_PUT_URL="your-put-url"
@endcode

Note: A pre-signed GET URL is required for all HTTP S3 demos. For upload demos, in addition to the GET URL, a pre-signed PUT URL is also required.
</ol>

### Parameter Info
	- `--bucket` : The name of the target S3 bucket used in the demos.
	- `--key` : The name of the existing object you wish to download (GET), or the name of the object you wish to upload (PUT).
	- `--region` : The name of the region in which your S3 bucket was created. If this is not passed in, the region configured in AWS CLI (or us-east-1, if not configured) will be used.


@section configuring_ota_demos Configuring the Over-the-air Update Demos
@brief Configurations and Prerequisites for the OTA Demo

## Requirements for OTA demo

### Prerequisites
<ol>
	<li> To perform a successful OTA update you would need to complete the prerequisites mentioned here: https://docs.aws.amazon.com/freertos/latest/userguide/ota-prereqs.html </li>
	<li> A code signing certificate is required to authenticate the update. A code signing certificate based on the SHA-256 ECDSA algorithm will work with the current demos. An example of how to generate this kind of certificate can be found here: https://docs.aws.amazon.com/freertos/latest/userguide/ota-code-sign-cert-esp.html </li>
</ol>

### Configuration
You will need to specify the following parameters in the file demo_config.h (located in `demos/ota/ota_demo_[mqtt/http]/`)

<ol>
<li> AWS_IOT_ENDPOINT: This is the endpoint for your account. The endpoint should be for the region that your thing was created in. This can be found by going to the AWS IoT Core console, pressing the “Settings” tab on the left hand side of the page. It is under the section labeled “Custom endpoint”. </li>
<li> CLIENT_CERT_PATH: This is the client certificate that was downloaded when you created your thing. The path specified needs to be either an absolute path, or a path that is relative to the “cloned-repo-root-dir/build/bin" directory where the demo will be ran from.</li>
<li> CLIENT_PRIVATE_KEY_PATH: This is the client private key that was downloaded when you created your thing. The path specified needs to be either an absolute path, or a path that is relative to the “cloned-repo-root-dir/build/bin" directory where the demo will be ran from.</li>
<li> CLIENT_IDENTIFIER: This is the name of the thing you created during the OTA Prerequisites section.</li>
</ol>

An example expected output:
@code{sh}
#define AWS_IOT_ENDPOINT           "endpoint##-ats.iot.us-west-2.amazonaws.com"
#define CLIENT_CERT_PATH           "/home/ubuntu/certificates/thing#-certificate.pem.crt"
#define CLIENT_PRIVATE_KEY_PATH    "/home/ubuntu/certificates/thing#-private.pem.key"
#define CLIENT_IDENTIFIER          "testclient"
@endcode

### Scheduling an OTA Update Job
After you build and run the initial executable you will have to create another executable and schedule an OTA update job with this image.
<ol>
	<li> Increase the version of the application by setting macro `APP_VERSION_BUILD` in demos/ota_demo_core_[mqtt/http]/demo_config.h to a different version than what is running.</li>
	<li> Rebuild the application using @ref building_demo_commmandline from below into a different directory, say build-dir-2</li>
	<li> Rename the demo executable to reflect the change, e.g. `mv ota_demo_core_mqtt ota_demo_core_mqtt2`</li>
	<li> Create an OTA job:
		<ol>
		<li> Go to the AWS IoT Core console console.aws.amazon.com/iot/ (https://console.aws.amazon.com/iot/)</li>
		<li> Manage → Jobs → Create → Create a FreeRTOS OTA update job → Select `testclient` from the thing list</li>
		<li> Sign a new firmware → Create a new profile → Select any SHA-ECDSA signing platform → Upload the code signing certificate(from prerequisites) and provide its path on the device.</li>
		<li> Select the image → Select the bucket you created in prerequisites → Upload the binary build-dir-2/bin/ota_demo2</li>
		<li> The path on device should be the complete path to place the executable and the binary name: eg /home/ubuntu/aws-iot-device-sdk-embedded-C-staging/build-dir/bin/ota_demo_core_mqtt2</li>
		<li> Select the IAM role created in prerequisites</li>
		<li> Create the Job
		</ol>
	</li>
	<li>Run the initial executable again with the following command: `sudo ./ota_demo_core_mqtt or sudo ./ota_demo_core_http`</li>
</ol>

@section building_demo_commmandline Build Steps
@brief How to build the demo applications on the command-line.

- While in the root directory of AWS IoT Device SDK C, create a build directory, then change to that build directory.
@code{sh}
mkdir build && cd build
@endcode

- Run cmake while inside build directory.
@code{sh}
cmake ..
@endcode

- Run this command to build the demos.
@code{sh}
make
@endcode

<p>All demo executables can now be found in the `build/bin` directory and
should be run while inside that directory.</p>

@subsection docker_containers_for_demos Installing Docker Containers for Demos
@brief Alternative option of using Docker containers for running demos locally.

Install Docker:

@code{sh}
curl -fsSL https://get.docker.com -o get-docker.sh

sh get-docker.sh
@endcode

#### Installing Mosquitto Broker to run MQTT demos locally

The following instructions have been tested on an Ubuntu 18.04 environment with Docker and OpenSSL installed.
<ol>
<li>Download the official Docker image for Mosquitto 1.6.14. This version is deliberately chosen so that the Docker container can load certificates from the host system.
Any version after 1.6.14 will drop privileges as soon as the configuration file has been read (before TLS certificates are loaded).</li>

@code{sh}
docker pull eclipse-mosquitto:1.6.14
@endcode

<li>`BROKER_ENDPOINT` defined in `demos/mqtt/mqtt_demo_basic_tls/demo_config.h` can now be set to `localhost`.</li>

<li>For TLS communication with Mosquitto broker, server and CA credentials need to be created. Use OpenSSL commands to generate the credentials for the Mosquitto server.</li>

- Generate CA key and certificate. Provide the Subject field information as appropriate.
@code{sh}
openssl req -x509 -nodes -sha256 -days 365 -newkey rsa:2048 -keyout ca.key -out ca.crt
@endcode

- Generate server key and certificate and sign with the CA cert.
@code{sh}

openssl req -nodes -sha256 -new -keyout server.key -out server.csr

openssl x509 -req -sha256 -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 365
@endcode

<li>Create a mosquitto.conf file to use port 8883 (for TLS communication) and providing path to the generated credentials.</li>

@code
port 8883

cafile /mosquitto/config/ca.crt
certfile /mosquitto/config/server.crt
keyfile /mosquitto/config/server.key

# Use this option for TLS mutual authentication (where client will provide CA signed certificate)
#require_certificate true
tls_version tlsv1.2
#use_identity_as_username true

@endcode

<li>Run the docker container from the local directory containing the generated credential and mosquitto.conf files.</li>

@code{sh}
docker run -it -p 8883:8883 -v $(pwd):/mosquitto/config/ --name mosquitto-basic-tls eclipse-mosquitto:1.6.14
@endcode

<li>Set `ROOT_CA_CERT_PATH` to the absolute path of the CA certificate created in step 3. for the local Mosquitto server.</li>
</ol>

*/