本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 對  錯誤進行故障診斷 每個測試套件執行都有唯一的執行 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/)。