diff --git a/.github/.cSpellWords.txt b/.github/.cSpellWords.txt index d9eb837..5f5c417 100644 --- a/.github/.cSpellWords.txt +++ b/.github/.cSpellWords.txt @@ -73,3 +73,4 @@ subpubunsubconfig tsens unsubscriptions utest +mosquitto diff --git a/GettingStartedGuide.md b/GettingStartedGuide.md index 80cff64..898eb51 100644 --- a/GettingStartedGuide.md +++ b/GettingStartedGuide.md @@ -616,7 +616,9 @@ disabled when running the qualification test. You can change the log level by 1. Device Advisor Test - Create a [Device Advisor test suite](https://docs.aws.amazon.com/iot/latest/developerguide/device-advisor.html) - in the console. + in the console. Make sure that the region you choose supports the Device Advisor Tests feature. + - When asked to select a Device Role, create a new role with the following configurations: + ![alt text](./artifacts/device-advisor-tests-role-config.jpg) - Find the Device Advisor test endpoint for your account - Under `Featured FreeRTOS IoT Integration -> Qualification Test Configurations -> Qualification Execution Test Configurations`, choose `Device Advisor Test`. @@ -625,14 +627,30 @@ disabled when running the qualification test. You can change the log level by - Set `Thing Name for Device Advisor Test/OTA end-to-end Test` to AWS IoT Thing under test. - Build and run. - See Device Advisor test result in the console. + - Example Result + ![alt text](./artifacts/device-advisor-tests-result.jpg) 2. MQTT Test + - Setup an AWS account and create a new thing. + - Under the "Attach policies to certificate" section create a new policy with all the MQTT related permissions as these are required for the tests: + ![alt text](./artifacts/mqtt-thing-cert-policy-permissions.jpg) - Under `Featured FreeRTOS IoT Integration -> Qualification Test Configurations -> Qualification Execution Test Configurations`, choose `MQTT Test`. - Under `FreeRTOS IoT Integration -> Qualification Test Configurations -> Qualification Parameter Configurations` - Set `Endpoint for MQTT Broker to use` to your AWS IoT endpoint - Set `Client Identifier for MQTT Test` - Build and run. + - The test requires that there be no retained message associated with the test topic. If you receive memory leak reports from Unity, it could be due to retained messages. Try clearing the retained messages. Install any MQTT client library (e.g. mosquitto CLI) and publish a message to the test topic with an empty message. + ``` + mosquitto_pub.exe \ + --cert \ + --key \ + --cafile \ + -h -p 8883 \ + -t "" + -m "" + -r + ``` - See test result on target output. - Example output @@ -646,16 +664,31 @@ disabled when running the qualification test. You can change the log level by ``` 3. Transport Interface Test - - Follow + - First setup a TCP echo server. This can be done on any Linux machine but following are the instructions to do so in an AWS EC2 instance. + - Create an EC2 instance and change the security group inbound rules to accept packets from all traffic. + - Clone [FreeRTOS-Libraries-Integration-Tests](https://github.com/FreeRTOS/FreeRTOS-Libraries-Integration-Tests) in a directory of your choice within your EC2 file system. + - Follow the instructions [here](https://github.com/FreeRTOS/FreeRTOS-Libraries-Integration-Tests/tree/main/tools/echo_server) to generate the self signed certificates. Download the certificates generated for the server to your PC. + - Run the go server at `FreeRTOS-Libraries-Integration-Tests/tools/echo_server` with TLS. Follow [Run The Transport Interface Test](https://github.com/FreeRTOS/FreeRTOS-Libraries-Integration-Tests/tree/main/src/transport_interface#6-run-the-transport-interface-test) to start an echo server. + - In the file [test_param_config.h](./components/FreeRTOS-Libraries-Integration-Tests/config/test_param_config.h) set `ECHO_SERVER_ROOT_CA` to `NULL` + - Replace the file `/main/certs/root_cert_auth.crt` with your server’s root-ca certificate that you downloaded but name the file same as before (including the extension `root_cert_auth.crt`). + - Use the command below to provision your board with the certificates you downloaded + ``` + python managed_components/espressif__esp_secure_cert_mgr/tools/configure_esp_secure_cert.py \ + -p COM18 --keep_ds_data_on_host \ + --ca-cert certs/server.pem \ + --device-cert certs/client.pem \ + --private-key certs/client.key \ + --target_chip esp32c3 \ + --secure_cert_type cust_flash \ + --priv_key_algo RSA 2048 + ``` - Under `Featured FreeRTOS IoT Integration -> Qualification Test Configurations -> Qualification Execution Test Configurations`, choose `Transport Interface Test`. - Under `FreeRTOS IoT Integration -> Qualification Test Configurations -> Qualification Parameter Configurations` - - Set `Echo Server Domain Name/IP for Transport Interface Test` + - Set `Echo Server Domain Name/IP for Transport Interface Test` (it will be the Public IPv4 DNS of the EC2 instance if you are using one.) - Set `Port for Echo Server to use` - - Set ECHO_SERVER_ROOT_CA / TRANSPORT_CLIENT_CERTIFICATE and TRANSPORT_CLIENT_PRIVATE_KEY - in [test_param_config.h](./components/FreeRTOS-Libraries-Integration-Tests/config/test_param_config.h). - Build and run. - See test result on target output. - Example output diff --git a/artifacts/device-advisor-tests-result.jpg b/artifacts/device-advisor-tests-result.jpg new file mode 100644 index 0000000..fc35e35 Binary files /dev/null and b/artifacts/device-advisor-tests-result.jpg differ diff --git a/artifacts/device-advisor-tests-role-config.jpg b/artifacts/device-advisor-tests-role-config.jpg new file mode 100644 index 0000000..0243252 Binary files /dev/null and b/artifacts/device-advisor-tests-role-config.jpg differ diff --git a/artifacts/mqtt-thing-cert-policy-permissions.jpg b/artifacts/mqtt-thing-cert-policy-permissions.jpg new file mode 100644 index 0000000..ca95823 Binary files /dev/null and b/artifacts/mqtt-thing-cert-policy-permissions.jpg differ