Periodic update - 05/29/2020 2:00PM PDT

Author: robhath

doc_source/portingguide/afr-echo-server.md

@@ -1,7 +1,128 @@
-# Setting Up an Echo Server<a name="afr-echo-server"></a>
+# Setting up an echo server<a name="afr-echo-server"></a>
 
-Two simple echo servers, written in Go, are provided with FreeRTOS\. One server uses TLS for secure communication, and the other is unsecured\. The servers are located in the `<freertos>/tools/echo_server` folder\. The following topics walk you through setting up the echo servers\.
+The `freertos/tools/echo_server/` directory has the source code for a Go\-based echo server that you can use to test TCP on FreeRTOS\. You can find the TCP tests in the `freertos/libraries/abstractions/secure_sockets/test/iot_test_tcp.c` file\. Follow the instructions in this section to set up and run the echo server\. 
 
-**Topics**
-+ [Setting Up the TLS Echo Server](tls-echo-server.md)
-+ [Setting Up the Echo Server \(Without TLS\)](notls-echo-server.md)
+## Prerequisites<a name="afr-echo-server-prerequisites"></a>
+
+To run the TLS echo server, you must install the following:
++ Go – You can download the latest version from [ golang\.org](https://golang.org/dl/)\.
++ OpenSSL – For a Linux source code download, see [OpenSSL\.org](https://www.openssl.org/source/)\. You can also use a package manager to install OpenSSL for Linux and macOS\.
+
+## Create credentials<a name="afr-echo-server-credentials"></a>
+
+After you finish the prerequisites, you must enter the following commands to create your credentials\.
+
+**Server**  
+The following `openssl` command generates a self\-signed server certificate\.  
+
+```
+openssl req -newkey rsa:2048 -nodes -x509 -sha256 -out certs/server.pem -keyout certs/server.key -days 365 -subj "/C=US/ST=WA/L=Place/O=YourCompany/OU=IT/CN=www.your-company-website.com/[email protected]"
+```
+
+**Client**  
+The following `openssl` commands generate a client certificate\.  
+
+```
+openssl genrsa -out certs/client.key 2048
+```
+
+```
+openssl req -new -key certs/client.key -out certs/client.csr -subj "/C=US/ST=WA/L=Place/O=YourCompany/OU=IT/CN=www.your-company-website.com/[email protected]"
+```
+
+```
+openssl x509 -req -in certs/client.csr -CA certs/server.pem -CAkey certs/server.key -CAcreateserial -out certs/client.pem -days 365 -sha256
+```
+
+## Directory structure<a name="afr-echo-server-folder-struct"></a>
+
+By default, certificates and keys are stored in a directory named `certs` that is located on a relative path specified in the configuration file, `config.json`\. If you want to move your credentials to a different directory, you can update this directory location in the configuration file\.
+
+You can find the source code for the echo server in the `echo_server.go` file\.
+
+## Server configuration<a name="afr-echo-server-config"></a>
+
+The echo server reads a JSON based configuration file\. The default location for this JSON file is `./config.json`\. To override this, specify the location of the JSON with the `-config` flag\.
+
+The JSON file contains the following options:
+
+**server\-port**  
+Specify the port on which to open a socket\.
+
+**server\-certificate\-location**  
+The relative or absolute path to the server certificate generated in [Create credentials](#afr-echo-server-credentials)\.
+
+**secure\-connection**  
+Enable this option to have the echo server use TLS\. You must first [Create credentials](#afr-echo-server-credentials)\.
+
+**logging**  
+Enable this option to output all log messages received to a file\.
+
+**verbose**  
+Enable this option to output the contents of the message sent to the echo server\.
+
+**server\-key\-location**  
+The relative or absolute path to the server key generated in [Create credentials](#afr-echo-server-credentials)\.
+
+**Example configuration**
+
+```
+{
+    "verbose": false,
+    "logging": false,
+    "secure-connection": false,
+    "server-port": "9000",
+    "server-certificate-location": "./certs/server.pem",
+    "server-key-location": "./certs/server.pem"
+}
+```
+
+## Run the echo server from the command line<a name="afr-echo-server-run"></a>
+
+Enter the following commands to run the echo server\.
+
+```
+go run echo_server.go
+```
+
+Enter the following command to run with a custom config location\.
+
+```
+go run echo_server.go -config=config_file_path
+```
+
+If you want to run the unsecure and secure TCP tests at the same time, you must start both a secure and an unsecure echo server\. To do this, create a second, secure configuration file, and pass its location to the second instance of the echo server using the `-config` flag\. Remember to also specify a different TCP port in the second configuration file\.
+
+## Client device configuration<a name="afr-echo-server-device-config"></a>
+
+Before you run the TCP tests on your device, we recommend that you read [Getting Started with FreeRTOS](https://docs.aws.amazon.com/freertos/latest/userguide/freertos-getting-started.html) in the *FreeRTOS User Guide*\.
+
+After you complete the steps in [Create credentials](#afr-echo-server-credentials), you should have the following files:
++ `certs/server.pem`
++ `certs/server.key`
++ `certs/client.pem`
++ `certs/client.key`
++ `certs/client.csr`
++ `certs/server.srl`
+
+Make the following changes to these files:
+
+ `freertos/tests/include/aws_clientcredential.h`   
++ Define the broker endpoint\.
++ Define the thing name\.
++ Define access to Wi\-Fi \(if not on Ethernet\)\.
+
+ `freertos/tests/include/aws_clientcredential_keys.h`   
++ Set `keyCLIENT_CERTIFICATE_PEM` to the contents of `certs/client.pem`\.
++ Leave `keyJITR_DEVICE_CERTIFICATE_AUTHORITY_PEM` as `NULL`\.
++ Set `keyCLIENT_PRIVATE_KEY_PEM` to the contents of `certs/client.key`\.
++ For more information, see [ Configuring the FreeRTOS demos](https://docs.aws.amazon.com/freertos/latest/userguide/freertos-configure.html)\.
+
+ `freertos/tests/include/aws_test_tcp.h`   
++ Set `tcptestECHO_HOST_ROOT_CA` to the contents of `certs/server.pem`\.
++ Set the IP address and the port of the echo server:
+  + `tcptestECHO_SERVER_ADDR[0-3]`
+  + `tcptestECHO_PORT`
++ Set the IP address and the port of the secure echo server:
+  + `tcptestECHO_SERVER_TLS_ADDR0[0-3]`
+  + `tcptestECHO_PORT_TLS`

doc_source/portingguide/afr-porting-ble.md

@@ -1,4 +1,4 @@
-# Porting the Bluetooth Low Energy Library<a name="afr-porting-ble"></a>
+# Porting the Bluetooth Low Energy library<a name="afr-porting-ble"></a>
 
 You can use the FreeRTOS Bluetooth Low Energy library to provision Wi\-Fi and send MQTT messages over Bluetooth Low Energy\. The Bluetooth Low Energy library also includes higher\-level APIs that you can use to communicate directly with the Bluetooth Low Energy stack\. For more information, see [FreeRTOS Bluetooth Low Energy Library](https://docs.aws.amazon.com/freertos/latest/userguide/freertos-ble-library.html) in the FreeRTOS User Guide\.
 
@@ -13,12 +13,12 @@ To port the Bluetooth Low Energy library, you need the following:
   For information about setting up a test project, see [Setting Up Your FreeRTOS Source Code for Porting](porting-set-up-project.md)\.
 + A validated configuration of the FreeRTOS kernel\.
 
-  For information about configuring the FreeRTOS kernel for your platform, see [Configuring a FreeRTOS Kernel Port](afr-porting-kernel.md)\.
+  For information about configuring the FreeRTOS kernel for your platform, see [Configuring a FreeRTOS kernel port](afr-porting-kernel.md)\.
 + A [Raspberry Pi 3 Model B\+](https://www.raspberrypi.org/products/raspberry-pi-3-model-b-plus/), with a memory card\.
 
 ## Porting<a name="porting-steps-ble"></a>
 
-Three files in the `<freertos>/libraries/abstractions/ble_hal/include` folder define the FreeRTOS Bluetooth Low Energy APIs:
+Three files in the `freertos/libraries/abstractions/ble_hal/include` folder define the FreeRTOS Bluetooth Low Energy APIs:
 + `bt_hal_manager.h`
 + `bt_hal_manager_adapter_ble.h`
 + `bt_hal_gatt_server.h`
@@ -104,7 +104,7 @@ The Bluetooth Low Energy porting and qualification tests target the low\-level w
 
 If you are using an IDE to build test projects, you need to set up your library port in the IDE project\.
 
-### Setting Up the IDE Test Project<a name="testing-ide-ble"></a>
+### Setting up the IDE test project<a name="testing-ide-ble"></a>
 
 If you are using an IDE for porting and testing, you need to add some source files to the IDE test project before you can test your ported code\.
 
@@ -113,23 +113,23 @@ In the following steps, make sure that you add the source files to your IDE proj
 
 **To set up the Bluetooth Low Energy library in the IDE project**
 
-1. Add all of the files in `<freertos>/vendors/<vendor>/boards/<board>/ports/ble` to your `aws_tests` IDE project\.
+1. Add all of the files in `freertos/vendors/vendor/boards/board/ports/ble` to your `aws_tests` IDE project\.
 
-1. Add all of the files in `<freertos>/libraries/abstractions/ble_hal/include` to your `aws_tests` IDE project\.
+1. Add all of the files in `freertos/libraries/abstractions/ble_hal/include` to your `aws_tests` IDE project\.
 
-1. Add all of the files in `<freertos>/libraries/c_sdk/standard/ble` to your `aws_tests` IDE project\.
+1. Add all of the files in `freertos/libraries/c_sdk/standard/ble` to your `aws_tests` IDE project\.
 
-1. Open `<freertos>/vendors/<vendor>/boards/<board>/aws_tests/application_code/main.c`, and enable the required Bluetooth Low Energy drivers\.
+1. Open `freertos/vendors/vendor/boards/board/aws_tests/application_code/main.c`, and enable the required Bluetooth Low Energy drivers\.
 
-### Configuring the `CMakeLists.txt` File<a name="testing-cmake-ble"></a>
+### Configuring the `CMakeLists.txt` file<a name="testing-cmake-ble"></a>
 
 If you are using CMake to build your test project, you need to define a portable layer target for the library in your CMake list file\.
 
-To define a library's portable layer target in `CMakeLists.txt`, follow the instructions in [FreeRTOS Portable Layers](cmake-template.md#cmake-portable)\.
+To define a library's portable layer target in `CMakeLists.txt`, follow the instructions in [FreeRTOS portable layers](cmake-template.md#cmake-portable)\.
 
-The `CMakeLists.txt` template list file under `<freertos>/vendors/<vendor>/boards/<board>/CMakeLists.txt` includes example portable layer target definitions\. You can uncomment the definition for the library that you are porting, and modify it to fit your platform\.
+The `CMakeLists.txt` template list file under `freertos/vendors/vendor/boards/board/CMakeLists.txt` includes example portable layer target definitions\. You can uncomment the definition for the library that you are porting, and modify it to fit your platform\.
 
-### Setting Up Your Local Testing Environment<a name="testing-local-ble"></a>
+### Setting up your local testing environment<a name="testing-local-ble"></a>
 
 **To set up the Raspberry Pi for testing**
 
@@ -141,7 +141,7 @@ The `CMakeLists.txt` template list file under `<freertos>/vendors/<vendor>/board
 
 1. Enable SSH on the Raspberry Pi\. For instructions, see the [Raspberry Pi documentation](https://www.raspberrypi.org/documentation/remote-access/ssh/)\.
 
-1. On your computer, open the `<freertos>/tests/bleTestsScripts/runPI.sh` script, and change the IP addresses in the first two lines to the IP address of your Raspberry Pi:
+1. On your computer, open the `freertos/tests/bleTestsScripts/runPI.sh` script, and change the IP addresses in the first two lines to the IP address of your Raspberry Pi:
 
    ```
    #!/bin/sh
@@ -155,7 +155,7 @@ The `CMakeLists.txt` template list file under `<freertos>/vendors/<vendor>/board
    ENDSSH
    ```
 
-### Running the Tests<a name="testing-run-ble"></a>
+### Running the tests<a name="testing-run-ble"></a>
 
 **To execute the Bluetooth Low Energy tests**
 

doc_source/portingguide/afr-porting-config.md

@@ -16,11 +16,11 @@ To implement the `configPRINT_STRING()` macro, you need the following:
 
 1. Connect your device to a terminal emulator to output test results\.
 
-1. Open the file `<freertos>/vendors/<vendor>/boards/<board>/aws_tests/application_code/main.c`, and locate the call to `configPRINT_STRING("Test Message")` in the `prvMiscInitialization()` function\.
+1. Open the file `freertos/vendors/vendor/boards/board/aws_tests/application_code/main.c`, and locate the call to `configPRINT_STRING("Test Message")` in the `prvMiscInitialization()` function\.
 
 1. Immediately before the call to `configPRINT_STRING("Test Message")`, add code that uses the vendor\-supplied UART driver to initialize the UART baud rate level to 115200\.
 
-1. Open `<freertos>/vendors/<vendor>/boards/<board>/aws_tests/config_files/FreeRTOSConfig.h`, and locate the empty definition of `configPRINT_STRING()`\. The macro takes a NULL\-terminated ASCII C string as its only parameter\.
+1. Open `freertos/vendors/vendor/boards/board/aws_tests/config_files/FreeRTOSConfig.h`, and locate the empty definition of `configPRINT_STRING()`\. The macro takes a NULL\-terminated ASCII C string as its only parameter\.
 
 1. Update the empty definition of `configPRINT_STRING()` so that it calls the vendor\-supplied UART output function\.
 
@@ -40,4 +40,4 @@ To implement the `configPRINT_STRING()` macro, you need the following:
 
 Build and execute the test demo project\. If Test Message appears in the UART console, then the console is connected and configured correctly, `configPRINT_STRING()` is behaving properly, and testing is complete\. You can remove the call to `configPRINT_STRING("Test Message")` from `prvMiscInitialization()`\.
 
-After you implement the `configPRINT_STRING()` macro, you can start configuring a FreeRTOS kernel port for your device\. See [Configuring a FreeRTOS Kernel Port](afr-porting-kernel.md) for instructions\.
+After you implement the `configPRINT_STRING()` macro, you can start configuring a FreeRTOS kernel port for your device\. See [Configuring a FreeRTOS kernel port](afr-porting-kernel.md) for instructions\.

doc_source/portingguide/afr-porting-https.md

@@ -1,4 +1,4 @@
-# Configuring the HTTPS Client Library for Testing<a name="afr-porting-https"></a>
+# Configuring the HTTPS client library for testing<a name="afr-porting-https"></a>
 
 The HTTPS Client library implements the HTTPS/1\.1 protocol over TLS for devices running FreeRTOS\.
 
@@ -7,33 +7,33 @@ The HTTPS Client library implements the HTTPS/1\.1 protocol over TLS for devices
 To set up the FreeRTOS HTTPS Client library tests, you need the following:
 + A port of the TLS library\.
 
-  For information about porting the TLS library to your platform, see [Porting the TLS Library](afr-porting-tls.md)\.
+  For information about porting the TLS library to your platform, see [Porting the TLS library](afr-porting-tls.md)\.
 
 If you are using an IDE to build test projects, you need to set up your library port in the IDE project\.
 
-## Setting Up the IDE Test Project<a name="testing-ide-https"></a>
+## Setting up the IDE test project<a name="testing-ide-https"></a>
 
-**To set up the HTTPS Client library in the IDE project**
-+ Add all of the test source files in `<freertos>/libraries/c_sdk/standard/https` and its subdirectories to the `aws_tests` IDE project\.
+**To set up the HTTPS client library in the IDE project**
++ Add all of the test source files in `freertos/libraries/c_sdk/standard/https` and its subdirectories to the `aws_tests` IDE project\.
 
-## Configuring the `CMakeLists.txt` File<a name="testing-cmake-https"></a>
+## Configuring the `CMakeLists.txt` file<a name="testing-cmake-https"></a>
 
 If you are using CMake to build your test project, you need to define a portable layer target for the library in your CMake list file\.
 
-To define a library's portable layer target in CMakeLists\.txt, follow the instructions in [FreeRTOS Portable Layers](cmake-template.md#cmake-portable)\.
+To define a library's portable layer target in CMakeLists\.txt, follow the instructions in [FreeRTOS portable layers](cmake-template.md#cmake-portable)\.
 
-The CMakeLists\.txt template list file under `<freertos>/vendors/<vendor>/boards/<board>/CMakeLists.txt` includes example portable layer target definitions\. You can uncomment the definition for the library that you are porting, and modify it to fit your platform\.
+The CMakeLists\.txt template list file under `freertos/vendors/vendor/boards/board/CMakeLists.txt` includes example portable layer target definitions\. You can uncomment the definition for the library that you are porting, and modify it to fit your platform\.
 
-## Setting Up Your Local Testing Environment<a name="testing-local-https"></a>
+## Setting up your local testing environment<a name="testing-local-https"></a>
 
 After you set up the library in the IDE project, you need to configure some other files for testing\.
 
-**To configure the source and header files for the HTTPS Client tests**
-+ To enable the HTTPS Client tests, open `<freertos>/vendors/<vendor>/boards/<board>/aws_tests/config_files/aws_test_runner_config.h`, and set the `testrunnerFULL_HTTPS_CLIENT_ENABLED ` macro to `1`\.
+**To configure the source and header files for the HTTPS client tests**
++ To enable the HTTPS Client tests, open `freertos/vendors/vendor/boards/board/aws_tests/config_files/aws_test_runner_config.h`, and set the `testrunnerFULL_HTTPS_CLIENT_ENABLED ` macro to `1`\.
 
-## Running the Tests<a name="testing-run-https"></a>
+## Running the tests<a name="testing-run-https"></a>
 
-**To execute the HTTPS Client tests**
+**To execute the HTTPS client tests**
 
 1. Build the test project, and then flash it to your device for execution\.