本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# AWS IoT Device Tester 適用於 FreeRTOS
IDT for FreeRTOS 是一種使用 FreeRTOS 作業系統限定資料輸送量速率的工具。裝置測試人員 (IDT) 會先開啟與裝置的 USB 或 UART 連線。然後，它會閃爍設定為在各種條件下測試裝置功能的 FreeRTOS 映像。 AWS IoT Device Tester 套件可擴展，並使用 IDT 進行客戶 AWS IoT 測試協調。
IDT for FreeRTOS 會在連接到要測試之裝置的主機電腦 (Windows、macOS 或 Linux) 上執行。IDT 會設定和協調測試案例，並彙總結果。還會提供可管理測試執行作業的命令列界面。
## FreeRTOS 資格套件
IDT for FreeRTOS 會驗證微型控制器上的 FreeRTOS 連接埠，以及它是否可以 AWS IoT 以可靠且安全的方式有效地與 通訊。具體而言，它會驗證 FreeRTOS 程式庫的移植層界面是否正確實作。它也會使用 end-to-end測試 AWS IoT Core。例如，它會驗證您的電路板是否可以傳送和接收 MQTT 訊息，並正確處理它們。
FreeRTOS 資格 (FRQ) 2.0 套件使用 FreeRTOS-Libraries-Integration-Tests [ FreeRTOS](https://docs.aws.amazon.com/freertos/latest/qualificationguide/freertos-qualification.html#qualifying-your-device-idt)和 Device Advisor 的測試案例。
IDT for FreeRTOS 會產生測試報告，您可以提交至 AWS 合作夥伴網路 (APN)，以在 AWS 合作夥伴裝置目錄中包含您的 FreeRTOS 裝置。如需詳細資訊，請參閱 [AWS 裝置資格計劃](https://aws.amazon.com/partners/dqp/)。
下圖顯示 FreeRTOS 資格的測試基礎設施設定。
![\[流程圖顯示 如何與您的電腦和微控制器 AWS IoT Core 互動。\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/images/devicetester_afr.png)
IDT for FreeRTOS 會將測試資源組織成測試套件和測試群組：
+ 測試套件是一組測試群組，用來驗證裝置是否適用於特定版本的 FreeRTOS。
+ 測試群組是一組與特定功能相關的個別測試案例，例如 BLE 和 MQTT 訊息。
如需詳細資訊，請參閱[測試套件版本](idt-test-suite-versions.md)
## 了解自訂測試套件
IDT for FreeRTOS 結合了標準化的組態設定和結果格式，以及測試套件環境。此環境可讓您為裝置和裝置軟體開發自訂測試套件。您可以為自己的內部驗證新增自訂測試，或將其提供給客戶進行裝置驗證。
設定自訂測試套件的方式會決定您必須提供給使用者才能執行自訂測試套件的設定組態。如需詳細資訊，請參閱[開發並執行您自己的 IDT 測試套件](idt-custom-tests.md)。
# 支援的 版本 AWS IoT Device Tester
本主題列出 AWS IoT Device Tester FreeRTOS 支援的 版本。最佳實務是，建議您使用支援 FreeRTOS 目標版本的最新版本 IDT for FreeRTOS。每個 IDT for FreeRTOS 版本都有其支援的一或多個對應 FreeRTOS 版本。我們建議您在發行新版 FreeRTOS 時，下載新版的 IDT for FreeRTOS。
透過下載軟體，即表示您同意下載存檔中包含的 AWS IoT Device Tester 授權合約。
**注意**
當您使用 AWS IoT Device Tester for FreeRTOS 時，我們建議您更新至最新版本 FreeRTOS-LTS 的最新版本修補程式。
**重要**
自 2022 年 10 月起， AWS IoT Device Tester for AWS IoT FreeRTOS 資格 (FRQ) 1.0 不會產生已簽章的資格報告。您無法使用 IDT FRQ 1.0 版本，讓新的 AWS IoT FreeRTOS 裝置有資格透過[AWS 裝置資格計劃](https://aws.amazon.com/partners/programs/dqp/)在[AWS 合作夥伴裝置目錄中](https://partners.amazonaws.com/qualified-devices)列出。雖然您無法使用 IDT FRQ 1.0 取得 FreeRTOS 裝置的資格，但您可以繼續使用 FRQ 1.0 繼續測試 FreeRTOS 裝置。我們建議您使用 [IDT FRQ 2.0](https://docs.aws.amazon.com/freertos/latest/userguide/lts-idt-freertos-qualification.html)，在合作夥伴裝置目錄中限定和列出 FreeRTOS 裝置。 [AWS](https://partners.amazonaws.com/qualified-devices)
## FreeRTOS AWS IoT Device Tester 的最新版本
使用以下連結下載最新版本的 IDT for FreeRTOS。
**FreeRTOS AWS IoT Device Tester 的最新版本**
| **AWS IoT Device Tester version** | **測試套件版本** | **支援的 FreeRTOS 版本** | **下載連結** | **發行日期** | **版本備註** |
| --- | --- | --- | --- | --- | --- |
| IDT 4.9.0 版 | FRQ\$12.5.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/dev-test-versions-afr.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/dev-test-versions-afr.html) | 2023.04.04 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/dev-test-versions-afr.html) |
**注意**
不建議多位使用者從 NFS 目錄或 Windows 網路共用資料夾等共用位置執行 IDT。此做法可能會導致當機或資料損毀。我們建議您將 IDT 套件解壓縮到本機磁碟機，並在本機工作站上執行 IDT 二進位檔。
## FreeRTOS 的早期 IDT 版本
也支援下列舊版的 IDT for FreeRTOS。
**AWS IoT Device Tester 適用於 FreeRTOS 的舊版**
| **AWS IoT Device Tester version** | **測試套件版本** | **支援的 FreeRTOS 版本** | **下載連結** | **發行日期** | **版本備註** |
| --- | --- | --- | --- | --- | --- |
| IDT 4.8.1 版 | FRQ\$12.4.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/dev-test-versions-afr.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/dev-test-versions-afr.html) | 2023.01.23 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/dev-test-versions-afr.html) |
| IDT 4.6.0 版 | FRQ\$12.3.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/dev-test-versions-afr.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/dev-test-versions-afr.html) | 2022.11.16 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/dev-test-versions-afr.html) |
| IDT v4.5.11 | FRQ\$12.2.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/dev-test-versions-afr.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/dev-test-versions-afr.html) | 2022.10.14 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/dev-test-versions-afr.html) |
如需詳細資訊，請參閱[了解 的支援政策 AWS IoT Device Tester](idt-support-policy.md)。
# FreeRTOS 不支援的 IDT 版本
本節列出不支援的 IDT for FreeRTOS 版本。不支援的版本不會收到錯誤修正或更新。如需詳細資訊，請參閱[了解 的支援政策 AWS IoT Device Tester](idt-support-policy.md)。
不再支援下列版本的 IDT-FreeRTOS。
**FreeRTOS 不支援 AWS IoT Device Tester 的 版本**
| **AWS IoT Device Tester version** | **測試套件版本** | **支援的 FreeRTOS 版本** | **發行日期** | **版本備註** |
| --- | --- | --- | --- | --- |
| IDT v4.5.10 | FRQ\$12.1.4 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/idt-unsupported-versions-afr.html) | 2022.09.02 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/idt-unsupported-versions-afr.html) |
| IDT 4.5.9 版 | FRQ\$12.1.3 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/idt-unsupported-versions-afr.html) | 2022.08.17 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/idt-unsupported-versions-afr.html) |
| IDT 4.5.6 版 | FRQ\$12.1.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/idt-unsupported-versions-afr.html) | 2022.06.29 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/idt-unsupported-versions-afr.html) |
| IDT 4.5.5 版 | FRQ\$12.1.1 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/idt-unsupported-versions-afr.html) | 2022.06.06 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/idt-unsupported-versions-afr.html) |
| IDT 4.5.5 版 | FRQ\$12.1.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/idt-unsupported-versions-afr.html) | 2022.05.31 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/idt-unsupported-versions-afr.html) |
| IDT 4.5.4 版 | FRQ\$12.0.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/idt-unsupported-versions-afr.html) | 2022.05.09 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/idt-unsupported-versions-afr.html) |
| IDT 4.5.2 版 | FRQ\$11.6.2 | 202107.00 | 2022.01.25 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/idt-unsupported-versions-afr.html) |
| IDT 4.0.3 版 | FRQ\$11.5.1 | 202012.00 | 2021.07.30 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/idt-unsupported-versions-afr.html) |
| IDT 4.3.0 版 | FRQ\$11.6.1 | 202107.00 | 2021.07.26 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/idt-unsupported-versions-afr.html) |
| IDT 4.1.0 版 | FRQ\$11.6.0 | 202107.00 | 2021.07.21 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/idt-unsupported-versions-afr.html) |
| IDT 4.0.1 版 | FRQ\$11.4.1 | 202012.00 | 2021.01.19 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/idt-unsupported-versions-afr.html) |
| IDT 3.4.0 版 | FRQ\$11.3.0 | 202011.01 | 2020.11.05 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/idt-unsupported-versions-afr.html) |
| IDT 3.3.0 版 | FRQ\$11.2.0 | 202007.00 | 2020.09.17 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/idt-unsupported-versions-afr.html) |
| IDT 3.0.2 版 | FRQ\$11.0.1 | 202002.00 | | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/idt-unsupported-versions-afr.html) |
| IDT 1.7.1 版 | FRQ\$11.0.0 | 202002.00 | | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/idt-unsupported-versions-afr.html) |
| IDT 1.6.2 版 | FRQ\$11.0.0 | 202002.00 | | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/idt-unsupported-versions-afr.html) |
| IDT 1.5.2 版 | FRQ\$11.0.0 | 201910.00 | | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/idt-unsupported-versions-afr.html) |
| IDT 1.4.1 版 | FRQ\$11.0.0 | 201908.00 | | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/idt-unsupported-versions-afr.html) |
| IDT 1.3.2 版 | FRQ\$11.0.0 | 201906.00 | | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/idt-unsupported-versions-afr.html) |
| IDT-FreeRTOS 1.2 版 | FRQ\$11.0.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/idt-unsupported-versions-afr.html) | | 新增使用 CMAKE 建置系統測試 FreeRTOS 裝置的支援。 |
| IDT-FreeRTOS 1.1 版 | FRQ\$11.0.0 | | | |
| IDT-FreeRTOS 1.0 版 | FRQ\$11.0.0 | | | |
# 下載 IDT for FreeRTOS
本主題說明下載 IDT for FreeRTOS 的選項。您可以使用下列其中一個軟體下載連結，也可以依照指示以程式設計方式下載 IDT。
**重要**
自 2022 年 10 月起， AWS IoT Device Tester for AWS IoT FreeRTOS 資格 (FRQ) 1.0 不會產生已簽章的資格報告。您不符合使用 IDT FRQ 1.0 版本透過裝置[AWS 資格計劃](https://aws.amazon.com/partners/programs/dqp/)在[AWS 合作夥伴裝置目錄中](https://partners.amazonaws.com/qualified-devices)列出新 AWS IoT FreeRTOS 裝置的資格。雖然您無法使用 IDT FRQ 1.0 取得 FreeRTOS 裝置的資格，但您可以繼續使用 FRQ 1.0 繼續測試 FreeRTOS 裝置。我們建議您使用 [IDT FRQ 2.0](https://docs.aws.amazon.com/freertos/latest/userguide/lts-idt-freertos-qualification.html)，在合作夥伴裝置目錄中限定和列出 FreeRTOS 裝置。 [AWS](https://partners.amazonaws.com/qualified-devices)
**Topics**
+ [手動下載 IDT](#idt-download-options)
+ [以程式設計方式下載 IDT](idt-programmatic-download-process.md)
透過下載軟體，即表示您同意下載存檔中包含的 AWS IoT Device Tester 授權合約。
**注意**
IDT 不支援由多位使用者從共用位置執行，例如 NFS 目錄或 Windows 網路共用資料夾。我們建議您將 IDT 套件解壓縮到本機磁碟機，並在本機工作站上執行 IDT 二進位檔。
## 手動下載 IDT
本主題列出支援版本的 IDT for FreeRTOS。最佳實務是，建議您使用 AWS IoT Device Tester 支援 FreeRTOS 目標版本的 最新版本。FreeRTOS 的新版本可能需要您下載新版本的 AWS IoT Device Tester。如果 AWS IoT Device Tester 與您正在使用的 FreeRTOS 版本不相容，則當您啟動測試執行時會收到通知。
請參閱[支援的 版本 AWS IoT Device Tester](dev-test-versions-afr.md)
# 以程式設計方式下載 IDT
IDT 提供 API 操作，可用來擷取 URL，以程式設計方式下載 IDT。您也可以使用此 API 操作來檢查您是否擁有最新版本的 IDT。此 API 操作具有下列端點。
```
https://download.devicetester.iotdevicesecosystem.amazonaws.com/latestidt
```
若要呼叫此 API 操作，您必須具有執行 **iot-device-tester:LatestIdt**動作的許可。包含您的 AWS 簽章，以 `iot-device-tester`做為服務名稱
## API 請求
HostOs主機機器的作業系統。您可以從以下選項中選擇：
+ `mac`
+ `linux`
+ `windows`
TestSuiteType – 測試套件的類型。選擇下列選項：
`FR` – IDT for FreeRTOS
ProductVersion
（選用） FreeRTOS 的版本。服務會傳回該 FreeRTOS 版本的最新相容 IDT 版本。如果您未指定此選項，服務會傳回最新版本的 IDT。
## API 回應
API 回應的格式如下。`DownloadURL` 包含 zip 檔案。
```
{
"Success": True or False,
"Message": Message,
"LatestBk": {
"Version": The version of the IDT binary,
"TestSuiteVersion": The version of the test suite,
"DownloadURL": The URL to download the IDT Bundle, valid for one hour
}
}
```
## 範例
您可以參考下列範例以程式設計方式下載 IDT。這些範例使用您存放在 `AWS_ACCESS_KEY_ID`和 `AWS_SECRET_ACCESS_KEY`環境變數中的登入資料。若要遵循最佳安全實務，請勿將登入資料存放在程式碼中。
**Example**
**範例：使用 cURL 7.75.0 版或更新版本 (Mac 和 Linux) 下載**
如果您有 cURL 7.75.0 版或更新版本，您可以使用 `aws-sigv4`旗標簽署 API 請求。此範例使用 [jq](https://stedolan.github.io/jq/) 從回應剖析下載 URL。
`aws-sigv4` 旗標要求 curl GET 請求的查詢參數依 **HostOs/ProductVersion/TestSuiteType** 或 **HostOs/TestSuiteType** 的順序排列。不符合的順序會導致從 API Gateway 取得正式字串不相符簽章的錯誤。
如果包含選用參數 **ProductVersion**，您必須使用支援的產品版本，如 [AWS IoT Device Tester FreeRTOS 支援版本](https://docs.aws.amazon.com/freertos/latest/userguide/dev-test-versions-afr.html) 中所述。
+ 將 *us-west-2* 取代為您的 AWS 區域。如需區域代碼清單，請參閱[區域端點](https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints)。
+ 將 *linux* 取代為主機機器的作業系統。
+ 將 *202107.00* 取代為您的 FreeRTOS 版本。
```
url=$(curl --request GET "https://download.devicetester.iotdevicesecosystem.amazonaws.com/latestidt?HostOs=linux&ProductVersion=202107.00&TestSuiteType=FR" \
--user $AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY \
--aws-sigv4 "aws:amz:us-west-2:iot-device-tester" \
| jq -r '.LatestBk["DownloadURL"]')
curl $url --output devicetester.zip
```
**Example**
**範例：使用舊版 cURL (Mac 和 Linux) 下載**
您可以使用下列 cURL 命令搭配您簽署和計算的 AWS 簽章。如需如何簽署和計算 AWS 簽章的詳細資訊，請參閱[簽署 AWS API 請求](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html)。
+ 將 *linux* 取代為主機機器的作業系統。
+ 將*時間戳記*取代為日期和時間，例如 **20220210T004606Z**。
+ 將*日期*取代為日期，例如 **20220210**。
+ 將 *AWSRegion* 取代為 AWS 區域。如需區域代碼清單，請參閱[區域端點](https://docs.aws.amazon.com/general/latest/gr/rande.html)。
+ 將 *AWSSignature* 取代為您產生的[AWS 簽章](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv-create-signed-request.html)。
```
curl --location --request GET 'https://download.devicetester.iotdevicesecosystem.amazonaws.com/latestidt?HostOs=linux&TestSuiteType=FR' \
--header 'X-Amz-Date: Timestamp \
--header 'Authorization: AWS4-HMAC-SHA256 Credential=$AWS_ACCESS_KEY_ID/Date/AWSRegion/iot-device-tester/aws4_request, SignedHeaders=host;x-amz-date, Signature=AWSSignature'
```
**Example**
**範例：使用 Python 指令碼下載**
此範例使用 Python [請求](https://pypi.org/project/requests/)程式庫。此範例改編自 Python 範例，以在*AWS 一般參考*中[簽署 AWS API 請求](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html)。
+ 將 *us-west-2* 取代為您的區域。如需區域代碼清單，請參閱[區域端點](https://docs.aws.amazon.com/general/latest/gr/rande.html)。
+ 將 *linux* 取代為主機機器的作業系統。
```
# Copyright 2010-2022 Amazon.com, Inc. or its affiliates. All Rights Reserved.
#
# This file is licensed under the Apache License, Version 2.0 (the "License").
# You may not use this file except in compliance with the License. A copy of the
#License is located at
#
# http://aws.amazon.com/apache2.0/
#
# This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS
# OF ANY KIND, either express or implied. See the License for the specific
# language governing permissions and limitations under the License.
# See: http://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html
# This version makes a GET request and passes the signature
# in the Authorization header.
import sys, os, base64, datetime, hashlib, hmac
import requests # pip install requests
# ************* REQUEST VALUES *************
method = 'GET'
service = 'iot-device-tester'
host = 'download.devicetester.iotdevicesecosystem.amazonaws.com'
region = 'us-west-2'
endpoint = 'https://download.devicetester.iotdevicesecosystem.amazonaws.com/latestidt'
request_parameters = 'HostOs=linux&TestSuiteType=FR'
# Key derivation functions. See:
# http://docs.aws.amazon.com/general/latest/gr/signature-v4-examples.html#signature-v4-examples-python
def sign(key, msg):
return hmac.new(key, msg.encode('utf-8'), hashlib.sha256).digest()
def getSignatureKey(key, dateStamp, regionName, serviceName):
kDate = sign(('AWS4' + key).encode('utf-8'), dateStamp)
kRegion = sign(kDate, regionName)
kService = sign(kRegion, serviceName)
kSigning = sign(kService, 'aws4_request')
return kSigning
# Read AWS access key from env. variables or configuration file. Best practice is NOT
# to embed credentials in code.
access_key = os.environ.get('AWS_ACCESS_KEY_ID')
secret_key = os.environ.get('AWS_SECRET_ACCESS_KEY')
if access_key is None or secret_key is None:
print('No access key is available.')
sys.exit()
# Create a date for headers and the credential string
t = datetime.datetime.utcnow()
amzdate = t.strftime('%Y%m%dT%H%M%SZ')
datestamp = t.strftime('%Y%m%d') # Date w/o time, used in credential scope
# ************* TASK 1: CREATE A CANONICAL REQUEST *************
# http://docs.aws.amazon.com/general/latest/gr/sigv4-create-canonical-request.html
# Step 1 is to define the verb (GET, POST, etc.)--already done.
# Step 2: Create canonical URI--the part of the URI from domain to query
# string (use '/' if no path)
canonical_uri = '/latestidt'
# Step 3: Create the canonical query string. In this example (a GET request),
# request parameters are in the query string. Query string values must
# be URL-encoded (space=%20). The parameters must be sorted by name.
# For this example, the query string is pre-formatted in the request_parameters variable.
canonical_querystring = request_parameters
# Step 4: Create the canonical headers and signed headers. Header names
# must be trimmed and lowercase, and sorted in code point order from
# low to high. Note that there is a trailing \n.
canonical_headers = 'host:' + host + '\n' + 'x-amz-date:' + amzdate + '\n'
# Step 5: Create the list of signed headers. This lists the headers
# in the canonical_headers list, delimited with ";" and in alpha order.
# Note: The request can include any headers; canonical_headers and
# signed_headers lists those that you want to be included in the
# hash of the request. "Host" and "x-amz-date" are always required.
signed_headers = 'host;x-amz-date'
# Step 6: Create payload hash (hash of the request body content). For GET
# requests, the payload is an empty string ("").
payload_hash = hashlib.sha256(('').encode('utf-8')).hexdigest()
# Step 7: Combine elements to create canonical request
canonical_request = method + '\n' + canonical_uri + '\n' + canonical_querystring + '\n' + canonical_headers + '\n' + signed_headers + '\n' + payload_hash
# ************* TASK 2: CREATE THE STRING TO SIGN*************
# Match the algorithm to the hashing algorithm you use, either SHA-1 or
# SHA-256 (recommended)
algorithm = 'AWS4-HMAC-SHA256'
credential_scope = datestamp + '/' + region + '/' + service + '/' + 'aws4_request'
string_to_sign = algorithm + '\n' + amzdate + '\n' + credential_scope + '\n' + hashlib.sha256(canonical_request.encode('utf-8')).hexdigest()
# ************* TASK 3: CALCULATE THE SIGNATURE *************
# Create the signing key using the function defined above.
signing_key = getSignatureKey(secret_key, datestamp, region, service)
# Sign the string_to_sign using the signing_key
signature = hmac.new(signing_key, (string_to_sign).encode('utf-8'), hashlib.sha256).hexdigest()
# ************* TASK 4: ADD SIGNING INFORMATION TO THE REQUEST *************
# The signing information can be either in a query string value or in
# a header named Authorization. This code shows how to use a header.
# Create authorization header and add to request headers
authorization_header = algorithm + ' ' + 'Credential=' + access_key + '/' + credential_scope + ', ' + 'SignedHeaders=' + signed_headers + ', ' + 'Signature=' + signature
# The request can include any headers, but MUST include "host", "x-amz-date",
# and (for this scenario) "Authorization". "host" and "x-amz-date" must
# be included in the canonical_headers and signed_headers, as noted
# earlier. Order here is not significant.
# Python note: The 'host' header is added automatically by the Python 'requests' library.
headers = {'x-amz-date':amzdate, 'Authorization':authorization_header}
# ************* SEND THE REQUEST *************
request_url = endpoint + '?' + canonical_querystring
print('\nBEGIN REQUEST++++++++++++++++++++++++++++++++++++')
print('Request URL = ' + request_url)
response = requests.get(request_url, headers=headers)
print('\nRESPONSE++++++++++++++++++++++++++++++++++++')
print('Response code: %d\n' % response.status_code)
print(response.text)
download_url = response.json()["LatestBk"]["DownloadURL"]
r = requests.get(download_url)
open('devicetester.zip', 'wb').write(r.content)
```
# IDT with FreeRTOS 資格套件 2.0 (FRQ 2.0)
FreeRTOS 資格套件 2.0 是 FreeRTOS 資格套件的更新版本。我們建議開發人員使用 FRQ 2.0，因為它包含相關的測試案例，以限定執行 FreeRTOS 長期支援 (LTS) 程式庫的裝置。
IDT for FreeRTOS 會驗證微型控制器上 FreeRTOS 的連接埠，以及其是否有效通訊 AWS IoT。具體而言，它會驗證與 FreeRTOS 程式庫的移植層界面，以及 FreeRTOS 測試儲存庫是否正確實作。它也會使用 end-to-end測試 AWS IoT Core。IDT for FreeRTOS 執行的測試會在 [FreeRTOS GitHub 儲存庫](https://github.com/FreeRTOS/FreeRTOS-Libraries-Integration-Tests)中定義。
IDT for FreeRTOS 會以其在待測微控制器裝置上閃爍的內嵌應用程式的形式執行測試。應用程式二進位映像包括 FreeRTOS、移植的 FreeRTOS 介面和主機板裝置驅動程式。測試的目的是驗證移植的 FreeRTOS 介面在您的裝置驅動程式上是否正常運作。
IDT for FreeRTOS 會產生測試報告，您可以提交至 AWS IoT 以取得 AWS 合作夥伴裝置目錄中列出的硬體。如需詳細資訊，請參閱 [AWS 裝置資格計劃](https://aws.amazon.com/partners/dqp/)。
IDT for FreeRTOS 會在連接到待測裝置的主機電腦 (Windows、macOS 或 Linux) 上執行。IDT 會設定和協調測試案例，並彙總結果。它還提供命令列界面來管理執行測試。
為了測試您的裝置，IDT for FreeRTOS 會建立 AWS IoT 物件、FreeRTOS 群組、Lambda 函數等資源。為了建立這些資源，IDT for FreeRTOS 會使用 中設定的 AWS 登入`config.json`資料來代表您進行 API 呼叫。系統會在測試期間的不同時間點內佈建這些資源。
當您在主機電腦上執行 IDT for FreeRTOS 時，它會執行下列步驟：
1. 載入並驗證您的裝置和登入資料組態。
1. 對所需的本機和雲端資源執行選取的測試。
1. 清除本機和雲端資源。
1. 產生測試報告以指出主機板是否通過符合資格所需的測試。
# 設定 LTS 資格先決條件
本節說明使用 測試微控制器的先決條件 AWS IoT Device Tester。
## 準備 FreeRTOS 資格
**注意**
AWS IoT Device Tester for FreeRTOS 強烈建議使用最新的 FreeRTOS-LTS 版本修補程式版本。
IDT for FRQ 2.0 是 FreeRTOS 的資格。在執行 IDT FRQ 2.0 以獲得資格之前，您必須完成 FreeRTOS 資格指南中的[電路板](https://docs.aws.amazon.com/freertos/latest/qualificationguide/freertos-qualification.html)資格。 *FreeRTOS * 若要移植程式庫、測試和設定 `manifest.yml`，請參閱 [ FreeRTOS 移植指南中的移植 FreeRTOS 程式庫](https://docs.aws.amazon.com/freertos/latest/portingguide/afr-porting.html)。 *FreeRTOS * FRQ 2.0 包含不同的資格程序。如需詳細資訊，請參閱 *FreeRTOS * [資格指南中資格的最新變更](https://docs.aws.amazon.com/freertos/latest/qualificationguide/latest-changes.html)。
[FreeRTOS-Libraries-Integration-Tests](https://github.com/FreeRTOS/FreeRTOS-Libraries-Integration-Tests) 儲存庫必須存在，IDT 才能執行。請參閱 https：//[README.md](https://github.com/FreeRTOS/FreeRTOS-Libraries-Integration-Tests/blob/main/README.md)。FreeRTOS-Libraries-Integration-Tests 必須包含`manifest.yml`位於專案根目錄的 ，IDT 才能執行。
**注意**
IDT 取決於測試儲存庫對 的實作`UNITY_OUTPUT_CHAR`。測試輸出日誌和裝置日誌不得互相交錯。如需更多詳細資訊，請參閱 *FreeRTOS 移植指南*中的[實作程式庫日誌巨集](https://docs.aws.amazon.com/freertos/latest/portingguide/afr-library-logging-macros.html)一節。
## 下載 IDT for FreeRTOS
每個 FreeRTOS 版本都有對應的 IDT for FreeRTOS 版本，以執行資格測試。從 FreeRTOS [支援的 版本下載適當的 IDT for FreeRTOS AWS IoT Device Tester 版本](https://docs.aws.amazon.com/freertos/latest/userguide/dev-test-versions-afr.html)。
將 IDT for FreeRTOS 解壓縮到檔案系統上具有讀取和寫入許可的位置。由於 Microsoft Windows 具有路徑長度的字元限制，請將 IDT for FreeRTOS 擷取到根目錄，例如 `C:\`或 `D:\`。
**注意**
多個使用者不得從共用位置執行 IDT，例如 NFS 目錄或 Windows 網路共用資料夾。這會導致當機或資料損毀。建議您將 IDT 套件解壓縮至本機磁碟機。
## 下載 Git
IDT 必須安裝 Git 作為先決條件，以確保原始碼完整性。
遵循 [GitHub](https://github.com/git-guides/install-git) 指南中的指示來安裝 Git。若要驗證目前安裝的 Git 版本，請在終端機輸入 `git --version` 命令。
**警告**
IDT 使用 Git 來對齊目錄的乾淨或骯髒狀態。如果未安裝 Git，`FreeRTOSIntegrity`測試群組將會失敗，或無法如預期執行。如果 IDT 傳回錯誤，例如 `git executable not found`或 `git command not found`，請安裝或重新安裝 Git，然後再試一次。
**Topics**
+ [準備 FreeRTOS 資格](#idt-preparing-qualification)
+ [下載 IDT for FreeRTOS](#idt-download-dev-tester-afr)
+ [下載 Git](#idt-download-git)
+ [建立 AWS 帳戶](#lts-config-aws-account)
+ [AWS IoT Device Tester 受管政策](#managed-policy)
+ [（選用） 安裝 AWS Command Line Interface](#install-cli)
## 建立 AWS 帳戶
**注意**
僅在下列 中支援完整的 IDT 資格套件 AWS 區域
美國東部 (維吉尼亞北部)
美國西部 (奧勒岡)
亞太地區 (東京)
歐洲 (愛爾蘭)
為了測試您的裝置，IDT for FreeRTOS 會建立 AWS IoT 物件、FreeRTOS 群組和 Lambda 函數等資源。若要建立這些資源，IDT for FreeRTOS 會要求您建立和設定 AWS 帳戶，以及授予 IDT for FreeRTOS 在執行測試時代表您存取資源的 IAM 政策。
下列步驟是建立和設定 AWS 您的帳戶。
1. 如果您已有 AWS 帳戶，請跳到下一個步驟。否則，請建立 [AWS 帳戶](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/)。
1. 請遵循[建立 IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html)中的步驟。此時請勿新增許可或政策。
1. 若要執行 OTA 資格測試，請前往步驟 4。否則請前往步驟 5。
1. 將 OTA IAM 許可內嵌政策連接至您的 IAM 角色。
1.
**重要**
下列政策範本會授予 IDT 許可，允許使用者建立角色、建立政策，以及將政策附加至角色。IDT for FreeRTOS 會將這些許可用於建立角色的測試。雖然政策範本不會為使用者提供管理員權限，但許可可用來取得 AWS 您帳戶的管理員存取權。
1. 請依照下列步驟，將必要的許可連接至您的 IAM 角色：
1. 在**許可**頁面上，選擇**新增許可**。
1. 選擇**建立內嵌政策**。
1. 選擇 **JSON** 索引標籤，並將以下權限複製到 **JSON** 文字方塊中。如果您不在中國區域，請使用**大多數**區域下的範本。如果您位於中國區域，請使用**北京和寧夏區域的** 範本。
------
#### [ Most Regions ]
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iotdeviceadvisor:*",
"Resource": [
"arn:aws:iotdeviceadvisor:*:*:suiterun/*/*",
"arn:aws:iotdeviceadvisor:*:*:suitedefinition/*"
]
},
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::*:role/idt*",
"Condition": {
"StringEquals": {
"iam:PassedToService": "iotdeviceadvisor.amazonaws.com"
}
}
},
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke*",
"iam:ListRoles",
"iot:Connect",
"iot:CreateJob",
"iot:DeleteJob",
"iot:DescribeCertificate",
"iot:DescribeEndpoint",
"iot:DescribeJobExecution",
"iot:DescribeJob",
"iot:DescribeThing",
"iot:GetPolicy",
"iot:ListAttachedPolicies",
"iot:ListCertificates",
"iot:ListPrincipalPolicies",
"iot:ListThingPrincipals",
"iot:ListThings",
"iot:Publish",
"iot:UpdateThingShadow",
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:DescribeLogGroups",
"logs:DescribeLogStreams",
"logs:PutLogEvents",
"logs:PutRetentionPolicy"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "iotdeviceadvisor:*",
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "logs:DeleteLogGroup",
"Resource": "arn:aws:logs:*:*:log-group:/aws/iot/deviceadvisor/*"
},
{
"Effect": "Allow",
"Action": "logs:GetLogEvents",
"Resource": "arn:aws:logs:*:*:log-group:/aws/iot/deviceadvisor/*:log-stream:*"
},
{
"Effect": "Allow",
"Action": [
"iam:CreatePolicy",
"iam:DetachRolePolicy",
"iam:DeleteRolePolicy",
"iam:DeletePolicy",
"iam:CreateRole",
"iam:DeleteRole",
"iam:AttachRolePolicy"
],
"Resource": [
"arn:aws:iam::*:policy/idt*",
"arn:aws:iam::*:role/idt*"
]
},
{
"Effect": "Allow",
"Action": [
"ssm:GetParameters"
],
"Resource": [
"arn:aws:ssm:*::parameter/aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-x86_64-gp2"
]
},
{
"Effect": "Allow",
"Action": [
"ec2:DescribeInstances",
"ec2:RunInstances",
"ec2:CreateSecurityGroup",
"ec2:CreateTags",
"ec2:DeleteTags"
],
"Resource": [
"*"
]
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateKeyPair",
"ec2:DeleteKeyPair"
],
"Resource": [
"arn:aws:ec2:*:*:key-pair/idt-ec2-ssh-key-*"
]
},
{
"Effect": "Allow",
"Condition": {
"StringEqualsIgnoreCase": {
"aws:ResourceTag/Owner": "IoTDeviceTester"
}
},
"Action": [
"ec2:TerminateInstances",
"ec2:DeleteSecurityGroup",
"ec2:AuthorizeSecurityGroupIngress",
"ec2:RevokeSecurityGroupIngress"
],
"Resource": [
"*"
]
}
]
}
```
------
------
#### [ Beijing and Ningxia Regions ]
下列政策範本可用於北京和寧夏區域。
------
1. 完成時，請選擇 **Review policy (檢閱政策)**。
1. 輸入 **IDTFreeRTOSIAMPermissions** 做為政策名稱。
1. 選擇**建立政策**。
1. 將 **AWSIoTDeviceTesterForFreeRTOSFullAccess** 連接至您的 IAM 角色。
1. 若要將必要的許可連接至您的 IAM 角色：
1. 在**許可**頁面上，選擇**新增許可**。
1. 選擇**連接政策**。
1. 搜尋 **AWSIoTDeviceTesterForFreeRTOSFullAccess** 政策。勾選方塊。
1. 選擇**新增許可**。
1. 匯出 IDT 的登入資料。如需詳細資訊，請參閱[取得 CLI 存取的 IAM 角色登入](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtogetcredentials.html)資料。
## AWS IoT Device Tester 受管政策
`AWSIoTDeviceTesterForFreeRTOSFullAccess` 受管政策包含下列版本檢查、自動更新功能和指標集合的 AWS IoT Device Tester 許可。
+ `iot-device-tester:SupportedVersion`
AWS IoT Device Tester 准許擷取支援的產品、測試套件和 IDT 版本清單。
+ `iot-device-tester:LatestIdt`
AWS IoT Device Tester 准許擷取可供下載的最新 IDT 版本。
+ `iot-device-tester:CheckVersion`
AWS IoT Device Tester 准許檢查 IDT、測試套件和產品的版本相容性。
+ `iot-device-tester:DownloadTestSuite`
AWS IoT Device Tester 准許下載測試套件更新。
+ `iot-device-tester:SendMetrics`
AWS 准許收集有關 AWS IoT Device Tester 內部使用的指標。
## （選用） 安裝 AWS Command Line Interface
您可能偏好使用 AWS CLI 來執行一些操作。如果您沒有 AWS CLI 安裝 ，請遵循[安裝 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/installing.html)中的指示。
**aws configure** 從命令列執行， AWS CLI 為您要使用的 AWS 區域設定 。如需支援 IDT for FreeRTOS AWS 的區域資訊，請參閱[AWS 區域和端點](https://docs.aws.amazon.com/general/latest/gr/rande.html#amazon-freertos-ota-control)。如需詳細資訊，**aws configure**請參閱[使用 進行快速組態**aws configure**](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-config)。
# 微控制器電路板的第一個測試
您可以使用 IDT for FreeRTOS 來測試 FreeRTOS 程式庫的實作。在您為主機板的裝置驅動程式移植 FreeRTOS 程式庫之後，請使用 AWS IoT Device Tester 在您的微型控制器主機板上執行資格測試。
## 新增程式庫移植層
若要為您的裝置移植 FreeRTOS，請參閱 [FreeRTOS 移植指南](https://docs.aws.amazon.com/freertos/latest/portingguide/porting-guide.html)。實作 FreeRTOS 測試儲存庫和移植 FreeRTOS 層時，您必須提供每個程式庫的`manifest.yml`路徑，包括測試儲存庫。此檔案將位於原始程式碼的根目錄中。如需詳細資訊，請參閱[資訊清單檔案說明](https://docs.aws.amazon.com/freertos/latest/qualificationguide/afq-checklist-manifest-instr.html)。
## 設定您的 AWS 登入資料 AWS IoT Device Tester ，讓 與 AWS 雲端通訊
您需要設定 的 AWS 登入資料 AWS IoT Device Tester ，才能與 AWS 雲端通訊。如需詳細資訊，請參閱[設定 AWS 用於開發的登入資料和區域](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/setup-credentials.html)。有效的 AWS 登入資料會在`devicetester_extract_location/devicetester_freertos_[win|mac|linux]/configs/config.json`組態檔案中指定。
```
"auth": {
"method": "environment"
}
"auth": {
"method": "file",
"credentials": {
"profile": ""
}
}
```
`config.json` 檔案的 `auth` 屬性具有控制 AWS 身分驗證的方法欄位，可宣告為檔案或環境。將 欄位設定為環境會從主機機器的環境變數提取您的 AWS 登入資料。將 欄位設定為 檔案會從`.aws/credentials`組態檔案匯入指定的設定檔。
**Topics**
+ [新增程式庫移植層](#lts-add-port-layer)
+ [設定您的 AWS 登入資料 AWS IoT Device Tester ，讓 與 AWS 雲端通訊](#lts-cfg-aws-afr)
+ [在 IDT for FreeRTOS 中建立裝置集區](lts-cfg-dt-dp.md)
+ [設定建置、刷新和測試設定](lts-cfg-dt-ud.md)
# 在 IDT for FreeRTOS 中建立裝置集區
系統會將要測試的裝置整理為裝置集區，每個裝置集區都包含一個或多個相同的裝置。您可以設定 IDT for FreeRTOS 來測試單一裝置或集區中的多個裝置。為了加速資格程序，IDT for FreeRTOS 可以平行測試具有相同規格的裝置。該工具會採用循環配置資源方法，在裝置集區的每個裝置上執行不同的測試群組。
`device.json` 檔案的頂層具有 陣列。每個陣列屬性都是新的裝置集區。每個裝置集區都有裝置陣列屬性，該屬性已宣告多個裝置。在 範本中，裝置集區中只有一個裝置。您可以在 `configs` 資料夾中編輯 `device.json` 範本的 `devices` 區段，進而新增一或多個裝置至裝置集區。
**注意**
相同集區中的所有裝置都必須具有相同的技術規格和 SKU。若要為不同的測試群組啟用來源碼的平行建置，IDT for FreeRTOS 會將來源碼複製到 IDT for FreeRTOS 解壓縮資料夾內的結果資料夾。您必須使用 `testdata.sourcePath`變數，在建置或 Flash 命令中參考原始程式碼路徑。IDT for FreeRTOS 會將此變數取代為複製來源碼的暫時路徑。如需詳細資訊，請參閱[IDT for FreeRTOS 變數](lts-dt-vars.md)。
以下是用來建立具有多個裝置之裝置集區的範例`device.json`檔案。
```
[
{
"id": "pool-id",
"sku": "sku",
"features": [
{
"name": "Wifi",
"value": "Yes | No"
},
{
"name": "Cellular",
"value": "Yes | No"
},
{
"name": "BLE",
"value": "Yes | No"
},
{
"name": "PKCS11",
"value": "RSA | ECC | Both"
},
{
"name": "OTA",
"value": "Yes | No",
"configs": [
{
"name": "OTADataPlaneProtocol",
"value": "MQTT | HTTP | None"
}
]
},
{
"name": "KeyProvisioning",
"value": "Onboard | Import | Both | No"
}
],
"devices": [
{
"id": "device-id",
"connectivity": {
"protocol": "uart",
"serialPort": "/dev/tty*"
},
"secureElementConfig" : {
"publicKeyAsciiHexFilePath": "absolute-path-to/public-key-txt-file: contains-the-hex-bytes-public-key-extracted-from-onboard-private-key",
"publiDeviceCertificateArn": "arn:partition:iot:region:account-id:resourcetype:resource:qualifier",
"secureElementSerialNumber": "secure-element-serialNo-value",
"preProvisioned" : "Yes | No",
"pkcs11JITPCodeVerifyRootCertSupport": "Yes | No"
},
"identifiers": [
{
"name": "serialNo",
"value": "serialNo-value"
}
]
}
]
}
]
```
以下是 `device.json` 檔案中使用的屬性：
** `id` **
使用者定義的英數字 ID，可唯一識別裝置集區。屬於集區的裝置必須為相同類型。執行測試套件時，集區中的裝置將用來將工作負載平行化。
** `sku` **
可唯一識別您要測試之主機板的英數字元值。SKU 用來追蹤合格的主機板。
如果您想要在 AWS Partner Device Catalog 中列出您的電路板，您在此處指定的 SKU 必須符合您在列出程序中使用的 SKU。
** `features` **
包含裝置支援功能的陣列。 AWS IoT Device Tester 會使用此資訊選取要執行的資格測試。
支援的值如下：
** `Wifi` **
指出您的面板是否具有 Wi-Fi 功能。
** `Cellular` **
指出您的電路板是否具有行動功能。
** `PKCS11` **
指出面板支援的公有金鑰密碼編譯演算法。您需要 PKCS11 才能獲得資格。支援的值為 `ECC`、 `RSA`和 `Both`。 `Both`表示電路板同時支援 `ECC`和 `RSA`。
** `KeyProvisioning` **
指出將受信任的 X.509 用戶端憑證寫入面板的方法。
有效值為 `Import`、 `Onboard``Both`和 `No`。需要 `Both`、 `Onboard`或 `No`金鑰佈建才能符合資格。 `Import`單獨不是有效的資格選項。
+ `Import` 只有在您的電路板允許匯入私有金鑰時，才能使用 。選取 `Import` 不是資格的有效組態，應僅用於測試用途，特別是 PKCS11 測試案例。 `Onboard``Both`或 `No`是資格所需。
+ `Onboard` 如果您的電路板支援內建私有金鑰 （例如，如果裝置具有安全元素，或者您偏好產生自己的裝置金鑰對和憑證），請使用 。請務必在每個裝置區段中新增一個 `secureElementConfig` 元素，並在 `publicKeyAsciiHexFilePath` 欄位中放置公有金鑰檔案的絕對路徑。
+ `Both` 如果您的主機板支援匯入私有金鑰和產生內建金鑰以進行金鑰佈建，請使用 。
+ `No` 如果您的電路板不支援金鑰佈建，請使用 。只有在您的裝置也已預先佈建時， `No`才是有效的選項。
** `OTA` **
指出您的面板是否支援無線 (OTA) 更新功能。`OtaDataPlaneProtocol` 屬性指出裝置支援哪個 OTA 資料平面通訊協定。需要具有 HTTP 或 MQTT 資料平面通訊協定的 OTA 才能符合資格。若要在測試時略過執行中的 OTA 測試，請將 OTA 功能設定為 ，`No`並將 `OtaDataPlaneProtocol` 屬性設定為 `None`。這不會是資格執行。
** `BLE` **
指出您的面板是否支援低功耗藍牙 (BLE)。
** `devices.id` **
使用者定義的唯一識別符，用於識別要測試的裝置。
** `devices.connectivity.serialPort` **
要測試用於連接到裝置之主機電腦的序列埠。
** `devices.secureElementConfig.PublicKeyAsciiHexFilePath` **
如果您的電路板不是 `pre-provisioned`或未提供`PublicDeviceCertificateArn`，則為必要項目。由於 `Onboard`是金鑰佈建的必要類型，因此 FullTransportInterfaceTLS 測試群組目前需要此欄位。如果您的裝置是 `pre-provisioned`， `PublicKeyAsciiHexFilePath` 是選用的，不需要包含。
以下區塊是 檔案的絕對路徑，其中包含從`Onboard`私有金鑰擷取的十六進位位元組公有金鑰。
```
3059 3013 0607 2a86 48ce 3d02 0106 082a
8648 ce3d 0301 0703 4200 04cd 6569 ceb8
1bb9 1e72 339f e8cf 60ef 0f9f b473 33ac
6f19 1813 6999 3fa0 c293 5fae 08f1 1ad0
41b7 345c e746 1046 228e 5a5f d787 d571
dcb2 4e8d 75b3 2586 e2cc 0c
```
如果您的公有金鑰是 .der 格式，您可以直接對公有金鑰進行十六進位編碼，以產生十六進位檔案。
若要從 .der 公有金鑰產生 hex 檔案，請輸入下列**xxd**命令：
```
xxd -p pubkey.der > outFile
```
如果您的公有金鑰是 .pem 格式，您可以擷取 base64 編碼的標頭和頁尾，並將其解碼為二進位格式。然後，您會對二進位字串進行十六進位編碼，以產生十六進位檔案。
若要產生 .pem 公有金鑰的十六進位檔案，請執行下列動作：
1. 執行下列**base64**命令，從公有金鑰移除 base64 標頭和頁尾。然後，名為 的解碼金鑰`base64key`會輸出到檔案 `pubkey.der`：
```
base64 —decode base64key > pubkey.der
```
1. 執行下列**xxd**命令以`pubkey.der`轉換為十六進位格式。產生的金鑰會儲存為 `outFile`
```
xxd -p pubkey.der > outFile
```
** `devices.secureElementConfig.PublicDeviceCertificateArn` **
上傳到之安全元素的憑證 ARN AWS IoT Core。如需將憑證上傳至 的資訊 AWS IoT Core，請參閱《 *AWS IoT 開發人員指南*》中的 [X.509 用戶端憑證](https://docs.aws.amazon.com/iot/latest/developerguide/x509-client-certs.html)。
** `devices.secureElementConfig.SecureElementSerialNumber` **
(選用) 安全元素的序號。序號是選擇性用來建立 JITR 金鑰佈建的裝置憑證。
** `devices.secureElementConfig.preProvisioned` **
（選用） 如果裝置具有具有鎖定登入資料的預先佈建安全元素，且無法匯入、建立或銷毀物件，請設定為「是」。如果此屬性設定為**是**，您必須提供對應的 pkcs11 標籤。
** `devices.secureElementConfig.pkcs11JITPCodeVerifyRootCertSupport` **
（選用） 如果裝置的 corePKCS11 實作支援 JITP 儲存，請將 設定為**是**。這將在測試核心 PKCS 11 時啟用 JITP `codeverify`測試，並且需要提供程式碼驗證金鑰、JITP 憑證和根憑證 PKCS 11 標籤。
** `identifiers` **
(選用) 任意的名稱/值組的陣列。您可以在下一節所述的建置和刷新命令中使用這些值。
# 設定建置、刷新和測試設定
IDT for FreeRTOS 會自動在您的主機板上建置和閃爍測試。若要啟用此功能，您必須設定 IDT 來執行硬體的建置和快閃記憶體命令。您可以在位於 `config` 資料夾的 `userdata.json` 範本檔案中配置建置和刷新命令設定。
# 配置設定以測試裝置
您可以在 `configs/userdata.json` 檔案中進行建置、刷新和測試設定。下列 JSON 範例示範如何設定 IDT for FreeRTOS 來測試多個裝置：
```
{
"sourcePath": "",
"retainModifiedSourceDirectories": true | false,
"freeRTOSVersion": "",
"freeRTOSTestParamConfigPath": "{{testData.sourcePath}}/path/from/source/path/to/test_param_config.h",
"freeRTOSTestExecutionConfigPath": "{{testData.sourcePath}}/path/from/source/path/to/test_execution_config.h",
"buildTool": {
"name": "your-build-tool-name",
"version": "your-build-tool-version",
"command": [
" -any-additional-flags {{testData.sourcePath}}"
]
},
"flashTool": {
"name": "your-flash-tool-name",
"version": "your-flash-tool-version",
"command": [
" -any-additional-flags {{testData.sourcePath}} -any-additional-flags"
]
},
"testStartDelayms": 0,
"echoServerConfiguration": {
"keyGenerationMethod": "EC | RSA",
"serverPort": 9000
},
"otaConfiguration": {
"otaE2EFirmwarePath": "{{testData.sourcePath}}/relative-path-to/ota-image-generated-in-build-process",
"otaPALCertificatePath": "/path/to/ota/pal/certificate/on/device",
"deviceFirmwarePath" : "/path/to/firmware/image/name/on/device",
"codeSigningConfiguration": {
"signingMethod": "AWS | Custom",
"signerHashingAlgorithm": "SHA1 | SHA256",
"signerSigningAlgorithm": "RSA | ECDSA",
"signerCertificate": "arn:partition:service:region:account-id:resource:qualifier | /absolute-path-to/signer-certificate-file",
"untrustedSignerCertificate": "arn:partition:service:region:account-id:resourcetype:resource:qualifier",
"signerCertificateFileName": "signerCertificate-file-name",
"compileSignerCertificate": true | false,
// ***********Use signerPlatform if you choose AWS for signingMethod***************
"signerPlatform": "AmazonFreeRTOS-Default | AmazonFreeRTOS-TI-CC3220SF"
]
}
},
**********
This section is used for PKCS #11 labels of private key, public key, device certificate, code verification key, JITP certificate, and root certificate.
When configuring PKCS11, you set up labels and you must provide the labels of the device certificate, public key,
and private key for the key generation type (EC or RSA) it was created with. If your device supports PKCS11 storage of JITP certificate,
code verification key, and root certificate, set 'pkcs11JITPCodeVerifyRootCertSupport' to 'Yes' in device.json and provide the corresponding labels.
**********
"pkcs11LabelConfiguration":{
"pkcs11LabelDevicePrivateKeyForTLS": "",
"pkcs11LabelDevicePublicKeyForTLS": "",
"pkcs11LabelDeviceCertificateForTLS": "",
"pkcs11LabelPreProvisionedECDevicePrivateKeyForTLS": "",
"pkcs11LabelPreProvisionedECDevicePublicKeyForTLS": "",
"pkcs11LabelPreProvisionedECDeviceCertificateForTLS": "",
"pkcs11LabelPreProvisionedRSADevicePrivateKeyForTLS": "",
"pkcs11LabelPreProvisionedRSADevicePublicKeyForTLS": "",
"pkcs11LabelPreProvisionedRSADeviceCertificateForTLS": "",
"pkcs11LabelCodeVerifyKey": "",
"pkcs11LabelJITPCertificate": "",
"pkcs11LabelRootCertificate": ""
}
}
```
以下列出 `userdata.json` 中使用的屬性：
** `sourcePath` **
移植 FreeRTOS 原始程式碼根目錄的路徑。
** `retainModifiedSourceDirectories` **
（選用） 檢查是否要保留建置和刷新期間用於偵錯的修改來源目錄。如果設為 `true`，修改後的來源目錄會命名為 retainedSrc，並在每個測試群組執行中的結果日誌資料夾中找到。如果未包含， 欄位會預設為 `false`。
** `freeRTOSTestParamConfigPath` **
FreeRTOS-Libraries-Integration-Tests 整合的 `test_param_config.h` 檔案路徑。此檔案必須使用`{{testData.sourcePath}}`預留位置變數，使其相對於來源碼 root。 AWS IoT Device Tester 使用此檔案中的參數來設定測試。
** `freeRTOSTestExecutionConfigPath` **
FreeRTOS-Libraries-Integration-Tests 整合的 `test_execution_config.h` 檔案路徑。此檔案必須使用`{{testData.sourcePath}}`預留位置變數，使其相對於儲存庫 root。 AWS IoT Device Tester 使用此檔案來控制必須執行的測試。
** `freeRTOSVersion` **
FreeRTOS 的版本，包括實作中使用的修補程式版本。請參閱 [AWS IoT Device Tester FreeRTOS 支援的 版本，以取得與 for FreeRTOS](https://docs.aws.amazon.com/freertos/latest/userguide/dev-test-versions-afr.html) FreeRTOS 相容的 FreeRTOS AWS IoT Device Tester 版本。
** `buildTool` **
用於建置原始程式碼的 命令。建置命令中對來源碼路徑的所有參考都必須取代為 AWS IoT Device Tester 變數 `{{testData.sourcePath}}`。使用`{{config.idtRootPath}}`預留位置參考相對於 AWS IoT Device Tester 根路徑的建置指令碼。
** `flashTool` **
將映像刷新到裝置的命令。所有對 flash 命令中原始程式碼路徑的參考都必須取代為 AWS IoT Device Tester 變數 `{{testData.sourcePath}}`。使用`{{config.idtRootPath}}`預留位置參考相對於 AWS IoT Device Tester 根路徑的快閃記憶體指令碼。
使用 FRQ 2.0 的新整合測試結構不需要路徑變數，例如 `{{enableTests}}`和 `{{buildImageName}}`。OTA 端對端測試會使用 [ FreeRTOS-Libraries-Integration-Tests](https://github.com/FreeRTOS/FreeRTOS-Libraries-Integration-Tests/blob/main/config_template/) GitHub 儲存庫中提供的組態範本執行。如果您的父系來源專案中存在 GitHub 儲存庫中的檔案，則測試之間不會變更原始程式碼。如果需要 OTA 端對端的不同建置映像，您必須在建置指令碼中建置此映像，並在 下指定的`userdata.json`檔案中指定它`otaConfiguration`。
** `testStartDelayms` **
指定 FreeRTOS 測試執行器在開始執行測試之前要等待多少毫秒。如果待測裝置在 IDT 因網路或其他延遲問題而有機會連線和開始記錄之前，開始輸出重要的測試資訊，這會很有用。此值僅適用於 FreeRTOS 測試群組，不適用於未使用 FreeRTOS 測試執行器的其他測試群組，例如 OTA 測試。如果您收到與**預期 10 相關的錯誤，但收到 5**，則此欄位應設定為 5000。
** `echoServerConfiguration` **
設定 TLS 測試之 echo 伺服器的組態。此欄位為必填。
** `keyGenerationMethod` **
回應伺服器是使用此選項設定。選項為 EC 或 RSA。
** `serverPort` **
回應伺服器執行所在的連接埠號碼。
** `otaConfiguration` **
OTA PAL 和 OTA E2E 測試的組態。此欄位為必填。
**`otaE2EFirmwarePath`**
IDT 用於 OTA 端對端測試的 OTA 儲存貯體映像路徑。
** `otaPALCertificatePath` **
裝置上 OTA PAL 測試的憑證路徑。這用於驗證簽章。例如，**ecdsa-sha256-signer.crt.pem**。
** `deviceFirmwarePath` **
要開機之韌體映像的硬式編碼名稱路徑。如果您的裝置不使用檔案系統進行韌體開機，請將此欄位指定為 `'NA'`。如果您的裝置使用檔案系統進行韌體開機，請指定韌體開機映像的路徑或名稱。
** `codeSigningConfiguration` **
** `signingMethod` **
程式碼簽章方法。可能的值為 AWS 或 Custom。
對於北京和寧夏區域，該區域不支援使用 Custom. AWS code 簽署。
** `signerHashingAlgorithm` **
裝置上支援的雜湊演算法。可能的值為 `SHA1` 或 `SHA256`。
** `signerSigningAlgorithm` **
裝置上支援的簽署演算法。可能的值為 `RSA` 或 `ECDSA`。
** `signerCertificate` **
用於 OTA 的信任憑證。對於 AWS 程式碼簽署方法，請針對上傳至 AWS Certificate Manager 的信任憑證使用 Amazon Resource Name (ARN)。對於自訂程式碼簽署方法，請使用簽署者憑證檔案的絕對路徑。如需有關建立信任憑證的資訊，請參閱[建立程式碼簽署憑證](https://docs.aws.amazon.com/freertos/latest/userguide/ota-code-sign-cert.html)。
** `untrustedSignerCertificate` **
某些 OTA 測試中使用的第二個憑證的 ARN 或檔案路徑，做為不受信任的憑證。如需建立憑證的資訊，請參閱[建立程式碼簽署憑證](https://docs.aws.amazon.com//freertos/latest/userguide/ota-code-sign-cert.html)。
** `signerCertificateFileName` **
裝置上的程式碼簽署憑證檔案名稱。此值必須符合您在執行 `aws acm import-certificate`命令時提供的檔案名稱。
** `compileSignerCertificate` **
決定簽章驗證憑證狀態的布林值。有效值為 `true` 和 `false`。
如果未佈建或刷新程式碼簽署者簽章驗證憑證，請將此值設為 **true**。它必須編譯到專案中。 會 AWS IoT Device Tester 擷取信任的憑證並將其編譯到 `aws_codesigner_certificate.h`。
** `signerPlatform` **
AWS Code Signer 在建立 OTA 更新任務時使用的簽署和雜湊演算法。目前，此欄位的可能值為 `AmazonFreeRTOS-TI-CC3220SF` 和 `AmazonFreeRTOS-Default`。
+ 如果是 `SHA1` 和 `RSA` 則選擇 `AmazonFreeRTOS-TI-CC3220SF`。
+ 如果是 `SHA256` 和 `ECDSA` 則選擇 `AmazonFreeRTOS-Default`。
+ 如果您的組態需要 `SHA256` \$1 `RSA` 或 `SHA1` \$1 `ECDSA`，請聯絡我們以取得進一步支援。
+ 如果您針對 `signingMethod` 選擇 `Custom`，請設定 `signCommand`。
** `signCommand` **
命令中需要 `{{inputImageFilePath}}` 和 `{{outputSignatureFilePath}}` 兩個預留位置。`{{inputImageFilePath}}` 是由 IDT 建立要簽署之影像的檔案路徑。`{{outputSignatureFilePath}} ` 是將由指令碼產生簽章的檔案路徑。
** `pkcs11LabelConfiguration` **
PKCS11 標籤組態至少需要一組裝置憑證標籤、公有金鑰標籤和私有金鑰標籤，才能執行 PKCS11 測試群組。所需的 PKCS11 標籤是以您在 `device.json` 檔案中的裝置組態為基礎。如果預先佈建在 中設定為**是**`device.json`，則根據 PKCS11 功能的選擇，所需的標籤必須是下列其中一項。
+ `PreProvisionedEC`
+ `PreProvisionedRSA`
如果預先佈建在 中設定為**否**`device.json`，則所需的標籤為：
+ `pkcs11LabelDevicePrivateKeyForTLS`
+ `pkcs11LabelDevicePublicKeyForTLS`
+ `pkcs11LabelDeviceCertificateForTLS`
只有當您在 `pkcs11JITPCodeVerifyRootCertSupport` `device.json` 檔案中為 選取**是**時，才需要以下三個標籤。
+ `pkcs11LabelCodeVerifyKey`
+ `pkcs11LabelRootCertificate`
+ `pkcs11LabelJITPCertificate`
這些欄位的值應與 [FreeRTOS 移植指南](https://docs.aws.amazon.com/freertos/latest/portingguide/afr-porting-pkcs.html)中定義的值相符。
** `pkcs11LabelDevicePrivateKeyForTLS` **
（選用） 此標籤用於私有金鑰的 PKCS \$111 標籤。對於具有金鑰佈建的內建和匯入支援的裝置，此標籤用於測試。此標籤可能與針對預先佈建案例定義的標籤不同。如果您將金鑰佈建設定為**否**，並將預先佈建設定為**是**，在 中`device.json`，這會取消定義。
** `pkcs11LabelDevicePublicKeyForTLS` **
（選用） 此標籤用於公有金鑰的 PKCS \$111 標籤。對於具有金鑰佈建的內建和匯入支援的裝置，此標籤用於測試。此標籤可能與針對預先佈建案例定義的標籤不同。如果您將金鑰佈建設定為**否**，並將預先佈建設定為**是**，在 中`device.json`，這會取消定義。
** `pkcs11LabelDeviceCertificateForTLS` **
（選用） 此標籤用於裝置憑證的 PKCS \$111 標籤。對於具有金鑰佈建的內建和匯入支援的裝置，此標籤將用於測試。此標籤可能與針對預先佈建案例定義的標籤不同。如果您將金鑰佈建設定為**否**，並將預先佈建設定為**是**，在 中`device.json`，這會取消定義。
** `pkcs11LabelPreProvisionedECDevicePrivateKeyForTLS` **
（選用） 此標籤用於私有金鑰的 PKCS \$111 標籤。對於具有安全元素或硬體限制的裝置，這會有不同的標籤來保留 AWS IoT 登入資料。如果您的裝置支援使用 EC 金鑰預先佈建，請提供此標籤。當preProvisioned在 中設定為**是**`device.json`時，必須提供此標籤、 `pkcs11LabelPreProvisionedRSADevicePrivateKeyForTLS`或兩者。此標籤可能與為加入和匯入案例定義的標籤不同。
** `pkcs11LabelPreProvisionedECDevicePublicKeyForTLS` **
（選用） 此標籤用於公有金鑰的 PKCS \$111 標籤。對於具有安全元素或硬體限制的裝置，這會有不同的標籤來保留 AWS IoT 登入資料。如果您的裝置支援使用 EC 金鑰預先佈建，請提供此標籤。當preProvisioned在 中設定為**是**`device.json`時，必須提供此標籤、 `pkcs11LabelPreProvisionedRSADevicePublicKeyForTLS`或兩者。此標籤可能與為加入和匯入案例定義的標籤不同。
** `pkcs11LabelPreProvisionedECDeviceCertificateForTLS` **
（選用） 此標籤用於裝置憑證的 PKCS \$111 標籤。對於具有安全元素或硬體限制的裝置，這會有不同的標籤來保留 AWS IoT 登入資料。如果您的裝置支援使用 EC 金鑰預先佈建，請提供此標籤。當preProvisioned在 中設定為**是**`device.json`時，必須提供此標籤、 `pkcs11LabelPreProvisionedRSADeviceCertificateForTLS`或兩者。此標籤可能與為加入和匯入案例定義的標籤不同。
** `pkcs11LabelPreProvisionedRSADevicePrivateKeyForTLS` **
（選用） 此標籤用於私有金鑰的 PKCS \$111 標籤。對於具有安全元素或硬體限制的裝置，這會有不同的標籤來保留 AWS IoT 登入資料。如果您的裝置支援使用 RSA 金鑰預先佈建，請提供此標籤。當preProvisioned在 中設定為**是**`device.json`時，必須提供此標籤、 `pkcs11LabelPreProvisionedECDevicePrivateKeyForTLS`或兩者。
** `pkcs11LabelPreProvisionedRSADevicePublicKeyForTLS` **
（選用） 此標籤用於公有金鑰的 PKCS \$111 標籤。對於具有安全元素或硬體限制的裝置，這會有不同的標籤來保留 AWS IoT 登入資料。如果您的裝置支援使用 RSA 金鑰預先佈建，請提供此標籤。當preProvisioned在 中設定為**是**`device.json`時，必須提供此標籤、 `pkcs11LabelPreProvisionedECDevicePublicKeyForTLS`或兩者。
** `pkcs11LabelPreProvisionedRSADeviceCertificateForTLS` **
（選用） 此標籤用於裝置憑證的 PKCS \$111 標籤。對於具有安全元素或硬體限制的裝置，這會有不同的標籤來保留 AWS IoT 登入資料。如果您的裝置支援使用 RSA 金鑰預先佈建，請提供此標籤。當preProvisioned在 中設定為**是**`device.json`時，必須提供此標籤、 `pkcs11LabelPreProvisionedECDeviceCertificateForTLS`或兩者。
** `pkcs11LabelCodeVerifyKey` **
（選用） 此標籤用於程式碼驗證金鑰的 PKCS \$111 標籤。如果您的裝置支援 JITP 憑證、程式碼驗證金鑰和根憑證的 PKCS \$111 儲存，請提供此標籤。當 `pkcs11JITPCodeVerifyRootCertSupport` 中的 `device.json` 設定為**是**時，必須提供此標籤。
** `pkcs11LabelJITPCertificate` **
（選用） 此標籤用於 JITP 憑證的 PKCS \$111 標籤。如果您的裝置支援 JITP 憑證、程式碼驗證金鑰和根憑證的 PKCS \$111 儲存，請提供此標籤。當 `pkcs11JITPCodeVerifyRootCertSupport` 中的 `device.json` 設定為**是**時，必須提供此標籤。
# IDT for FreeRTOS 變數
建置程式碼和刷新裝置的命令可能需要連線或裝置的其他資訊，才能成功執行。 AWS IoT Device Tester 可讓您參考刷新中的裝置資訊，並使用 [JsonPath](https://goessner.net/articles/JsonPath/) 建置命令。透過使用簡單的 JsonPath 運算式，您可以擷取 `device.json` 檔案中指定的必要資訊。
## 路徑變數
IDT for FreeRTOS 定義下列路徑變數，可用於命令列和組態檔案：
** `{{testData.sourcePath}}` **
展開至原始程式碼路徑。如果您使用此變數，則必須同時在快閃和建置命令中使用。
** `{{device.connectivity.serialPort}}` **
展開至序列埠。
** `{{device.identifiers[?(@.name == 'serialNo')].value[0]}}` **
展開至裝置的序號。
** `{{config.idtRootPath}}` **
展開至 AWS IoT Device Tester 根路徑。
# IDT for FreeRTOS 資格套件 2.0 的 UI (FRQ 2.0)
AWS IoT Device Tester for FreeRTOS (IDT for FreeRTOS) 包含 Web 型使用者介面 (UI)，您可以在其中與 IDT 命令列應用程式和相關組態檔案互動。您可以使用 IDT for FreeRTOS UI 為您的裝置建立新的組態，或修改現有的組態。您也可以使用 UI 呼叫 IDT 應用程式，並對您的裝置執行 FreeRTOS 測試。
如需有關如何使用命令列來執行資格測試的資訊，請參閱 [微控制器電路板的第一個測試](lts-qual-steps.md)。
本節說明 IDT for FreeRTOS UI 的先決條件，以及如何從 UI 執行資格測試。
**Topics**
+ [設定 IDT 先決條件](#lts-dev-tester-ui-prereqs)
+ [設定 AWS 登入資料以使用 IDT UI](lts-configure-aws-credentials.md)
+ [開啟 IDT for FreeRTOS UI](lts-open-idt-ui.md)
+ [建立新的組態](lts-create-new-configuration.md)
+ [修改現有的組態](lts-modify-existing-configuration.md)
+ [執行資格測試](lts-run-tests-from-ui.md)
## 設定 IDT 先決條件
若要透過 FreeRTOS UI 的 AWS IoT Device Tester (IDT) 執行測試，您必須完成 IDT FreeRTOS 資格 (FRQ) 2.x 頁面上[設定 LTS 資格先決條件](lts-idt-dev-tester-prereqs.md)的先決條件。
# 設定 AWS 登入資料以使用 IDT UI
您必須為您在 中建立的使用者設定 IAM AWS 使用者憑證[建立 AWS 帳戶](lts-idt-dev-tester-prereqs.md#lts-config-aws-account)。您可以使用下列兩種方式的其中之一指定登入資料：
+ 在登入資料檔案中
+ 做為環境變數
## 使用 AWS 登入資料檔案設定登入資料
IDT 會使用與 AWS CLI相同的登入資料檔案。如需詳細資訊，請參閱[組態與登入資料檔案](https://docs.aws.amazon.com/cli/latest/userguide/cli-config-files.html)。
登入資料檔案的位置會根據您使用的作業系統而有所不同：
+ **macOS 和 Linux** – `~/.aws/credentials`
+ **Windows** – `C:\Users\UserName\.aws\credentials`
以下列格式將您的 AWS 登入資料新增至 `credentials` 檔案：
```
[default]
aws_access_key_id = your_access_key_id
aws_secret_access_key = your_secret_access_key
```
**注意**
如果您不使用`default` AWS 設定檔，則必須在 IDT for FreeRTOS UI 中指定設定檔名稱。如需設定檔的詳細資訊，請參閱[組態和登入資料檔案設定](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)。
## 使用環境變數設定 AWS 登入資料
環境變數是由作業系統維護且由系統命令使用的變數。如果您關閉 SSH 工作階段，則不會儲存它們。IDT for FreeRTOS UI 使用 `AWS_ACCESS_KEY_ID`和 `AWS_SECRET_ACCESS_KEY`環境變數來存放您的 AWS 登入資料。
若要在 Linux、macOS 或 Unix 上設定這些變數，請使用 **export**：
```
export AWS_ACCESS_KEY_ID=your_access_key_id
export AWS_SECRET_ACCESS_KEY=your_secret_access_key
```
若要在 Windows 上設定這些變數，請使用 **set**：
```
set AWS_ACCESS_KEY_ID=your_access_key_id
set AWS_SECRET_ACCESS_KEY=your_secret_access_key
```
# 開啟 IDT for FreeRTOS UI
本主題說明如何開啟 IDT for FreeRTOS UI 以使用 FreeRTOS 資格套件。
**開啟 IDT for FreeRTOS UI**
1. 下載支援的 IDT for FreeRTOS 版本。然後將下載的封存解壓縮到您具有讀取和寫入許可的目錄。
1. 導覽至 IDT for FreeRTOS 安裝目錄：
```
cd devicetester-extract-location/bin
```
1. 執行下列命令以開啟 IDT for FreeRTOS UI：
------
#### [ Linux ]
```
.devicetester_ui_linux_x86-64
```
------
#### [ Windows ]
```
./devicetester_ui_win_x64-64
```
------
#### [ macOS ]
```
./devicetester_ui_mac_x86-64
```
**注意**
在 macOS 中，若要允許系統執行 UI，請前往**系統偏好設定 -> 安全性與隱私權**。當您執行測試時，您可能需要再這樣做三次。
------
IDT for FreeRTOS UI 會在您的預設瀏覽器中開啟。下列瀏覽器的最新三個主要版本支援 UI：
+ Google Chrome
+ Mozilla Firefox
+ Microsoft Edge
+ 適用於 macOS 的 Apple Safari
**注意**
為了獲得更好的體驗，我們建議 Google Chrome 或 Mozilla Firefox 存取 IDT for FreeRTOS UI。UI 不支援 Microsoft Internet Explorer。
**重要**
您必須先設定 AWS 登入資料，才能開啟 UI。如果您尚未設定登入資料，請關閉 IDT for FreeRTOS UI 瀏覽器視窗，遵循 中的步驟[設定 AWS 登入資料以使用 IDT UI](lts-configure-aws-credentials.md)，然後重新開啟 IDT for FreeRTOS UI。
# 建立新的組態
如果您是第一次使用，則必須建立新的組態，以設定 IDT for FreeRTOS 執行測試所需的 JSON 組態檔案。然後，您可以執行測試或修改建立的組態。
如需 `config.json`、 `device.json`和 `userdata.json` 檔案的範例，請參閱 [微控制器電路板的第一個測試](lts-qual-steps.md)。
**建立新的組態。**
1. 在 IDT for FreeRTOS UI 中，開啟導覽功能表，然後選擇**建立新組態**。
![\[Device Tester for FreeRTOS 介面搭配「建立新的組態」按鈕，以及有關自動自我測試微控制器的資訊。\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/images/gsg-create-configuration.png)
1. 遵循組態精靈來輸入用於執行資格測試的 IDT 組態設定。精靈會在位於 `devicetester-extract-location/config`目錄中的 JSON 組態檔案中設定下列設定。
+ **裝置設定** – 要測試之裝置的裝置集區設定。這些設定是在 `id`和 `sku`欄位中設定，以及 `config.json` 檔案中**裝置**集區的裝置區塊。
![\[適用於 FreeRTOS 的 Device Tester 組態畫面，其中包含用於設定裝置集區的識別碼和 SKU 欄位、連線方法、金鑰佈建、PKCS #11 設定、裝置詳細資訊輸入欄位等裝置設定選項，以及用於新增裝置或識別碼的控制項。\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/images/gsg-device-settings.png)
+ **AWS 帳戶設定** – AWS 帳戶 IDT for FreeRTOS 在測試執行期間用來建立 AWS 資源的資訊。這些設定是在 `config.json` 檔案中設定。
![\[AWS 帳戶 設定頁面，其中包含帳戶區域的欄位、檔案或環境的登入資料位置，以及設定檔名稱\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/images/gsg-account-settings.png)
+ **FreeRTOS 實作** – FreeRTOS 儲存庫和移植程式碼的絕對路徑，以及您想要執行 IDT FRQ 的 FreeRTOS 版本。從 `FreeRTOS-Libraries-Integration-Tests` GitHub 儲存庫到執行和參數組態標頭檔案的路徑。硬體的建置和刷新命令，可讓 IDT 自動在您的主機板上建置和刷新測試。這些設定是在 `userdata.json` 檔案中設定。
![\[包含儲存庫路徑、測試執行路徑、FreeRTOS 版本、建置工具詳細資訊和快閃記憶體工具設定的 FreeRTOS 實作組態區段。\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/images/gsg-implementation-settings.png)
+ **PKCS \$111 標籤和 Echo 伺服器** – 根據金鑰功能和金鑰佈建方法，對應至硬體中佈建之金鑰的 [PKCS \$111](https://docs.aws.amazon.com/freertos/latest/portingguide/afr-porting-pkcs.html) 標籤。傳輸介面測試的 echo 伺服器組態設定。這些設定是在 `userdata.json`和 `device.json`檔案中設定。
![\[PKCS #11 標籤和 Echo 伺服器組態，其中包含金鑰標籤、金鑰產生方法和伺服器連接埠號碼的輸入欄位\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/images/gsg-pkcs11-settings.png)
+ **Over-the-air(OTA) 更新** – 控制 OTA 功能測試的設定。這些設定是在 `device.json`和 `userdata.json` 檔案的 `features`區塊中設定。
![\[OTA 更新組態選項：略過測試、資料通訊協定、韌體路徑、PAL 憑證路徑、程式碼簽署、雜湊/簽署演算法、受信任/不受信任簽署者憑證、簽署者憑證檔案、編譯簽署者憑證、簽署者平台。\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/images/gsg-ota-settings.png)
1. 在**檢閱**頁面上，驗證您的組態資訊。
![\[Device Tester for FreeRTOS 的組態建立對話方塊，顯示有關使用編輯或執行測試的選項建立新的測試組態的詳細資訊。\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/images/gsg-configuration-created.png)
檢閱組態完成後，若要執行資格測試，請選擇**執行測試**。
# 修改現有的組態
如果您已經為 IDT for FreeRTOS 設定組態檔案，您可以使用 IDT for FreeRTOS UI 來修改現有的組態。現有的組態檔案必須位於 `devicetester-extract-location/config`目錄中。
**修改組態**
1. 在 IDT for FreeRTOS UI 中，開啟導覽功能表，然後選擇**編輯現有組態**。
組態儀表板會顯示現有組態設定的相關資訊。如果組態不正確或無法使用，則該組態的狀態為 `Error validating configuration`。
![\[裝置 AWS 帳戶、FreeRTOS 實作、PKCS 標籤和 echo 伺服器、over-the-air更新，以及顯示有效狀態的測試執行設定區段的組態畫面。\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/images/modify-existing-configuration.png)
1. 若要修改現有的組態設定，請完成下列步驟：
1. 選擇組態設定的名稱以開啟其設定頁面。
1. 修改設定，然後選擇**儲存**以重新產生對應的組態檔案。
1. 若要修改 IDT for FreeRTOS 測試執行設定，請在編輯檢視中選擇 **IDT 測試執行設定**：
![\[IDT 測試執行設定對話方塊，其中包含測試選擇、略過測試群組、逾時乘數，以及在第一次失敗時停止的選項。\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/images/idt-testrun-settings.png)
修改組態完成後，請確認所有組態設定都通過驗證。如果每個組態設定的狀態為 `Valid`，您可以使用此組態執行資格測試。
# 執行資格測試
為 IDT for FreeRTOS UI 建立組態後，您可以執行資格測試。
**執行資格測試**
1. 在導覽功能表中，選擇**執行測試**。
1. 選擇**開始測試**以開始測試執行。根據預設，會針對您的裝置組態執行所有適用的測試。IDT for FreeRTOS 會在所有測試完成時產生資格報告。
![\[Device Tester for FreeRTOS 介面顯示尚未執行任何測試，並提供建立新組態、編輯現有組態和執行測試的選項。\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/images/idt-run-tests.png)
IDT for FreeRTOS 會執行資格測試。然後，它會在測試執行**器主控台中顯示測試執行**摘要和任何錯誤。測試執行完成後，您可以從下列位置檢視測試結果和日誌：
+ 測試結果位於 `devicetester-extract-location/results/execution-id`目錄中。
+ 測試日誌位於 `devicetester-extract-location/results/execution-id/logs`目錄中。
如需測試結果和日誌的詳細資訊，請參閱 [檢視 IDT for FreeRTOSresults](view-results-lts.md)和 [檢視 IDT for FreeRTOSlogs](view-logs-lts.md)。
![\[適用於 FreeRTOS 的 Device Tester 執行日誌，顯示通過的測試、測試群組，以及日誌和報告的檔案路徑。\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/images/idt-results.png)
# 執行 FreeRTOS 資格 2.0 套件
使用 AWS IoT Device Tester for FreeRTOS 可執行檔與 IDT for FreeRTOS 互動。以下命令列範例會說明如何執行裝置集區 (一組相同的裝置) 的資格測試。
------
#### [ IDT v4.5.2 and later ]
```
devicetester_[linux | mac | win] run-suite \
--suite-id suite-id \
--group-id group-id \
--pool-id your-device-pool \
--test-id test-id \
--userdata userdata.json
```
在裝置集區上執行測試套件。`userdata.json` 檔案必須位於 `devicetester_extract_location/devicetester_freertos_[win|mac|linux]/configs/` 目錄。
**注意**
如果您在 Windows 上執行 IDT for FreeRTOS，請使用正斜線 (/) 指定`userdata.json`檔案的路徑。
使用下列命令來執行特定的測試群組：
```
devicetester_[linux | mac | win] run-suite \
--suite-id FRQ_1.99.0 \
--group-id group-id \
--pool-id pool-id \
--userdata userdata.json
```
如果您是在單一裝置集區上執行單一測試套件 (也就是說，您在 `device.json` 檔案中僅定義了一個裝置集區)，`suite-id` 和 `pool-id` 參數則為選用。
使用下列命令，在測試群組中執行特定的測試案例：
```
devicetester_[linux | mac | win_x86-64] run-suite \
--group-id group-id \
--test-id test-id
```
您可以使用 `list-test-cases` 命令列出測試群組中的測試案例。
**IDT for FreeRTOS 命令列選項**
**group-id**
(選用) 要執行的測試群組，以逗號分隔的清單。如果未指定，IDT 會執行測試套件中的所有測試群組。
**pool-id**
(選用) 要測試的裝置集區。如果您在 `device.json` 中定義多個裝置集區，這則為必要。如果您只有一個裝置集區，就可以省略此選項。
**suite-id**
(選用) 要執行的測試套件版本。如果未指定，IDT 則會使用系統的測試目錄中的最新版本。
**test-id**
(選用) 要執行的測試，以逗號分隔的清單。若已指定，`group-id` 必須指定單一群組。
**Example**
```
devicetester_[linux | mac | win_x86-64] run-suite --group-id FreeRTOSVersion --test-id FreeRTOSVersion
```
**h**
使用說明選項以進一步了解 `run-suite` 選項。
**Example**
**範例**
```
devicetester_[linux | mac | win_x86-64] run-suite -h
```
------
## IDT for FreeRTOS 命令
IDT for FreeRTOS 命令支援下列操作：
------
#### [ IDT v4.5.2 and later ]
** `help` **
列出所指定命令的相關資訊。
** `list-groups` **
列出指定套件中的群組。
** `list-suites` **
列出可用套件。
** `list-supported-products` **
列出支援的產品和測試套件版本。
** `list-supported-versions` **
列出目前 IDT 版本支援的 FreeRTOS 和測試套件版本。
** `list-test-cases` **
列出指定群組中的測試案例。
** `run-suite` **
在裝置集區上執行測試套件。
使用 `--suite-id` 選項以指定測試套件版本，或省略它以使用系統上的最新版本。
使用 `--test-id` 執行個別測試案例。
**Example**
```
devicetester_[linux | mac | win_x86-64] run-suite --group-id FreeRTOSVersion --test-id FreeRTOSVersion
```
從 IDT v3.0.0 開始，IDT 會在線上檢查是否有更新的測試套件。如需詳細資訊，請參閱[測試套件版本](idt-test-suite-versions.md)。
------
# 檢視 IDT for FreeRTOSresults
執行期間，IDT 會將錯誤寫入主控台、日誌檔和測試報告。IDT 完成資格測試套件後，即會將測試執行摘要寫入主控台，並產生兩份測試報告。您可以在 `devicetester-extract-location/results/execution-id/` 中找到這些報告。這兩份報告都會從資格測試套件執行擷取結果。
`awsiotdevicetester_report.xml` 是您提交 AWS 至 以在 AWS Partner Device Catalog 中列出裝置的資格測試報告。該報告包含下列元素：
+ IDT for FreeRTOS 版本。
+ 已測試的 FreeRTOS 版本。
+ 根據通過的測試，裝置支援的 FreeRTOS 功能。
+ `device.json` 檔案中指定的 SKU 和裝置名稱。
+ `device.json` 檔案中所指定裝置的功能。
+ 測試案例結果的彙總摘要。
+ 根據裝置功能進行測試的程式庫測試案例結果明細。
`FRQ_Report.xml` 報告採用標準的 [JUnit XML 格式](https://llg.cubic.org/docs/junit/)。您可以將它整合到 CI/CD 平台，例如 [Jenkins](https://jenkins.io/)、[Bamboo](https://www.atlassian.com/software/bamboo) 等等。該報告包含下列元素：
+ 測試案例結果的彙總摘要。
+ 根據裝置功能進行測試的程式庫測試案例結果明細。
# 解譯 IDT for FreeRTOS 結果
`awsiotdevicetester_report.xml` 或 `FRQ_Report.xml` 中的報告部分會列出所執行測試的結果。
第一個 XML 標籤 `` 包含測試執行的整體摘要。例如：
``
**``標籤中使用的屬性**
** `name` **
測試套件的名稱。
** `time` **
執行資格套件所花費的時間 (以秒為單位)。
** `tests` **
所執行的測試案例數目。
** `failures` **
已執行但未通過的測試案例數目。
** `errors` **
IDT for FreeRTOS 無法執行的測試案例數量。
** `disabled` **
此屬性未使用，可忽略。
如果沒有測試案例失敗或錯誤，您的裝置符合執行 FreeRTOS 的技術要求，並且可以與 AWS IoT 服務互通。如果您選擇在 AWS 合作夥伴裝置目錄中列出您的裝置，您可以使用此報告做為資格證據。
在測試案例失敗或發生錯誤的情況下，您可以透過檢閱 `` XML 標籤來識別失敗的測試案例。`` 標籤內的 `` XML 標籤會顯示測試群組的測試案例結果摘要。
``
該格式與 `` 標籤相似，但具有不使用且可忽略的 `skipped` 屬性。在每個 `` XML 標籤內，系統為測試群組執行的每個測試案例都有 `` 標籤。例如：
``
**``標籤中使用的屬性**
** `name` **
受測產品名稱。
** `version` **
受測產品版本。
** `features` **
驗證的功能。標記為 `required` 的功能為提交主機板獲得資格時所需。下列程式碼片段顯示此項目在 `awsiotdevicetester_report.xml` 檔案中的顯示方式。
```
```
標記為 `optional` 的功能不需要進行資格測試。以下程式碼片段顯示選用功能。
```
```
如果必要功能沒有測試失敗或錯誤，您的裝置會符合執行 FreeRTOS 的技術需求，並且可以與 AWS IoT 服務互通。如果您想要在[AWS 合作夥伴裝置目錄中](https://partners.amazonaws.com/qualified-devices)列出您的裝置，您可以使用此報告做為資格證據。
如果測試發生失敗或錯誤，您可以檢閱 `` XML 標籤來識別失敗的測試。`` 標籤內的 `` XML 標籤會顯示測試群組的測試結果摘要。例如：
```
```
格式類似於 ``標籤，但具有未使用的`skipped`屬性，可以忽略。在每個 `` XML 標籤內，測試群組每個執行的測試都有 `` 標籤。例如：
```
```
**``標籤中使用的屬性**
** `name` **
測試案例的名稱。
** `attempts` **
IDT for FreeRTOS 執行測試案例的次數。
當測試案例失敗或發生錯誤時，系統就會將 `` 或 `` 標籤新增至 `` 標籤，其中附有相關資訊以利故障診斷。例如：
```
Reason for the test case failure
Reason for the test case execution error
```
如需詳細資訊，請參閱[對 錯誤進行故障診斷](dt-afr-troubleshooting.md)。
# 檢視 IDT for FreeRTOSlogs
您可以在 中找到 IDT for FreeRTOS 從測試執行產生的日誌`devicetester-extract-location/results/execution-id/logs`。該工具會產生兩組日誌：
+ `test_manager.log`
包含從 IDT for FreeRTOS 產生的日誌 （例如，日誌相關的組態和報告產生）。
+ `test_group_id/test_case_id/test_case_id.log`
測試案例的日誌檔案，包括來自測試中裝置的輸出。日誌檔案會根據執行的測試群組和測試案例命名。
# IDT with FreeRTOS 資格套件 1.0 (FRQ 1.0)
**重要**
自 2022 年 10 月起， AWS IoT Device Tester for AWS IoT FreeRTOS 資格 (FRQ) 1.0 不會產生已簽章的資格報告。您無法使用 IDT FRQ 1.0 版本，讓新的 AWS IoT FreeRTOS 裝置有資格透過[AWS 裝置資格計劃](https://aws.amazon.com/partners/programs/dqp/)在[AWS 合作夥伴裝置目錄中](https://partners.amazonaws.com/qualified-devices)列出。雖然您無法使用 IDT FRQ 1.0 限定 FreeRTOS 裝置，但您可以繼續使用 FRQ 1.0 繼續測試 FreeRTOS 裝置。我們建議您使用 [IDT FRQ 2.0](https://docs.aws.amazon.com/freertos/latest/userguide/lts-idt-freertos-qualification.html) 來限定和列出合作夥伴裝置目錄中的 FreeRTOS 裝置。 [AWS](https://partners.amazonaws.com/qualified-devices)
您可以使用 IDT for FreeRTOS 資格來驗證 FreeRTOS 作業系統是否可在您的裝置本機運作，並可與其通訊 AWS IoT。具體而言，它會驗證 FreeRTOS 程式庫的移植層界面是否正確實作。它也會使用 end-to-end測試 AWS IoT Core。舉例來說，其會驗證主機板是否能傳送和接收 MQTT 訊息，並正確處理這些項目。IDT for FreeRTOS 執行的測試在 [FreeRTOS GitHub 儲存庫](https://github.com/aws/amazon-freertos)中定義。
測試會以主機板內嵌應用程式的方式執行。應用程式二進位映像包括 FreeRTOS、半導體廠商移植的 FreeRTOS 介面，以及主機板裝置驅動程式。測試的目的是驗證移植的 FreeRTOS 介面在裝置驅動程式上是否正常運作。
IDT for FreeRTOS 會產生測試報告，您可以提交至 AWS IoT ，將硬體新增至 AWS 合作夥伴裝置目錄。如需詳細資訊，請參閱 [AWS 裝置資格計劃](https://aws.amazon.com/partners/dqp/)。
IDT for FreeRTOS 會在連接到要測試之主機板的主機電腦 (Windows、macOS 或 Linux) 上執行。此外，IDT 會執行測試案例並彙總結果，還會提供可管理測試執行作業的命令列界面。
除了測試裝置之外，IDT for FreeRTOS 還會建立資源 （例如 AWS IoT 物件、FreeRTOS 群組、Lambda 函數等），以促進資格程序。為了建立這些資源，IDT for FreeRTOS 會使用 中設定的 AWS 登入`config.json`資料來代表您進行 API 呼叫。系統會在測試期間的不同時間點內佈建這些資源。
當您在主機電腦上執行 IDT for FreeRTOS 時，它會執行下列步驟：
1. 載入並驗證您的裝置和登入資料組態。
1. 對所需的本機和雲端資源執行選取的測試。
1. 清除本機和雲端資源。
1. 產生測試報告以指出主機板是否通過符合資格所需的測試。
**Topics**
+ [設定 1.0 資格先決條件](dev-tester-prereqs.md)
+ [微控制器電路板的第一個測試](qual-steps.md)
+ [使用 IDT 使用者介面執行 FreeRTOS 資格套件](device-tester-ui.md)
+ [執行低功耗藍牙測試](afr-bridgekeeper-dt-bt.md)
+ [執行 FreeRTOS 資格套件](run-tests.md)
+ [檢視 IDT for FreeRTOS 結果](view-results-frq.md)
+ [解譯 IDT for FreeRTOS 結果](interpreting-results-frq.md)
+ [檢視 IDT for FreeRTOS 日誌](view-logs-frq.md)
# 設定 1.0 資格先決條件
本節說明使用 測試微控制器的先決條件 AWS IoT Device Tester。
## 下載 FreeRTOS
您可以使用下列命令從 [GitHub](https://github.com/aws/amazon-freertos) 下載 FreeRTOS 版本：
```
git clone --branch --recurse-submodules https://github.com/aws/amazon-freertos.git
cd amazon-freertos
git submodule update --checkout --init --recursive
```
其中 是對應於 中所列 IDT 版本的 FreeRTOS 版本 （例如 202007.00)[支援的 版本 AWS IoT Device Tester](dev-test-versions-afr.md)。這可確保您擁有完整的原始程式碼，包括子模組，並針對 FreeRTOS 版本使用正確的 IDT 版本，反之亦然。
Windows 的路徑長度限制為 260 個字元。FreeRTOS 的路徑結構非常深入，因此如果您使用的是 Windows，請將檔案路徑保持在 260 個字元的限制以下。例如，將 FreeRTOS 複製到 `C:\FreeRTOS`而非 `C:\Users\username\programs\projects\myproj\FreeRTOS\`。
### 具有 LTS 程式庫的 FreeRTOS 資格
+ 為了讓您的微型控制器在 AWS Partner Device Catalog 中指定為支援長期支援 (LTS) 型 FreeRTOS 版本，您必須提供資訊清單檔案。如需詳細資訊，請參閱 [ FreeRTOS 資格指南中的 FreeRTOS 資格檢查清單](https://docs.aws.amazon.com/freertos/latest/qualificationguide/afq-checklist.html)。 *FreeRTOS *
+ 為了驗證您的微型控制器是否支援以 LTS 為基礎的 FreeRTOS 版本，並有資格提交至 AWS Partner Device Catalog，您必須使用 AWS IoT Device Tester (IDT) 搭配 FreeRTOS Qualification (FRQ) 測試套件版本 v1.4.x。
+ FreeRTOS 的 LTS 型版本支援僅限於 FreeRTOS 的 202012.xx 版本。
## 下載 IDT for FreeRTOS
每個 FreeRTOS 版本都有對應的 IDT for FreeRTOS 版本，以執行資格測試。從 下載適當的 IDT for FreeRTOS 版本[支援的 版本 AWS IoT Device Tester](dev-test-versions-afr.md)。
將 IDT for FreeRTOS 解壓縮到檔案系統上具有讀取和寫入許可的位置。由於 Microsoft Windows 具有路徑長度的字元限制，請將 IDT for FreeRTOS 擷取到根目錄，例如 `C:\`或 `D:\`。
**注意**
不建議多位使用者從 NFS 目錄或 Windows 網路共用資料夾等共用位置執行 IDT。這麼做可能會導致當機或資料損毀。建議您將 IDT 套件解壓縮至本機磁碟機。
## 建立和設定 AWS 帳戶
### 註冊 AWS 帳戶
如果您沒有 AWS 帳戶，請完成下列步驟來建立一個。
**註冊 AWS 帳戶**
1. 開啟 [https://portal.aws.amazon.com/billing/signup](https://portal.aws.amazon.com/billing/signup)。
1. 請遵循線上指示進行。
部分註冊程序需接收來電或簡訊，並在電話鍵盤輸入驗證碼。
當您註冊 時 AWS 帳戶，*AWS 帳戶根使用者*會建立 。根使用者有權存取該帳戶中的所有 AWS 服務 和資源。作為安全最佳實務，請將管理存取權指派給使用者，並且僅使用根使用者來執行[需要根使用者存取權的任務](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks)。
AWS 會在註冊程序完成後傳送確認電子郵件給您。您可以隨時登錄 [https://aws.amazon.com/](https://aws.amazon.com/) 並選擇**我的帳戶**，以檢視您目前的帳戶活動並管理帳戶。
### 建立具有管理存取權的使用者
註冊 後 AWS 帳戶，請保護 AWS 帳戶根使用者、啟用 AWS IAM Identity Center和建立管理使用者，以免將根使用者用於日常任務。
**保護您的 AWS 帳戶根使用者**
1. 選擇**根使用者**並輸入 AWS 帳戶 您的電子郵件地址，以帳戶擁有者[AWS 管理主控台](https://console.aws.amazon.com/)身分登入 。在下一頁中，輸入您的密碼。
如需使用根使用者登入的說明，請參閱 *AWS 登入 使用者指南*中的[以根使用者身分登入](https://docs.aws.amazon.com/signin/latest/userguide/console-sign-in-tutorials.html#introduction-to-root-user-sign-in-tutorial)。
1. 若要在您的根使用者帳戶上啟用多重要素驗證 (MFA)。
如需說明，請參閱《*IAM 使用者指南*》中的[為您的 AWS 帳戶 根使用者 （主控台） 啟用虛擬 MFA 裝置](https://docs.aws.amazon.com/IAM/latest/UserGuide/enable-virt-mfa-for-root.html)。
**建立具有管理存取權的使用者**
1. 啟用 IAM Identity Center。
如需指示，請參閱《AWS IAM Identity Center 使用者指南》**中的[啟用 AWS IAM Identity Center](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-set-up-for-idc.html)。
1. 在 IAM Identity Center 中，將管理存取權授予使用者。
如需使用 IAM Identity Center 目錄 做為身分來源的教學課程，請參閱*AWS IAM Identity Center 《 使用者指南*》中的[使用預設值設定使用者存取 IAM Identity Center 目錄](https://docs.aws.amazon.com//singlesignon/latest/userguide/quick-start-default-idc.html)。
**以具有管理存取權的使用者身分登入**
+ 若要使用您的 IAM Identity Center 使用者簽署，請使用建立 IAM Identity Center 使用者時傳送至您電子郵件地址的簽署 URL。
如需使用 IAM Identity Center 使用者登入的說明，請參閱*AWS 登入 《 使用者指南*》中的[登入 AWS 存取入口網站](https://docs.aws.amazon.com/signin/latest/userguide/iam-id-center-sign-in-tutorial.html)。
**指派存取權給其他使用者**
1. 在 IAM Identity Center 中，建立一個許可集來遵循套用最低權限的最佳實務。
如需指示，請參閱《AWS IAM Identity Center 使用者指南》**中的[建立許可集](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-started-create-a-permission-set.html)。
1. 將使用者指派至群組，然後對該群組指派單一登入存取權。
如需指示，請參閱《AWS IAM Identity Center 使用者指南》**中的[新增群組](https://docs.aws.amazon.com//singlesignon/latest/userguide/addgroups.html)。
## AWS IoT Device Tester 受管政策
`AWSIoTDeviceTesterForFreeRTOSFullAccess` 受管政策包含下列版本檢查、自動更新功能和指標集合的 AWS IoT Device Tester 許可。
+ `iot-device-tester:SupportedVersion`
AWS IoT Device Tester 准許擷取支援的產品、測試套件和 IDT 版本清單。
+ `iot-device-tester:LatestIdt`
AWS IoT Device Tester 准許擷取可供下載的最新 IDT 版本。
+ `iot-device-tester:CheckVersion`
AWS IoT Device Tester 准許檢查 IDT、測試套件和產品的版本相容性。
+ `iot-device-tester:DownloadTestSuite`
AWS IoT Device Tester 准許下載測試套件更新。
+ `iot-device-tester:SendMetrics`
AWS 准許收集有關 AWS IoT Device Tester 內部使用的指標。
## （選用） 安裝 AWS Command Line Interface
您可能偏好使用 AWS CLI 來執行一些操作。如果您沒有 AWS CLI 安裝 ，請遵循[安裝 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/installing.html)中的指示。
**aws configure** 從命令列執行， AWS CLI 為您要使用的 AWS 區域設定 。如需支援 IDT for FreeRTOS AWS 的區域資訊，請參閱[AWS 區域和端點](https://docs.aws.amazon.com/general/latest/gr/rande.html#amazon-freertos-ota-control)。如需詳細資訊，**aws configure**請參閱[使用 的快速組態**aws configure**](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-config)。
# 微控制器電路板的第一個測試
您可以在移植 FreeRTOS 介面時，使用 IDT for FreeRTOS 進行測試。在您為電路板的裝置驅動程式移植 FreeRTOS 介面之後，您可以使用 AWS IoT Device Tester 在您的微型控制器電路板上執行資格測試。
## 新增程式庫移植層
若要為您的裝置移植 FreeRTOS，請遵循 [FreeRTOS 移植指南](https://docs.aws.amazon.com/freertos/latest/portingguide/)中的指示。
## 設定您的 AWS 登入資料
您需要設定 的 AWS 登入資料 AWS IoT Device Tester ，才能與 AWS 雲端通訊。如需詳細資訊，請參閱[設定 AWS 用於開發的登入資料和區域](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/setup-credentials.html)。必須在`devicetester_extract_location/devicetester_afreertos_[win|mac|linux]/configs/config.json`組態檔案中指定有效的 AWS 登入資料。
**Topics**
+ [新增程式庫移植層](#add-port-layer)
+ [設定您的 AWS 登入資料](#cfg-aws-afr)
+ [在 IDT for FreeRTOS 中建立裝置集區](cfg-dt-dp.md)
+ [設定建置、刷新和測試設定](cfg-dt-ud.md)
# 在 IDT for FreeRTOS 中建立裝置集區
系統會將要測試的裝置整理為裝置集區，每個裝置集區都包含一個或多個相同的裝置。您可以設定 IDT for FreeRTOS 來測試集區中的單一裝置或集區中的多個裝置。為了加速資格程序，IDT for FreeRTOS 可以平行測試具有相同規格的裝置。該工具會採用循環配置資源方法，在裝置集區的每個裝置上執行不同的測試群組。
您可以在 `configs` 資料夾中編輯 `device.json` 範本的 `devices` 區段，進而新增一或多個裝置至裝置集區。
**注意**
同一個集區中的所有裝置皆需採用相同技術規格和 SKU。
若要為不同的測試群組啟用來源碼的平行建置，IDT for FreeRTOS 會將來源碼複製到 IDT for FreeRTOS 解壓縮資料夾內的結果資料夾。您必須使用 `testdata.sourcePath`或 `sdkPath`變數來參考建置或 Flash 命令中的原始碼路徑。IDT for FreeRTOS 會將此變數取代為複製來源碼的暫時路徑。如需詳細資訊，請參閱 [IDT for FreeRTOS 變數](dt-vars.md)。
下方範例 `device.json` 檔案可用來建立具有多個裝置的裝置集區。
```
[
{
"id": "pool-id",
"sku": "sku",
"features": [
{
"name": "WIFI",
"value": "Yes | No"
},
{
"name": "Cellular",
"value": "Yes | No"
},
{
"name": "OTA",
"value": "Yes | No",
"configs": [
{
"name": "OTADataPlaneProtocol",
"value": "HTTP | MQTT"
}
]
},
{
"name": "BLE",
"value": "Yes | No"
},
{
"name": "TCP/IP",
"value": "On-chip | Offloaded | No"
},
{
"name": "TLS",
"value": "Yes | No"
},
{
"name": "PKCS11",
"value": "RSA | ECC | Both | No"
},
{
"name": "KeyProvisioning",
"value": "Import | Onboard | No"
}
],
"devices": [
{
"id": "device-id",
"connectivity": {
"protocol": "uart",
"serialPort": "/dev/tty*"
},
***********Remove the section below if the device does not support onboard key generation***************
"secureElementConfig" : {
"publicKeyAsciiHexFilePath": "absolute-path-to/public-key-txt-file: contains-the-hex-bytes-public-key-extracted-from-onboard-private-key",
"secureElementSerialNumber": "secure-element-serialNo-value",
"preProvisioned" : "Yes | No"
},
**********************************************************************************************************
"identifiers": [
{
"name": "serialNo",
"value": "serialNo-value"
}
]
}
]
}
]
```
以下是 `device.json` 檔案中使用的屬性：
**`id`**
使用者定義的英數字 ID，可唯一識別裝置集區。屬於集區的裝置必須為相同類型。執行測試套件時，集區中的裝置將用來將工作負載平行化。
**`sku`**
可唯一識別您要測試之主機板的英數字元值。SKU 用來追蹤合格的主機板。
如果您想要在 AWS Partner Device Catalog 中列出電路板，您在此處指定的 SKU 必須符合您在列出程序中使用的 SKU。
**`features`**
包含裝置支援功能的陣列。 AWS IoT Device Tester 會使用此資訊選取要執行的資格測試。
支援的值如下：
**`TCP/IP`**
指出您的面板是否支援 TCP/IP 堆疊，以及支援晶載 (MCU) 或轉移到另一個模組。你需要 TCP/IP 才能符合資格。
**`WIFI`**
指出您的面板是否具有 Wi-Fi 功能。`No` 如果 設定為 ，則必須`Cellular`設定為 `Yes`。
**`Cellular`**
指出您的電路板是否具有行動功能。`No` 如果 設定為 ，則必須`WIFI`設定為 `Yes`。當此功能設為 時`Yes`，將使用 AWS t2.micro EC2 執行個體執行 FullSecureSockets 測試，這可能會對您的帳戶產生額外費用。如需詳細資訊，請參閱 [Amazon EC2 定價](https://aws.amazon.com/ec2/pricing/)。
**`TLS`**
指出您的面板是否支援 TLS。您需要 TLS 才能獲得資格。
**`PKCS11`**
指出面板支援的公有金鑰密碼編譯演算法。您需要 PKCS11 才能獲得資格。支援的值為 `ECC`、`RSA`、`Both` 和 `No`。`Both` 表示主機板同時支援 `ECC` 和 `RSA` 演算法。
**`KeyProvisioning`**
指出將受信任的 X.509 用戶端憑證寫入面板的方法。有效值為 `Import`、`Onboard` 和 `No`。需有主要佈建才能符合資格。
+ 如果主機板可允許匯入私有金鑰，請使用 `Import`。IDT 將建立私有金鑰，並將其建置至 FreeRTOS 原始程式碼。
+ 如果主機板可支援產生內建私有金鑰 (例如，如果裝置有安全元素，或您偏好產生自己的裝置金鑰對和憑證)，請使用 `Onboard`。請務必在每個裝置區段中新增一個 `secureElementConfig` 元素，並在 `publicKeyAsciiHexFilePath` 欄位中放置公有金鑰檔案的絕對路徑。
+ 如果主機板不支援金鑰佈建，請使用 `No`。
**`OTA`**
指出您的面板是否支援無線 (OTA) 更新功能。`OtaDataPlaneProtocol` 屬性指出裝置支援哪個 OTA 資料平面通訊協定。如果裝置不支援 OTA 功能，則會忽略此屬性。選取 `"Both"` 時，由於同時執行 MQTT、HTTP 和混合測試，OTA 測試執行時間會延長。
從 IDT v4.1.0 開始， 僅`OtaDataPlaneProtocol`接受 `HTTP`和 `MQTT`作為支援的值。
**`BLE`**
指出您的面板是否支援低功耗藍牙 (BLE)。
**`devices.id`**
使用者定義的唯一識別符，用於識別要測試的裝置。
**`devices.connectivity.protocol`**
用來與此裝置通訊的通訊協定。支援的值為：`uart`。
**`devices.connectivity.serialPort`**
要測試用於連接到裝置之主機電腦的序列埠。
**`devices.secureElementConfig.PublicKeyAsciiHexFilePath`**
檔案的絕對路徑，此檔案包含從內建私有金鑰擷取的十六進位位元組公有金鑰。
範例格式：
```
3059 3013 0607 2a86 48ce 3d02 0106 082a
8648 ce3d 0301 0703 4200 04cd 6569 ceb8
1bb9 1e72 339f e8cf 60ef 0f9f b473 33ac
6f19 1813 6999 3fa0 c293 5fae 08f1 1ad0
41b7 345c e746 1046 228e 5a5f d787 d571
dcb2 4e8d 75b3 2586 e2cc 0c
```
如果您的公有金鑰是 .der 格式，您可以直接對公有金鑰進行十六進位編碼，以產生十六進位檔案。
.der 公有金鑰產生十六進位檔案的範例命令：
```
xxd -p pubkey.der > outFile
```
如果您的公有金鑰是 .pem 格式，您可以擷取 base64 編碼的部分，將其解碼為二進位格式，然後十六進位編碼它以產生十六進位檔案。
例如，使用這些命令來產生 .pem 公有金鑰的十六進位檔案：
1. 取出金鑰的 base64 編碼部分 （略過標頭和頁尾 )，並將其存放在檔案中，例如將其命名為 `base64key`，執行此命令將其轉換為 .der 格式：
```
base64 —decode base64key > pubkey.der
```
1. 執行 `xxd`命令，將其轉換為十六進位格式。
```
xxd -p pubkey.der > outFile
```
**`devices.secureElementConfig.SecureElementSerialNumber`**
(選用) 安全元素的序號。當您執行 FreeRTOS 示範/測試專案時，請在序號與裝置公有金鑰一起印出時提供此欄位。
**`devices.secureElementConfig.preProvisioned`**
（選用） 如果裝置具有具有鎖定登入資料的預先佈建安全元素，且無法匯入、建立或銷毀物件，則設定為「是」。此組態只有在 `features` `KeyProvisioning`設為 "Onboard" 且 `PKCS11` 設為 "ECC" 時才會生效。
**`identifiers`**
(選用) 任意的名稱/值組的陣列。您可以在下一節所述的建置和刷新命令中使用這些值。
# 設定建置、刷新和測試設定
若要讓 IDT for FreeRTOS 自動在您的主機板上建置和刷新測試，您必須設定 IDT 來執行硬體的建置和刷新命令。您可以在位於 `config` 資料夾的 `userdata.json` 範本檔案中配置建置和刷新命令設定。
# 配置設定以測試裝置
您可以在 `configs/userdata.json` 檔案中進行建置、刷新和測試設定。我們透過在 中載入用戶端和伺服器憑證和金鑰來支援 Echo Server 組態`customPath`。如需詳細資訊，請參閱 *FreeRTOS 移植指南*中的[設定 echo 伺服器](https://docs.aws.amazon.com/freertos/latest/portingguide/afr-echo-server.html)。下列 JSON 範例示範如何設定 IDT for FreeRTOS 來測試多個裝置：
```
{
"sourcePath": "/absolute-path-to/freertos",
"vendorPath": "{{testData.sourcePath}}/vendors/vendor-name/boards/board-name",
// ***********The sdkConfiguration block below is needed if you are not using the default, unmodified FreeRTOS repo.
// In other words, if you are using the default, unmodified FreeRTOS repo then remove this block***************
"sdkConfiguration": {
"name": "sdk-name",
"version": "sdk-version",
"path": "/absolute-path-to/sdk"
},
"buildTool": {
"name": "your-build-tool-name",
"version": "your-build-tool-version",
"command": [
"{{config.idtRootPath}}/relative-path-to/build-parallel.sh {{testData.sourcePath}} {{enableTests}}"
]
},
"flashTool": {
"name": "your-flash-tool-name",
"version": "your-flash-tool-version",
"command": [
"/{{config.idtRootPath}}/relative-path-to/flash-parallel.sh {{testData.sourcePath}} {{device.connectivity.serialPort}} {{buildImageName}}"
],
"buildImageInfo" : {
"testsImageName": "tests-image-name",
"demosImageName": "demos-image-name"
}
},
"testStartDelayms": 0,
"clientWifiConfig": {
"wifiSSID": "ssid",
"wifiPassword": "password",
"wifiSecurityType": "eWiFiSecurityOpen | eWiFiSecurityWEP | eWiFiSecurityWPA | eWiFiSecurityWPA2 | eWiFiSecurityWPA3"
},
"testWifiConfig": {
"wifiSSID": "ssid",
"wifiPassword": "password",
"wifiSecurityType": "eWiFiSecurityOpen | eWiFiSecurityWEP | eWiFiSecurityWPA | eWiFiSecurityWPA2 | eWiFiSecurityWPA3"
},
//**********
//This section is used to start echo server based on server certificate generation method,
//When certificateGenerationMethod is set as Automatic specify the eccCurveFormat to generate certifcate and key based on curve format,
//When certificateGenerationMethod is set as Custom specify the certificatePath and PrivateKeyPath to be used to start echo server
//**********
"echoServerCertificateConfiguration": {
"certificateGenerationMethod": "Automatic | Custom",
"customPath": {
"clientCertificatePath":"/path/to/clientCertificate",
"clientPrivateKeyPath": "/path/to/clientPrivateKey",
"serverCertificatePath":"/path/to/serverCertificate",
"serverPrivateKeyPath": "/path/to/serverPrivateKey"
},
"eccCurveFormat": "P224 | P256 | P384 | P521"
},
"echoServerConfiguration": {
"securePortForSecureSocket": 33333, // Secure tcp port used by SecureSocket test. Default value is 33333. Ensure that the port configured isn't blocked by the firewall or your corporate network
"insecurePortForSecureSocket": 33334, // Insecure tcp port used by SecureSocket test. Default value is 33334. Ensure that the port configured isn't blocked by the firewall or your corporate network
"insecurePortForWiFi": 33335 // Insecure tcp port used by Wi-Fi test. Default value is 33335. Ensure that the port configured isn't blocked by the firewall or your corporate network
},
"otaConfiguration": {
"otaFirmwareFilePath": "{{testData.sourcePath}}/relative-path-to/ota-image-generated-in-build-process",
"deviceFirmwareFileName": "ota-image-name-on-device",
"otaDemoConfigFilePath": "{{testData.sourcePath}}/relative-path-to/ota-demo-config-header-file",
"codeSigningConfiguration": {
"signingMethod": "AWS | Custom",
"signerHashingAlgorithm": "SHA1 | SHA256",
"signerSigningAlgorithm": "RSA | ECDSA",
"signerCertificate": "arn:partition:service:region:account-id:resource:qualifier | /absolute-path-to/signer-certificate-file",
"signerCertificateFileName": "signerCertificate-file-name",
"compileSignerCertificate": boolean,
// ***********Use signerPlatform if you choose aws for signingMethod***************
"signerPlatform": "AmazonFreeRTOS-Default | AmazonFreeRTOS-TI-CC3220SF",
"untrustedSignerCertificate": "arn:partition:service:region:account-id:resourcetype:resource:qualifier",
// ***********Use signCommand if you choose custom for signingMethod***************
"signCommand": [
"/absolute-path-to/sign.sh {{inputImageFilePath}} {{outputSignatureFilePath}}"
]
}
},
// ***********Remove the section below if you're not configuring CMake***************
"cmakeConfiguration": {
"boardName": "board-name",
"vendorName": "vendor-name",
"compilerName": "compiler-name",
"frToolchainPath": "/path/to/freertos/toolchain",
"cmakeToolchainPath": "/path/to/cmake/toolchain"
},
"freertosFileConfiguration": {
"required": [
{
"configName": "pkcs11Config",
"filePath": "{{testData.sourcePath}}/vendors/vendor-name/boards/board-name/aws_tests/config_files/core_pkcs11_config.h"
},
{
"configName": "pkcs11TestConfig",
"filePath": "{{testData.sourcePath}}/vendors/vendor-name/boards/board-name/aws_tests/config_files/iot_test_pkcs11_config.h"
}
],
"optional": [
{
"configName": "otaAgentTestsConfig",
"filePath": "{{testData.sourcePath}}/vendors/vendor-name/boards/board-name/aws_tests/config_files/ota_config.h"
},
{
"configName": "otaAgentDemosConfig",
"filePath": "{{testData.sourcePath}}/vendors/vendor-name/boards/board-name/aws_demos/config_files/ota_config.h"
},
{
"configName": "otaDemosConfig",
"filePath": "{{testData.sourcePath}}/vendors/vendor-name/boards/board-name/aws_demos/config_files/ota_demo_config.h"
}
]
}
}
```
以下列出 `userdata.json` 中使用的屬性：
**`sourcePath`**
移植的 FreeRTOS 原始程式碼根目錄的路徑。對於使用 SDK 進行平行測試，`sourcePath`可以使用`{{userData.sdkConfiguration.path}}`預留位置設定 。例如：
```
{ "sourcePath":"{{userData.sdkConfiguration.path}}/freertos" }
```
**`vendorPath`**
廠商特定 FreeRTOS 程式碼的路徑。針對序列測試，`vendorPath` 可設定為絕對路徑。例如：
```
{ "vendorPath":"C:/path-to-freertos/vendors/espressif/boards/esp32" }
```
針對平行測試，可使用 `{{testData.sourcePath}}` 預留位置設定 `vendorPath`。例如：
```
{ "vendorPath":"{{testData.sourcePath}}/vendors/espressif/boards/esp32" }
```
只有在在沒有 SDK 的情況下執行時，才需要 `vendorPath`變數，否則可以將其移除。
在沒有 SDK 的情況下平行執行測試時，必須在 `vendorPath`、`buildTool`、 `flashTool`欄位中使用`{{testData.sourcePath}}`預留位置。使用單一裝置執行測試時，必須在 `vendorPath`、`buildTool`、`flashTool` 欄位中使用絕對路徑。使用 SDK 執行 時，必須在 `sourcePath`、 `buildTool`和 `flashTool`命令中使用`{{sdkPath}}`預留位置。
**`sdkConfiguration`**
如果您正在限定 FreeRTOS，且對檔案和資料夾結構所做的任何修改超過移植所需的修改，則需要在此區塊中設定 SDK 資訊。如果您不符合 SDK 內移植 FreeRTOS 的資格，則應完全省略此區塊。
**`sdkConfiguration.name`**
您搭配 FreeRTOS 使用的 SDK 名稱。如果您不是使用 SDK，則應該省略整個`sdkConfiguration`區塊。
**`sdkConfiguration.version`**
您搭配 FreeRTOS 使用的 SDK 版本。如果您不是使用 SDK，則應該省略整個`sdkConfiguration`區塊。
**`sdkConfiguration.path`**
包含 FreeRTOS 程式碼之 SDK 目錄的絕對路徑。如果您不是使用 SDK，則應該省略整個`sdkConfiguration`區塊。
**`buildTool`**
建置指令碼的完整路徑 (.bat 或 .sh)，其中包含用來建立來源碼的命令。組建命令中對原始程式碼路徑的所有參考都必須取代為 AWS IoT Device Tester 變數，`{{testdata.sourcePath}}`而 SDK 路徑的參考應該取代為 `{{sdkPath}}`。使用`{{config.idtRootPath}}`預留位置來參考絕對或相對 IDT 路徑。
**`testStartDelayms`**
指定 FreeRTOS 測試執行器在開始執行測試之前等待多少毫秒。如果待測裝置在 IDT 因網路或其他延遲而有機會連線和開始記錄之前，就開始輸出重要的測試資訊，這會很有用。允許的值上限為 30000 毫秒 (30 秒）。此值僅適用於 FreeRTOS 測試群組，不適用於未使用 FreeRTOS 測試執行器的其他測試群組，例如 OTA 測試。
**`flashTool`**
包含用於裝置的刷入命令之刷入指令碼 (.sh 或 .bat) 的完整路徑。所有對 flash 命令中原始碼路徑的參考都必須取代為 IDT for FreeRTOS 變數`{{testdata.sourcePath}}`，而所有對 SDK 路徑的參考都必須取代為 IDT for FreeRTOS 變數 `{{sdkPath}}`。使用`{{config.idtRootPath}}`預留位置來參考絕對或相對 IDT 路徑。
**`buildImageInfo`**
**`testsImageName`**
從 `freertos-source/tests` 資料夾建置測試時，建置命令產生的檔案名稱。
**`demosImageName`**
從 `freertos-source/demos` 資料夾建置測試時，建置命令產生的檔案名稱。
**`clientWifiConfig`**
用戶端 Wi-Fi 組態。Wi-Fi 程式庫測試需要 MCU 主機板，以連接到兩個存取點。(兩個存取點可以是相同的。) 此屬性會設定第一個存取點的 Wi-Fi 設定。某些 Wi-Fi 測試案例希望存取點有一些安全保障，因此並未開放使用。請確定兩個存取點與執行 IDT 的主機電腦位於相同的子網路上。
**`wifi_ssid`**
Wi-Fi SSID。
**`wifi_password`**
Wi-Fi 密碼。
**`wifiSecurityType`**
使用的 Wi-Fi 安全性類型。其中一個值：
+ `eWiFiSecurityOpen`
+ `eWiFiSecurityWEP`
+ `eWiFiSecurityWPA`
+ `eWiFiSecurityWPA2`
+ `eWiFiSecurityWPA3`
即使主機板不支援 Wi-Fi，您仍需在 `device.json` 檔案中加入 `clientWifiConfig` 區段，但可以省略這些屬性的值。
**`testWifiConfig`**
測試 Wi-Fi 組態。Wi-Fi 程式庫測試需要 MCU 主機板，以連接到兩個存取點。(兩個存取點可以是相同的。) 此屬性會設定第二個存取點的 Wi-Fi 設定。某些 Wi-Fi 測試案例希望存取點有一些安全保障，因此並未開放使用。請確定兩個存取點與執行 IDT 的主機電腦位於相同的子網路上。
**`wifiSSID`**
Wi-Fi SSID。
**`wifiPassword`**
Wi-Fi 密碼。
**`wifiSecurityType`**
使用的 Wi-Fi 安全性類型。其中一個值：
+ `eWiFiSecurityOpen`
+ `eWiFiSecurityWEP`
+ `eWiFiSecurityWPA`
+ `eWiFiSecurityWPA2`
+ `eWiFiSecurityWPA3`
即使主機板不支援 Wi-Fi，您仍需在 `device.json` 檔案中加入 `testWifiConfig` 區段，但可以省略這些屬性的值。
**`echoServerCertificateConfiguration`**
用於安全通訊端測試的可設定 echo 伺服器憑證產生預留位置。此欄位為必填。
**`certificateGenerationMethod`**
指定是自動產生還是手動提供伺服器憑證。
**`customPath`**
如果 `certificateGenerationMethod`是「自訂」，`privateKeyPath`則需要 `certificatePath`和 。
**`certificatePath`**
指定伺服器憑證的 filepath。
**`privateKeyPath`**
指定私有金鑰的檔案路徑。
**`eccCurveFormat`**
指定主機板支援的曲線格式。在 中`PKCS11`將 設定為 "ecc" 時為必要`device.json`。有效值為「P224」、「P256」、「P384」或「P521」。
**`echoServerConfiguration`**
適用於 WiFi 和安全通訊端測試的可設定 echo 伺服器連接埠。此欄位為選用欄位。
**`securePortForSecureSocket`**
用於設定具有 TLS 的 echo 伺服器連接埠，以供安全通訊端測試之用。預設值為 33333。請確定防火牆或您公司的網路未封鎖設定的連接埠。
**`insecurePortForSecureSocket`**
用於設定不具有 TLS 的 echo 伺服器連接埠，以供安全通訊端測試之用。測試中使用的預設值為 33334。請確定防火牆或您公司的網路未封鎖設定的連接埠。
**`insecurePortForWiFi`**
用於設定無 TLS 的 echo 伺服器連接埠，以供 WiFi 測試之用。測試中使用的預設值為 33335。請確定防火牆或您公司的網路未封鎖設定的連接埠。
**`otaConfiguration`**
OTA 組態。[選用]
**`otaFirmwareFilePath`**
建置之後建立的 OTA 映像的完整路徑。例如 `{{testData.sourcePath}}/relative-path/to/ota/image/from/source/root`。
**`deviceFirmwareFileName`**
MCU 裝置上 OTA 韌體所在的完整檔案路徑。有些裝置不使用此欄位，但您仍必須提供值。
**`otaDemoConfigFilePath`**
`aws_demo_config.h` 的完整路徑，位於 `afr-source/vendors/vendor/boards/board/aws_demos/config_files/` 內。這些檔案包含在 FreeRTOS 提供的移植程式碼範本中。
**`codeSigningConfiguration`**
程式碼簽章組態。
**`signingMethod`**
程式碼簽章方法。可能的值為 `AWS` 或 `Custom`。
對於北京和寧夏區域，請使用 `Custom`。這些區域不支援`AWS`程式碼簽署。
**`signerHashingAlgorithm`**
裝置上支援的雜湊演算法。可能的值為 `SHA1` 或 `SHA256`。
**`signerSigningAlgorithm`**
裝置上支援的簽署演算法。可能的值為 `RSA` 或 `ECDSA`。
**`signerCertificate`**
用於 OTA 的信任憑證。
對於 AWS 程式碼簽署方法，請針對上傳至 的信任憑證使用 Amazon Resource Name (ARN) AWS Certificate Manager。
對於自訂程式碼簽署方法，請使用簽署者憑證檔案的絕對路徑。
如需建立信任憑證的詳細資訊，請參閱 [建立程式碼簽署憑證](ota-code-sign-cert.md)。
**`signerCertificateFileName`**
裝置上的程式碼簽署憑證檔案名稱。此值必須符合您在執行 `aws acm import-certificate`命令時提供的檔案名稱。
如需詳細資訊，請參閱[建立程式碼簽署憑證](ota-code-sign-cert.md)。
**`compileSignerCertificate`**
`true` 如果未佈建或刷新程式碼簽署者簽章驗證憑證，則設定為 ，因此必須將其編譯至專案。 會 AWS IoT Device Tester 擷取信任的憑證並將其編譯至 `aws_codesigner_certifiate.h`。
**`untrustedSignerCertificate`**
某些 OTA 測試中使用的第二個憑證的 ARN 或檔案路徑，做為不受信任的憑證。如需建立憑證的詳細資訊，請參閱[建立程式碼簽署憑證](https://docs.aws.amazon.com/freertos/latest/userguide/ota-code-sign-cert.html)。
**`signerPlatform`**
AWS Code Signer 在建立 OTA 更新任務時所使用的簽署和雜湊演算法。目前，此欄位的可能值為 `AmazonFreeRTOS-TI-CC3220SF` 和 `AmazonFreeRTOS-Default`。
+ 如果是 `SHA1` 和 `RSA` 則選擇 `AmazonFreeRTOS-TI-CC3220SF`。
+ 如果是 `SHA256` 和 `ECDSA` 則選擇 `AmazonFreeRTOS-Default`。
如果您的組態需要 `SHA256` \$1 `RSA` 或 `SHA1` \$1 `ECDSA`，請聯絡我們以取得進一步支援。
如果您針對 `signingMethod` 選擇 `Custom`，請設定 `signCommand`。
**`signCommand`**
用於執行自訂程式碼簽署的命令。您可以在 `/configs/script_templates` 目錄中找到範本。
命令中需要 `{{inputImageFilePath}}` 和 `{{outputSignatureFilePath}}` 兩個預留位置。`{{inputImageFilePath}}` 是由 IDT 建立要簽署之影像的檔案路徑。`{{outputSignatureFilePath}}` 是將由指令碼產生簽章的檔案路徑。
**`cmakeConfiguration`**
CMake 組態 [選用]
您需要提供主機板名稱、廠商名稱，以及 `frToolchainPath` 或 `compilerName`，才能執行 CMake 測試案例。`cmakeToolchainPath` 如果您有 CMake 工具鏈的自訂路徑，您也可以提供 。
**`boardName`**
待測主機板的名稱。主機板名稱應與 `path/to/afr/source/code/vendors/vendor/boards/board` 下的資料夾名稱相同。
**`vendorName`**
待測主機板的廠商名稱。廠商應與 `path/to/afr/source/code/vendors/vendor` 下的資料夾名稱相同。
**`compilerName`**
編譯器的名稱。
**`frToolchainPath`**
編譯器工具鏈的完整路徑。
**`cmakeToolchainPath` **
CMake 工具鏈的完整路徑。此為選用欄位。
**`freertosFileConfiguration`**
IDT 在執行測試之前修改的 FreeRTOS 檔案組態。
**`required`**
本節會指定您已移動其組態檔案的必要測試，例如 PKCS11、TLS 等。
**`configName`**
正在設定的測試名稱。
**`filePath`**
`freertos` 儲存庫中組態檔案的絕對路徑。使用 `{{testData.sourcePath}}`變數來定義路徑。
**`optional`**
本節指定您已移動其組態檔案的選用測試，例如 OTA、WiFi 等。
**`configName`**
正在設定的測試名稱。
**`filePath`**
`freertos` 儲存庫中組態檔案的絕對路徑。使用 `{{testData.sourcePath}}`變數來定義路徑。
**注意**
您需要提供主機板名稱、廠商名稱，以及 `afrToolchainPath` 或 `compilerName`，才能執行 CMake 測試案例。如果您有 CMake 工具鏈的自訂路徑，也可以提供 `cmakeToolchainPath`。
# IDT for FreeRTOS 變數
建置程式碼和刷新裝置的命令可能需要連線或裝置的其他資訊，才能成功執行。 AWS IoT Device Tester 可讓您參考刷新中的裝置資訊，並使用 [JsonPath](https://goessner.net/articles/JsonPath/) 建置命令。透過使用簡單的 JsonPath 運算式，您可以擷取 `device.json` 檔案中指定的必要資訊。
## 路徑變數
IDT for FreeRTOS 定義下列路徑變數，可用於命令列和組態檔案：
**`{{testData.sourcePath}}`**
展開至原始程式碼路徑。如果您使用此變數，則必須同時在快閃和建置命令中使用。
**`{{sdkPath}}`**
在組建和快閃記憶體命令中使用`userData.sdkConfiguration.path`時， 會擴展至 中的值。
**`{{device.connectivity.serialPort}}`**
展開至序列埠。
**`{{device.identifiers[?(@.name == 'serialNo')].value[0]}}`**
展開至裝置的序號。
**`{{enableTests}}`**
指出建置是否用於測試 (值 1) 或示範 (值 0) 的整數值。
**`{{buildImageName}}`**
檔案名稱使用建置命令產生的映像建置。
**`{{otaCodeSignerPemFile}}`**
OTA 程式碼簽署者的 PEM 檔案。
**`{{config.idtRootPath}}`**
展開至 AWS IoT Device Tester 根路徑。當組建和快閃記憶體命令使用時，此變數會取代 IDT 的絕對路徑。
# 使用 IDT 使用者介面執行 FreeRTOS 資格套件
從 IDT v4.3.0 開始， AWS IoT Device Tester 針對 FreeRTOS (IDT-FreeRTOS) 包含 Web 型使用者介面，可讓您與 IDT 命令列可執行檔和相關組態檔案互動。您可以使用 IDT-FreeRTOS UI 建立新的組態以執行 IDT 測試，或修改現有的組態。您也可以使用 UI 來叫用 IDT 可執行檔並執行測試。
IDT-FreeRTOS UI 提供下列函數：
+ 簡化 IDT-FreeRTOS 測試的組態檔案設定。
+ 使用 IDT-FreeRTOS 來簡化執行資格測試。
如需使用命令列執行資格測試的 相關資訊，請參閱 [微控制器電路板的第一個測試](qual-steps.md)。
本節說明使用 IDT-FreeRTOS UI 的先決條件，並說明如何開始在 UI 中執行資格測試。
**Topics**
+ [設定先決條件以執行 FreeRTOS 資格套件](dev-tester-ui-prereqs.md)
+ [IDT-FreeRTOS UI 入門](dev-tester-ui-getting-started.md)
# 設定先決條件以執行 FreeRTOS 資格套件
本節說明使用 測試微控制器的先決條件 AWS IoT Device Tester。
**Topics**
+ [使用支援的 Web 瀏覽器](#idt-ui-supported-web-browser)
+ [下載 FreeRTOS](#ui-download-afr)
+ [下載 IDT for FreeRTOS](#ui-download-dev-tester-afr)
+ [建立和設定 AWS 帳戶](#ui-config-aws-account)
+ [AWS IoT Device Tester 受管政策](#ui-managed-policy)
## 使用支援的 Web 瀏覽器
IDT-FreeRTOS UI 支援下列 Web 瀏覽器。
| 瀏覽器 | 版本 |
| --- | --- |
| Google Chrome | 最近三個主要版本 |
| Mozilla Firefox | 最近三個主要版本 |
| Microsoft Edge | 最近三個主要版本 |
| 適用於 macOS 的 Apple Safari | 最近三個主要版本 |
我們建議您使用 Google Chrome 或 Mozilla Firefox 以獲得更好的體驗。
**注意**
IDT-FreeRTOS UI 不支援 Microsoft Internet Explorer。
## 下載 FreeRTOS
您可以使用下列命令從 [GitHub](https://github.com/aws/amazon-freertos) 下載 FreeRTOS 版本：
```
git clone --branch --recurse-submodules https://github.com/aws/amazon-freertos.git
cd amazon-freertos
git submodule update --checkout --init --recursive
```
其中 是對應於 中所列 IDT 版本的 FreeRTOS 版本 （例如 202007.00)[支援的 版本 AWS IoT Device Tester](dev-test-versions-afr.md)。這可確保您擁有完整的原始程式碼，包括子模組，並針對 FreeRTOS 版本使用正確的 IDT 版本，反之亦然。
Windows 的路徑長度限制為 260 個字元。FreeRTOS 的路徑結構非常深入，因此如果您使用的是 Windows，請將檔案路徑保持在 260 個字元的限制以下。例如，將 FreeRTOS 複製到 ，`C:\FreeRTOS`而不是 `C:\Users\username\programs\projects\myproj\FreeRTOS\`。
### LTS 資格的考量 （使用 LTS 程式庫的 FreeRTOS 資格）
+ 為了讓您的微型控制器在 AWS Partner Device Catalog 中指定為支援長期支援 (LTS) 型 FreeRTOS 版本，您必須提供資訊清單檔案。如需詳細資訊，請參閱 [FreeRTOS 資格指南中的 FreeRTOS 資格檢查清單](https://docs.aws.amazon.com/freertos/latest/qualificationguide/afq-checklist.html)。 *FreeRTOS *
+ 為了驗證您的微型控制器是否支援以 LTS 為基礎的 FreeRTOS 版本，並有資格提交至 AWS Partner Device Catalog，您必須使用 AWS IoT Device Tester (IDT) 搭配 FreeRTOS Qualification (FRQ) 測試套件版本 v1.4.x。
+ FreeRTOS 的 LTS 型版本支援僅限於 FreeRTOS 的 202012.xx 版本。
## 下載 IDT for FreeRTOS
每個 FreeRTOS 版本都有對應的 IDT for FreeRTOS 版本，以執行資格測試。從 下載適當的 IDT for FreeRTOS 版本[支援的 版本 AWS IoT Device Tester](dev-test-versions-afr.md)。
將 IDT for FreeRTOS 解壓縮到檔案系統上具有讀取和寫入許可的位置。由於 Microsoft Windows 具有路徑長度的字元限制，請將 IDT for FreeRTOS 擷取至根目錄，例如 `C:\`或 `D:\`。
**注意**
我們建議您將 IDT 套件擷取到本機磁碟機。允許多個使用者從共用位置執行 IDT，例如 NFS 目錄或 Windows 網路共用資料夾，可能會導致系統沒有回應或資料損毀。
## 建立和設定 AWS 帳戶
### 註冊 AWS 帳戶
如果您沒有 AWS 帳戶，請完成下列步驟來建立一個。
**註冊 AWS 帳戶**
1. 開啟 [https://portal.aws.amazon.com/billing/signup](https://portal.aws.amazon.com/billing/signup)。
1. 請遵循線上指示進行。
部分註冊程序需接收來電或簡訊，並在電話鍵盤輸入驗證碼。
當您註冊 時 AWS 帳戶，*AWS 帳戶根使用者*會建立 。根使用者有權存取該帳戶中的所有 AWS 服務 和資源。作為安全最佳實務，請將管理存取權指派給使用者，並且僅使用根使用者來執行[需要根使用者存取權的任務](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks)。
AWS 會在註冊程序完成後傳送確認電子郵件給您。您可以隨時登錄 [https://aws.amazon.com/](https://aws.amazon.com/) 並選擇**我的帳戶**，以檢視您目前的帳戶活動並管理帳戶。
### 建立具有管理存取權的使用者
註冊 後 AWS 帳戶，請保護 AWS 帳戶根使用者、啟用 AWS IAM Identity Center和建立管理使用者，以免將根使用者用於日常任務。
**保護您的 AWS 帳戶根使用者**
1. 選擇**根使用者**並輸入 AWS 帳戶 您的電子郵件地址，以帳戶擁有者[AWS 管理主控台](https://console.aws.amazon.com/)身分登入 。在下一頁中，輸入您的密碼。
如需使用根使用者登入的說明，請參閱 *AWS 登入 使用者指南*中的[以根使用者身分登入](https://docs.aws.amazon.com/signin/latest/userguide/console-sign-in-tutorials.html#introduction-to-root-user-sign-in-tutorial)。
1. 若要在您的根使用者帳戶上啟用多重要素驗證 (MFA)。
如需說明，請參閱《*IAM 使用者指南*》中的[為您的 AWS 帳戶 根使用者 （主控台） 啟用虛擬 MFA 裝置](https://docs.aws.amazon.com/IAM/latest/UserGuide/enable-virt-mfa-for-root.html)。
**建立具有管理存取權的使用者**
1. 啟用 IAM Identity Center。
如需指示，請參閱《AWS IAM Identity Center 使用者指南》**中的[啟用 AWS IAM Identity Center](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-set-up-for-idc.html)。
1. 在 IAM Identity Center 中，將管理存取權授予使用者。
如需使用 IAM Identity Center 目錄 做為身分來源的教學課程，請參閱*AWS IAM Identity Center 《 使用者指南*》中的[使用預設值設定使用者存取 IAM Identity Center 目錄](https://docs.aws.amazon.com//singlesignon/latest/userguide/quick-start-default-idc.html)。
**以具有管理存取權的使用者身分登入**
+ 若要使用您的 IAM Identity Center 使用者簽署，請使用建立 IAM Identity Center 使用者時傳送至您電子郵件地址的簽署 URL。
如需使用 IAM Identity Center 使用者登入的說明，請參閱*AWS 登入 《 使用者指南*》中的[登入 AWS 存取入口網站](https://docs.aws.amazon.com/signin/latest/userguide/iam-id-center-sign-in-tutorial.html)。
**指派存取權給其他使用者**
1. 在 IAM Identity Center 中，建立一個許可集來遵循套用最低權限的最佳實務。
如需指示，請參閱《AWS IAM Identity Center 使用者指南》**中的[建立許可集](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-started-create-a-permission-set.html)。
1. 將使用者指派至群組，然後對該群組指派單一登入存取權。
如需指示，請參閱《AWS IAM Identity Center 使用者指南》**中的[新增群組](https://docs.aws.amazon.com//singlesignon/latest/userguide/addgroups.html)。
## AWS IoT Device Tester 受管政策
若要讓裝置測試人員執行 和 收集指標， `AWSIoTDeviceTesterForFreeRTOSFullAccess`受管政策包含下列許可：
+ `iot-device-tester:SupportedVersion`
准許取得 IDT 支援的 FreeRTOS 版本和測試套件版本清單，以便從 取得 AWS CLI。
+ `iot-device-tester:LatestIdt`
准許取得可供下載的 AWS IoT Device Tester 最新版本。
+ `iot-device-tester:CheckVersion`
授予檢查產品、測試套件和 AWS IoT Device Tester 版本之組合是否相容的許可。
+ `iot-device-tester:DownloadTestSuite`
准許 AWS IoT Device Tester 下載測試套件。
+ `iot-device-tester:SendMetrics`
准許發佈 AWS IoT Device Tester 用量指標資料。
# IDT-FreeRTOS UI 入門
本節說明如何使用 IDT-FreeRTOS UI 來建立或修改您的組態，然後示範如何執行測試。
**Topics**
+ [設定 AWS 登入資料](#configure-aws-credentials)
+ [開啟 IDT-FreeRTOS UI](#open-idt-ui)
+ [建立新的組態](#create-new-configuration)
+ [修改現有的組態](#modify-existing-configuration)
+ [執行資格測試](#run-tests-from-ui)
## 設定 AWS 登入資料
您必須為您在 中建立 AWS 的使用者設定登入資料[建立和設定 AWS 帳戶](dev-tester-ui-prereqs.md#ui-config-aws-account)。您可以使用下列兩種方式的其中之一指定登入資料：
+ 在登入資料檔案中
+ 做為環境變數
### 使用 AWS 登入資料檔案設定登入資料
IDT 會使用與 AWS CLI相同的登入資料檔案。如需詳細資訊，請參閱[組態與登入資料檔案](https://docs.aws.amazon.com/cli/latest/userguide/cli-config-files.html)。
登入資料檔案的位置會有所不同，取決於您使用的作業系統：
+ macOS, Linux: `~/.aws/credentials`
+ Windows：`C:\Users\UserName\.aws\credentials`
以下列格式將您的 AWS 登入資料新增至 `credentials` 檔案：
```
[default]
aws_access_key_id =
aws_secret_access_key =
```
**注意**
如果您不使用`default` AWS 設定檔，請務必在 IDT-FreeRTOS UI 中指定設定檔名稱。如需設定檔的詳細資訊，請參閱[組態和登入資料檔案設定](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html)。
### 使用環境變數設定 AWS 登入資料
環境變數是由作業系統維護且由系統命令使用的變數。如果您關閉 SSH 工作階段，則不會儲存它們。IDT-FreeRTOS UI 使用 `AWS_ACCESS_KEY_ID`和 `AWS_SECRET_ACCESS_KEY`環境變數來存放您的 AWS 登入資料。
若要在 Linux、macOS 或 Unix 上設定這些變數，請使用 **export**：
```
export AWS_ACCESS_KEY_ID=
export AWS_SECRET_ACCESS_KEY=
```
若要在 Windows 上設定這些變數，請使用 **set**：
```
set AWS_ACCESS_KEY_ID=
set AWS_SECRET_ACCESS_KEY=
```
## 開啟 IDT-FreeRTOS UI
**開啟 IDT-FreeRTOS UI**
1. 下載支援的 IDT-FreeRTOS 版本，並將下載的封存解壓縮到檔案系統上具有讀取和寫入許可的位置。
1. 執行下列命令以導覽至 IDT-FreeRTOS 安裝目錄：
```
cd devicetester-extract-location/bin
```
1. 執行下列命令以開啟 IDT-FreeRTOS UI：
------
#### [ Linux ]
```
.devicetestergui_linux_x86-64.exe
```
------
#### [ Windows ]
```
./devicetestergui_win_x64-64
```
------
#### [ macOS ]
```
./devicetestergui_mac_x86-64
```
**注意**
在 Mac 上，若要允許系統執行 UI，請前往**系統偏好設定 -> 安全性與隱私權**。當您執行測試時，您可能需要再執行三次。
------
IDT-FreeRTOS UI 會在您的預設瀏覽器中開啟。如需支援的瀏覽器相關資訊，請參閱 [使用支援的 Web 瀏覽器](dev-tester-ui-prereqs.md#idt-ui-supported-web-browser)。
## 建立新的組態
如果您是第一次使用，則必須建立新的組態，以設定 IDT-FreeRTOS 執行測試所需的 JSON 組態檔案。然後，您可以執行測試或修改已建立的組態。
如需 `config.json`、 `device.json`和 `userdata.json` 檔案的範例，請參閱 [微控制器電路板的第一個測試](qual-steps.md)。如需僅用於執行低功耗藍牙 (BLE) 測試`resource.json`的檔案範例，請參閱 [執行低功耗藍牙測試](afr-bridgekeeper-dt-bt.md)。
**建立新的組態**
1. 在 IDT-FreeRTOS UI 中，開啟導覽功能表，然後選擇**建立新組態**。
**重要**
您必須先設定 AWS 登入資料，才能開啟 UI。如果您尚未設定登入資料，請關閉 IDT-FreeRTOS UI 瀏覽器視窗，遵循 中的步驟[設定 AWS 登入資料](#configure-aws-credentials)，然後重新開啟 IDT-FreeRTOS UI。
1. 遵循組態精靈來輸入用於執行資格測試的 IDT 組態設定。精靈會在位於 `devicetester-extract-location/config`目錄中的 JSON 組態檔案中設定下列設定。
+ **AWS settings**—IDT-FreeRTOS 在 AWS 帳戶 測試執行期間用來建立 AWS 資源的資訊。這些設定是在 `config.json` 檔案中設定。
+ **FreeRTOS 儲存庫** - FreeRTOS 儲存庫和移植程式碼的絕對路徑，以及您要執行的資格類型。這些設定是在 `userdata.json` 檔案中設定。
您必須先為裝置移植 FreeRTOS，才能執行資格測試。如需詳細資訊，請參閱 [FreeRTOS 移植指南](https://docs.aws.amazon.com/freertos/latest/portingguide/)
+ **建置和刷新** - 硬體的建置和刷新命令，可讓 IDT 自動在主機板上建置和刷新測試。這些設定是在 `userdata.json` 檔案中設定。
+ **裝置** - 要測試之裝置的裝置集區設定。這些設定是在 `id`和 `sku`欄位中設定，以及 `device.json` 檔案中裝置集區的 `devices`區塊。
+ **網路**：測試裝置網路通訊支援的設定。這些設定是在 `device.json` 檔案的 `features` 區塊，以及 檔案的 `clientWifiConfig`和 `testWifiConfig`區塊中設定`userdata.json`。
+ **Echo 伺服器** - 安全通訊端測試的 echo 伺服器組態設定。這些設定是在 `userdata.json` 檔案中設定。
如需 echo 伺服器組態的詳細資訊，請參閱 [https://docs.aws.amazon.com/freertos/latest/portingguide/afr-echo-server.html](https://docs.aws.amazon.com/freertos/latest/portingguide/afr-echo-server.html)。
+ **CMake**—（選用） 執行 CMake 組建功能測試的設定。只有在您使用 CMake 做為建置系統時，才需要此組態。這些設定是在 `userdata.json` 檔案中設定。
+ **BLE** - 執行低功耗藍牙功能測試的設定。這些設定是在 `device.json` 檔案的 `features`區塊和 `resource.json`檔案中設定。
+ **OTA** - 執行 OTA 功能測試的設定。這些設定是在 `device.json` 檔案的 `features`區塊和 `userdata.json`檔案中設定。
1. 在**檢閱**頁面上，驗證您的組態資訊。
完成檢閱組態後，若要執行資格測試，請選擇**執行測試**。
## 修改現有的組態
如果您已經為 IDT 設定組態檔案，則可以使用 IDT-FreeRTOS UI 來修改現有的組態。請確定您現有的組態檔案可在 `devicetester-extract-location/config`目錄中使用。
**修改新組態**
1. 在 IDT-FreeRTOS UI 中，開啟導覽功能表，然後選擇**編輯現有組態**。
組態儀表板會顯示現有組態設定的相關資訊。如果組態不正確或無法使用，則該組態的狀態為 `Error validating configuration`。
1. 若要修改現有的組態設定，請完成下列步驟：
1. 選擇組態設定的名稱以開啟其設定頁面。
1. 修改設定，然後選擇**儲存**以重新產生對應的組態檔案。
修改組態完成後，請確認所有組態設定都通過驗證。如果每個組態設定的狀態為 `Valid`，您可以使用此組態執行資格測試。
## 執行資格測試
建立 IDT-FreeRTOS 組態之後，您可以執行資格測試。
**執行資格測試**
1. 驗證您的組態。
1. 在導覽功能表中，選擇**執行測試**。
1. 若要開始測試執行，請選擇**開始測試**。
IDT-FreeRTOS 會執行資格測試，並在測試**執行器**主控台中顯示測試執行摘要和任何錯誤。測試執行完成後，您可以從下列位置檢視測試結果和日誌：
+ 測試結果位於 `devicetester-extract-location/results/execution-id`目錄中。
+ 測試日誌位於 `devicetester-extract-location/results/execution-id/logs`目錄中。
如需測試結果和日誌的詳細資訊，請參閱 [檢視 IDT for FreeRTOS 結果](view-results-frq.md)和 [檢視 IDT for FreeRTOS 日誌](view-logs-frq.md)。
# 執行低功耗藍牙測試
本節說明如何使用 AWS IoT Device Tester for FreeRTOS 設定和執行低功耗藍牙測試。
核心資格不需要進行藍牙測試。如果您不想使用 FreeRTOS 藍牙支援測試裝置，可以略過此設定，請務必將 device.json 中的 BLE 功能設為 `No`。
## 先決條件
+ 請遵循中的說明進行[微控制器電路板的第一個測試](qual-steps.md)
+ Raspberry Pi 4B 或 3B\$1。(需要執行 Raspberry Pi BLE 配套應用程式)
+ Raspberry Pi 軟體使用的 MicroSD 卡和 SD 卡的轉接卡。
## Raspberry Pi 設定
若要測試待測裝置的 BLE 功能 (DUT)，您必須擁有 Raspberry Pi Model 4B 或 3B\$1。
**設定您的 Raspberry Pi 以執行 BLE 測試**
1. 下載其中一個自訂 Yocto 映像，其中包含執行測試所需的軟體。
+ [ Raspberry Pi 4B 的影像](https://docs.aws.amazon.com/freertos/latest/userguide/freertos/IDTFR_BLE_RaspberryPi4B_1.0.0_2021-04-13.rpi-sd.img)
+ [ Raspberry Pi 3B\$1 的影像](https://docs.aws.amazon.com/freertos/latest/userguide/freertos/IDTFR_BLE_RaspberryPi3Bplus_1.0.0_2021-04-13.rpi-sd.img)
**注意**
Yocto 映像只能用於透過 AWS IoT Device Tester for FreeRTOS 進行測試，不能用於任何其他用途。
1. 將 yocto 映像刷到 Raspberry Pi 的 SD 卡上。
1. 使用 SD 卡片撰寫工具 (例如 [Etcher](https://www.balena.io/etcher)) 將下載的 `image-name.rpi-sd.img` 檔案刷到 SD 卡片上。由於作業系統映像較大，此步驟需要時間才能完成。從電腦退出 SD 卡，並將 microSD 卡插入 Raspberry Pi。
1. 設定您的 Raspberry Pi。
1. 第一次啟動時，建議您將 Raspberry Pi 連接到螢幕、鍵盤和滑鼠。
1. 將您的 Raspberry Pi 連接到 micro USB 電源。
1. 使用預設的登入資料進行登入。使用者 ID 請輸入 **root**。密碼請輸入 **idtafr**。
1. 使用乙太網路或 Wi-Fi 連線將 Raspberry Pi 連接到您的網路。
1. 若要透過 Wi-Fi 連接 Raspberry Pi，請開啟 Raspberry Pi 的 `/etc/wpa_supplicant.conf`，然後將您的 Wi-Fi 登入資料新增到 `Network` 組態。
```
ctrl_interface=/var/run/wpa_supplicant
ctrl_interface_group=0
update_config=1
network={
scan_ssid=1
ssid="your-wifi-ssid"
psk="your-wifi-password"
}
```
1. 執行 `ifup wlan0` 以啟動 Wi-Fi 連線。連接到 Wi-Fi 網路可能需時一分鐘。
1. 若為乙太網路連線，請執行 `ifconfig eth0`。若為 Wi-Fi 連線，請執行 `ifconfig wlan0`。請記下在命令輸出中顯示為 `inet addr` 的 IP 地址。在此程序稍後您將需要該 IP 地址。
1. (選用) 該測試會使用 yocto 映像預設的登入資料，透過 SSH 在 Pi Raspberry 上執行命令。如需增加安全性，我們建議您為 SSH 設定公開金鑰身分驗證並停用以密碼為基礎的 SSH。
1. 使用 OpenSSL `ssh-keygen` 命令建立 SSH 金鑰。如果您的主機電腦上已有 SSK 金鑰對，最佳實務是建立新的金鑰對，以允許 AWS IoT Device Tester FreeRTOS 登入您的 Raspberry Pi。
**注意**
Windows 不附帶已安裝的 SSH 用戶端。有關如何在 Windows 安裝 SSH 用戶端的詳細資訊，請參閱[下載 SSH 軟體](https://www.ssh.com/ssh/#sec-Download-client-software)。
1. `ssh-keygen` 命令會提示您提供金鑰對的存放名稱和路徑。根據預設，該金鑰對檔案會命名為 `id_rsa` (私有金鑰) 和 `id_rsa.pub` (公有金鑰)。在 macOS 和 Linux 上，這些檔案的預設位置是 `~/.ssh/`。在 Windows 上，預設位置為 `C:\Users\user-name`。
1. 提示您輸入金鑰字詞時，只要按 Enter 鍵即可。
1. 若要將 SSH 金鑰新增至 Raspberry Pi AWS IoT Device Tester ，以便 FreeRTOS 可以登入裝置，請從主機電腦使用 `ssh-copy-id`命令。此命令會將您的公有金鑰新增至 Raspberry Pi 上的 `~/.ssh/authorized_keys` 檔案。
`ssh-copy-id root@raspberry-pi-ip-address`
1. 提示您輸入密碼時，請輸入 **idtafr**。此為 yocto 映像預設的密碼。
**注意**
`ssh-copy-id` 命令會假設公有金鑰名稱為 `id_rsa.pub`。在 macOS 和 Linux，預設位置是 ` ~/.ssh/`。在 Windows 上，預設位置為 `C:\Users\user-name\.ssh`。如果您給公有金鑰不同的名稱，或將其存放在不同的位置中，則必須在 `ssh-copy-id` 中使用 `-i` 選項，以指定 SSH 公有金鑰的完整路徑 (例如，`ssh-copy-id -i ~/my/path/myKey.pub`)。如需有關建立 SSH 金鑰和複製公有金鑰的詳細資訊，請參閱 [SSH-COPY-ID](https://www.ssh.com/ssh/copy-id)。
1. 若要測試公有金鑰身分驗證運作正常，請執行 `ssh -i /my/path/myKey root@raspberry-pi-device-ip`。
如果您未被提示輸入密碼，則您的公開金鑰身分驗證運作正常。
1. 請確認您是用公開金鑰登入您的 Raspberry Pi，然後停用密碼為基礎的 SSH。
1. 在 Raspberry Pi 上編輯 `/etc/ssh/sshd_config` 檔案。
1. 將 `PasswordAuthentication` 屬性設為 `no`。
1. 儲存並關閉 `sshd_config` 檔案。
1. 執行 `/etc/init.d/sshd reload` 以重新載入 SSH 伺服器。
1. 建立 `resource.json` 檔案。
1. 在您解壓縮 AWS IoT Device Tester 的目錄中，建立名為 的檔案`resource.json`。
1. 新增有關您 Raspberry Pi 的以下資訊至檔案，再以 Raspberry Pi 的 IP 地址替換 *rasp-pi-ip-address*。
```
[
{
"id": "ble-test-raspberry-pi",
"features": [
{"name":"ble", "version":"4.2"}
],
"devices": [
{
"id": "ble-test-raspberry-pi-1",
"connectivity": {
"protocol": "ssh",
"ip": "rasp-pi-ip-address"
}
}
]
}
]
```
1. 如果您未選擇對 SSH 使用公有金鑰身分驗證，請將以下內容新增至 `resource.json` 檔案的 `connectivity`區段。
```
"connectivity": {
"protocol": "ssh",
"ip": "rasp-pi-ip-address",
"auth": {
"method": "password",
"credentials": {
"user": "root",
"password": "idtafr"
}
}
}
```
1. (選用) 如果您選擇使用 SSH 的公開金鑰身分驗證，請將下列項目新增至 `resource.json` 檔案的 `connectivity` 部分。
```
"connectivity": {
"protocol": "ssh",
"ip": "rasp-pi-ip-address",
"auth": {
"method": "pki",
"credentials": {
"user": "root",
"privKeyPath": "location-of-private-key"
}
}
}
```
## FreeRTOS 裝置設定
在您的 `device.json` 檔案中將 `BLE` 功能設為 `Yes`。如果您在藍牙測試可用之前開始使用 `device.json` 檔案，則需要將 BLE 功能新增到 `features` 陣列：
```
{
...
"features": [
{
"name": "BLE",
"value": "Yes"
},
...
}
```
## 執行 BLE 測試
在您啟用 `device.json` 中的 BLE 功能後，BLE 測試會在您執行 `devicetester_[linux | mac | win_x86-64] run-suite` 時執行，且*不會指定群組 ID*。
如果您想要單獨執行 BLE 測試，您可以指定 BLE 的群組 ID：`devicetester_[linux | mac | win_x86-64] run-suite --userdata path-to-userdata/userdata.json --group-id FullBLE`。
為獲得最可靠效能，請將您的 Raspberry Pi 靠近待測裝置 (DUT)。
## 故障診斷 BLE 測試
確定您已遵循 [微控制器電路板的第一個測試](qual-steps.md) 中的步驟。如果 BLE 以外的測試失敗，則該問題可能並非因為 藍牙組態所導致。
# 執行 FreeRTOS 資格套件
您可以使用 AWS IoT Device Tester for FreeRTOS 可執行檔與 IDT for FreeRTOS 互動。以下命令列範例會說明如何執行裝置集區 (一組相同的裝置) 的資格測試。
------
#### [ IDT v3.0.0 and later ]
```
devicetester_[linux | mac | win] run-suite \
--suite-id suite-id \
--group-id group-id \
--pool-id your-device-pool \
--test-id test-id \
--upgrade-test-suite y|n \
--update-idt y|n \
--update-managed-policy y|n \
--userdata userdata.json
```
在裝置集區上執行測試套件。`userdata.json` 檔案必須位於 `devicetester_extract_location/devicetester_afreertos_[win|mac|linux]/configs/` 目錄。
**注意**
如果您在 Windows 上執行 IDT for FreeRTOS，請使用正斜線 (/) 指定`userdata.json`檔案的路徑。
使用下列命令來執行特定的測試群組：
```
devicetester_[linux | mac | win] run-suite \
--suite-id FRQ_1.0.1 \
--group-id group-id \
--pool-id pool-id \
--userdata userdata.json
```
如果您是在單一裝置集區上執行單一測試套件 (也就是說，您在 `device.json` 檔案中僅定義了一個裝置集區)，`suite-id` 和 `pool-id` 參數則為選用。
使用下列命令，在測試群組中執行特定的測試案例：
```
devicetester_[linux | mac | win_x86-64] run-suite \
--group-id group-id \
--test-id test-id
```
您可以使用 `list-test-cases` 命令列出測試群組中的測試案例。IDT for FreeRTOS 命令列選項
**group-id**
(選用) 要執行的測試群組，以逗號分隔的清單。如果未指定，IDT 會執行測試套件中的所有測試群組。
**pool-id**
(選用) 要測試的裝置集區。如果您在 `device.json` 中定義多個裝置集區，這則為必要。如果您只有一個裝置集區，就可以省略此選項。
**suite-id**
(選用) 要執行的測試套件版本。如果未指定，IDT 則會使用系統的測試目錄中的最新版本。
從 IDT v3.0.0 開始，IDT 會在線上檢查是否有更新的測試套件。如需詳細資訊，請參閱[測試套件版本](idt-test-suite-versions.md)。
**test-id**
(選用) 要執行的測試，以逗號分隔的清單。若已指定，`group-id` 必須指定單一群組。
**Example**
```
devicetester_[linux | mac | win_x86-64] run-suite --group-id mqtt --test-id mqtt_test
```
**update-idt**
（選用） 如果未設定此參數，且有較新的 IDT 版本可用，系統會提示您更新 IDT。如果此參數設定為 `Y`，則如果 IDT 偵測到有較新的版本可用，則會停止測試執行。如果此參數設定為 `N`，IDT 將繼續測試執行。
**update-managed-policy**
（選用） 如果未使用此參數，且 IDT 偵測到您的受管政策不是up-to-date，系統會提示您更新受管政策。如果此參數設定為 `Y`，則如果 IDT 偵測到您的受管政策不是up-to-date，則將停止測試執行。如果此參數設定為 `N`，IDT 將繼續測試執行。
**upgrade-test-suite**
(選用) 若未使用，且有可用的更新測試套件版本，則會提示您進行下載。若要隱藏提示，請指定 `y` 以一律下載最新測試套件，或指定 `n` 以使用指定的測試套件或系統上的最新版本。
**Example**
**範例**
若要一律下載並使用最新測試套件，請使用下列命令。
```
devicetester_[linux | mac | win_x86-64] run-suite --userdata userdata file --group-id group ID --upgrade-test-suite y
```
若要在系統上使用最新測試套件，請使用下列命令。
```
devicetester_[linux | mac | win_x86-64] run-suite --userdata userdata file --group-id group ID --upgrade-test-suite n
```
**h**
使用說明選項以進一步了解 `run-suite` 選項。
**Example**
**範例**
```
devicetester_[linux | mac | win_x86-64] run-suite -h
```
------
#### [ IDT v1.7.0 and earlier ]
```
devicetester_[linux | mac | win] run-suite \
--suite-id suite-id \
--pool-id your-device-pool \
--userdata userdata.json
```
`userdata.json` 檔案應位於 `devicetester_extract_location/devicetester_afreertos_[win|mac|linux]/configs/` 目錄中。
**注意**
如果您在 Windows 上執行 IDT for FreeRTOS，請使用正斜線 (/) 來指定`userdata.json`檔案的路徑。
使用下列命令來執行特定的測試群組。
```
devicetester_[linux | mac | win] run-suite \
--suite-id FRQ_1 --group-id group-id \
--pool-id pool-id \
--userdata userdata.json
```
如果您是在單一裝置集區上執行單一測試套件 (也就是說，您在 `device.json` 檔案中僅定義了一個裝置集區)，則 `suite-id` 和 `pool-id` 為選用參數。IDT for FreeRTOS 命令列選項
**group-id**
(選用) 指定測試群組。
**pool-id**
指定要測試的裝置集區。如果您只有一個裝置集區，就可以省略此選項。
**suite-id**
(選用) 指定要執行的測試套件。
------
## IDT for FreeRTOS 命令
IDT for FreeRTOS 命令支援下列操作：
------
#### [ IDT v3.0.0 and later ]
**`help`**
列出所指定命令的相關資訊。
**`list-groups`**
列出指定套件中的群組。
**`list-suites`**
列出可用套件。
**`list-supported-products`**
列出支援的產品和測試套件版本。
**`list-supported-versions`**
列出目前 IDT 版本支援的 FreeRTOS 和測試套件版本。
**`list-test-cases`**
列出指定群組中的測試案例。
**`run-suite`**
在裝置集區上執行測試套件。
使用 `--suite-id` 選項以指定測試套件版本，或省略它以使用系統上的最新版本。
使用 `--test-id` 執行個別測試案例。
**Example**
```
devicetester_[linux | mac | win_x86-64] run-suite --group-id mqtt --test-id mqtt_test
```
如需選項的完整清單，請參閱[執行 FreeRTOS 資格套件](#run-tests)。
從 IDT v3.0.0 開始，IDT 會在線上檢查是否有更新的測試套件。如需詳細資訊，請參閱[測試套件版本](idt-test-suite-versions.md)。
------
#### [ IDT v1.7.0 and earlier ]
**`help`**
列出所指定命令的相關資訊。
**`list-groups`**
列出指定套件中的群組。
**`list-suites`**
列出可用套件。
**`run-suite`**
在裝置集區上執行測試套件。
------
## 重新取得資格的測試
隨著新版本的 IDT for FreeRTOS 資格測試發佈，或隨著您更新電路板特定的套件或裝置驅動程式，您可以使用 IDT for FreeRTOS 來測試微控制器電路板。如需後續資格，請確定您擁有最新版本的 FreeRTOS 和 IDT for FreeRTOS，並再次執行資格測試。
# 檢視 IDT for FreeRTOS 結果
執行期間，IDT 會將錯誤寫入主控台、日誌檔和測試報告。IDT 完成資格測試套件後，即會將測試執行摘要寫入主控台，並產生兩份測試報告。您可以在 `devicetester-extract-location/results/execution-id/` 中找到這些報告。這兩份報告都會從資格測試套件執行擷取結果。
`awsiotdevicetester_report.xml` 是您提交 AWS 至 以在 AWS Partner Device Catalog 中列出裝置的資格測試報告。該報告包含下列元素：
+ IDT for FreeRTOS 版本。
+ 已測試的 FreeRTOS 版本。
+ 根據通過的測試，裝置支援的 FreeRTOS 功能。
+ `device.json` 檔案中指定的 SKU 和裝置名稱。
+ `device.json` 檔案中所指定裝置的功能。
+ 測試案例結果的彙總摘要。
+ 根據裝置功能 (如 FullWiFi、FullMQTT 等) 進行測試的程式庫測試案例結果明細。
+ FreeRTOS 的此資格是否適用於使用 LTS 程式庫的 202012.00 版。
`FRQ_Report.xml` 報告採用標準的 [JUnit XML 格式](https://llg.cubic.org/docs/junit/)。您可以將它整合到 CI/CD 平台，例如 [Jenkins](https://jenkins.io/)、[Bamboo](https://www.atlassian.com/software/bamboo) 等等。該報告包含下列元素：
+ 測試案例結果的彙總摘要。
+ 根據裝置功能進行測試的程式庫測試案例結果明細。
# 解譯 IDT for FreeRTOS 結果
`awsiotdevicetester_report.xml` 或 `FRQ_Report.xml` 中的報告部分會列出所執行測試的結果。
第一個 XML 標籤 `` 包含測試執行的整體摘要。例如：
``
**``標籤中使用的屬性**
**`name`**
測試套件的名稱。
**`time`**
執行資格套件所花費的時間 (以秒為單位)。
**`tests`**
所執行的測試案例數目。
**`failures`**
已執行但未通過的測試案例數目。
**`errors`**
IDT for FreeRTOS 無法執行的測試案例數量。
**`disabled`**
此屬性未使用，可忽略。
如果沒有測試案例失敗或錯誤，您的裝置符合執行 FreeRTOS 的技術需求，並且可以與 AWS IoT 服務互通。如果您選擇在 AWS 合作夥伴裝置目錄中列出您的裝置，您可以使用此報告做為資格證據。
在測試案例失敗或發生錯誤的情況下，您可以透過檢閱 `` XML 標籤來識別失敗的測試案例。`` 標籤內的 `` XML 標籤會顯示測試群組的測試案例結果摘要。
``
該格式與 `` 標籤相似，但具有不使用且可忽略的 `skipped` 屬性。在每個 `` XML 標籤內，系統為測試群組執行的每個測試案例都有 `` 標籤。例如：
``
**``標籤中使用的屬性**
**`name`**
受測產品名稱。
**`version`**
受測產品版本。
**`sdk`**
如果您使用 SDK 執行 IDT，此區塊會包含 SDK 的名稱和版本。如果您未使用 SDK 執行 IDT，則此區塊包含：
```
N/A
N/A
```
**`features`**
驗證的功能。標記為 `required` 的功能為提交主機板獲得資格時所需。下列程式碼片段顯示此項目在 `awsiotdevicetester_report.xml` 檔案中的顯示方式。
```
```
標記為 `optional` 的功能不需要進行資格測試。以下程式碼片段顯示選用功能。
```
```
如果必要功能沒有測試失敗或錯誤，您的裝置會符合執行 FreeRTOS 的技術需求，並且可以與 AWS IoT 服務互通。如果您想要在[AWS 合作夥伴裝置目錄中](https://partners.amazonaws.com/qualified-devices)列出您的裝置，您可以使用此報告做為資格證據。
如果測試發生失敗或錯誤，您可以檢閱 `` XML 標籤來識別失敗的測試。`` 標籤內的 `` XML 標籤會顯示測試群組的測試結果摘要。例如：
```
```
格式類似於 ``標籤，但具有未使用的`skipped`屬性，可以忽略。在每個 `` XML 標籤內，測試群組每個執行的測試都有 `` 標籤。例如：
```
```
**`lts`**
如果您符合使用 LTS 程式庫的 FreeRTOS 版本資格，則為 true，否則為 false。
**``標籤中使用的屬性**
**`name`**
測試案例的名稱。
**`attempts`**
IDT for FreeRTOS 執行測試案例的次數。
當測試案例失敗或發生錯誤時，系統就會將 `` 或 `` 標籤新增至 `` 標籤，其中附有相關資訊以利故障診斷。例如：
```
Reason for the test case failure
Reason for the test case execution error
```
如需詳細資訊，請參閱[對 錯誤進行故障診斷](dt-afr-troubleshooting.md)。
# 檢視 IDT for FreeRTOS 日誌
您可以在 中找到 IDT for FreeRTOS 從測試執行產生的日誌`devicetester-extract-location/results/execution-id/logs`。該工具會產生兩組日誌：
**`test_manager.log`**
包含從 IDT for FreeRTOS 產生的日誌 （例如，日誌相關的組態和報告產生）。
**`test_group_id__test_case_id.log` (例如，`FullMQTT__Full_MQTT.log`)**
測試案例的日誌檔案，包括來自測試中裝置的輸出。日誌檔案會根據執行的測試群組和測試案例命名。
# 開發並執行您自己的 IDT 測試套件
從 IDT v4.0.0 開始，IDT for FreeRTOS 結合了標準化的組態設定和結果格式，以及測試套件環境，可讓您為裝置和裝置軟體開發自訂測試套件。您可以為自己的內部驗證新增自訂測試，或將其提供給客戶進行裝置驗證。
使用 IDT 來開發和執行自訂測試套件，如下所示：
****開發自訂測試套件****
+ 為您要測試的裝置建立具有自訂測試邏輯的測試套件。
+ 提供 IDT 您的自訂測試套件來測試執行器。包含測試套件特定設定組態的相關資訊。
****執行自訂測試套件****
+ 設定您要測試的裝置。
+ 實作您想要使用的測試套件所需的設定組態。
+ 使用 IDT 執行您的自訂測試套件。
+ 檢視 IDT 所執行測試的測試結果和執行日誌。
## 下載最新版本的 AWS IoT Device Tester for FreeRTOS
下載[最新版本](dev-test-versions-afr.md#idt-latest-version-afr)的 IDT，並將軟體解壓縮到檔案系統上具有讀取和寫入許可的位置。
**注意**
IDT 不支援由多位使用者從共用位置執行，例如 NFS 目錄或 Windows 網路共用資料夾。我們建議您將 IDT 套件解壓縮到本機磁碟機，並在本機工作站上執行 IDT 二進位檔。
Windows 的路徑長度限制為 260 個字元。如果您使用的是 Windows，請將 IDT 解壓縮到根目錄，例如 `C:\ ` 或 `D:\`，使路徑保持在 260 個字元的限制以下。
## 測試套件工作流程
測試套件由三種類型的檔案組成：
+ 為 IDT 提供如何執行測試套件資訊的組態檔案。
+ 測試 IDT 用來執行測試案例的可執行檔。
+ 執行測試所需的其他檔案。
完成下列基本步驟以建立自訂 IDT 測試：
1. 為您的測試套件[建立組態檔案](idt-json-config.md)。
1. [建立包含測試套件測試邏輯的測試案例可執行檔](test-executables.md)。
1. 驗證並記錄[測試執行器執行測試套件所需的組態資訊](set-config-custom.md)。
1. 確認 IDT 可以執行您的測試套件，並如預期產生[測試結果](run-tests-custom.md)。
若要快速建置範例自訂套件並進行執行，請遵循 中的指示[教學課程：建置並執行範例 IDT 測試套件](build-sample-suite.md)。
若要開始在 Python 中建立自訂測試套件，請參閱 [教學課程：開發簡單的 IDT 測試套件](create-custom-tests.md)。
# 教學課程：建置並執行範例 IDT 測試套件
AWS IoT Device Tester 下載包含範例測試套件的原始程式碼。您可以完成此教學課程來建置和執行範例測試套件，以了解如何使用 AWS IoT Device Tester FreeRTOS 來執行自訂測試套件。雖然本教學課程使用 SSH，但了解如何 AWS IoT Device Tester 搭配 FreeRTOS 裝置使用 會很有用。
在本教學課程中，您將完成下列步驟：
1. [建置範例測試套件](build-sample.md)
1. [使用 IDT 執行範例測試套件](run-sample.md)
**Topics**
+ [設定範例測試套件的先決條件](prereqs-tutorial-sample.md)
+ [設定 IDT 的裝置資訊](configure-idt-sample.md)
+ [建置範例測試套件](build-sample.md)
+ [使用 IDT 執行範例測試套件](run-sample.md)
+ [故障診斷錯誤](tutorial-troubleshooting-custom.md)
# 設定範例測試套件的先決條件
為了完成本教學，您需要以下項目：
+
**主機電腦需求**
+ 的最新版本 AWS IoT Device Tester
+ [Python](https://docs.python.org/3/) 3.7 或更新版本
若要檢查安裝在電腦上的 Python 版本，請執行下列命令：
```
python3 --version
```
在 Windows 上，如果使用此命令傳回錯誤，請`python --version`改用 。如果傳回的版本編號為 3.7 或更新版本，請在 Powershell 終端機中執行下列命令，將 `python3`設定為`python`命令的別名。
```
Set-Alias -Name "python3" -Value "python"
```
如果未傳回版本資訊或版本編號小於 3.7，請遵循[下載 Python](https://wiki.python.org/moin/BeginnersGuide/Download) 中的指示安裝 Python 3.7\$1。如需詳細資訊，請參閱 [Python 文件](https://docs.python.org/3/)。
+ [urllib3](https://urllib3.readthedocs.io/en/latest/)
若要驗證 `urllib3` 是否正確安裝，請執行下列命令：
```
python3 -c 'import urllib3'
```
如果`urllib3`未安裝 ，請執行下列命令來安裝它：
```
python3 -m pip install urllib3
```
+
**裝置要求**
+ 具有 Linux 作業系統和與主機電腦相同網路連線的裝置。
我們建議您將 [Raspberry Pi](https://www.raspberrypi.org/) 與 Raspberry Pi 作業系統搭配使用。請務必在 Raspberry Pi 上設定 [SSH](https://www.raspberrypi.com/documentation/computers/remote-access.html) 以遠端連線到它。
# 設定 IDT 的裝置資訊
設定您的裝置資訊，讓 IDT 執行測試。您必須使用下列資訊更新位於 `/configs` 資料夾中的`device.json`範本。
```
[
{
"id": "pool",
"sku": "N/A",
"devices": [
{
"id": "",
"connectivity": {
"protocol": "ssh",
"ip": "",
"port": "",
"auth": {
"method": "pki | password",
"credentials": {
"user": "",
"privKeyPath": "/path/to/private/key",
"password": ""
}
}
}
}
]
}
]
```
在 `devices` 物件中，提供下列資訊：
**`id`**
您裝置的使用者定義唯一識別符。
**`connectivity.ip`**
您裝置的 IP 地址。
**`connectivity.port`**
選用。用於 SSH 連線至您裝置的連接埠號碼。
**`connectivity.auth`**
連線的驗證資訊。
只有當 `connectivity.protocol` 設為 `ssh` 時，才會套用此屬性。
**`connectivity.auth.method`**
用來透過指定的連線通訊協定存取裝置的驗證方法。
支援的值如下：
+ `pki`
+ `password`
**`connectivity.auth.credentials`**
用於驗證的燈入資料。
**`connectivity.auth.credentials.user`**
用來登入裝置的使用者名稱。
**`connectivity.auth.credentials.privKeyPath`**
用來登入您裝置之私有金鑰的完整路徑。
只有當 `connectivity.auth.method` 設為 `pki` 時，才會套用此值。
**`devices.connectivity.auth.credentials.password`**
用於登入您的裝置的密碼。
只有當 `connectivity.auth.method` 設為 `password` 時，才會套用此值。
**注意**
如果 `method` 是設定為 `pki`，則指定 `privKeyPath`
如果 `method` 是設定為 `password`，則指定 `password`
# 建置範例測試套件
`/samples/python` 資料夾包含範例組態檔案、原始程式碼和 IDT 用戶端 SDK，您可以使用提供的建置指令碼將其合併為測試套件。下列目錄樹狀結構顯示這些範例檔案的位置：
```
├── ...
├── tests
├── samples
│ ├── ...
│ └── python
│ ├── configuration
│ ├── src
│ └── build-scripts
│ ├── build.sh
│ └── build.ps1
└── sdks
├── ...
└── python
└── idt_client
```
若要建置測試套件，請在主機電腦上執行下列命令：
------
#### [ Windows ]
```
cd /samples/python/build-scripts
./build.ps1
```
------
#### [ Linux, macOS, or UNIX ]
```
cd /samples/python/build-scripts
./build.sh
```
------
這會在 `IDTSampleSuitePython_1.0.0` 資料夾內的 `/tests` 資料夾中建立範例測試套件。檢閱 `IDTSampleSuitePython_1.0.0` 資料夾中的檔案，以了解範例測試套件的結構，並查看各種測試案例可執行檔和測試組態檔案的範例。
**注意**
範例測試套件包含 python 原始程式碼。請勿在測試套件程式碼中包含敏感資訊。
下一步：使用 IDT 執行[您建立的範例測試套件](run-sample.md)。
# 使用 IDT 執行範例測試套件
若要執行範例測試套件，請在主機電腦上執行下列命令：
```
cd /bin
./devicetester_[linux | mac | win_x86-64] run-suite --suite-id IDTSampleSuitePython
```
IDT 會執行範例測試套件，並將結果串流至主控台。當測試完成執行時，您會看到下列資訊：
```
========== Test Summary ==========
Execution Time: 5s
Tests Completed: 4
Tests Passed: 4
Tests Failed: 0
Tests Skipped: 0
----------------------------------
Test Groups:
sample_group: PASSED
----------------------------------
Path to AWS IoT Device Tester Report: /path/to/devicetester/results/87e673c6-1226-11eb-9269-8c8590419f30/awsiotdevicetester_report.xml
Path to Test Execution Logs: /path/to/devicetester/results/87e673c6-1226-11eb-9269-8c8590419f30/logs
Path to Aggregated JUnit Report: /path/to/devicetester/results/87e673c6-1226-11eb-9269-8c8590419f30/IDTSampleSuitePython_Report.xml
```
# 故障診斷錯誤
使用以下資訊來協助解決完成教學課程的任何問題。
**測試案例未成功執行**
+ 如果測試未成功執行，IDT 會將錯誤日誌串流至主控台，以協助您對測試執行進行疑難排解。請確定您符合本教學課程的所有[先決條件](prereqs-tutorial-sample.md)。
**無法連線至待測裝置**
請確認下列內容：
+ 您的 `device.json` 檔案包含正確的 IP 地址、連接埠和身分驗證資訊。
+ 您可以從主機電腦透過 SSH 連線至裝置。
# 教學課程：開發簡單的 IDT 測試套件
測試套件結合了下列項目：
+ 包含測試邏輯的測試可執行檔
+ 描述測試套件的組態檔案
本教學課程說明如何使用 IDT for FreeRTOS 來開發包含單一測試案例的 Python 測試套件。雖然本教學課程使用 SSH，但了解如何 AWS IoT Device Tester 搭配 FreeRTOS 裝置使用 會很有用。
在本教學課程中，您將完成下列步驟：
1. [建立測試套件目錄](test-suite-dir.md)
1. [建立組態檔案](test-suite-json.md)
1. [建立測試案例可執行檔](test-suite-exe.md)
1. [執行測試套件](run-test-suite.md)
請依照下列步驟完成開發簡單 IDT 測試套件的教學課程。
**Topics**
+ [設定簡單 IDT 測試套件的先決條件](prereqs-tutorial-custom.md)
+ [建立測試套件目錄](test-suite-dir.md)
+ [建立組態檔案](test-suite-json.md)
+ [取得 IDT 用戶端 SDK](add-idt-sdk.md)
+ [建立測試案例可執行檔](test-suite-exe.md)
+ [設定 IDT 的裝置資訊](configure-idt-sample2.md)
+ [執行測試套件](run-test-suite.md)
+ [故障診斷錯誤](tutorial-troubleshooting.md)
+ [建立 IDT 測試套件組態檔案](idt-json-config.md)
+ [設定 IDT 測試協調器](idt-test-orchestrator.md)
+ [設定 IDT 狀態機器](idt-state-machine.md)
+ [建立 IDT 測試案例可執行檔](test-executables.md)
+ [使用 IDT 內容](idt-context.md)
+ [設定測試執行器的設定](set-config-custom.md)
+ [偵錯並執行自訂測試套件](run-tests-custom.md)
+ [檢閱 IDT 測試結果和日誌](idt-review-results-logs.md)
+ [提交 IDT 用量指標](idt-usage-metrics.md)
# 設定簡單 IDT 測試套件的先決條件
為了完成本教學，您需要以下項目：
+
**主機電腦需求**
+ 的最新版本 AWS IoT Device Tester
+ [Python](https://www.python.org/downloads/) 3.7 或更新版本
若要檢查安裝在電腦上的 Python 版本，請執行下列命令：
```
python3 --version
```
在 Windows 上，如果使用此命令傳回錯誤，請`python --version`改用 。如果傳回的版本編號為 3.7 或更新版本，請在 Powershell 終端機中執行下列命令，將 `python3`設定為`python`命令的別名。
```
Set-Alias -Name "python3" -Value "python"
```
如果未傳回版本資訊或版本編號小於 3.7，請遵循[下載 Python](https://wiki.python.org/moin/BeginnersGuide/Download) 中的指示安裝 Python 3.7\$1。如需詳細資訊，請參閱 [Python 文件](https://docs.python.org/3/)。
+ [urllib3](https://urllib3.readthedocs.io/en/latest/)
若要驗證 `urllib3` 是否正確安裝，請執行下列命令：
```
python3 -c 'import urllib3'
```
如果`urllib3`未安裝 ，請執行下列命令來安裝它：
```
python3 -m pip install urllib3
```
+
**裝置要求**
+ 具有 Linux 作業系統和與主機電腦相同網路連線的裝置。
我們建議您將 [Raspberry Pi](https://www.raspberrypi.org/) 與 Raspberry Pi 作業系統搭配使用。請確定您在 Raspberry Pi 上設定 [SSH](https://www.raspberrypi.com/documentation/computers/remote-access.html) 以遠端連線到它。
# 建立測試套件目錄
IDT 會在邏輯上將測試案例分成每個測試套件內的測試群組。每個測試案例都必須位於測試群組內。在本教學課程中，請建立名為 的資料夾，`MyTestSuite_1.0.0`並在此資料夾中建立下列目錄樹狀目錄：
```
MyTestSuite_1.0.0
└── suite
└── myTestGroup
└── myTestCase
```
# 建立組態檔案
您的測試套件必須包含下列必要的[組態檔案](idt-json-config.md)：
**必要檔案**
**`suite.json`**
包含測試套件的相關資訊。請參閱 [設定 suite.json](idt-json-config.md#suite-json)。
**`group.json`**
包含測試群組的相關資訊。您必須為測試套件中的每個測試群組建立`group.json`檔案。請參閱 [設定 group.json](idt-json-config.md#group-json)。
**`test.json`**
包含測試案例的相關資訊。您必須為測試套件中的每個測試案例建立`test.json`檔案。請參閱 [設定 test.json](idt-json-config.md#test-json)。
1. 在 `MyTestSuite_1.0.0/suite`資料夾中，建立具有下列結構`suite.json`的檔案：
```
{
"id": "MyTestSuite_1.0.0",
"title": "My Test Suite",
"details": "This is my test suite.",
"userDataRequired": false
}
```
1. 在 `MyTestSuite_1.0.0/myTestGroup`資料夾中，建立具有下列結構`group.json`的檔案：
```
{
"id": "MyTestGroup",
"title": "My Test Group",
"details": "This is my test group.",
"optional": false
}
```
1. 在 `MyTestSuite_1.0.0/myTestGroup/myTestCase`資料夾中，建立具有下列結構`test.json`的檔案：
```
{
"id": "MyTestCase",
"title": "My Test Case",
"details": "This is my test case.",
"execution": {
"timeout": 300000,
"linux": {
"cmd": "python3",
"args": [
"myTestCase.py"
]
},
"mac": {
"cmd": "python3",
"args": [
"myTestCase.py"
]
},
"win": {
"cmd": "python3",
"args": [
"myTestCase.py"
]
}
}
}
```
資料夾的目錄樹狀目錄現在`MyTestSuite_1.0.0`看起來應該如下所示：
```
MyTestSuite_1.0.0
└── suite
├── suite.json
└── myTestGroup
├── group.json
└── myTestCase
└── test.json
```
# 取得 IDT 用戶端 SDK
您可以使用 [IDT 用戶端 SDK](test-executables.md#idt-client-sdk) 讓 IDT 與待測裝置互動，並報告測試結果。在本教學課程中，您將使用 開發套件的 Python 版本。
從 `/sdks/python/` 資料夾，將 `idt_client` 資料夾複製到您的 `MyTestSuite_1.0.0/suite/myTestGroup/myTestCase` 資料夾。
若要確認軟體開發套件已成功複製，請執行下列命令。
```
cd MyTestSuite_1.0.0/suite/myTestGroup/myTestCase
python3 -c 'import idt_client'
```
# 建立測試案例可執行檔
測試案例可執行檔包含您要執行的測試邏輯。測試套件可以包含多個測試案例可執行檔。在本教學課程中，您只會建立一個測試案例可執行檔。
1. 建立測試套件檔案。
在 `MyTestSuite_1.0.0/suite/myTestGroup/myTestCase`資料夾中，建立具有下列內容`myTestCase.py`的檔案：
```
from idt_client import *
def main():
# Use the client SDK to communicate with IDT
client = Client()
if __name__ == "__main__":
main()
```
1. 使用用戶端 SDK 函數將下列測試邏輯新增至您的 `myTestCase.py` 檔案：
1. 在待測裝置上執行 SSH 命令。
```
from idt_client import *
def main():
# Use the client SDK to communicate with IDT
client = Client()
# Create an execute on device request
exec_req = ExecuteOnDeviceRequest(ExecuteOnDeviceCommand("echo 'hello world'"))
# Run the command
exec_resp = client.execute_on_device(exec_req)
# Print the standard output
print(exec_resp.stdout)
if __name__ == "__main__":
main()
```
1. 將測試結果傳送至 IDT。
```
from idt_client import *
def main():
# Use the client SDK to communicate with IDT
client = Client()
# Create an execute on device request
exec_req = ExecuteOnDeviceRequest(ExecuteOnDeviceCommand("echo 'hello world'"))
# Run the command
exec_resp = client.execute_on_device(exec_req)
# Print the standard output
print(exec_resp.stdout)
# Create a send result request
sr_req = SendResultRequest(TestResult(passed=True))
# Send the result
client.send_result(sr_req)
if __name__ == "__main__":
main()
```
# 設定 IDT 的裝置資訊
設定您的裝置資訊，讓 IDT 執行測試。您必須使用下列資訊更新位於 `/configs` 資料夾中的`device.json`範本。
```
[
{
"id": "pool",
"sku": "N/A",
"devices": [
{
"id": "",
"connectivity": {
"protocol": "ssh",
"ip": "",
"port": "",
"auth": {
"method": "pki | password",
"credentials": {
"user": "",
"privKeyPath": "/path/to/private/key",
"password": ""
}
}
}
}
]
}
]
```
在 `devices` 物件中，提供下列資訊：
**`id`**
您裝置的使用者定義唯一識別符。
**`connectivity.ip`**
您裝置的 IP 地址。
**`connectivity.port`**
選用。用於 SSH 連線至您裝置的連接埠號碼。
**`connectivity.auth`**
連線的驗證資訊。
只有當 `connectivity.protocol` 設為 `ssh` 時，才會套用此屬性。
**`connectivity.auth.method`**
用來透過指定的連線通訊協定存取裝置的驗證方法。
支援的值如下：
+ `pki`
+ `password`
**`connectivity.auth.credentials`**
用於驗證的燈入資料。
**`connectivity.auth.credentials.user`**
用來登入裝置的使用者名稱。
**`connectivity.auth.credentials.privKeyPath`**
用來登入您裝置之私有金鑰的完整路徑。
只有當 `connectivity.auth.method` 設為 `pki` 時，才會套用此值。
**`devices.connectivity.auth.credentials.password`**
用於登入您的裝置的密碼。
只有當 `connectivity.auth.method` 設為 `password` 時，才會套用此值。
**注意**
如果 `method` 是設定為 `pki`，則指定 `privKeyPath`
如果 `method` 是設定為 `password`，則指定 `password`
# 執行測試套件
建立測試套件之後，您要確保其如預期般運作。完成下列步驟，以使用您現有的裝置集區執行測試套件。
1. 將您的`MyTestSuite_1.0.0`資料夾複製到 `/tests`。
1. 執行下列命令：
```
cd /bin
./devicetester_[linux | mac | win_x86-64] run-suite --suite-id MyTestSuite
```
IDT 會執行您的測試套件，並將結果串流至主控台。當測試完成執行時，您會看到下列資訊：
```
time="2020-10-19T09:24:47-07:00" level=info msg=Using pool: pool
time="2020-10-19T09:24:47-07:00" level=info msg=Using test suite "MyTestSuite_1.0.0" for execution
time="2020-10-19T09:24:47-07:00" level=info msg=b'hello world\n' suiteId=MyTestSuite groupId=myTestGroup testCaseId=myTestCase deviceId=my-device executionId=9a52f362-1227-11eb-86c9-8c8590419f30
time="2020-10-19T09:24:47-07:00" level=info msg=All tests finished. executionId=9a52f362-1227-11eb-86c9-8c8590419f30
time="2020-10-19T09:24:48-07:00" level=info msg=
========== Test Summary ==========
Execution Time: 1s
Tests Completed: 1
Tests Passed: 1
Tests Failed: 0
Tests Skipped: 0
----------------------------------
Test Groups:
myTestGroup: PASSED
----------------------------------
Path to AWS IoT Device Tester Report: /path/to/devicetester/results/9a52f362-1227-11eb-86c9-8c8590419f30/awsiotdevicetester_report.xml
Path to Test Execution Logs: /path/to/devicetester/results/9a52f362-1227-11eb-86c9-8c8590419f30/logs
Path to Aggregated JUnit Report: /path/to/devicetester/results/9a52f362-1227-11eb-86c9-8c8590419f30/MyTestSuite_Report.xml
```
# 故障診斷錯誤
使用以下資訊來協助解決完成教學課程的任何問題。
**測試案例未成功執行**
如果測試未成功執行，IDT 會將錯誤日誌串流至主控台，以協助您對測試執行進行疑難排解。檢查錯誤日誌之前，請確認下列事項：
+ IDT 用戶端 SDK 位於正確的資料夾中，如中所述[取得 IDT 用戶端 SDK](add-idt-sdk.md)。
+ 您符合本教學課程的所有先決條件。如需詳細資訊，請參閱[設定簡單 IDT 測試套件的先決條件](prereqs-tutorial-custom.md)。
**無法連線至測試中的裝置**
請確認下列內容：
+ 您的 `device.json` 檔案包含正確的 IP 地址、連接埠和身分驗證資訊。
+ 您可以從主機電腦透過 SSH 連線至裝置。
# 建立 IDT 測試套件組態檔案
本節說明您在撰寫自訂測試套件時所包含之組態檔案的建立格式。
**必要的組態檔案**
**`suite.json`**
包含測試套件的相關資訊。請參閱 [設定 suite.json](#suite-json)。
**`group.json`**
包含測試群組的相關資訊。您必須為測試套件中的每個測試群組建立`group.json`檔案。請參閱 [設定 group.json](#group-json)。
**`test.json`**
包含測試案例的相關資訊。您必須為測試套件中的每個測試案例建立`test.json`檔案。請參閱 [設定 test.json](#test-json)。
**選用組態檔案**
**`test_orchestrator.yaml` 或 `state_machine.json`**
定義 IDT 執行測試套件時如何執行測試。SSe [設定 test\$1orchestrator.yaml](#test-orchestrator-config)。
從 IDT v4.5.2 開始，您可以使用 `test_orchestrator.yaml` 檔案來定義測試工作流程。在舊版的 IDT 中，您會使用 `state_machine.json` 檔案。如需狀態機器的資訊，請參閱 [設定 IDT 狀態機器](idt-state-machine.md)。
**`userdata_schema.json`**
定義測試執行器可以包含在其設定組態中的[`userdata.json`檔案](set-config-custom.md#userdata-config-custom)結構描述。`userdata.json` 檔案會用於執行測試所需的任何其他組態資訊，但不會出現在`device.json`檔案中。請參閱 [設定 userdata\$1schema.json](#userdata-schema-json)。
組態檔案會放置在您的 中``，如下所示。
```
└── suite
├── suite.json
├── test_orchestrator.yaml
├── userdata_schema.json
├──
├── group.json
├──
└── test.json
```
## 設定 suite.json
`suite.json` 檔案會設定環境變數，並判斷是否需要使用者資料才能執行測試套件。使用下列範本來設定您的`/suite/suite.json`檔案：
```
{
"id": "_",
"title": "",
"details": "",
"userDataRequired": true | false,
"environmentVariables": [
{
"key": "",
"value": "",
},
...
{
"key": "",
"value": "",
}
]
}
```
如下所述，包含值的所有欄位皆為必要：
**`id`**
測試套件的唯一使用者定義 ID。的值`id`必須符合 `suite.json` 檔案所在的測試套件資料夾名稱。套件名稱和套件版本也必須符合下列要求：
+ `` 不能包含底線。
+ `` 表示為 `x.x.x`，其中 `x`是數字。
ID 會顯示在 IDT 產生的測試報告中。
**`title`**
此測試套件正在測試之產品或功能的使用者定義名稱。名稱會顯示在測試執行器的 IDT CLI 中。
**`details`**
測試套件用途的簡短描述。
**`userDataRequired`**
定義測試執行器是否需要在`userdata.json`檔案中包含自訂資訊。如果您將此值設定為 `true`，您還必須在測試套件資料夾中包含 [`userdata_schema.json` 檔案](#userdata-schema-json)。
**`environmentVariables`**
選用。要為此測試套件設定的環境變數陣列。
**`environmentVariables.key`**
環境變數的名稱。
**`environmentVariables.value`**
環境變數的值。
## 設定 group.json
`group.json` 檔案會定義測試群組為必要或選用。使用下列範本來設定您的`/suite//group.json`檔案：
```
{
"id": "",
"title": "",
"details": "",
"optional": true | false,
}
```
如下所述，包含值的所有欄位皆為必要：
**`id`**
測試群組的唯一使用者定義 ID。的值`id`必須符合`group.json`檔案所在的測試群組資料夾名稱，且不應有底線 (`_`)。ID 用於 IDT 產生的測試報告。
**`title`**
測試群組的描述性名稱。名稱會顯示在測試執行器的 IDT CLI 中。
**`details`**
測試群組用途的簡短描述。
**`optional`**
選用。設定為 `true` 以在 IDT 完成執行所需的測試後，將此測試群組顯示為選用群組。預設值為 `false`。
## 設定 test.json
`test.json` 檔案會決定測試案例可執行檔和測試案例所使用的環境變數。如需建立測試案例可執行檔的詳細資訊，請參閱 [建立 IDT 測試案例可執行檔](test-executables.md)。
使用下列範本來設定您的`/suite///test.json`檔案：
```
{
"id": "",
"title": "",
"details": "",
"requireDUT": true | false,
"requiredResources": [
{
"name": "",
"features": [
{
"name": "",
"version": "",
"jobSlots":
}
]
}
],
"execution": {
"timeout": ,
"mac": {
"cmd": "/path/to/executable",
"args": [
""
],
},
"linux": {
"cmd": "/path/to/executable",
"args": [
""
],
},
"win": {
"cmd": "/path/to/executable",
"args": [
""
]
}
},
"environmentVariables": [
{
"key": "",
"value": "",
}
]
}
```
如下所述，包含值的所有欄位皆為必要：
**`id`**
測試案例的唯一使用者定義 ID。的值`id`必須符合`test.json`檔案所在的測試案例資料夾名稱，且不應有底線 (`_`)。ID 用於 IDT 產生的測試報告。
**`title`**
測試案例的描述性名稱。名稱會顯示在測試執行器的 IDT CLI 中。
**`details`**
測試案例用途的簡短描述。
**`requireDUT`**
選用。`true` 如果需要裝置執行此測試，請將 設定為 ，否則將 設定為 `false`。預設值為 `true`。測試執行器會設定將用來在其 `device.json` 檔案中執行測試的裝置。
**`requiredResources`**
選用。陣列，提供執行此測試所需的資源裝置相關資訊。
**`requiredResources.name`**
執行此測試時提供給資源裝置的唯一名稱。
**`requiredResources.features`**
使用者定義資源裝置功能的陣列。
**`requiredResources.features.name`**
功能的名稱。您要使用此裝置的裝置功能。此名稱會與 `resource.json` 檔案中測試執行器所提供的功能名稱相符。
**`requiredResources.features.version`**
選用。功能的版本。此值會與 `resource.json` 檔案中測試執行器所提供的功能版本相符。如果未提供版本，則不會檢查該功能。如果功能不需要版本號碼，請將此欄位保留空白。
**`requiredResources.features.jobSlots`**
選用。此功能可支援的同時測試數量。預設值為 `1`。如果您希望 IDT 針對個別功能使用不同的裝置，建議您將此值設定為 `1`。
**`execution.timeout`**
IDT 等待測試完成執行的時間量 （以毫秒為單位）。如需設定此值的詳細資訊，請參閱 [建立 IDT 測試案例可執行檔](test-executables.md)。
**`execution.os`**
要根據執行 IDT 之主機電腦的作業系統執行的測試案例可執行檔。支援的值為 `linux`、`mac` 和 `win`。
**`execution.os.cmd`**
您想要在指定作業系統上執行的測試案例可執行檔路徑。此位置必須位於系統路徑中。
**`execution.os.args`**
選用。要用來執行測試案例可執行檔的引數。
**`environmentVariables`**
選用。為此測試案例設定的環境變數陣列。
**`environmentVariables.key`**
環境變數的名稱。
**`environmentVariables.value`**
環境變數的值。
如果您在 `test.json` 檔案和 檔案中指定相同的環境變數`suite.json`，則 `test.json` 檔案中的值優先。
## 設定 test\$1orchestrator.yaml
測試協調器是一種控制測試套件執行流程的建構。它決定測試套件的開始狀態、根據使用者定義的規則管理狀態轉換，並繼續轉換這些狀態，直到達到結束狀態為止。
如果您的測試套件不包含使用者定義的測試協調器，IDT 會為您產生測試協調器。
預設測試協調器會執行下列函數：
+ 讓測試執行器能夠選取和執行特定測試群組，而不是整個測試套件。
+ 如果未選取特定測試群組， 會以隨機順序執行測試套件中的每個測試群組。
+ 產生報告並列印主控台摘要，顯示每個測試群組和測試案例的測試結果。
如需 IDT 測試協調器如何運作的詳細資訊，請參閱 [設定 IDT 測試協調器](idt-test-orchestrator.md)。
## 設定 userdata\$1schema.json
`userdata_schema.json` 檔案會決定測試執行器提供使用者資料的結構描述。如果您的測試套件需要`device.json`檔案中不存在的資訊，則需要使用者資料。例如，您的測試可能需要使用者必須提供的 Wi-Fi 網路登入資料、特定開放連接埠或憑證。此資訊可以做為名為 的輸入參數提供給 IDT，這是使用者在其`/config`資料夾中建立`userdata.json`的檔案`userdata`值。檔案的格式`userdata.json`取決於您在測試套件中包含的 `userdata_schema.json` 檔案。
若要指出測試執行器必須提供 `userdata.json` 檔案：
1. 在 `suite.json`檔案中，將 `userDataRequired` 設定為 `true`。
1. 在您的 中``，建立 `userdata_schema.json` 檔案。
1. 編輯 `userdata_schema.json` 檔案以建立有效的 [IETF 草稿 v4 JSON 結構描述](https://json-schema.org/specification-links#draft-4)。
當 IDT 執行您的測試套件時，它會自動讀取結構描述，並使用它來驗證測試執行器所提供的`userdata.json`檔案。如果有效，`userdata.json`檔案的內容可在 [IDT 內容](idt-context.md)和[測試協調器內容](idt-test-orchestrator.md#idt-test-orchestrator-context)中使用。
# 設定 IDT 測試協調器
從 IDT v4.5.2 開始，IDT 包含新的*測試協調器*元件。測試協調器是一種 IDT 元件，可控制測試套件執行流程，並在 IDT 完成執行所有測試後產生測試報告。測試協調器會根據使用者定義的規則，決定測試選擇和執行測試的順序。
如果您的測試套件不包含使用者定義的測試協調器，IDT 會為您產生測試協調器。
預設測試協調器會執行下列函數：
+ 讓測試執行器能夠選取和執行特定測試群組，而不是整個測試套件。
+ 如果未選取特定測試群組， 會以隨機順序執行測試套件中的每個測試群組。
+ 產生報告並列印主控台摘要，顯示每個測試群組和測試案例的測試結果。
測試協調器會取代 IDT 狀態機器。我們強烈建議您使用測試協調器來開發測試套件，而非 IDT 狀態機器。測試協調器提供下列改善功能：
+ 相較於 IDT 狀態機器使用的命令格式， 會使用宣告式格式。這可讓您指定要執行哪些測試，以及何時要執行這些測試。
+ 管理特定群組處理、報告產生、錯誤處理和結果追蹤，因此您不需要手動管理這些動作。
+ 使用 YAML 格式，預設支援註解。
+ 需要比測試協調器少 80% 的磁碟空間，才能定義相同的工作流程。
+ 新增測試前驗證，以確認您的工作流程定義不包含不正確的測試 IDs或循環相依性。
## 測試協調器格式
您可以使用下列範本來設定自己的`custom-test-suite-folder/suite/test_orchestrator.yaml`檔案：
```
Aliases:
string: context-expression
ConditionalTests:
- Condition: context-expression
Tests:
- test-descriptor
Order:
- - group-descriptor
- group-descriptor
Features:
- Name: feature-name
Value: support-description
Condition: context-expression
Tests:
- test-descriptor
OneOfTests:
- test-descriptor
IsRequired: boolean
```
如下所述，包含值的所有欄位皆為必要：
`Aliases`
選用。映射至內容表達式的使用者定義字串。別名可讓您產生易記的名稱，以識別測試協調器組態中的內容表達式。如果您要建立複雜內容表達式或您在多個位置使用的表達式，這特別有用。
您可以使用內容表達式來存放內容查詢，讓您從其他 IDT 組態存取資料。如需詳細資訊，請參閱[在內容中存取資料](idt-context.md#accessing-context-data)。
**Example**
**範例**
```
Aliases:
FizzChosen: "'{{$pool.features[?(@.name == 'Fizz')].value[0]}}' == 'yes'"
BuzzChosen: "'{{$pool.features[?(@.name == 'Buzz')].value[0]}}' == 'yes'"
FizzBuzzChosen: "'{{$aliases.FizzChosen}}' && '{{$aliases.BuzzChosen}}'"
```
`ConditionalTests`
選用。條件清單，以及滿足每個條件時執行的對應測試案例。每個條件可以有多個測試案例；不過，您可以將指定的測試案例指派給一個條件。
根據預設，IDT 會執行未指派給此清單中條件的任何測試案例。如果您未指定本節，IDT 會在測試套件中執行所有測試群組。
`ConditionalTests` 清單中的每個項目都包含下列參數：
`Condition`
評估為布林值的內容表達式。如果評估的值為 true，IDT 會執行 `Tests` 參數中指定的測試案例。
`Tests`
測試描述項的清單。
每個測試描述項都使用測試群組 ID 和一或多個測試案例 IDs，來識別要從特定測試群組執行的個別測試。測試描述項使用下列格式：
```
GroupId: group-id
CaseIds: [test-id, test-id] # optional
```
**Example**
**範例**
下列範例使用您可以定義為 的一般內容表達式`Aliases`。
```
ConditionalTests:
- Condition: "{{$aliases.Condition1}}"
Tests:
- GroupId: A
- GroupId: B
- Condition: "{{$aliases.Condition2}}"
Tests:
- GroupId: D
- Condition: "{{$aliases.Condition1}} || {{$aliases.Condition2}}"
Tests:
- GroupId: C
```
根據定義的條件，IDT 會選取測試群組，如下所示：
+ 如果 `Condition1` 為 true，IDT 會在測試群組 A、B 和 C 中執行測試。
+ 如果 `Condition2` 為 true，IDT 會在測試群組 C 和 D 中執行測試。
`Order`
選用。執行測試的順序。您可以在測試群組層級指定測試順序。如果您未指定本節，IDT 會以隨機順序執行所有適用的測試群組。的值`Order`是群組描述項清單的清單。您在 中未列出的任何測試群組，`Order`都可以與任何其他列出的測試群組平行執行。
每個群組描述項清單都包含其中一個群組描述項，並識別執行每個描述項中指定之群組的順序。您可以使用下列格式來定義個別群組描述項：
+ `group-id`- 現有測試群組的群組 ID。
+ `[group-id, group-id]`- 可以相對於彼此以任何順序執行的測試群組清單。
+ `"*"`—萬用字元。這相當於目前群組描述項清單中尚未指定的所有測試群組清單。
的值`Order`也必須符合下列要求：
+ 您在群組描述項中指定的測試群組 IDs 必須存在於您的測試套件中。
+ 每個群組描述項清單必須至少包含一個測試群組。
+ 每個群組描述項清單必須包含唯一的群組 IDs。您無法在個別群組描述項中重複測試群組 ID。
+ 群組描述項清單最多可有一個萬用字元群組描述項。萬用字元群組描述項必須是清單中的第一個或最後一個項目。
**Example**
**範例**
對於包含測試群組 A、B、C、D 和 E 的測試套件，以下範例清單顯示指定 IDT 應先執行測試群組 A、接著執行測試群組 B，然後以任何順序執行測試群組 C、D 和 E 的不同方式。
+
```
Order:
- - A
- B
- [C, D, E]
```
+
```
Order:
- - A
- B
- "*"
```
+
```
Order:
- - A
- B
- - B
- C
- - B
- D
- - B
- E
```
`Features`
選用。您希望 IDT 新增至 `awsiotdevicetester_report.xml` 檔案的產品功能清單。如果您未指定此區段，IDT 不會將任何產品功能新增至報告。
產品功能是有關裝置可能符合的特定條件的使用者定義資訊。例如，MQTT 產品功能可以指定裝置正確發佈 MQTT 訊息。在 中`awsiotdevicetester_report.xml`，產品功能會根據是否通過指定的測試，設定為 `supported`、 `not-supported`或自訂使用者定義值。
`Features` 清單中的每個項目都包含下列參數：
`Name`
功能的名稱。
`Value`
選用。您想要在報告中使用的自訂值，而不是 `supported`。如果未指定此值，則以 IDT `not-supported` 為基礎的功能值會根據測試結果設為 `supported`或 。如果您使用不同的條件測試相同的功能，您可以為`Features`清單中該功能的每個執行個體使用自訂值，IDT 會串連支援條件的功能值。如需詳細資訊，請參閱
`Condition`
評估為布林值的內容表達式。如果評估的值為 true，IDT 會在測試報告完成執行測試套件之後，將此功能新增至測試報告。如果評估的值為 false，則測試不會包含在報告中。
`Tests`
選用。測試描述項的清單。此清單中指定的所有測試都必須通過，才能支援此功能。
此清單中的每個測試描述項都使用測試群組 ID 和一或多個測試案例 IDs，來識別要從特定測試群組執行的個別測試。測試描述項使用下列格式：
```
GroupId: group-id
CaseIds: [test-id, test-id] # optional
```
您必須`OneOfTests`為`Features`清單中的每個功能指定 `Tests`或 。
`OneOfTests`
選用。測試描述項的清單。此清單中指定的至少一個測試必須通過，才能支援此功能。
此清單中的每個測試描述項都使用測試群組 ID 和一或多個測試案例 IDs，來識別要從特定測試群組執行的個別測試。測試描述項使用下列格式：
```
GroupId: group-id
CaseIds: [test-id, test-id] # optional
```
您必須`OneOfTests`為`Features`清單中的每個功能指定 `Tests`或 。
`IsRequired`
布林值，定義測試報告中是否需要此功能。預設值為 `false`。
## 測試協調器內容
測試協調器內容是唯讀 JSON 文件，其中包含在執行期間可供測試協調器使用的資料。測試協調器內容只能從測試協調器存取，並包含決定測試流程的資訊。例如，您可以使用 `userdata.json` 檔案中測試執行器設定的資訊來判斷是否需要執行特定測試。
測試協調器內容使用以下格式：
```
{
"pool": {
},
"userData": {
},
"config": {
}
}
```
`pool`
為測試執行選取之裝置集區的相關資訊。對於選取的裝置集區，此資訊會從 `device.json`檔案中定義的對應頂層裝置集區陣列元素擷取。
`userData`
`userdata.json` 檔案中的資訊。
`config`
`config.json` 檔案中的資訊。
您可以使用 JSONPath 表示法查詢內容。狀態定義中 JSONPath 查詢的語法為 `{{query}}`。當您從測試協調器內容存取資料時，請確定每個值評估為字串、數字或布林值。
如需使用 JSONPath 表示法從內容存取資料的詳細資訊，請參閱 [使用 IDT 內容](idt-context.md)。
# 設定 IDT 狀態機器
**重要**
從 IDT v4.5.2 開始，此狀態機器已棄用。我們強烈建議您使用新的測試協調器。如需詳細資訊，請參閱[設定 IDT 測試協調器](idt-test-orchestrator.md)。
狀態機器是一種控制測試套件執行流程的建構。它決定測試套件的開始狀態、根據使用者定義的規則管理狀態轉換，並繼續轉換這些狀態，直到達到結束狀態為止。
如果您的測試套件不包含使用者定義的狀態機器，IDT 會為您產生狀態機器。預設狀態機器會執行下列函數：
+ 讓測試執行器能夠選取和執行特定測試群組，而不是整個測試套件。
+ 如果未選取特定測試群組， 會以隨機順序執行測試套件中的每個測試群組。
+ 產生報告並列印主控台摘要，顯示每個測試群組和測試案例的測試結果。
IDT 測試套件的狀態機器必須符合下列條件：
+ 每個狀態對應於 IDT 要採取的動作，例如執行測試群組或製作報告檔案的產品。
+ 轉換為 狀態會執行與 狀態相關聯的動作。
+ 每個狀態都會定義下一個狀態的轉換規則。
+ 結束狀態必須為 `Succeed`或 `Fail`。
## 狀態機器格式
您可以使用下列範本來設定自己的`/suite/state_machine.json`檔案：
```
{
"Comment": "",
"StartAt": "",
"States": {
"": {
"Type": "",
// Additional state configuration
}
// Required states
"Succeed": {
"Type": "Succeed"
},
"Fail": {
"Type": "Fail"
}
}
}
```
如下所述，包含值的所有欄位皆為必要：
**`Comment`**
狀態機器的描述。
**`StartAt`**
IDT 開始執行測試套件的狀態名稱。的值`StartAt`必須設定為 `States` 物件中列出的其中一個狀態。
**`States`**
將使用者定義狀態名稱映射至有效 IDT 狀態的物件。每個 States.*state-name* 物件都包含映射至 *state-name* 的有效狀態定義。
`States` 物件必須包含 `Succeed`和 `Fail` 狀態。如需有效狀態的資訊，請參閱 [有效狀態和狀態定義](#valid-states)。
## 有效狀態和狀態定義
本節說明可在 IDT 狀態機器中使用的所有有效狀態的狀態定義。下列某些狀態支援測試案例層級的組態。不過，建議您在測試群組層級設定狀態轉換規則，而非測試案例層級，除非絕對必要。
**Topics**
+ [RunTask](#state-runtask)
+ [Choice](#state-choice)
+ [平行](#state-parallel)
+ [AddProductFeatures](#state-addproductfeatures)
+ [報告](#state-report)
+ [LogMessage](#state-logmessage)
+ [SelectGroup](#state-selectgroup)
+ [失敗](#state-fail)
+ [Succeed](#state-succeed)
### RunTask
`RunTask` 狀態會從測試套件中定義的測試群組執行測試案例。
```
{
"Type": "RunTask",
"Next": "",
"TestGroup": "",
"TestCases": [
""
],
"ResultVar": ""
}
```
如下所述，包含值的所有欄位皆為必要：
**`Next`**
在目前狀態下執行動作後，要轉換為的狀態名稱。
**`TestGroup`**
選用。要執行的測試群組 ID。如果未指定此值，IDT 會執行測試執行器選取的測試群組。
**`TestCases`**
選用。來自 中指定群組的測試案例 IDs 陣列`TestGroup`。根據 `TestGroup`和 的值`TestCases`，IDT 會決定測試執行行為，如下所示：
+ 同時指定 `TestCases` `TestGroup`和 時，IDT 會從測試群組執行指定的測試案例。
+ `TestCases` 指定`TestGroup`但未指定 時，IDT 會執行指定的測試案例。
+ `TestGroup` 指定 但未指定 `TestCases` 時，IDT 會執行指定測試群組中的所有測試案例。
+ 未指定 `TestCases` `TestGroup`或 時，IDT 會從測試執行器從 IDT CLI 中選取的測試群組中執行所有測試案例。若要啟用測試執行器的群組選擇，您必須在 `statemachine.json` 檔案中同時包含 `RunTask`和 `Choice` 狀態。如需如何運作的範例，請參閱[範例狀態機器：執行使用者選取的測試群組](#allow-specific-groups)。
如需為測試執行器啟用 IDT CLI 命令的詳細資訊，請參閱 [啟用 IDT CLI 命令](test-executables.md#idt-cli-coop)。
**`ResultVar`**
使用測試執行結果設定的內容變數名稱。如果您未指定 的值，請勿指定此值`TestGroup`。IDT `false`會根據下列項目，將您在 中定義的變數值`ResultVar`設定為 `true`或 ：
+ 如果變數名稱的格式為 `text_text_passed`，則值會設定為是否通過或略過第一個測試群組中的所有測試。
+ 在所有其他情況下，該值會設定為是否通過或略過所有測試群組中的所有測試。
一般而言，您將使用 `RunTask` 狀態來指定測試群組 ID，而不指定個別測試案例 IDs，以便 IDT 執行指定測試群組中的所有測試案例。此狀態執行的所有測試案例都會以隨機順序平行執行。不過，如果所有測試案例都需要裝置才能執行，而且只有單一裝置可用，則測試案例將改為依序執行。
**錯誤處理**
如果任何指定的測試群組或測試案例 IDs 無效，則此狀態會發出`RunTaskError`執行錯誤。如果狀態遇到執行錯誤，也會將狀態機器內容中的`hasExecutionError`變數設定為 `true`。
### Choice
`Choice` 狀態可讓您動態設定下一個狀態，以根據使用者定義的條件轉換為 。
```
{
"Type": "Choice",
"Default": "",
"FallthroughOnError": true | false,
"Choices": [
{
"Expression": "",
"Next": ""
}
]
}
```
如下所述，包含值的所有欄位皆為必要：
**`Default`**
如果 中定義的任何表達式`Choices`都無法評估為 ，則要轉換為的預設狀態`true`。
**`FallthroughOnError`**
選用。指定狀態在評估表達式時發生錯誤時的行為。`true` 如果您想要在評估導致錯誤時略過表達式，請將 設定為 。如果沒有符合的表達式，則狀態機器會轉換為 `Default` 狀態。如果未指定 `FallthroughOnError`值，則預設為 `false`。
**`Choices`**
運算式和狀態的陣列，用於判斷在目前狀態下執行動作後要轉換到哪個狀態。
**`Choices.Expression`**
評估為布林值的表達式字串。如果表達式評估為 `true`，則狀態機器會轉換為 中定義的狀態`Choices.Next`。表達式字串會從狀態機器內容擷取值，然後對其執行操作以到達布林值。如需存取狀態機器內容的相關資訊，請參閱 [狀態機器內容](#state-machine-context)。
**`Choices.Next`**
如果 中定義的表達式`Choices.Expression`評估為 ，則要轉換為的狀態名稱`true`。
**錯誤處理**
在下列情況下， `Choice` 狀態可能需要錯誤處理：
+ 選擇表達式中的某些變數不存在於狀態機器內容中。
+ 表達式的結果不是布林值。
+ JSON 查詢的結果不是字串、數字或布林值。
您無法使用`Catch`區塊來處理此狀態的錯誤。如果您想要在遇到錯誤時停止執行狀態機器，您必須將 `FallthroughOnError`設定為 `false`。不過，我們建議您將 `FallthroughOnError`設定為 `true`，並根據您的使用案例執行下列其中一項操作：
+ 如果您存取的變數預期在某些情況下不存在，請使用 值`Default`和其他`Choices`區塊來指定下一個狀態。
+ 如果您存取的變數應一律存在，請將`Default`狀態設定為 `Fail`。
### 平行
`Parallel` 狀態可讓您彼此平行定義和執行新的狀態機器。
```
{
"Type": "Parallel",
"Next": "",
"Branches": [
]
}
```
如下所述，包含值的所有欄位皆為必要：
**`Next`**
在目前狀態下執行動作後，要轉換為的狀態名稱。
**`Branches`**
要執行的狀態機器定義陣列。每個狀態機器定義都必須包含自己的 `StartAt`、 `Succeed`和 `Fail` 狀態。此陣列中的狀態機器定義無法參考其定義以外的狀態。
由於每個分支狀態機器共用相同的狀態機器內容，因此在一個分支中設定變數，然後從另一個分支讀取這些變數可能會導致意外行為。
`Parallel` 狀態只有在執行所有分支狀態機器之後才會移至下一個狀態。每個需要裝置的狀態都會等待執行，直到裝置可用為止。如果有多個裝置可用，此狀態會從多個群組平行執行測試案例。如果沒有足夠的裝置可用，則測試案例會依序執行。由於測試案例在平行執行時以隨機順序執行，因此可能會使用不同的裝置從相同的測試群組執行測試。
**錯誤處理**
請確定分支狀態機器和父系狀態機器都會轉換為 `Fail` 狀態，以處理執行錯誤。
由於分支狀態機器不會將執行錯誤傳輸至父系狀態機器，因此您無法使用`Catch`區塊來處理分支狀態機器中的執行錯誤。請改為在共用狀態機器內容中使用 `hasExecutionErrors`值。如需如何運作的範例，請參閱 [狀態機器範例：平行執行兩個測試群組](#run-in-parallel)。
### AddProductFeatures
`AddProductFeatures` 狀態可讓您將產品功能新增至 IDT 產生的`awsiotdevicetester_report.xml`檔案。
產品功能是有關裝置可能符合的特定條件的使用者定義資訊。例如，`MQTT`產品功能可以指定裝置正確發佈 MQTT 訊息。在報告中，產品功能會根據是否通過指定的測試，設定為 `supported`、 `not-supported`或自訂值。
**注意**
`AddProductFeatures` 狀態本身不會產生報告。此狀態必須轉換為 [`Report` 狀態](#state-report)才能產生報告。
```
{
"Type": "Parallel",
"Next": "",
"Features": [
{
"Feature": "",
"Groups": [
""
],
"OneOfGroups": [
""
],
"TestCases": [
""
],
"IsRequired": true | false,
"ExecutionMethods": [
""
]
}
]
}
```
如下所述，包含值的所有欄位皆為必要：
**`Next`**
在目前狀態下執行動作後，要轉換為的狀態名稱。
**`Features`**
要在 `awsiotdevicetester_report.xml` 檔案中顯示的產品功能陣列。
**`Feature`**
功能的名稱
**`FeatureValue`**
選用。要在報告中使用的自訂值，而非 `supported`。如果未指定此值，則根據測試結果，功能值會設為 `supported`或 `not-supported`。
如果您使用 的自訂值`FeatureValue`，則可以使用不同的條件測試相同的功能，IDT 會串連支援條件的功能值。例如，以下摘錄顯示具有兩個不同`MyFeature`特徵值的功能：
```
...
{
"Feature": "MyFeature",
"FeatureValue": "first-feature-supported",
"Groups": ["first-feature-group"]
},
{
"Feature": "MyFeature",
"FeatureValue": "second-feature-supported",
"Groups": ["second-feature-group"]
},
...
```
如果兩個測試群組都通過，則功能值會設為 `first-feature-supported, second-feature-supported`。
**`Groups`**
選用。測試群組 IDs的陣列。每個指定測試群組中的所有測試都必須通過，才能支援此功能。
**`OneOfGroups`**
選用。測試群組 IDs的陣列。至少一個指定測試群組內的所有測試都必須通過，才能支援此功能。
**`TestCases`**
選用。測試案例 IDs的陣列。如果您指定此值，則適用下列條件：
+ 所有指定的測試案例都必須通過，才能支援此功能。
+ `Groups` 只能包含一個測試群組 ID。
+ `OneOfGroups` 不得指定。
**`IsRequired`**
選用。設定為 `false` 以在報告中將此功能標記為選用功能。預設值為 `true`。
**`ExecutionMethods`**
選用。符合 `device.json` 檔案中指定`protocol`值的執行方法陣列。如果指定此值，則測試執行器必須指定`protocol`符合此陣列中其中一個值的值，以在報告中包含 功能。如果未指定此值，則功能一律會包含在報告中。
若要使用 `AddProductFeatures` 狀態，您必須將 `RunTask` 狀態`ResultVar`中的 值設定為下列其中一個值：
+ 如果您指定個別測試案例 IDs，請將 `ResultVar`設定為 `group-id_test-id_passed`。
+ 如果您未指定個別測試案例 IDs，請將 `ResultVar`設定為 `group-id_passed`。
`AddProductFeatures` 狀態會以下列方式檢查測試結果：
+ 如果您未指定任何測試案例 IDs，則每個測試群組的結果取決於狀態機器內容中的 `group-id_passed`變數值。
+ 如果您確實指定測試案例 IDs，則每個測試的結果取決於狀態機器內容中的 `group-id_test-id_passed`變數值。
**錯誤處理**
如果在此狀態下提供的群組 ID 不是有效的群組 ID，則此狀態會導致`AddProductFeaturesError`執行錯誤。如果狀態遇到執行錯誤，則也會將狀態機器內容中的`hasExecutionErrors`變數設定為 `true`。
### 報告
`Report` 狀態會產生 `suite-name_Report.xml`和 `awsiotdevicetester_report.xml` 檔案。此狀態也會將報告串流至 主控台。
```
{
"Type": "Report",
"Next": ""
}
```
如下所述，包含值的所有欄位皆為必要：
**`Next`**
在目前狀態下執行動作後，要轉換為的狀態名稱。
您應該一律在測試執行流程結束時轉換為 `Report` 狀態，以便測試執行器可以檢視測試結果。一般而言，此狀態之後的下一個狀態為 `Succeed`。
**錯誤處理**
如果此狀態在產生報告時遇到問題，則會發出`ReportError`執行錯誤。
### LogMessage
`LogMessage` 狀態會產生 `test_manager.log` 檔案，並將日誌訊息串流至 主控台。
```
{
"Type": "LogMessage",
"Next": ""
"Level": "info | warn | error"
"Message": ""
}
```
如下所述，包含值的所有欄位皆為必要：
**`Next`**
在目前狀態下執行動作後，要轉換為的狀態名稱。
**`Level`**
建立日誌訊息的錯誤層級。如果您指定的關卡無效，此狀態會產生錯誤訊息並予以捨棄。
**`Message`**
要記錄的訊息。
### SelectGroup
`SelectGroup` 狀態會更新狀態機器內容，以指出已選取哪些群組。此狀態設定的值會由任何後續`Choice`狀態使用。
```
{
"Type": "SelectGroup",
"Next": ""
"TestGroups": [
"
]
}
```
如下所述，包含值的所有欄位皆為必要：
**`Next`**
在目前狀態下執行動作後，要轉換為的狀態名稱。
**`TestGroups`**
將標記為選取的測試群組陣列。對於此陣列中的每個測試群組 ID，`group-id_selected`變數會在內容`true`中設定為 。請務必提供有效的測試群組 IDs因為 IDT 不會驗證指定的群組是否存在。
### 失敗
`Fail` 狀態表示狀態機器未正確執行。這是狀態機器的結束狀態，每個狀態機器定義都必須包含此狀態。
```
{
"Type": "Fail"
}
```
### Succeed
`Succeed` 狀態表示狀態機器已正確執行。這是狀態機器的結束狀態，每個狀態機器定義都必須包含此狀態。
```
{
"Type": "Succeed"
}
```
## 狀態機器內容
狀態機器內容是唯讀 JSON 文件，其中包含可在執行期間提供給狀態機器的資料。狀態機器內容只能從狀態機器存取，並包含決定測試流程的資訊。例如，您可以使用 `userdata.json` 檔案中測試執行器設定的資訊來判斷是否需要執行特定測試。
狀態機器內容使用下列格式：
```
{
"pool": {
},
"userData": {
},
"config": {
},
"suiteFailed": true | false,
"specificTestGroups": [
""
],
"specificTestCases": [
""
],
"hasExecutionErrors": true
}
```
**`pool`**
為測試執行選取之裝置集區的相關資訊。對於選取的裝置集區，此資訊會從 `device.json`檔案中定義的對應頂層裝置集區陣列元素擷取。
**`userData`**
`userdata.json` 檔案中的資訊。
**`config`**
資訊鎖定`config.json`檔案。
**`suiteFailed`**
狀態機器啟動`false`時，此值會設為 。如果測試群組在 `RunTask` 狀態失敗，則此值會在狀態機器執行的`true`剩餘持續時間內設定為 。
**`specificTestGroups`**
如果測試執行器選取要執行的特定測試群組，而不是整個測試套件，則會建立此金鑰，並包含特定測試群組 IDs的清單。
**`specificTestCases`**
如果測試執行器選取要執行的特定測試案例，而不是整個測試套件，則會建立此金鑰並包含特定測試案例 IDs的清單。
**`hasExecutionErrors`**
狀態機器啟動時不會結束。如果任何狀態遇到執行錯誤，則會建立此變數`true`，並在狀態機器執行的剩餘持續時間內設定為 。
您可以使用 JSONPath 表示法查詢內容。狀態定義中 JSONPath 查詢的語法為 `{{$.query}}`。您可以在某些狀態下使用 JSONPath 查詢做為預留位置字串。IDT 會將預留位置字串取代為內容中評估 JSONPath 查詢的值。您可以針對下列值使用預留位置：
+ 狀態`TestCases`的值`RunTask`。
+ `Expression` 值`Choice`狀態。
當您從狀態機器內容存取資料時，請確定符合下列條件：
+ 您的 JSON 路徑必須以 開頭 `$.`
+ 每個值都必須評估為字串、數字或布林值。
如需使用 JSONPath 表示法從內容存取資料的詳細資訊，請參閱 [使用 IDT 內容](idt-context.md)。
## 執行錯誤
執行錯誤是狀態機器在執行狀態時遇到的狀態機器定義錯誤。IDT 會記錄`test_manager.log`檔案中每個錯誤的相關資訊，並將日誌訊息串流至主控台。
您可以使用下列方法來處理執行錯誤：
+ 在狀態定義中新增[`Catch`區塊](#catch)。
+ 在狀態機器內容中檢查[`hasExecutionErrors`值](#context)的值。
### 擷取
若要使用 `Catch`，請將下列項目新增至您的狀態定義：
```
"Catch": [
{
"ErrorEquals": [
""
]
"Next": ""
}
]
```
如下所述，包含值的所有欄位皆為必要：
**`Catch.ErrorEquals`**
要擷取的錯誤類型陣列。如果執行錯誤符合其中一個指定的值，則狀態機器會轉換為 中指定的狀態`Catch.Next`。如需其產生的錯誤類型的相關資訊，請參閱每個狀態定義。
**`Catch.Next`**
如果目前狀態遇到符合 中指定其中一個值的執行錯誤，則會轉換為下一個狀態`Catch.ErrorEquals`。
擷取區塊會依序處理，直到一個相符為止。如果沒有錯誤符合 Catch 區塊中列出的錯誤，則狀態機器會繼續執行。由於執行錯誤是不正確狀態定義的結果，我們建議您在狀態遇到執行錯誤時轉換為失敗狀態。
### hasExecutionError
當某些狀態遇到執行錯誤時，除了發出錯誤之外，也會在狀態機器內容`true`中將`hasExecutionError`值設定為 。您可以使用此值來偵測何時發生錯誤，然後使用 `Choice` 狀態將狀態機器轉換為 `Fail` 狀態。
此方法具有下列特性。
+ 狀態機器不會以指派給 的任何值開頭`hasExecutionError`，且此值在特定狀態設定之前無法使用。這表示您必須針對存取此值`FallthroughOnError``false``Choice`的狀態，將 明確設定為 ，以防止狀態機器在未發生執行錯誤時停止。
+ 一旦設定為 `true`， `hasExecutionError` 永遠不會設定為 false 或從內容中移除。這表示此值只有在第一次設定為 時才有用`true`，而且對於所有後續狀態，它不提供有意義的值。
+ 該`hasExecutionError`值會與 `Parallel` 狀態的所有分支狀態機器共用，這可能會導致非預期的結果，具體取決於存取它的順序。
由於這些特性，如果您可以改用 Catch 區塊，我們不建議您使用此方法。
## 狀態機器範例
本節提供一些範例狀態機器組態。
**Topics**
+ [狀態機器範例：執行單一測試群組](#single-test-group)
+ [狀態機器範例：執行使用者選取的測試群組](#allow-specific-groups)
+ [狀態機器範例：使用產品功能執行單一測試群組](#run-with-product-features)
+ [狀態機器範例：平行執行兩個測試群組](#run-in-parallel)
### 狀態機器範例：執行單一測試群組
此狀態機器：
+ 執行 ID 為 的測試群組`GroupA`，該群組必須存在於 `group.json` 檔案的 套件中。
+ 檢查執行錯誤，並在發現任何 `Fail` 時轉換為 。
+ `Succeed` 如果沒有錯誤，則產生報告並轉換為 ，`Fail`否則。
```
{
"Comment": "Runs a single group and then generates a report.",
"StartAt": "RunGroupA",
"States": {
"RunGroupA": {
"Type": "RunTask",
"Next": "Report",
"TestGroup": "GroupA",
"Catch": [
{
"ErrorEquals": [
"RunTaskError"
],
"Next": "Fail"
}
]
},
"Report": {
"Type": "Report",
"Next": "Succeed",
"Catch": [
{
"ErrorEquals": [
"ReportError"
],
"Next": "Fail"
}
]
},
"Succeed": {
"Type": "Succeed"
},
"Fail": {
"Type": "Fail"
}
}
}
```
### 狀態機器範例：執行使用者選取的測試群組
此狀態機器：
+ 檢查測試執行器是否已選取特定測試群組。狀態機器不會檢查特定測試案例，因為測試執行器無法在未同時選取測試群組的情況下選取測試案例。
+ 如果選取測試群組：
+ 在選取的測試群組中執行測試案例。若要這樣做，狀態機器不會明確指定 `RunTask` 狀態中的任何測試群組或測試案例。
+ 執行所有測試並結束之後產生報告。
+ 如果未選取測試群組：
+ 在測試群組 中執行測試`GroupA`。
+ 產生報告並結束。
```
{
"Comment": "Runs specific groups if the test runner chose to do that, otherwise runs GroupA.",
"StartAt": "SpecificGroupsCheck",
"States": {
"SpecificGroupsCheck": {
"Type": "Choice",
"Default": "RunGroupA",
"FallthroughOnError": true,
"Choices": [
{
"Expression": "{{$.specificTestGroups[0]}} != ''",
"Next": "RunSpecificGroups"
}
]
},
"RunSpecificGroups": {
"Type": "RunTask",
"Next": "Report",
"Catch": [
{
"ErrorEquals": [
"RunTaskError"
],
"Next": "Fail"
}
]
},
"RunGroupA": {
"Type": "RunTask",
"Next": "Report",
"TestGroup": "GroupA",
"Catch": [
{
"ErrorEquals": [
"RunTaskError"
],
"Next": "Fail"
}
]
},
"Report": {
"Type": "Report",
"Next": "Succeed",
"Catch": [
{
"ErrorEquals": [
"ReportError"
],
"Next": "Fail"
}
]
},
"Succeed": {
"Type": "Succeed"
},
"Fail": {
"Type": "Fail"
}
}
}
```
### 狀態機器範例：使用產品功能執行單一測試群組
此狀態機器：
+ 執行測試群組 `GroupA`。
+ 檢查執行錯誤，並在發現任何 `Fail` 時轉換為 。
+ 將 `FeatureThatDependsOnGroupA`功能新增至 `awsiotdevicetester_report.xml` 檔案：
+ 如果`GroupA`通過，則功能會設為 `supported`。
+ 該功能在報告中不會標記為選用。
+ `Succeed` 如果沒有錯誤，則產生報告並轉換為 ，`Fail`否則
```
{
"Comment": "Runs GroupA and adds product features based on GroupA",
"StartAt": "RunGroupA",
"States": {
"RunGroupA": {
"Type": "RunTask",
"Next": "AddProductFeatures",
"TestGroup": "GroupA",
"ResultVar": "GroupA_passed",
"Catch": [
{
"ErrorEquals": [
"RunTaskError"
],
"Next": "Fail"
}
]
},
"AddProductFeatures": {
"Type": "AddProductFeatures",
"Next": "Report",
"Features": [
{
"Feature": "FeatureThatDependsOnGroupA",
"Groups": [
"GroupA"
],
"IsRequired": true
}
]
},
"Report": {
"Type": "Report",
"Next": "Succeed",
"Catch": [
{
"ErrorEquals": [
"ReportError"
],
"Next": "Fail"
}
]
},
"Succeed": {
"Type": "Succeed"
},
"Fail": {
"Type": "Fail"
}
}
}
```
### 狀態機器範例：平行執行兩個測試群組
此狀態機器：
+ 平行執行 `GroupA`和 `GroupB` 測試群組。分支狀態機器中`RunTask`狀態存放在內容中的`ResultVar`變數可供 `AddProductFeatures` 狀態使用。
+ 檢查執行錯誤，並在發現任何 `Fail` 時轉換為 。此狀態機器不會使用`Catch`區塊，因為該方法不會偵測分支狀態機器中的執行錯誤。
+ 根據傳遞 的群組，將功能新增至 `awsiotdevicetester_report.xml` 檔案
+ 如果`GroupA`通過，則功能會設為 `supported`。
+ 該功能在報告中不會標記為選用。
+ `Succeed` 如果沒有錯誤，則產生報告並轉換為 ，`Fail`否則
如果在裝置集區中設定了兩個裝置，則 `GroupA`和 `GroupB` 可以同時執行。不過，如果 `GroupA`或 有`GroupB`多個測試，則兩個裝置可能會配置到這些測試。如果只設定一個裝置，測試群組將依序執行。
```
{
"Comment": "Runs GroupA and GroupB in parallel",
"StartAt": "RunGroupAAndB",
"States": {
"RunGroupAAndB": {
"Type": "Parallel",
"Next": "CheckForErrors",
"Branches": [
{
"Comment": "Run GroupA state machine",
"StartAt": "RunGroupA",
"States": {
"RunGroupA": {
"Type": "RunTask",
"Next": "Succeed",
"TestGroup": "GroupA",
"ResultVar": "GroupA_passed",
"Catch": [
{
"ErrorEquals": [
"RunTaskError"
],
"Next": "Fail"
}
]
},
"Succeed": {
"Type": "Succeed"
},
"Fail": {
"Type": "Fail"
}
}
},
{
"Comment": "Run GroupB state machine",
"StartAt": "RunGroupB",
"States": {
"RunGroupA": {
"Type": "RunTask",
"Next": "Succeed",
"TestGroup": "GroupB",
"ResultVar": "GroupB_passed",
"Catch": [
{
"ErrorEquals": [
"RunTaskError"
],
"Next": "Fail"
}
]
},
"Succeed": {
"Type": "Succeed"
},
"Fail": {
"Type": "Fail"
}
}
}
]
},
"CheckForErrors": {
"Type": "Choice",
"Default": "AddProductFeatures",
"FallthroughOnError": true,
"Choices": [
{
"Expression": "{{$.hasExecutionErrors}} == true",
"Next": "Fail"
}
]
},
"AddProductFeatures": {
"Type": "AddProductFeatures",
"Next": "Report",
"Features": [
{
"Feature": "FeatureThatDependsOnGroupA",
"Groups": [
"GroupA"
],
"IsRequired": true
},
{
"Feature": "FeatureThatDependsOnGroupB",
"Groups": [
"GroupB"
],
"IsRequired": true
}
]
},
"Report": {
"Type": "Report",
"Next": "Succeed",
"Catch": [
{
"ErrorEquals": [
"ReportError"
],
"Next": "Fail"
}
]
},
"Succeed": {
"Type": "Succeed"
},
"Fail": {
"Type": "Fail"
}
}
}
```
# 建立 IDT 測試案例可執行檔
您可以透過下列方式，在測試套件資料夾中建立和放置測試案例可執行檔：
+ 對於使用 `test.json` 檔案中的引數或環境變數來判斷要執行哪些測試的測試套件，您可以為整個測試套件建立單一測試案例可執行檔，或為測試套件中的每個測試群組建立測試可執行檔。
+ 對於您想要根據指定命令執行特定測試的測試套件，您可以為測試套件中的每個測試案例建立一個測試案例可執行檔。
身為測試寫入器，您可以判斷哪種方法適合您的使用案例，並據以建構您的測試案例可執行檔。請確定您的 在每個`test.json`檔案中提供正確的測試案例可執行檔路徑，並且指定的可執行檔正確執行。
當所有裝置都準備好執行測試案例時，IDT 會讀取下列檔案：
+ 所選測試案例`test.json`的 會決定要啟動的程序，以及要設定的環境變數。
+ 測試套件`suite.json`的 決定要設定的環境變數。
IDT 會根據 `test.json` 檔案中指定的命令和引數啟動所需的測試可執行檔程序，並將所需的環境變數傳遞給程序。
## 使用 IDT 用戶端 SDK
IDT 用戶端 SDKs 可讓您使用 API 命令，簡化在測試可執行檔中撰寫測試邏輯的方式，您可以使用這些命令與 IDT 和待測裝置互動。IDT 目前提供下列 SDKs：
+ 適用於 Python 的 IDT 用戶端 SDK
+ IDT 用戶端 SDK for Go
+ 適用於 Java 的 IDT 用戶端 SDK
這些 SDKs位於 `/sdks` 資料夾中。建立新的測試案例可執行檔時，您必須將要使用的開發套件複製到包含測試案例可執行檔的資料夾，並在程式碼中參考開發套件。本節提供可在測試案例可執行檔中使用的可用 API 命令的簡短描述。
**Topics**
+ [裝置互動](#api-device-interaction)
+ [IDT 互動](#api-idt-interaction)
+ [主機互動](#api-host-interaction)
### 裝置互動
下列命令可讓您與待測裝置通訊，而不必實作任何額外的裝置互動和連線管理功能。
**`ExecuteOnDevice`**
允許測試套件在支援 SSH 或 Docker shell 連線的裝置上執行 Shell 命令。
**`CopyToDevice`**
允許測試套件將本機檔案從執行 IDT 的主機機器複製到支援 SSH 或 Docker shell 連線之裝置上的指定位置。
**`ReadFromDevice`**
允許測試套件從支援 UART 連線的裝置序列連接埠讀取。
**注意**
由於 IDT 不會管理使用來自內容的裝置存取資訊所建立之裝置的直接連線，因此我們建議您在測試案例可執行檔中使用這些裝置互動 API 命令。不過，如果這些命令不符合您的測試案例需求，則您可以從 IDT 內容擷取裝置存取資訊，並使用它從測試套件直接連線至裝置。
若要進行直接連線，請分別擷取 中的資訊，`device.connectivity`以及待測裝置和資源裝置`resource.devices.connectivity`的欄位。如需使用 IDT 內容的詳細資訊，請參閱 [使用 IDT 內容](idt-context.md)。
### IDT 互動
下列命令可讓您的測試套件與 IDT 通訊。
**`PollForNotifications`**
允許測試套件檢查來自 IDT 的通知。
**`GetContextValue ` 和 `GetContextString`**
允許測試套件從 IDT 內容擷取值。如需詳細資訊，請參閱[使用 IDT 內容](idt-context.md)。
**`SendResult`**
允許測試套件向 IDT 報告測試案例結果。此命令必須在測試套件中每個測試案例的結尾呼叫。
### 主機互動
下列命令可讓您的測試套件與主機機器通訊。
**`PollForNotifications`**
允許測試套件檢查來自 IDT 的通知。
**`GetContextValue` 和 `GetContextString`**
允許測試套件從 IDT 內容擷取值。如需詳細資訊，請參閱[使用 IDT 內容](idt-context.md)。
**`ExecuteOnHost`**
允許測試套件在本機電腦上執行命令，並讓 IDT 管理測試案例可執行生命週期。
## 啟用 IDT CLI 命令
`run-suite` 命令 IDT CLI 提供數個選項，可讓測試執行器自訂測試執行。若要允許測試執行器使用這些選項來執行您的自訂測試套件，請實作對 IDT CLI 的支援。如果您未實作支援，測試執行器仍然可以執行測試，但某些 CLI 選項將無法正常運作。為了提供理想的客戶體驗，建議您在 IDT CLI 中為 `run-suite`命令實作下列引數的支援：
**`timeout-multiplier`**
指定大於 1.0 的值，將在執行測試時套用至所有逾時。
測試執行器可以使用此引數來增加他們想要執行的測試案例的逾時。當測試執行器在其`run-suite`命令中指定此引數時，IDT 會使用它來計算 IDT\$1TEST\$1TIMEOUT 環境變數的值，並在 IDT 內容中設定 `config.timeoutMultiplier` 欄位。若要支援此引數，您必須執行下列動作：
+ 讀取 IDT\$1TEST\$1TIMEOUT 環境變數以取得正確計算的逾時值，而不是直接使用 `test.json` 檔案的逾時值。
+ 從 IDT 內容擷取`config.timeoutMultiplier`值，並將其套用至長時間執行的逾時。
如需因逾時事件而提早結束的詳細資訊，請參閱 [指定結束行為](#test-exec-exiting)。
**`stop-on-first-failure`**
指定 IDT 應在遇到失敗時停止執行所有測試。
當測試執行器在其`run-suite`命令中指定此引數時，IDT 會在遇到失敗時立即停止執行測試。不過，如果測試案例平行執行，則這可能會導致非預期的結果。若要實作支援，請確定如果 IDT 遇到此事件，您的測試邏輯會指示所有執行中的測試案例停止、清除臨時資源，並向 IDT 報告測試結果。如需在故障時提早結束的詳細資訊，請參閱 [指定結束行為](#test-exec-exiting)。
**`group-id` 和 `test-id`**
指定 IDT 應僅執行選取的測試群組或測試案例。
測試執行器可以將這些引數與其`run-suite`命令搭配使用，以指定下列測試執行行為：
+ 在指定的測試群組內執行所有測試。
+ 從指定的測試群組內執行一系列測試。
若要支援這些引數，測試套件的狀態機器必須在狀態機器中包含一組特定的 `RunTask`和 `Choice` 狀態。如果您不是使用自訂狀態機器，則預設的 IDT 狀態機器會包含所需的狀態，而且您不需要採取其他動作。不過，如果您使用的是自訂狀態機器，請使用 [狀態機器範例：執行使用者選取的測試群組](idt-state-machine.md#allow-specific-groups)做為範例，在狀態機器中新增所需的狀態。
如需 IDT CLI 命令的詳細資訊，請參閱 [偵錯並執行自訂測試套件](run-tests-custom.md)。
## 寫入事件日誌
測試執行時，您可以將資料傳送至 `stdout`和 `stderr`，以將事件日誌和錯誤訊息寫入 主控台。如需主控台訊息格式的資訊，請參閱 [主控台訊息格式](idt-review-results-logs.md#idt-console-format)。
當 IDT 完成執行測試套件時，此資訊也可在 資料夾的 `test_manager.log` 檔案中取得`/results//logs`。
您可以設定每個測試案例，將日誌從其測試執行寫入至位於 `/results/execution-id/logs` 資料夾中`_`的檔案，包括來自待測裝置的日誌。若要這樣做，請從具有`testData.logFilePath`查詢的 IDT 內容擷取日誌檔案的路徑，在該路徑建立檔案，然後寫入您想要的內容。IDT 會根據正在執行的測試案例自動更新路徑。如果您選擇不建立測試案例的日誌檔案，則該測試案例不會產生任何檔案。
您也可以設定文字可執行檔，視需要在 `/logs` 資料夾中建立其他日誌檔案。建議您為日誌檔案名稱指定唯一的字首，以免您的檔案遭到覆寫。
## 向 IDT 報告結果
IDT 會將測試結果寫入 `awsiotdevicetester_report.xml`和 `suite-name_report.xml` 檔案。這些報告檔案位於 。 `/results//`兩個報告都會擷取測試套件執行的結果。如需 IDT 用於這些報告之結構描述的詳細資訊，請參閱 [檢閱 IDT 測試結果和日誌](idt-review-results-logs.md)
若要填入`suite-name_report.xml`檔案的內容，您必須在測試執行完成之前，使用 `SendResult`命令向 IDT 報告測試結果。如果 IDT 找不到測試的結果，則會發出測試案例的錯誤。下列 Python 摘錄顯示將測試結果傳送至 IDT 的命令：
```
request-variable = SendResultRequest(TestResult(result))
client.send_result(request-variable)
```
如果您未透過 API 報告結果，IDT 會在測試成品資料夾中尋找測試結果。此資料夾的路徑會存放在 IDT 內容中`testData.testArtifactsPath`存檔的 中。在此資料夾中，IDT 會使用第一個依字母順序排序的 XML 檔案做為測試結果。
如果您的測試邏輯產生 JUnit XML 結果，您可以將測試結果寫入成品資料夾中的 XML 檔案，直接將結果提供給 IDT，而不是剖析結果，然後使用 API 將結果提交給 IDT。
如果您使用此方法，請確定您的測試邏輯準確摘要測試結果，並以與 檔案相同的格式格式化結果`suite-name_report.xml`檔案。IDT 不會對您提供的資料執行任何驗證，但以下情況除外：
+ IDT 會忽略`testsuites`標籤的所有屬性。反之，它會從其他報告的測試群組結果計算標籤屬性。
+ 必須至少有一個`testsuite`標籤存在於 中`testsuites`。
由於 IDT 對所有測試案例使用相同的成品資料夾，並且不會在測試執行之間刪除結果檔案，如果 IDT 讀取不正確的檔案，則此方法也可能導致錯誤報告。建議您在所有測試案例中使用相同的名稱來產生 XML 結果檔案，以覆寫每個測試案例的結果，並確保 IDT 可以使用正確的結果。雖然您可以使用混合方法在測試套件中報告，也就是說，對某些測試案例使用 XML 結果檔案，並透過 API 向其他人提交結果，但不建議使用此方法。
## 指定結束行為
將您的文字可執行檔設定為一律以結束碼 0 結束，即使測試案例報告失敗或錯誤結果亦然。僅使用非零結束代碼來表示測試案例未執行，或測試案例可執行檔無法將任何結果傳達給 IDT。當 IDT 收到非零結束碼時，它會標記測試案例發生錯誤，導致無法執行。
IDT 可能會請求或預期測試案例在下列事件完成之前停止執行。使用此資訊來設定您的測試案例可執行檔，以從測試案例偵測下列每個事件：
****Timeout (逾時)****
當測試案例執行的時間超過`test.json`檔案中指定的逾時值時，便會發生。如果測試執行器使用`timeout-multiplier`引數指定逾時乘數，則 IDT 會使用乘數計算逾時值。
若要偵測此事件，請使用 IDT\$1TEST\$1TIMEOUT 環境變數。當測試執行器啟動測試時，IDT 會將 IDT\$1TEST\$1TIMEOUT 環境變數的值設定為計算的逾時值 （以秒為單位），並將變數傳遞至測試案例可執行檔。您可以讀取變數值來設定適當的計時器。
****中斷****
當測試執行器中斷 IDT 時發生。例如，按 Ctrl\$1C。
由於終端機會將訊號傳播到所有子程序，因此您只需在測試案例中設定訊號處理常式，即可偵測中斷訊號。
或者，您可以定期輪詢 API，以檢查 `PollForNotifications` API `CancellationRequested` 回應中的布林值。當 IDT `CancellationRequested` 收到中斷訊號時，會將布林值設定為 `true`。
****第一次失敗時停止****
當與目前測試案例平行執行的測試案例失敗，且測試執行器使用 `stop-on-first-failure`引數指定 IDT 應在遇到任何失敗時停止時，便會發生。
若要偵測此事件，您可以定期輪詢 API，以檢查 `PollForNotifications` API `CancellationRequested` 回應中的布林值。當 IDT 遇到失敗並設定為在第一次失敗時停止時，它會將`CancellationRequested`布林值設定為 `true`。
當這些事件發生時，IDT 會等待 5 分鐘，讓任何目前正在執行的測試案例完成執行。如果所有執行中的測試案例未在 5 分鐘內結束，IDT 會強制其每個程序停止。如果 IDT 在程序結束之前尚未收到測試結果，則會將測試案例標記為已逾時。最佳實務是，您應該確保測試案例在遇到其中一個事件時執行下列動作：
1. 停止執行正常測試邏輯。
1. 清除任何臨時資源，例如待測裝置上的測試成品。
1. 向 IDT 報告測試結果，例如測試失敗或錯誤。
1. 結束。
# 使用 IDT 內容
當 IDT 執行測試套件時，測試套件可以存取一組資料，用於判斷每個測試的執行方式。此資料稱為 IDT 內容。例如，`userdata.json`在 IDT 內容中，測試執行器提供的使用者資料組態可用於測試套件。
IDT 內容可視為唯讀 JSON 文件。測試套件可以使用物件、陣列、數字等標準 JSON 資料類型，從 擷取資料並將資料寫入內容。
## 內容結構描述
IDT 內容使用下列格式：
```
{
"config": {
"timeoutMultiplier": timeout-multiplier,
"idtRootPath":
},
"device": {
},
"devicePool": {
},
"resource": {
"devices": [
{
"name": ""
}
]
},
"testData": {
"awsCredentials": {
"awsAccessKeyId": "",
"awsSecretAccessKey": "",
"awsSessionToken": ""
},
"logFilePath": "/path/to/log/file"
},
"userData": {
}
}
```
**`config`**
來自 [`config.json` 檔案](set-config-custom.md#config-json-custom)的資訊。`config` 欄位也包含下列其他欄位：
**`config.timeoutMultiplier`**
測試套件使用的任何逾時值的乘數。此值由 IDT CLI 的測試執行器指定。預設值為 `1`。
**`config.idRootPath`**
此值是設定`userdata.json`檔案時 IDT 絕對路徑值的預留位置。這由建置和快閃記憶體命令使用。
**`device`**
為測試執行選取之裝置的相關資訊。此資訊等同於所選裝置 [`device.json` 檔案中](set-config-custom.md#device-config-custom)的`devices`陣列元素。
**`devicePool`**
為測試執行選取之裝置集區的相關資訊。此資訊等同於所選裝置集區`device.json`檔案中定義的最上層裝置集區陣列元素。
**`resource`**
檔案中資源裝置的相關資訊`resource.json`。
**`resource.devices`**
此資訊等同於 `resource.json` 檔案中定義的`devices`陣列。每個`devices`元素都包含下列額外欄位：
**`resource.device.name`**
資源裝置的名稱。此值設定為 `test.json` 檔案中`requiredResource.name`的值。
**`testData.awsCredentials`**
測試用來連線至雲端的 AWS AWS 登入資料。此資訊是從 `config.json` 檔案取得。
**`testData.logFilePath`**
測試案例寫入日誌訊息的日誌檔案路徑。如果檔案不存在，測試套件會建立此檔案。
**`userData`**
測試執行器在 [`userdata.json` 檔案中](set-config-custom.md#userdata-config-custom)提供的資訊。
## 在內容中存取資料
您可以使用組態檔案和文字可執行檔中的 JSONPath 標記法，搭配 `GetContextValue`和 `GetContextString` APIs 來查詢內容。用於存取 IDT 內容的 JSONPath 字串語法會有所不同，如下所示：
+ 在 `suite.json`和 中`test.json`，您可以使用 `{{query}}`。也就是說，請勿使用根元素`$.`來啟動表達式。
+ 在 中`statemachine.json`，您可以使用 `{{$.query}}`。
+ 在 API 命令中，您可以使用 `query`或 `{{$.query}}`，視命令而定。如需詳細資訊，請參閱 SDKs中的內嵌文件。
下表說明典型foobar JSONPath 表達式中的運算子：
| 運算子 | Description |
| --- | --- |
| \$1 | 根元素。由於 IDT 的最上層內容值是 物件，因此您通常會使用 \$1. 來啟動查詢。 |
| .childName | childName 使用 物件的名稱存取子元素。如果套用至陣列， 會產生新的陣列，並將此運算子套用至每個元素。元素名稱區分大小寫。例如，存取 config 物件中awsRegion值的查詢是 \$1.config.awsRegion。 |
| [start:end] | 從陣列篩選元素，擷取從start索引開始到end索引的項目，兩者皆包含在內。 |
| [index1, index2, ... , indexN] | 從陣列篩選元素，僅從指定的索引擷取項目。 |
| [?(expr)] | 使用 expr表達式篩選陣列中的元素。此表達式必須評估為布林值。 |
若要建立篩選條件表達式，請使用下列語法：
```
| operator |
```
在此語法中：
+ `jsonpath` 是使用標準 JSON 語法的 JSONPath。
+ `value` 是使用標準 JSON 語法的任何自訂值。
+ `operator` 是下列其中一個運算子：
+ `<` （小於）
+ `<=` （小於或等於）
+ `==` （等於）
如果表達式中的 JSONPath 或值是陣列、布林值或物件值，則這是您可以唯一支援的二進位運算子。
+ `>=` （大於或等於）
+ `>` （大於）
+ `=~` （規則表達式比對）。若要在篩選條件表達式中使用此運算子，表達式左側的 JSONPath 或值必須評估為字串，右側必須是遵循 [RE2 語法](https://github.com/google/re2/wiki/Syntax)的模式值。
您可以使用格式為 \$1\$1*query*\$1\$1 的 JSONPath 查詢，做為`test.json`檔案中 `args`和 `environmentVariables` 欄位內，以及`suite.json`檔案中 `environmentVariables` 欄位內的預留位置字串。IDT 會執行內容查詢，並將查詢的評估值填入欄位。例如，在 `suite.json` 檔案中，您可以使用預留位置字串來指定每個測試案例變更的環境變數值，IDT 會將每個測試案例的正確值填入環境變數。不過，當您在 `test.json`和 `suite.json` 檔案中使用預留位置字串時，下列考量適用於您的查詢：
+ 您必須以所有小寫在查詢中每次出現 `devicePool`金鑰。也就是說，請`devicepool`改用 。
+ 對於陣列，您只能使用字串陣列。此外，陣列使用非標準`item1, item2,...,itemN`格式。如果陣列只包含一個元素，則會將其序列化為 `item`，使其與字串欄位無法區分。
+ 您無法使用預留位置從內容中擷取物件。
由於這些考量，我們建議您盡可能使用 API 來存取測試邏輯中的內容，而不是 `test.json`和 `suite.json` 檔案中的預留位置字串。不過，在某些情況下，使用 JSONPath 預留位置擷取單一字串以設定為環境變數可能會更方便。
# 設定測試執行器的設定
若要執行自訂測試套件，測試執行器必須根據他們想要執行的測試套件來設定其設定。根據位於 `/configs/` 資料夾中的組態檔案範本來指定設定。如有需要，測試執行器也必須設定 IDT 用來連線至 AWS 雲端的 AWS 登入資料。
身為測試寫入器，您需要設定這些檔案來[偵錯您的測試套件](run-tests-custom.md)。您必須提供測試執行器的說明，以便他們可以視需要設定下列設定來執行您的測試套件。
## 設定 device.json
`device.json` 檔案包含執行測試之裝置的相關資訊 （例如 IP 地址、登入資訊、作業系統和 CPU 架構）。
測試執行器可以使用位於 `/configs/` 資料夾中的下列範本`device.json`檔案提供此資訊。
```
[
{
"id": "",
"sku": "",
"features": [
{
"name": "",
"value": "",
"configs": [
{
"name": "",
"value": ""
}
],
}
],
"devices": [
{
"id": "",
"pairedResource": "", //used for no-op protocol
"connectivity": {
"protocol": "ssh | uart | docker | no-op",
// ssh
"ip": "",
"port": ,
"publicKeyPath": "",
"auth": {
"method": "pki | password",
"credentials": {
"user": "",
// pki
"privKeyPath": "/path/to/private/key",
// password
"password": "",
}
},
// uart
"serialPort": "",
// docker
"containerId": "",
"containerUser": "",
}
}
]
}
]
```
如下所述，包含值的所有欄位皆為必要：
**`id`**
使用者定義的英數字元 ID，可唯一識別裝置的集合，稱為「裝置集區」**。屬於同一個集區的裝置必須有相同的硬體。當您執行測試套件，集區中的裝置會用來將工作負載平行化。多個裝置用來執行不同的測試。
**`sku`**
可唯一識別測試裝置的英數字元值。SKU 用於追蹤合格裝置。
如果您想要在 AWS 合作夥伴裝置目錄中列出您的電路板，您在此處指定的 SKU 必須符合您在列出程序中使用的 SKU。
**`features`**
選用。包含裝置支援功能的陣列。裝置功能是您在測試套件中設定的使用者定義值。您必須提供測試執行器有關要包含在 `device.json` 檔案中的功能名稱和值的資訊。例如，如果您想要測試可做為其他裝置的 MQTT 伺服器運作的裝置，則可以設定測試邏輯來驗證名為 之功能的特定支援層級`MQTT_QoS`。測試執行器提供此功能名稱，並將功能值設定為其裝置支援的 QoS 層級。您可以透過`devicePool.features`查詢從 [IDT 內容](idt-context.md)擷取提供的資訊，或透過`pool.features`查詢從[狀態機器內容](idt-state-machine.md#state-machine-context)擷取提供的資訊。
**`features.name`**
功能的名稱。
**`features.value`**
支援的功能值。
**`features.configs`**
如有需要，此功能的組態設定。
**`features.config.name`**
組態設定的名稱。
**`features.config.value`**
支援的設定值。
**`devices`**
要測試之集區中的裝置陣列。至少需要一個裝置。
**`devices.id`**
使用者定義的唯一識別符，用於識別要測試的裝置。
**`devices.pairedResource`**
資源裝置的使用者定義唯一識別符。當您使用`no-op`連線通訊協定測試裝置時，需要此值。
**`connectivity.protocol`**
用來與此裝置通訊的通訊協定。集區中的每個裝置都必須使用相同的通訊協定。
目前，`uart`對於實體裝置、Docker `docker` 容器，以及沒有 IDT 主機機器直接連線但需要資源裝置做為實體中介軟體來與主機機器通訊`no-op`的裝置，唯一支援的值為 `ssh`和 。
對於無操作裝置，您可以在 中設定資源裝置 ID`devices.pairedResource`。您也必須在 `resource.json` 檔案中指定此 ID。配對的裝置必須是實際與待測裝置配對的裝置。在 IDT 識別並連線至配對的資源裝置後，IDT 將不會根據 `test.json` 檔案中所述的功能連線至其他資源裝置。
**`connectivity.ip`**
要測試之裝置的 IP 位址。
只有當 `connectivity.protocol` 設為 `ssh` 時，才會套用此屬性。
**`connectivity.port`**
選用。用於 SSH 連線的連接埠號碼。
預設值為 22。
只有當 `connectivity.protocol` 設為 `ssh` 時，才會套用此屬性。
**`connectivity.publicKeyPath`**
選用。用來驗證待測裝置連線之公有金鑰的完整路徑。當您指定 時`publicKeyPath`，IDT 會在建立與待測裝置的 SSH 連線時驗證裝置的公有金鑰。如果未指定此值，IDT 會建立 SSH 連線，但不會驗證裝置的公有金鑰。
我們強烈建議您指定公有金鑰的路徑，並使用安全方法來擷取此公有金鑰。對於標準命令列型 SSH 用戶端， 檔案中會提供公有金鑰`known_hosts`。如果您指定單獨的公有金鑰檔案，此檔案必須使用與 `known_hosts` 檔案相同的格式，也就是 `ip-address key-type public-key`。
**`connectivity.auth`**
連線的驗證資訊。
只有當 `connectivity.protocol` 設為 `ssh` 時，才會套用此屬性。
**`connectivity.auth.method`**
用來透過指定的連線通訊協定存取裝置的驗證方法。
支援的值如下：
+ `pki`
+ `password`
**`connectivity.auth.credentials`**
用於驗證的燈入資料。
**`connectivity.auth.credentials.password`**
用於登入要測試裝置的密碼。
只有當 `connectivity.auth.method` 設為 `password` 時，才會套用此值。
**`connectivity.auth.credentials.privKeyPath`**
用來登入待測裝置之私有金鑰的完整路徑。
只有當 `connectivity.auth.method` 設為 `pki` 時，才會套用此值。
**`connectivity.auth.credentials.user`**
登入要測試之裝置的使用者名稱。
**`connectivity.serialPort`**
選用。裝置所連接的序列連接埠。
只有當 `connectivity.protocol` 設為 `uart` 時，才會套用此屬性。
**`connectivity.containerId`**
要測試之 Docker 容器的容器 ID 或名稱。
只有當 `connectivity.protocol` 設為 `docker` 時，才會套用此屬性。
**`connectivity.containerUser`**
選用。容器內使用者的名稱。預設值是 Dockerfile 中提供的使用者。
預設值為 22。
只有當 `connectivity.protocol` 設為 `docker` 時，才會套用此屬性。
若要檢查測試執行器是否設定不正確的測試裝置連線，您可以從`pool.Devices[0].Connectivity.Protocol`狀態機器內容擷取，並將其與`Choice`狀態中的預期值進行比較。如果使用不正確的通訊協定，請使用 `LogMessage` 狀態列印訊息並轉換為 `Fail` 狀態。
或者，您可以使用錯誤處理程式碼來報告不正確裝置類型的測試失敗。
## （選用） 設定 userdata.json
`userdata.json` 檔案包含測試套件所需的任何其他資訊，但未在 `device.json` 檔案中指定。此檔案的格式取決於測試套件中定義的[`userdata_scheme.json`檔案](idt-json-config.md#userdata-schema-json)。如果您是測試寫入器，請務必將此資訊提供給將執行您所寫入測試套件的使用者。
## （選用） 設定 resource.json
`resource.json` 檔案包含將用作資源裝置的任何裝置的相關資訊。資源裝置是測試待測裝置的特定功能所需的裝置。例如，若要測試裝置的藍牙功能，您可以使用資源裝置來測試您的裝置是否可以成功連接到裝置。資源裝置是選用的，您可以視需要要求任意數量的資源裝置。身為測試寫入器，您可以使用 [test.json 檔案](idt-json-config.md#test-json)來定義測試所需的資源裝置功能。然後，測試執行器會使用 `resource.json` 檔案來提供具有所需功能的資源裝置集區。請務必將此資訊提供給將執行您撰寫之測試套件的使用者。
測試執行器可以使用位於 `/configs/` 資料夾中的下列範本`resource.json`檔案提供此資訊。
```
[
{
"id": "",
"features": [
{
"name": "",
"version": "",
"jobSlots":
}
],
"devices": [
{
"id": "",
"connectivity": {
"protocol": "ssh | uart | docker",
// ssh
"ip": "",
"port": ,
"publicKeyPath": "",
"auth": {
"method": "pki | password",
"credentials": {
"user": "",
// pki
"privKeyPath": "/path/to/private/key",
// password
"password": "",
}
},
// uart
"serialPort": "",
// docker
"containerId": "",
"containerUser": "",
}
}
]
}
]
```
如下所述，包含值的所有欄位皆為必要：
**`id`**
使用者定義的英數字元 ID，可唯一識別裝置的集合，稱為「裝置集區」**。屬於同一個集區的裝置必須有相同的硬體。當您執行測試套件，集區中的裝置會用來將工作負載平行化。多個裝置用來執行不同的測試。
**`features`**
選用。包含裝置支援功能的陣列。此欄位所需的資訊會在測試套件的 [test.json 檔案中](idt-json-config.md#test-json)定義，並決定要執行哪些測試，以及如何執行這些測試。如果測試套件不需要任何功能，則不需要此欄位。
**`features.name`**
功能的名稱。
**`features.version`**
功能版本。
**`features.jobSlots`**
設定 以指出可以同時使用裝置的測試數量。預設值為 `1`。
**`devices`**
要測試之集區中的裝置陣列。至少需要一個裝置。
**`devices.id`**
使用者定義的唯一識別符，用於識別要測試的裝置。
**`connectivity.protocol`**
用來與此裝置通訊的通訊協定。集區中的每個裝置都必須使用相同的通訊協定。
目前，唯一支援的值為實體裝置的 `ssh`和 ，以及 `uart` Docker 容器`docker`的 和 。
**`connectivity.ip`**
要測試之裝置的 IP 位址。
只有當 `connectivity.protocol` 設為 `ssh` 時，才會套用此屬性。
**`connectivity.port`**
選用。用於 SSH 連線的連接埠號碼。
預設值為 22。
只有當 `connectivity.protocol` 設為 `ssh` 時，才會套用此屬性。
**`connectivity.publicKeyPath`**
選用。用來驗證待測裝置連線的公有金鑰完整路徑。當您指定 時`publicKeyPath`，IDT 會在建立與待測裝置的 SSH 連線時驗證裝置的公有金鑰。如果未指定此值，IDT 會建立 SSH 連線，但不會驗證裝置的公有金鑰。
我們強烈建議您指定公有金鑰的路徑，並使用安全方法來擷取此公有金鑰。對於標準命令列型 SSH 用戶端， `known_hosts`檔案中會提供公有金鑰。如果您指定單獨的公有金鑰檔案，此檔案必須使用與 `known_hosts` 檔案相同的格式，也就是 `ip-address key-type public-key`。
**`connectivity.auth`**
連線的驗證資訊。
只有當 `connectivity.protocol` 設為 `ssh` 時，才會套用此屬性。
**`connectivity.auth.method`**
用來透過指定的連線通訊協定存取裝置的驗證方法。
支援的值如下：
+ `pki`
+ `password`
**`connectivity.auth.credentials`**
用於驗證的燈入資料。
**`connectivity.auth.credentials.password`**
用於登入要測試裝置的密碼。
只有當 `connectivity.auth.method` 設為 `password` 時，才會套用此值。
**`connectivity.auth.credentials.privKeyPath`**
用來登入待測裝置之私有金鑰的完整路徑。
只有當 `connectivity.auth.method` 設為 `pki` 時，才會套用此值。
**`connectivity.auth.credentials.user`**
登入要測試之裝置的使用者名稱。
**`connectivity.serialPort`**
選用。裝置所連接的序列連接埠。
只有當 `connectivity.protocol` 設為 `uart` 時，才會套用此屬性。
**`connectivity.containerId`**
要測試之 Docker 容器的容器 ID 或名稱。
只有當 `connectivity.protocol` 設為 `docker` 時，才會套用此屬性。
**`connectivity.containerUser`**
選用。容器內使用者的名稱。預設值是 Dockerfile 中提供的使用者。
預設值為 22。
只有當 `connectivity.protocol` 設為 `docker` 時，才會套用此屬性。
## （選用） 設定 config.json
`config.json` 檔案包含 IDT 的組態資訊。一般而言，除了提供 IDT AWS 的使用者登入資料，以及選擇性 AWS 的區域之外，測試執行器不需要修改此檔案。如果 AWS 提供具有必要許可的登入資料， 會 AWS IoT Device Tester 收集並提交用量指標給 AWS。這是選擇加入功能，用於改善 IDT 功能。如需詳細資訊，請參閱[提交 IDT 用量指標](idt-usage-metrics.md)。
測試執行器可以透過下列其中一種方式設定其 AWS 登入資料：
+ **憑證檔案**
IDT 會使用與 AWS CLI相同的登入資料檔案。如需詳細資訊，請參閱[組態與登入資料檔案](https://docs.aws.amazon.com/cli/latest/userguide/cli-config-files.html)。
登入資料檔案的位置會有所不同，取決於您使用的作業系統：
+ macOS, Linux: `~/.aws/credentials`
+ Windows：`C:\Users\UserName\.aws\credentials`
+ **環境變數**
環境變數是由作業系統維護且由系統命令使用的變數。在 SSH 工作階段期間定義的變數在該工作階段關閉後無法使用。IDT 可以使用 `AWS_ACCESS_KEY_ID`和 `AWS_SECRET_ACCESS_KEY` 環境變數來存放 AWS 登入資料
若要在 Linux、macOS 或 Unix 上設定這些變數，請使用 **export**：
```
export AWS_ACCESS_KEY_ID=
export AWS_SECRET_ACCESS_KEY=
```
若要在 Windows 上設定這些變數，請使用 **set**：
```
set AWS_ACCESS_KEY_ID=
set AWS_SECRET_ACCESS_KEY=
```
若要設定 IDT 的 AWS 登入資料，測試執行器會在 資料夾的 `config.json` 檔案中編輯 `auth`區段`/configs/`。
```
{
"log": {
"location": "logs"
},
"configFiles": {
"root": "configs",
"device": "configs/device.json"
},
"testPath": "tests",
"reportPath": "results",
"awsRegion": "",
"auth": {
"method": "file | environment",
"credentials": {
"profile": ""
}
}
}
]
```
如下所述，包含值的所有欄位皆為必要：
**注意**
此檔案中的所有路徑都是相對於 ** 所定義。
**`log.location`**
<*device-tester-extract-location>* 中日誌資料夾的路徑。
**`configFiles.root`**
包含組態檔案之資料夾的路徑。
**`configFiles.device`**
`device.json` 檔案的路徑。
**`testPath`**
包含測試套件的資料夾路徑。
**`reportPath`**
IDT 執行測試套件後，將包含測試結果的資料夾路徑。
**`awsRegion`**
選用。測試套件將使用 AWS 的區域。如果未設定，則測試套件將使用每個測試套件中指定的預設區域。
**`auth.method`**
IDT 用來擷取 AWS 登入資料的方法。支援的值是從登入資料檔案`file`擷取登入資料，並使用環境變數`environment`擷取登入資料。
**`auth.credentials.profile`**
從登入資料檔案使用的登入資料設定檔。只有當 `auth.method` 設為 `file` 時，才會套用此屬性。
# 偵錯並執行自訂測試套件
設定[必要的組態](set-config-custom.md)後，IDT 可以執行您的測試套件。完整測試套件的執行時間取決於硬體和測試套件的組成。如需參考，在 Raspberry Pi 3B 上完成完整的 FreeRTOS 資格測試套件大約需要 30 分鐘。 3B
當您撰寫測試套件時，您可以使用 IDT 在偵錯模式下執行測試套件，在執行程式碼之前先檢查程式碼，或將其提供給測試執行器。
## 在偵錯模式下執行 IDT
由於測試套件倚賴 IDT 與裝置互動、提供內容並接收結果，因此您無法在沒有任何 IDT 互動的情況下，在 IDE 中對測試套件進行偵錯。若要這樣做，IDT CLI 會提供 `debug-test-suite`命令，讓您以偵錯模式執行 IDT。執行下列命令以檢視 的可用選項`debug-test-suite`：
```
devicetester_[linux | mac | win_x86-64] debug-test-suite -h
```
當您在偵錯模式下執行 IDT 時，IDT 實際上不會啟動測試套件或執行測試協調器；而是與您的 IDE 互動，以回應從 IDE 中執行的測試套件發出的請求，並將日誌列印到主控台。IDT 不會逾時，並等待結束，直到手動中斷為止。在偵錯模式中，IDT 也不會執行測試協調器，也不會產生任何報告檔案。若要偵錯測試套件，您必須使用 IDE 來提供 IDT 通常從組態檔案取得的一些資訊。請務必提供下列資訊：
+ 每個測試的環境變數和引數。IDT 不會從 `test.json`或 讀取此資訊`suite.json`。
+ 選取資源裝置的引數。IDT 不會從 讀取此資訊`test.json`。
若要偵錯您的測試套件，請完成下列步驟：
1. 建立執行測試套件所需的設定組態檔案。例如，如果您的測試套件需要 `device.json`、 `resource.json`和 `user data.json`，請務必視需要設定所有測試套件。
1. 執行下列命令，將 IDT 置於偵錯模式，然後選取執行測試所需的任何裝置。
```
devicetester_[linux | mac | win_x86-64] debug-test-suite [options]
```
在您執行此命令後，IDT 會等待來自測試套件的請求，然後回應這些請求。IDT 也會產生 IDT 用戶端 SDK 案例程序所需的環境變數。
1. 在您的 IDE 中，使用 `run`或 `debug`組態來執行下列動作：
1. 設定 IDT 產生環境變數的值。
1. 設定您在 `test.json`和 `suite.json` 檔案中指定的任何環境變數或引數的值。
1. 視需要設定中斷點。
1. 在 IDE 中執行測試套件。
您可以視需要多次偵錯並重新執行測試套件。IDT 不會在偵錯模式下逾時。
1. 完成偵錯後，請中斷 IDT 以結束偵錯模式。
## 用於執行測試的 IDT CLI 命令
下節說明 IDT CLI 命令：
------
#### [ IDT v4.0.0 ]
**`help`**
列出所指定命令的相關資訊。
**`list-groups`**
列出指定測試套件中的群組。
**`list-suites`**
列出可用的測試套件。
**`list-supported-products`**
列出您 IDT 版本的支援產品，在此情況下，為目前 IDT 版本提供 FreeRTOS 版本和 FreeRTOS 資格測試套件版本。
**`list-test-cases`**
列出特定測試群組中的測試案例。支援下列選項：
+ `group-id`。 要搜尋的測試群組。此選項為必要選項，且必須指定單一群組。
**`run-suite`**
在裝置集區上執行測試套件。以下是一些常用的選項：
+ `suite-id`。 要執行的測試套件版本。如果未指定，IDT 會使用 `tests` 資料夾中的最新版本。
+ `group-id`。 要執行的測試群組，以逗號分隔的清單。如果未指定，IDT 會執行測試套件中的所有測試群組。
+ `test-id`。 要執行的測試案例，以逗號分隔的清單。指定時，`group-id` 必須指定單一群組。
+ `pool-id`。 要測試的裝置集區。如果測試執行器在您的 `device.json` 檔案中定義了多個裝置集區，則必須指定集區。
+ `timeout-multiplier`。 設定 IDT 為具有使用者定義乘數的測試修改 `test.json` 檔案中指定的測試執行逾時。
+ `stop-on-first-failure`。 設定 IDT 在第一次失敗時停止執行。此選項應與 `group-id` 搭配使用以偵錯指定的測試群組。
+ `userdata`。 設定 檔案，其中包含執行測試套件所需的使用者資料資訊。只有在測試套件的 `suite.json` 檔案中`userdataRequired`設定為 true 時，才需要這樣做。
如需 `run-suite` 選項的詳細資訊，請使用下列 `help` 選項：
```
devicetester_[linux | mac | win_x86-64] run-suite -h
```
**`debug-test-suite`**
在除錯模式下執行測試套件。如需詳細資訊，請參閱[在偵錯模式下執行 IDT](#idt-debug-mode)。
------
# 檢閱 IDT 測試結果和日誌
本節說明 IDT 產生主控台日誌和測試報告的格式。
## 主控台訊息格式
AWS IoT Device Tester 啟動測試套件時， 會使用標準格式將訊息列印到主控台。以下摘錄顯示 IDT 產生的主控台訊息範例。
```
[INFO] [2000-01-02 03:04:05]: Using suite: MyTestSuite_1.0.0 executionId=9a52f362-1227-11eb-86c9-8c8590419f30
```
大多數主控台訊息包含下列欄位：
**`time`**
已記錄事件的完整 ISO 8601 時間戳記。
**`level`**
所記錄事件的訊息層級。一般而言，記錄的訊息層級是 `info`、 `warn`或 之一`error`。如果 IDT 遇到導致它提早結束的預期事件，則發出 `fatal`或 `panic` 訊息。
**`msg`**
記錄的訊息。
**`executionId`**
目前 IDT 程序的唯一 ID 字串。此 ID 用於區分個別的 IDT 執行。
從測試套件產生的主控台訊息提供有關待測裝置以及 IDT 執行的測試套件、測試群組和測試案例的其他資訊。以下摘錄顯示從測試套件產生的主控台訊息範例。
```
[INFO] [2000-01-02 03:04:05]: Hello world! suiteId=MyTestSuitegroupId=myTestGroup testCaseId=myTestCase deviceId=my-deviceexecutionId=9a52f362-1227-11eb-86c9-8c8590419f30
```
主控台訊息的測試套件特定部分包含下列欄位：
**`suiteId`**
目前正在執行的測試套件名稱。
**`groupId`**
目前正在執行的測試群組 ID。
**`testCaseId`**
目前執行的測試案例 ID。
**`deviceId`**
目前測試案例使用的待測裝置 ID。
測試摘要包含測試套件的相關資訊、執行的每個群組的測試結果，以及產生的日誌和報告檔案的位置。下列範例顯示測試摘要訊息。
```
========== Test Summary ==========
Execution Time: 5m00s
Tests Completed: 4
Tests Passed: 3
Tests Failed: 1
Tests Skipped: 0
----------------------------------
Test Groups:
GroupA: PASSED
GroupB: FAILED
----------------------------------
Failed Tests:
Group Name: GroupB
Test Name: TestB1
Reason: Something bad happened
----------------------------------
Path to AWS IoT Device Tester Report: /path/to/awsiotdevicetester_report.xml
Path to Test Execution Logs: /path/to/logs
Path to Aggregated JUnit Report: /path/to/MyTestSuite_Report.xml
```
## AWS IoT Device Tester 報告結構描述
`awsiotdevicetester_report.xml` 是已簽章的報告，其中包含下列資訊：
+ IDT 版本。
+ 測試套件版本。
+ 用於簽署報告的報告簽章和金鑰。
+ `device.json` 檔案中指定的裝置 SKU 和裝置集區名稱。
+ 已測試的產品版本和裝置功能。
+ 測試結果的彙總摘要。此資訊與 `suite-name_report.xml` 檔案中包含的資訊相同。
```
idt-version
test-suite-version
signature
keyname
execution-id
start-time
end-time
product-name
product-version
device-sku
device-name
ssh | uart | docker
```
`awsiotdevicetester_report.xml` 檔案包含 `` 標籤，其中包含關於受測產品和經過一系列測試驗證後之產品功能的資訊。
**``標籤中使用的屬性**
**`name`**
受測產品名稱。
**`version`**
受測產品版本。
**`features`**
驗證的功能。測試套件`required`需要標記為 的功能，才能驗證裝置。以下片段顯示此資訊如何出現在 `awsiotdevicetester_report.xml` 檔案中。
```
```
標記為 `optional` 的功能不需要驗證。以下程式碼片段顯示選用功能。
```
```
## 測試套件報告結構描述
`suite-name_Result.xml` 報告採用 [JUnit XML 格式](https://llg.cubic.org/docs/junit/)。您可以將它整合到持續整合和部署平台，例如 [Jenkins](https://jenkins.io/)、[Bamboo](https://www.atlassian.com/software/bamboo) 等。報告包含測試結果的彙總摘要。
```
reason
reason
reason
```
`awsiotdevicetester_report.xml` 或 中的報告區段會`suite-name_report.xml`列出已執行的測試和結果。
第一個 XML 標籤 `` 包含測試執行的摘要。例如：
```
```
**``標籤中使用的屬性**
**`name`**
測試套件的名稱。
**`time`**
執行測試套件所需的時間，以秒為單位。
**`tests`**
執行的測試次數。
**`failures`**
已執行但未通過的測試次數。
**`errors`**
IDT 無法執行的測試次數。
**`disabled`**
此屬性未使用，可忽略。
如果測試發生失敗或錯誤，您可以檢閱 `` XML 標籤來識別失敗的測試。`` 標籤內的 `` XML 標籤會顯示測試群組的測試結果摘要。例如：
```
```
其格式類似於 `` 標籤，但有不使用且可忽略的 `skipped` 屬性。在每個 `` XML 標籤內，測試群組每個執行的測試都有 `` 標籤。例如：
```
```
**``標籤中使用的屬性**
**`name`**
測試的名稱。
**`attempts`**
IDT 執行測試案例的次數。
當測試案例失敗或發生錯誤時，系統就會將 `` 或 `` 標籤新增至 `` 標籤，其中附有相關資訊以利故障診斷。例如：
```
Reason for the test failure
Reason for the test execution error
```
# 提交 IDT 用量指標
如果您提供具有必要許可的 AWS 登入資料， 會 AWS IoT Device Tester 收集並提交用量指標給 AWS。這是選擇加入功能，用於改善 IDT 功能。IDT 會收集下列資訊：
+ 用來執行 IDT AWS 的帳戶 ID
+ 用於執行測試的 IDT CLI 命令
+ 執行的測試套件
+ ** 資料夾的測試套件
+ 在裝置集區中設定的裝置數量
+ 測試案例名稱和執行時間
+ 測試結果資訊，例如測試是否通過、失敗、發生錯誤或被略過
+ 測試的產品功能
+ IDT 結束行為，例如非預期或提早結束
IDT 傳送的所有資訊也會記錄到 `/results//` 資料夾中`metrics.log`的檔案。您可以檢視日誌檔案，以查看在測試執行期間收集的資訊。只有在您選擇收集用量指標時，才會產生此檔案。
若要停用指標集合，您不需要採取其他動作。只要不要存放您的 AWS 登入資料，而且如果您有存放的 AWS 登入資料，請勿設定 `config.json` 檔案來存取這些登入資料。
## 註冊 AWS 帳戶
如果您沒有 AWS 帳戶，請完成下列步驟來建立一個。
**註冊 AWS 帳戶**
1. 開啟 [https://portal.aws.amazon.com/billing/signup](https://portal.aws.amazon.com/billing/signup)。
1. 請遵循線上指示進行。
部分註冊程序需接收來電或簡訊，並在電話鍵盤輸入驗證碼。
當您註冊 時 AWS 帳戶，*AWS 帳戶根使用者*會建立 。根使用者有權存取該帳戶中的所有 AWS 服務 和資源。作為安全最佳實務，請將管理存取權指派給使用者，並且僅使用根使用者來執行[需要根使用者存取權的任務](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks)。
AWS 會在註冊程序完成後傳送確認電子郵件給您。您可以隨時登錄 [https://aws.amazon.com/](https://aws.amazon.com/) 並選擇**我的帳戶**，以檢視您目前的帳戶活動並管理帳戶。
## 建立具有管理存取權的使用者
註冊 後 AWS 帳戶，請保護 AWS 帳戶根使用者、啟用 AWS IAM Identity Center和建立管理使用者，以免將根使用者用於日常任務。
**保護您的 AWS 帳戶根使用者**
1. 選擇**根使用者**並輸入 AWS 帳戶 您的電子郵件地址，以帳戶擁有者[AWS 管理主控台](https://console.aws.amazon.com/)身分登入 。在下一頁中，輸入您的密碼。
如需使用根使用者登入的說明，請參閱 *AWS 登入 使用者指南*中的[以根使用者身分登入](https://docs.aws.amazon.com/signin/latest/userguide/console-sign-in-tutorials.html#introduction-to-root-user-sign-in-tutorial)。
1. 若要在您的根使用者帳戶上啟用多重要素驗證 (MFA)。
如需說明，請參閱《*IAM 使用者指南*》中的[為您的 AWS 帳戶 根使用者 （主控台） 啟用虛擬 MFA 裝置](https://docs.aws.amazon.com/IAM/latest/UserGuide/enable-virt-mfa-for-root.html)。
**建立具有管理存取權的使用者**
1. 啟用 IAM Identity Center。
如需指示，請參閱《AWS IAM Identity Center 使用者指南》**中的[啟用 AWS IAM Identity Center](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-set-up-for-idc.html)。
1. 在 IAM Identity Center 中，將管理存取權授予使用者。
如需使用 IAM Identity Center 目錄 做為身分來源的教學課程，請參閱*AWS IAM Identity Center 《 使用者指南*》中的[使用預設值設定使用者存取 IAM Identity Center 目錄](https://docs.aws.amazon.com//singlesignon/latest/userguide/quick-start-default-idc.html)。
**以具有管理存取權的使用者身分登入**
+ 若要使用您的 IAM Identity Center 使用者簽署，請使用建立 IAM Identity Center 使用者時傳送至您電子郵件地址的簽署 URL。
如需使用 IAM Identity Center 使用者登入的說明，請參閱*AWS 登入 《 使用者指南*》中的[登入 AWS 存取入口網站](https://docs.aws.amazon.com/signin/latest/userguide/iam-id-center-sign-in-tutorial.html)。
**指派存取權給其他使用者**
1. 在 IAM Identity Center 中，建立一個許可集來遵循套用最低權限的最佳實務。
如需指示，請參閱《AWS IAM Identity Center 使用者指南》**中的[建立許可集](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-started-create-a-permission-set.html)。
1. 將使用者指派至群組，然後對該群組指派單一登入存取權。
如需指示，請參閱《AWS IAM Identity Center 使用者指南》**中的[新增群組](https://docs.aws.amazon.com//singlesignon/latest/userguide/addgroups.html)。
若要提供存取權，請新增權限至您的使用者、群組或角色：
+ 中的使用者和群組 AWS IAM Identity Center：
建立權限合集。請按照《*AWS IAM Identity Center 使用者指南*》中的[建立權限合集](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html)說明進行操作。
+ 透過身分提供者在 IAM 中管理的使用者：
建立聯合身分的角色。遵循《*IAM 使用者指南*》的[為第三方身分提供者 (聯合) 建立角色](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html)中的指示。
+ IAM 使用者：
+ 建立您的使用者可擔任的角色。請按照《*IAM 使用者指南*》的[為 IAM 使用者建立角色](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html)中的指示。
+ (不建議) 將政策直接附加至使用者，或將使用者新增至使用者群組。請遵循《*IAM 使用者指南*》的[新增許可到使用者 (主控台)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) 中的指示。
## 提供 AWS 登入資料給 IDT
若要允許 IDT 存取您的 AWS 登入資料並提交指標 AWS，請執行下列動作：
1. 將 IAM 使用者的 AWS 登入資料儲存為環境變數或儲存在登入資料檔案中：
1. 若要使用環境變數，請執行下列命令：
```
AWS_ACCESS_KEY_ID=access-key
AWS_SECRET_ACCESS_KEY=secret-access-key
```
1. 若要使用登入資料檔案，請將下列資訊新增至 `.aws/credentials file:`
```
[profile-name]
aws_access_key_id=access-key
aws_secret_access_key=secret-access-key
```
1. 設定 `config.json` 檔案的 `auth`區段。如需詳細資訊，請參閱[（選用） 設定 config.json](set-config-custom.md#config-json-custom)。
# 維護測試套件版本
IDT for FreeRTOS 會將測試資源組織成測試套件和測試群組：
+ 測試套件是一組測試群組，用來驗證裝置是否適用於特定版本的 FreeRTOS。
+ 測試群組是一組與特定功能相關的個別測試，例如 BLE 和 MQTT 簡訊。
從 IDT v3.0.0 開始，測試套件使用從 1.0.0 開始的 `major`.`minor`.`patch` 格式進行版本化。當您下載 IDT 時，套件會包含最新的測試套件版本。
當您在命令列界面中啟動 IDT 時，IDT 會檢查是否有可用的更新測試套件版本。如果有，則會提示您更新至新版。您可以選擇進行更新或繼續使用目前的測試。
**注意**
IDT 支援三種最新的測試套件版本，以符合資格。如需詳細資訊，請參閱[了解 的支援政策 AWS IoT Device Tester](idt-support-policy.md)。
您可以使用 `upgrade-test-suite` 命令下載測試套件。或者，您可以在啟動 IDT 時使用選用參數 `-upgrade-test-suite flag`，其中 *flag* 可設為 '`y`' 以一律下載最新版本，或設為 '`n`' 以使用現有的版本。
您也可以執行 `list-supported-versions`命令，列出目前 IDT 版本支援的 FreeRTOS 和測試套件版本。
新測試可能會引入新的 IDT 組態設定。如果這些是選用設定，IDT 會通知您並繼續執行測試。如果這些是必要設定，IDT 會通知您並停止執行。完成設定後，您可以繼續執行測試。
# 對 錯誤進行故障診斷
每個測試套件執行都有唯一的執行 ID，用於 `results` 目錄中建立名為 `results/execution-id` 的資料夾。個別測試群組日誌位於 `results/execution-id/logs` 目錄下。使用 IDT for FreeRTOS 主控台輸出來尋找失敗之測試案例的執行 ID、測試案例 ID 和測試群組 ID，然後開啟名為 之測試案例的日誌檔案`results/execution-id/logs/test_group_id__test_case_id.log`。此檔案中的資訊包括：
+ 完整的建置和刷入命令輸出。
+ 測試執行輸出。
+ 更多詳細的 IDT for FreeRTOS 主控台輸出。
我們建議您採用以下工作流程來進行故障診斷：
1. 如果您看到錯誤「*使用者/角色*未獲授權存取此資源」，請確定您設定 中指定的許可[建立和設定 AWS 帳戶](dev-tester-prereqs.md#config-aws-account)。
1. 讀取主控台輸出以找出相關資訊，如執行 UUID 和目前執行中的任務。
1. 在 `FRQ_Report.xml` 檔案中查看每個測試的錯誤陳述式。此目錄會包含每個測試群組的執行日誌。
1. 查看 下的日誌檔案`/results/execution-id/logs`。
1. 調查下列其中一個問題領域：
+ 裝置組態，例如 `/configs/` 資料夾中的 JSON 組態檔案。
+ 裝置界面。您可以查看日誌以判斷故障的界面。
+ 裝置工具。請確認用來建置和刷新裝置的工具鏈皆已正確安裝與設定。
+ 對於 FRQ 1.x.x，請確定 FreeRTOS 原始程式碼有可用的乾淨複製版本。FreeRTOS 版本會根據 FreeRTOS 版本進行標記。若要複製特定版本的程式碼，請使用下列命令：
```
git clone --branch version-number https://github.com/aws/amazon-freertos.git
cd amazon-freertos
git submodule update --checkout --init --recursive
```
## 裝置組態故障診斷
當您使用 IDT for FreeRTOS 時，您必須先取得正確的組態檔案，才能執行二進位檔。如果您遇到剖析和組態錯誤，第一步應該是找到適合環境的組態範本並加以運用。這些範本皆位於 `IDT_ROOT/configs` 目錄中。
如果您仍然有問題，請參閱下列除錯程序。
### 查詢位置
首先，請讀取主控台輸出以找出相關資訊，例如本文件中做為 `execution-id` 參考的執行 UUID。
接著，在 `/results/execution-id` 目錄中查看 `FRQ_Report.xml` 檔案。此檔案包含已執行的所有測試案例，以及每次失敗的錯誤片段。若要取得所有的執行日誌，請尋找每個測試案例的 `/results/execution-id/logs/test_group_id__test_case_id.log` 檔案。
### IDT 錯誤代碼
下表說明 IDT for FreeRTOS 產生的錯誤代碼：
| 錯誤程式碼 | 錯誤代碼名稱 | 可能的根本原因 | 疑難排解 |
| --- | --- | --- | --- |
| 201 | InvalidInputError | `device.json`、`config.json`、或 `userdata.json` 中的欄位遺失或格式不正確。 | 請確定列出的檔案中未遺漏必要欄位且為必要格式。如需詳細資訊，請參閱[微控制器電路板的第一個測試](qual-steps.md)。 |
| 202 | ValidationError | `device.json`、`config.json`、或 `userdata.json` 中的欄位包含無效的值。 | 請查看報告中錯誤代碼右手方的錯誤訊息： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/dt-afr-troubleshooting.html) |
| 203 | CopySourceCodeError | 無法將 FreeRTOS 原始程式碼複製到指定的目錄。 | 請確認下列項目： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/dt-afr-troubleshooting.html) |
| 204 | BuildSourceError | 無法編譯 FreeRTOS 原始程式碼。 | 請確認下列項目： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/dt-afr-troubleshooting.html) |
| 205 | FlashOrRunTestError | IDT FreeRTOS 無法在您的 DUT 上刷新或執行 FreeRTOS。 | 確認您 `userdata.json` 檔案底下的 `flashTool` 資訊是否正確。如需詳細資訊，請參閱[設定建置、刷新和測試設定](cfg-dt-ud.md)。 |
| 206 | StartEchoServerError | IDT FreeRTOS 無法啟動適用於 WiFi 或安全通訊端測試的 echo 伺服器。 | 請驗證防火牆或網路設定未使用或封鎖設定在 `userdata.json` 檔案 `echoServerConfiguration` 項下的連接埠。 |
### 偵錯組態檔案剖析錯誤
JSON 組態中的錯字有時會導致剖析錯誤。在大部分的情況下，問題是出在 JSON 檔案中省略了括弧、逗號或引號。IDT for FreeRTOS 會執行 JSON 驗證並列印偵錯資訊。該工具會印出發生錯誤的行、行號和語法錯誤的欄號。此資訊應足以協助您修正錯誤，但若仍無法找到問題所在，您可以在 IDE 和文字編輯器 (如 Atom 或 Sublime) 中手動執行驗證，也可以透過 JSONLint 等線上工具完成驗證。
### 偵錯測試結果剖析錯誤
從 [ FreeRTOS-Libraries-Integration-Tests](https://github.com/FreeRTOS/FreeRTOS-Libraries-Integration-Tests) 執行測試群組時，例如 **FullTransportInterfaceTLS、FullPKCS11\$1Core、FullPKCS11\$1Onboard\$1ECC、FullPKCS11\$1Onboard\$1RSA、FullPKCS11\$1PreProvisioned\$1ECC、FullPKCS11\$1PreProvisioned\$1RSA** 或 **OTACore**，IDT for FreeRTOS 會使用序列連線剖析測試裝置的測試結果。有時，裝置上的額外序列輸出可能會干擾測試結果的剖析。
在上述情況下，會輸出奇怪的測試案例失敗原因，例如源自不相關裝置輸出的字串。IDT for FreeRTOS 測試案例日誌檔案 （包括測試期間 IDT for FreeRTOS 收到的所有序列輸出） 可能會顯示下列項目：
```
TEST(Full_PKCS11_Capabilities, PKCS11_Capabilities)
PASS
```
在上述範例中，不相關的裝置輸出可防止 IDT for FreeRTOS 偵測 **PASS** 的測試結果。
檢查下列項目以確保最佳測試。
+ 確定裝置上使用的日誌巨集是執行緒安全。如需詳細資訊[，請參閱實作程式庫日誌巨集](https://docs.aws.amazon.com/freertos/latest/portingguide/afr-library-logging-macros.html)。
+ 在測試期間，請確保序列連線的輸出最少。即使您的記錄巨集正確執行安全，其他裝置輸出仍可能是個問題，因為測試結果會在測試期間以不同的呼叫輸出。
IDT for FreeRTOS 測試案例日誌理想情況下會顯示不中斷的測試結果輸出，如下所示：
```
---------STARTING TESTS---------
TEST(Full_OTA_PAL, otaPal_CloseFile_ValidSignature) PASS
TEST(Full_OTA_PAL, otaPal_CloseFile_InvalidSignatureBlockWritten) PASS
-----------------------
2 Tests 0 Failures 0 Ignored
```
### 偵錯完整性檢查失敗
如果使用 FRQ 1.x.x 版的 FreeRTOS，則適用下列完整性檢查。
當您執行 FreeRTOSIntegrity 測試群組並遇到失敗時，請先確定您尚未修改任何`freertos`目錄檔案。如果您尚未，且仍然遇到問題，請確定您使用的是正確的分支。如果您執行 IDT 的`list-supported-products`命令，您可以找到應使用哪個標記`freertos`的儲存庫分支。
如果您複製了`freertos`儲存庫的正確標記分支，但仍發生問題，請確定您已執行 `submodule update`命令。`freertos` 儲存庫的複製工作流程如下所示。
```
git clone --branch version-number https://github.com/aws/amazon-freertos.git
cd amazon-freertos
git submodule update --checkout —init —recursive
```
完整性檢查程式尋找的檔案清單位於 `freertos`目錄中的 `checksums.json` 檔案中。若要在不修改檔案和資料夾結構的情況下限定 FreeRTOS 連接埠，請確定檔案的「`exhaustive`」和「`minimal`」區段中列出的`checksums.json`任何檔案都未遭到修改。若要在設定 SDK 的情況下執行 ，請確認 '`minimal`' 區段下的任何檔案都未修改。
如果您使用 SDK 執行 IDT 並已修改 `freertos`目錄中的一些檔案，請確定您已在 `userdata` 檔案中正確設定 SDK。否則，完整性檢查程式會驗證 `freertos`目錄中的所有檔案。
### 偵錯 FullWiFi 測試群組失敗
如果您使用 FRQ 1.x.x 並在 FullWiFi 測試群組中遇到失敗，且「`AFQP_WiFiConnectMultipleAP`」測試失敗，這可能是因為兩個存取點都不在與執行 IDT 的主機電腦相同的子網路中。確定兩個存取點都與執行 IDT 的主機電腦位於相同的子網路中。
### 偵錯「必要參數遺失」錯誤
由於新功能正在新增至 IDT for FreeRTOS，因此可能會引入組態檔案的變更。使用舊的組態檔案可能會破壞組態。如果發生這種情況，`results/execution-id/logs` 目錄下的 `test_group_id__test_case_id.log` 檔案會明確列出所有遺漏的參數。IDT for FreeRTOS 會驗證您的 JSON 組態檔案結構描述，以確保已使用最新的支援版本。
### 偵錯「測試無法啟動」錯誤
可能會出現錯誤，指向測試開始期間發生的失敗。由於這類錯誤有多種可能原因，請務必檢查下列領域的正確性：
+ 確定您在執行命令中加入的集區名稱實際存在。系統會直接參考您的 `device.json` 檔案。
+ 確保集區中的一或多個裝置都有正確的組態參數。
### 偵錯「找不到測試結果的開始」錯誤
當 IDT 嘗試剖析受測裝置輸出的結果時，您可能會看到錯誤。有幾個可能的原因，因此請檢查下列區域是否正確：
+ 請確定受測裝置與主機機器有穩定的連線。您可以檢查日誌檔案是否有顯示這些錯誤的測試，以查看 IDT 正在接收的內容。
+ 如果使用 FRQ 1.x.x，且測試中的裝置是透過慢速網路或其他介面連線，或者您在 FreeRTOS 測試群組日誌和其他 FreeRTOS 測試群組輸出中看不到 "------STARTING TESTS---------" 旗標，您可以嘗試增加使用者資料組態`testStartDelayms`中的 值。如需詳細資訊，請參閱[設定建置、刷新和測試設定](cfg-dt-ud.md)。
### 偵錯「測試失敗：預期 \$1\$1 個結果，但看到 \$1\$1\$1」錯誤
您可能會在測試期間看到指向測試失敗的錯誤。測試預期有一定數量的結果，且在測試期間不會看到。有些 FreeRTOS 測試會在 IDT 看到來自裝置的輸出之前執行。如果您看到此錯誤，您可以嘗試增加 *userdata* 組態`testStartDelayms`中的 值。如需詳細資訊，請參閱[設定建置、刷新和測試設定](lts-cfg-dt-ud.md)。
### 偵錯「因為 ConditionalTests 限制條件而取消選取」錯誤
這表示您正在與測試不相容的裝置集區上執行測試。這可能會在 OTA E2E 測試中發生。例如，在執行`OTADataplaneMQTT`測試群組和`device.json`組態檔案中，您已將 OTA 選擇為**否**或選擇`OTADataPlaneProtocol`為 **HTTP**。選擇執行的測試群組必須符合您的`device.json`功能選擇。
### 在裝置輸出監控期間偵錯 IDT 逾時
IDT 可能會因為多種原因而逾時。如果在測試的裝置輸出監控階段發生逾時，而且您可以在 IDT 測試案例日誌中看到結果，這表示 IDT 錯誤剖析結果。其中一個原因可能是測試結果中間的交錯日誌訊息。如果是這種情況，請參閱 [FreeRTOS 移植指南](https://docs.aws.amazon.com/freertos/latest/portingguide/afr-porting-ota.html)，以取得如何設定 UNITY 日誌的更多詳細資訊。
裝置輸出監控期間逾時的另一個原因是裝置在單一 TLS 測試案例失敗後重新啟動。裝置接著會執行刷新的影像，並導致日誌中看到無限迴圈。如果發生這種情況，請確定您的裝置未在測試失敗後重新啟動。
### 偵錯「未授權存取資源」錯誤
您可能會在終端機輸出或 下的 `test_manager.log` 檔案中看到錯誤「*使用者/角色*未獲授權存取此資源」`/results/execution-id/logs`。若要解決這個問題，請將 `AWS IoTDeviceTesterForFreeRTOSFullAccess` 受管政策連接到您的測試使用者。如需詳細資訊，請參閱[建立和設定 AWS 帳戶](dev-tester-prereqs.md#config-aws-account)。
### 偵錯網路測試錯誤
進行以網路為基礎的測試時，IDT 會在主機機器上啟動連結至非預留連接埠的 echo 伺服器。如果在 WiFi 或安全通訊端測試中因逾時或無法連線而發生錯誤，請確認網路已設定為允許流量傳送至 1024 - 49151 範圍內的已設定連接埠。
根據預設，安全通訊端測試會使用連接埠 33333 和 33334。根據預設，WiFi 測試會使用連接埠 33335。如果這三個連接埠都為防火牆或網路使用或封鎖，您可以在 userdata.json 中選擇不同的連接埠以供測試。如需詳細資訊，請參閱[設定建置、刷新和測試設定](cfg-dt-ud.md)。您可以使用下列命令檢查某個特定的連接埠是否正在使用中：
+ Windows：`netsh advfirewall firewall show rule name=all | grep port`
+ Linux：`sudo netstat -pan | grep port`
+ macOS：`netstat -nat | grep port`
### 由於相同版本承載導致 OTA 更新失敗
如果 OTA 測試案例由於執行 OTA 後裝置上的相同版本而失敗，可能是因為您的建置系統 （例如 cmake) 未注意到 IDT 對 FreeRTOS 原始程式碼的變更，也未建置更新的二進位檔。這會導致 OTA 與目前位於裝置上的相同二進位檔搭配執行，因而測試失敗。若要疑難排解 OTA 更新失敗，請先確定您使用的是建置系統的最新支援版本。
### 測試案例上的 OTA `PresignedUrlExpired` 測試失敗
此測試的其中一個先決條件是 OTA 更新時間應該超過 60 秒，否則測試將會失敗。如果發生這種情況，可在日誌中找到下列錯誤訊息：「測試花費不到 60 秒 (URL 到期時間) 即已完成。請聯絡我們。」
### 偵錯裝置界面和連接埠錯誤
本節包含 IDT 用來連接至裝置的裝置界面相關資訊。
#### 支援平台
IDT 支援 Linux、macOS 和 Windows，這三個平台對與其連接的序列裝置有不同的命名機制：
+ Linux：`/dev/tty*`
+ macOS：`/dev/tty.*` 或 `/dev/cu.*`
+ Windows：COM\$1
檢查裝置 ID：
+ 若為 Linux/macOS，請開啟終端機並執行 `ls /dev/tty*`。
+ 若為 macOS，請開啟終端機並執行 `ls /dev/tty.*` 或 `ls /dev/cu.*`。
+ 若為 Windows，請開啟裝置管理員並展開序列裝置群組。
驗證連接至連接埠的裝置：
+ 若為 Linux，請確認已安裝 `udev` 套件，接著執行 `udevadm info –name=PORT`。此公用程式會印出裝置驅動程式資訊，可協助您驗證使用的連接埠是否正確。
+ 若為 macOS，請開啟 Launchpad 並搜尋 **System Information**。
+ 若為 Windows，請開啟裝置管理員並展開序列裝置群組。
#### 裝置界面
每個內嵌裝置均不同，這表示它們可能有一或多個序列埠。裝置與機器連結時有兩個連接埠是很常見的情況，
+ 其中一個是用來刷新裝置的資料連接埠，
+ 另一個則是可讀取輸出的讀取連接埠。
請務必在 `device.json` 檔案中設定正確的讀取連接埠。否則，系統可能無法讀取來自裝置的輸出。
在有多個連接埠的情況下，您應在 `device.json` 檔案中使用裝置的讀取連接埠。例如，如果您插入 Espressif WRover 裝置，而指派給該裝置的兩個連接埠為 `/dev/ttyUSB0` 和 `/dev/ttyUSB1`，則請在 `device.json` 檔案中使用 `/dev/ttyUSB1`。
使用 Windows 時，也是遵循相同的邏輯操作。
#### 讀取裝置資料
IDT for FreeRTOS 使用個別裝置建置和快閃記憶體工具來指定連接埠組態。如果您正在測試裝置但沒有取得輸出，可以嘗試使用下列預設設定：
+ 傳輸速率：115200
+ 資料位元：8
+ 同位：無
+ 停止位元：1
+ 流量控制：無
這些設定由 IDT for FreeRTOS 處理。因此您不需要自行設定。不過，您可以使用相同方法來手動讀取裝置輸出。在 Linux 或 macOS 上，您可以使用 `screen` 命令執行此操作。在 Windows 上，則可使用 TeraTerm 等程式。
`Screen: screen /dev/cu.usbserial 115200`
`TeraTerm: Use the above-provided settings to set the fields explicitly in the GUI.`
### 開發工具鏈問題
本節討論您的工具鏈可能發生的問題。
#### Ubuntu 上的 Code Composer Studio
Ubuntu 較新版本 (17.10 和 18.04) 具備的 `glibc` 套件版本與 Code Composer Studio 7.*x* 版並不相容，建議您安裝 Code Composer Studio 8.2 版或更新版本。
不相容的症狀可能包括：
+ FreeRTOS 無法建置或刷新您的裝置。
+ Code Composer Studio 安裝程式可能會凍結。
+ 執行建置或刷新程序期間，主控台中不會顯示任何日誌輸出。
+ 即使是在無界面模式中叫用建置命令，該命令仍會嘗試以 GUI 模式啟動。
### 日誌
IDT for FreeRTOS 日誌會放置在單一位置。從根 IDT 目錄中，這些檔案可在 `results/execution-id/` 下取得：
+ `FRQ_Report.xml`
+ `awsiotdevicetester_report.xml`
+ `logs/test_group_id__test_case_id.log`
`FRQ_Report.xml` 和 `logs/test_group_id__test_case_id.log` 是要檢查的最重要日誌。`FRQ_Report.xml` 包含關於哪些測試案例失敗並出現特定錯誤訊息的資訊。然後，您可以使用 `logs/test_group_id__test_case_id.log` 進一步挖掘問題，深入了解來龍去脈。
#### 主控台錯誤
AWS IoT Device Tester 執行 時，失敗會以簡短訊息回報至主控台。您可以在 `results/execution-id/logs/test_group_id__test_case_id.log` 中查看該內容，以進一步了解錯誤。
#### 日誌錯誤
每個測試套件執行都有一個唯一的執行 ID，用來建立名為 `results/execution-id` 的資料夾。個別測試群組日誌位於 `results/execution-id/logs` 目錄下。使用 IDT for FreeRTOS 主控台的輸出來尋找失敗之測試案例的執行 ID、測試案例 ID 和測試群組 ID。然後使用此資訊來尋找和開啟名為 的測試案例的日誌檔案`results/execution-id/logs/test_group_id__test_case_id.log`。此檔案中的資訊包含完整的建置和快閃記憶體命令輸出、測試執行輸出，以及更詳細的 AWS IoT Device Tester 主控台輸出。
#### S3 儲存貯體問題
如果您在執行 IDT CTRL\$1C時按下 ，IDT 將啟動清除程序。清理的一部分是移除已在 IDT 測試中建立的 Amazon S3 資源。如果清除無法完成，您可能會遇到已建立太多 Amazon S3 儲存貯體的問題。這表示您下次執行 IDT 時，測試將會開始失敗。
如果您按 CTRL\$1C 停止 IDT，則必須讓它完成清除程序以避免此問題。您也可以從您的帳戶刪除手動建立的 Amazon S3 儲存貯體。
## 故障診斷逾時錯誤
如果在執行測試套件時出現逾時錯誤，請指定逾時乘數係數增加逾時。此係數會套用至預設的逾時值。此旗標設定的任何值必須大於或等於 1.0。若要使用逾時乘數，請在執行測試套件時使用標記 `--timeout-multiplier`。
**Example**
```
./devicetester_linux run-suite --suite-id FRQ_1.0.1 --pool-id DevicePool1 --timeout-multiplier 2.5
```
```
./devicetester_linux run-suite --suite-id FRQ_1 --pool-id DevicePool1 --timeout-multiplier 2.5
```
## 行動電話功能和 AWS 費用
當您`Yes`的 `device.JSON` 檔案中將`Cellular`功能設定為 時，FullSecureSockets 將使用 t.micro EC2 執行個體來執行測試，這可能會對 AWS 您的帳戶產生額外費用。如需詳細資訊，請參閱 [Amazon EC2 定價](https://aws.amazon.com/ec2/pricing/)。
## 資格報告產生政策
資格報告僅由 AWS IoT Device Tester (IDT) 版本產生，該版本支援過去兩年內發行的 FreeRTOS 版本。如果您對支援政策有任何疑問，請聯絡 [AWS 支援](https://aws.amazon.com/contact-us/)。
# 了解 的 AWS 受管政策 AWS IoT Device Tester
AWS 受管政策是由 AWS AWS 受管政策建立和管理的獨立政策旨在為許多常用案例提供許可，以便您可以開始將許可指派給使用者、群組和角色。
請記住， AWS 受管政策可能不會授予特定使用案例的最低權限許可，因為這些許可可供所有 AWS 客戶使用。我們建議您定義特定於使用案例的[客戶管理政策](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#customer-managed-policies)，以便進一步減少許可。
您無法變更 AWS 受管政策中定義的許可。如果 AWS 更新受 AWS 管政策中定義的許可，則更新會影響政策連接的所有委託人身分 （使用者、群組和角色）。當新的 AWS 服務 啟動或新的 API 操作可供現有服務使用時， AWS 最有可能更新 AWS 受管政策。
如需詳細資訊，請參閱 *IAM 使用者指南*中的 [AWS 受管政策](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies)。
**Topics**
+ [AWS 受管政策： AWS IoTDeviceTesterForFreeRTOSFullAccess](#aws-managed-policies-AWSIoTDT)
+ [AWS 受管政策的更新](#aws-managed-policy-updates)
## AWS 受管政策： AWS IoTDeviceTesterForFreeRTOSFullAccess
`AWSIoTDeviceTesterForFreeRTOSFullAccess` 受管政策包含下列版本檢查、自動更新功能和指標集合的 AWS IoT Device Tester 許可。
**許可詳細資訊**
此政策包含以下許可：
+ `iot-device-tester:SupportedVersion`
AWS IoT Device Tester 准許擷取支援的產品、測試套件和 IDT 版本清單。
+ `iot-device-tester:LatestIdt`
AWS IoT Device Tester 准許擷取可供下載的最新 IDT 版本。
+ `iot-device-tester:CheckVersion`
AWS IoT Device Tester 准許檢查 IDT、測試套件和產品的版本相容性。
+ `iot-device-tester:DownloadTestSuite`
AWS IoT Device Tester 准許下載測試套件更新。
+ `iot-device-tester:SendMetrics`
AWS 准許收集有關 AWS IoT Device Tester 內部使用的指標。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::*:role/idt-*",
"Condition": {
"StringEquals": {
"iam:PassedToService": "iot.amazonaws.com"
}
}
},
{
"Sid": "VisualEditor1",
"Effect": "Allow",
"Action": [
"iot:DeleteThing",
"iot:AttachThingPrincipal",
"iot:DeleteCertificate",
"iot:GetRegistrationCode",
"iot:CreatePolicy",
"iot:UpdateCACertificate",
"s3:ListBucket",
"iot:DescribeEndpoint",
"iot:CreateOTAUpdate",
"iot:CreateStream",
"signer:ListSigningJobs",
"acm:ListCertificates",
"iot:CreateKeysAndCertificate",
"iot:UpdateCertificate",
"iot:CreateCertificateFromCsr",
"iot:DetachThingPrincipal",
"iot:RegisterCACertificate",
"iot:CreateThing",
"iam:ListRoles",
"iot:RegisterCertificate",
"iot:DeleteCACertificate",
"signer:PutSigningProfile",
"s3:ListAllMyBuckets",
"signer:ListSigningPlatforms",
"iot-device-tester:SendMetrics",
"iot-device-tester:SupportedVersion",
"iot-device-tester:LatestIdt",
"iot-device-tester:CheckVersion",
"iot-device-tester:DownloadTestSuite"
],
"Resource": "*"
},
{
"Sid": "VisualEditor2",
"Effect": "Allow",
"Action": [
"iam:GetRole",
"signer:StartSigningJob",
"acm:GetCertificate",
"signer:DescribeSigningJob",
"s3:CreateBucket",
"execute-api:Invoke",
"s3:DeleteBucket",
"s3:PutBucketVersioning",
"signer:CancelSigningProfile"
],
"Resource": [
"arn:aws:execute-api:us-east-1:098862408343:9xpmnvs5h4/prod/POST/metrics",
"arn:aws:signer:*:*:/signing-profiles/*",
"arn:aws:signer:*:*:/signing-jobs/*",
"arn:aws:iam::*:role/idt-*",
"arn:aws:acm:*:*:certificate/*",
"arn:aws:s3:::idt-*",
"arn:aws:s3:::afr-ota*"
]
},
{
"Sid": "VisualEditor3",
"Effect": "Allow",
"Action": [
"iot:DeleteStream",
"iot:DeleteCertificate",
"iot:AttachPolicy",
"iot:DetachPolicy",
"iot:DeletePolicy",
"s3:ListBucketVersions",
"iot:UpdateCertificate",
"iot:GetOTAUpdate",
"iot:DeleteOTAUpdate",
"iot:DescribeJobExecution"
],
"Resource": [
"arn:aws:s3:::afr-ota*",
"arn:aws:iot:*:*:thinggroup/idt*",
"arn:aws:iam::*:role/idt-*"
]
},
{
"Sid": "VisualEditor4",
"Effect": "Allow",
"Action": [
"iot:DeleteCertificate",
"iot:AttachPolicy",
"iot:DetachPolicy",
"s3:DeleteObjectVersion",
"iot:DeleteOTAUpdate",
"s3:PutObject",
"s3:GetObject",
"iot:DeleteStream",
"iot:DeletePolicy",
"s3:DeleteObject",
"iot:UpdateCertificate",
"iot:GetOTAUpdate",
"s3:GetObjectVersion",
"iot:DescribeJobExecution"
],
"Resource": [
"arn:aws:s3:::afr-ota*/*",
"arn:aws:s3:::idt-*/*",
"arn:aws:iot:*:*:policy/idt*",
"arn:aws:iam::*:role/idt-*",
"arn:aws:iot:*:*:otaupdate/idt*",
"arn:aws:iot:*:*:thing/idt*",
"arn:aws:iot:*:*:cert/*",
"arn:aws:iot:*:*:job/*",
"arn:aws:iot:*:*:stream/*"
]
},
{
"Sid": "VisualEditor5",
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::afr-ota*/*",
"arn:aws:s3:::idt-*/*"
]
},
{
"Sid": "VisualEditor6",
"Effect": "Allow",
"Action": [
"iot:CancelJobExecution"
],
"Resource": [
"arn:aws:iot:*:*:job/*",
"arn:aws:iot:*:*:thing/idt*"
]
},
{
"Sid": "VisualEditor7",
"Effect": "Allow",
"Action": [
"ec2:TerminateInstances"
],
"Resource": [
"arn:aws:ec2:*:*:instance/*"
],
"Condition": {
"StringEquals": {
"ec2:ResourceTag/Owner": "IoTDeviceTester"
}
}
},
{
"Sid": "VisualEditor8",
"Effect": "Allow",
"Action": [
"ec2:AuthorizeSecurityGroupIngress",
"ec2:DeleteSecurityGroup"
],
"Resource": [
"arn:aws:ec2:*:*:security-group/*"
],
"Condition": {
"StringEquals": {
"ec2:ResourceTag/Owner": "IoTDeviceTester"
}
}
},
{
"Sid": "VisualEditor9",
"Effect": "Allow",
"Action": [
"ec2:RunInstances"
],
"Resource": [
"arn:aws:ec2:*:*:instance/*"
],
"Condition": {
"StringEquals": {
"aws:RequestTag/Owner": "IoTDeviceTester"
}
}
},
{
"Sid": "VisualEditor10",
"Effect": "Allow",
"Action": [
"ec2:RunInstances"
],
"Resource": [
"arn:aws:ec2:*:*:image/*",
"arn:aws:ec2:*:*:security-group/*",
"arn:aws:ec2:*:*:volume/*",
"arn:aws:ec2:*:*:key-pair/*",
"arn:aws:ec2:*:*:placement-group/*",
"arn:aws:ec2:*:*:snapshot/*",
"arn:aws:ec2:*:*:network-interface/*",
"arn:aws:ec2:*:*:subnet/*"
]
},
{
"Sid": "VisualEditor11",
"Effect": "Allow",
"Action": [
"ec2:CreateSecurityGroup"
],
"Resource": [
"arn:aws:ec2:*:*:security-group/*"
],
"Condition": {
"StringEquals": {
"aws:RequestTag/Owner": "IoTDeviceTester"
}
}
},
{
"Sid": "VisualEditor12",
"Effect": "Allow",
"Action": [
"ec2:DescribeInstances",
"ec2:DescribeSecurityGroups",
"ssm:DescribeParameters",
"ssm:GetParameters"
],
"Resource": "*"
},
{
"Sid": "VisualEditor13",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": [
"arn:aws:ec2:*:*:security-group/*",
"arn:aws:ec2:*:*:instance/*"
],
"Condition": {
"ForAnyValue:StringEquals": {
"aws:TagKeys": [
"Owner"
]
},
"StringEquals": {
"ec2:CreateAction": [
"RunInstances",
"CreateSecurityGroup"
]
}
}
}
]
}
```
------
## AWS 受管政策的更新
從此服務開始追蹤這些變更起 AWS IoT Device Tester ，您可以檢視 AWS 受管政策更新的詳細資訊。
| 版本 | 變更 | 描述 | Date |
| --- | --- | --- | --- |
| 7 （最新） | 重組`ec2:CreateTags`條件。 | 移除 的用量`ForAnyValues`。 | 6/14/2023 |
| 6 | `freertos:ListHardwarePlatforms` 從政策中移除。 | 自 2023 年 3 月 1 日起移除此動作的許可。 | 6/2/2023 |
| 5 | 新增使用 EC2 執行 echo 伺服器測試的許可。 | 這是用於啟動和停止客戶 AWS 帳戶中的 EC2 執行個體。 | 12/15/2020 |
| 4 | 新增了 `iot:CancelJobExecution`。 | 此許可會取消 OTA 任務。 | 7/17/2020 |
| 3 | 新增下列許可： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/security-iam-aws-managed-policies.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/security-iam-aws-managed-policies.html) | 3/23/2020 |
| 2 | 新增`iot-device-tester:SendMetrics`許可。 | AWS 准許收集有關 AWS IoT Device Tester 內部使用的指標。 | 2/18/2020 |
| 1 | 初始版本。 | | 2/12/2020 |
# 了解 的支援政策 AWS IoT Device Tester
**重要**
截至 2022 年 10 月， AWS IoT Device Tester for AWS IoT FreeRTOS 資格 (FRQ) 1.0 不會產生已簽章的資格報告。您無法使用 IDT FRQ 1.0 版本，讓新的 AWS IoT FreeRTOS 裝置有資格透過[AWS 裝置資格計劃](https://aws.amazon.com/partners/programs/dqp/)在[AWS 合作夥伴裝置目錄中](https://partners.amazonaws.com/qualified-devices)列出。雖然您無法使用 IDT FRQ 1.0 限定 FreeRTOS 裝置，但您可以繼續使用 FRQ 1.0 繼續測試 FreeRTOS 裝置。我們建議您使用 [IDT FRQ 2.0](https://docs.aws.amazon.com/freertos/latest/userguide/lts-idt-freertos-qualification.html) 來限定和列出合作夥伴裝置目錄中的 FreeRTOS 裝置。 [AWS](https://partners.amazonaws.com/qualified-devices)
AWS IoT Device Tester for FreeRTOS 是一種測試自動化工具，用於驗證裝置的 FreeRTOS 連接埠。此外，您可以[限定](https://aws.amazon.com/partners/programs/dqp/) FreeRTOS 裝置，並將其列在[AWS 合作夥伴裝置目錄](https://partners.amazonaws.com/qualified-devices) 上。 AWS IoT Device Tester 適用於 FreeRTOS 的 支援 GitHub 上 FreeRTOS 長期支援 (LTS) 程式庫的驗證和資格，位於 [FreeRTOS/FreeRTOS-LTS ](https://github.com/FreeRTOS/FreeRTOS-LTS)，以及 FreeRTOS[/FreeRTOS 上提供的 FreeRTOS](https://github.com/FreeRTOS/FreeRTOS) 主線。我們建議您使用最新版本的 FreeRTOS 和 AWS IoT Device Tester for FreeRTOS 來驗證和限定您的裝置。
對於 FreeRTOS-LTS，IDT 支援 FreeRTOS 202210 LTS 版本的驗證和資格。如需 [FreeRTOS LTS 版本](https://www.freertos.org/lts-libraries.html)及其維護時間表的詳細資訊，請參閱此處。一旦這些 LTS 版本的支援期間結束，您仍然可以繼續驗證，但 IDT 不會產生報告，這將允許您提交裝置以符合資格。
對於 FreeRTOS/FreeRTOS [FreeRTOS 提供的主線 FreeRTOS](https://github.com/FreeRTOS/FreeRTOS)，我們支援過去六個月內發行的所有版本的驗證和資格，如果發行超過六個月，則支援前兩個版本的 FreeRTOS。如需[目前支援的版本]( https://docs.aws.amazon.com//freertos/latest/userguide/dev-test-versions-afr.html)，請參閱此處。對於不支援的 FreeRTOS 版本，您仍然可以繼續驗證，但 IDT 不會產生報告，這可讓您提交裝置以符合資格。
如需最新支援的 IDT 和 FreeRTOS 版本[支援的 版本 AWS IoT Device Tester](dev-test-versions-afr.md)，請參閱 。您可以使用任何支援的 版本 AWS IoT Device Tester 搭配對應的 FreeRTOS 版本，來測試或限定您的裝置。如果您繼續使用 [FreeRTOS 不支援的 IDT 版本](idt-unsupported-versions-afr.md)，您將不會收到最新的錯誤修正或更新。
有關支援政策的問題，請聯絡 [AWS 客戶支援](https://aws.amazon.com/contact-us/)。