You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-[#5](https://github.com/FreeRTOS/iot-reference-esp32c3/pull/5) and [#10](https://github.com/FreeRTOS/iot-reference-esp32c3/pull/10) Documentation updates
[2.2 Configure the project with the AWS IoT Thing Name and AWS device Endpoint](#22-configure-the-project-with-the-aws-iot-thing-name-and-aws-device-endpoint)<br>
14
+
[2.3 Provision the ESP32-C3 with the private key, device certificate and CA certificate in Development Mode](#23-provision-the-esp32-c3-with-the-private-key-device-certificate-and-ca-certificate-in-development-mode)<br>
15
+
16
+
[3 Build and flash the demo project](#3-build-and-flash-the-demo-project)<br>
17
+
18
+
[4 Monitoring the demo](#4-monitoring-the-demo)<br>
19
+
20
+
[5 Perform firmware Over-the-Air Updates with AWS IoT](#5-perform-firmware-over-the-air-updates-with-aws-iot)<br>
21
+
[5.1 Setup pre-requisites for OTA cloud resources](#51-setup-pre-requisites-for-ota-cloud-resources)<br>
22
+
[5.2 Provision the project with the code-signing public key certificate](#52-provision-the-project-with-the-code-signing-public-key-certificate)<br>
23
+
[5.3 Build an application binary with a higher version number, to be downloaded and activated on the device](#53-build-an-application-binary-with-a-higher-version-number-to-be-downloaded-and-activated-on-the-device)<br>
24
+
[5.4 Build and flash the device with a binary with a lower version number](#54-build-and-flash-the-device-with-a-binary-with-a-lower-version-number)<br>
25
+
[5.5 Upload the binary with the higher version number (created in step 5.3) and create an OTA Update Job](#55-upload-the-binary-with-the-higher-version-number-created-in-step-53-and-create-an-ota-update-job)<br>
@@ -15,7 +46,7 @@ Once completed, one can progress to the [Use Security Features](UseSecurityFeatu
15
46
16
47
### 1.2 Software Requirements
17
48
18
-
* ESP-IDF 4.4 or higher to configure, build, and flash the project. To setup for the ESP32-C3, follow Espressif's [Getting Started Guide for the ESP32-C3](https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/get-started/index.html).
49
+
* ESP-IDF 4.4.3 or higher to configure, build, and flash the project. To setup for the ESP32-C3, follow Espressif's [Getting Started Guide for the ESP32-C3](https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/get-started/index.html).
19
50
*[Python3](https://www.python.org/downloads/)
20
51
and the Package Installer for Python [pip](https://pip.pypa.io/en/stable/installation/) to use the AWS CLI to import certificates and perform OTA Job set up. Pip is included when you install
21
52
from Python 3.10.
@@ -32,7 +63,7 @@ Once completed, one can progress to the [Use Security Features](UseSecurityFeatu
32
63
33
64
## 2 Demo setup
34
65
35
-
### 2.1 Setup AWS IoT Core:
66
+
### 2.1 Setup AWS IoT Core
36
67
37
68
To setup AWS IoT Core, follow the [AWS IoT Core Setup Guide](AWSSetup.md). The guide shows you how to sign up for an AWS account, create a user, and register your device with AWS IoT Core.
38
69
After you have followed the instructions in the AWS IoT Core Setup Guide, you will have created a **device Endpoint**, an AWS IoT **thing**, a **PEM-encoded device certificate**, a **PEM-encoded private key**, and a **PEM-encoded root CA certificate**. (An explanation of these entities is given in the Setup Guide.) The root CA certificate can also be downloaded [here](https://www.amazontrust.com/repository/AmazonRootCA1.pem). Your ESP23-C3 board must now be provisioned with these entities in order for it to connect securely with AWS IoT Core.
@@ -421,3 +452,162 @@ I (3444) coreMQTT: Packet received. ReceivedBytes=3.
421
452
I (3444) ota_over_mqtt_demo: Subscribed to topic $aws/things/thing_esp32c3_nonOta/jobs/notify-next.
422
453
```
423
454
455
+
## 6 Run FreeRTOS Integration Test
456
+
457
+
### 6.1 Prerequisite
458
+
- Follow the [OTA update with AWS IoT Guide](#5-perform-firmware-over-the-air-updates-with-aws-iot) to create an OTA update and verify the digital signature, checksum and version number of the new image. If firmware update is verified, you can run the tests on your device.
459
+
- Run `idf.py menuconfig`.
460
+
- Under `Featured FreeRTOS IoT Integration`, choose `Run qualification test`.
461
+
- Under `Component config -> Unity unit testing library`, choose `Include Unity test fixture`.
462
+
463
+
*Note: The log of module `esp_ota_ops`, `AWS_OTA` and `esp-tls-mbedtls` will be disabled when running the qualification test. You can change the log level by `esp_log_level_set` in [main.c](./main/main.c).*
464
+
465
+
### 6.2 Steps for each test case
466
+
467
+
1. Device Advisor Test
468
+
- Create a [Device Advisor test suite](https://docs.aws.amazon.com/iot/latest/developerguide/device-advisor.html) in the console.
469
+
- Find the Device Advisor test endpoint for your account
470
+
- Under `Freatured FreeRTOS IoT Integration -> Qualification Test Configurations -> Qualification Execution Test Configurations`, choose `Device Advisor Test`.
471
+
- Under `FreeRTOS IoT Integration -> Qualification Test Configurations -> Qualification Parameter Configurations`
472
+
- Set `Endpoint for MQTT Broker to use` to Device Avdisor test endpoint
473
+
- Set `Thing Name for Device Advisor Test/OTA end-to-end Test` to AWS IoT Thing under test.
474
+
- Build and run.
475
+
- See Device Advisor test result in the console.
476
+
2. MQTT Test
477
+
- Under `Freatured FreeRTOS IoT Integration -> Qualification Test Configurations -> Qualification Execution Test Configurations`, choose `MQTT Test`.
478
+
- Under `FreeRTOS IoT Integration -> Qualification Test Configurations -> Qualification Parameter Configurations`
479
+
- Set `Endpoint for MQTT Broker to use` to your AWS IoT endpoint
480
+
- Set `Client Identifier for MQTT Test`
481
+
- Build and run.
482
+
- See test result on target output.
483
+
- Example output
484
+
```
485
+
I (821) qual_main: Run qualification test.
486
+
...
487
+
-----------------------
488
+
8 Tests 0 Failures 0 Ignored
489
+
OK
490
+
I (84381) qual_main: End qualification test.
491
+
```
492
+
3. Transport Interface Test
493
+
- 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.
494
+
- Under `Freatured FreeRTOS IoT Integration -> Qualification Test Configurations -> Qualification Execution Test Configurations`, choose `Transport Interface Test`.
495
+
- Under `FreeRTOS IoT Integration -> Qualification Test Configurations -> Qualification Parameter Configurations`
496
+
- Set `Echo Server Domain Name/IP for Transport Interface Test`
497
+
- Set `Port for Echo Server to use`
498
+
- 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).
499
+
- Build and run.
500
+
- See test result on target output.
501
+
- Example output
502
+
```
503
+
I (855) qual_main: Run qualification test.
504
+
...
505
+
-----------------------
506
+
14 Tests 0 Failures 0 Ignored
507
+
OK
508
+
I (612755) qual_main: End qualification test.
509
+
```
510
+
4. OTA PAL Test
511
+
- Under `Freatured FreeRTOS IoT Integration -> Qualification Test Configurations -> Qualification Execution Test Configurations`, choose `OTA PAL Test`.
512
+
- Build and run.
513
+
- See test result on target output.
514
+
- Example output
515
+
```
516
+
I (905) qual_main: Run qualification test.
517
+
...
518
+
-----------------------
519
+
15 Tests 0 Failures 0 Ignored
520
+
OK
521
+
I (113755) qual_main: End qualification test.
522
+
```
523
+
5. Core PKCS11 Test
524
+
- Under `Freatured FreeRTOS IoT Integration -> Qualification Test Configurations -> Qualification Execution Test Configurations`, choose `CorePKCS#11 Test`.
525
+
- Build and run.
526
+
- See test result on target output.
527
+
- Example output
528
+
```
529
+
I (858) qual_main: Run qualification test.
530
+
...
531
+
-----------------------
532
+
17 Tests 0 Failures 0 Ignored
533
+
OK
534
+
I (7518) qual_main: End qualification test.
535
+
```
536
+
537
+
## 7 Run AWS IoT Device Tester
538
+
539
+
This repository can be tested using [AWS IoT Device Tester for FreeRTOS (IDT)](https://aws.amazon.com/freertos/device-tester/). IDT is a downloadable tool that can be used to exercise a device integration with FreeRTOS to validate functionality and compatibility with Amazon IoT cloud. Passing the test suite provided by IDT is also required to qualify a device for the [Amazon Partner Device Catalogue](https://devices.amazonaws.com/).
540
+
541
+
IDT runs a suite of tests that include testing the device's transport interface layer implementation, PKCS11 functionality, and OTA capabilities. In IDT test cases, the IDT binary will make a copy of the source code, update the header files in the project, then compile the project and flash the resulting image to your board. Finally, IDT will read serial output from the board and communicate with the AWS IoT cloud to ensure that test cases are passing.
542
+
543
+
### 7.1 Prerequisite
544
+
- Follow the [OTA update with AWS IoT Guide](#5-perform-firmware-over-the-air-updates-with-aws-iot) to create an OTA update and verify the digital signature, checksum and version number of the new image. If firmware update is verified, you can run the tests on your device.
545
+
- Run `idf.py menuconfig`.
546
+
- Under `Featured FreeRTOS IoT Integration`, choose `Run qualification test`.
547
+
- Under `Component config -> Unity unit testing library`, choose `Include Unity test fixture`.
548
+
- Under `Freatured FreeRTOS IoT Integration -> Qualification Test Configurations -> Qualification Execution Test Configurations`, **DISABLE** all the tests.
549
+
- Run `idf.py fullclean` to clear local CMAKE cache.
550
+
551
+
*Note: The log of module `esp_ota_ops`, `AWS_OTA` and `esp-tls-mbedtls` will be disabled when running the qualification test. You can change the log level by `esp_log_level_set` in [main.c](./main/main.c).*
552
+
553
+
### 7.2 Download AWS IoT Device Tester
554
+
555
+
The latest version of IDT can be downloaded from the [here](https://docs.aws.amazon.com/freertos/latest/userguide/dev-test-versions-afr.html). This repository has been qualified by IDT v4.6.0 and test suite version 2.3.0 for FreeRTOS 202210-LTS.
556
+
557
+
### 7.3 Configure AWS IoT Device Tester
558
+
559
+
Follow [the instructions to setup your AWS account](https://docs.aws.amazon.com/freertos/latest/userguide/lts-idt-dev-tester-prereqs.html#lts-config-aws-account).
560
+
561
+
Extract IDT for FreeRTOS to a location on the file system
562
+
563
+
* The `devicetester-extract-location/bin` directory holds the IDT binary, which is the entry point used to run IDT
564
+
* The `devicetester-extract-location/results` directory holds logs that are generated every time you run IDT.
565
+
* The `devicetester-extract-location/configs` directory holds configuration files that are required to setup IDT
566
+
567
+
Before running IDT, the files in `devicetester-extract-location/configs` need to be updated. We have pre-defined configures available in the [idt_config](https://github.com/FreeRTOS/iot-reference-esp32c3/tree/main/idt_config). Copy these templates to `devicetester-extract-location/configs`, and the rest of this section will walk through the remaining values that need to be filled in.
568
+
569
+
You need to configure your AWS credentials for IDT.
570
+
* In `config.json`, update the `profile` and `awsRegion` fields
571
+
572
+
You need to specify the device details for IDT.
573
+
* In `device.json`, update `serialPort` to the serial port of your board as from [PORT](./GettingStartedGuide.md#23-provision-the-esp32-c3-with-the-private-key-device-certificate-and-ca-certificate-in-development-mode). Update `publicKeyAsciiHexFilePath` to the absolute path to `dummyPublicKeyAsciiHex.txt`. Update `publicDeviceCertificateArn` to the ARN of the certificate uploaded when [Setup AWS IoT Core](./GettingStartedGuide.md#21-setup-aws-iot-core).
574
+
575
+
You need to configure IDT the build, flash and test settings.
576
+
* In `build.bat` / `build.sh`, update ESP_IDF_PATH, and ESP_IDF_FRAMEWORK_PATH
577
+
* In `flash.bat` / `flash.sh`, update ESP_IDF_PATH, ESP_IDF_FRAMEWORK_PATH, and NUM_COMPORT
578
+
* In `userdata.json`, update `sourcePath` to the absolute path to the root of this repository.
579
+
* In `userdata.json`, update `signerCertificate` with the ARN of the [Setup pre-requisites for OTA cloud resources
* Run all the steps to create a [second code signing certificate](./GettingStartedGuide.md#51-setup-pre-requisites-for-ota-cloud-resources) but do NOT provision the key onto your board. Copy the ARN for this certificate in `userdata.json` for the field `untrustedSignerCertificate`.
582
+
583
+
### 7.4 Running the FreeRTOS qualification 2.0 suite
584
+
585
+
With configuration complete, IDT can be run for an individual test group, a test case, or the entire qualification suite.
For more information, `.\devicetester_win_x86-64.exe help` will show all available commands.
612
+
613
+
When IDT is run, it generates the `results/uuid` directory that contains the logs and other information associated with your test run. See [Understanding results and logs](https://docs.aws.amazon.com/freertos/latest/userguide/lts-results-logs.html) for more details.
0 commit comments