本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 排查 错误 每个测试套件执行都有一个唯一的执行 ID，用于在 `results` 目录中创建名为 `results/execution-id` 的文件夹。单个测试组日志位于 `results/execution-id/logs` 目录下。使用适用于 FreeRTOS 的 IDT 控制台输出以查找失败的测试用例的执行 ID、测试用例 ID 和测试组 ID，然后打开名为 `results/execution-id/logs/test_group_id__test_case_id.log` 的测试用例的日志文件。此文件中的信息包括： + 完整的 build 和 flash 命令输出。 + 测试执行输出。 + 适用于 FreeRTOS 的 IDT 控制台更为详细的输出。 建议采用以下工作流程进行故障排除： 1. 如果您看到错误 “*user/role*无权访问此资源”，请确保按照中的规定配置权限[创建和配置 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 ``` ## 对设备配置进行故障排除 使用适用于 FreeRTOS 的 IDT 时，在执行二进制文件之前必须获取正确的配置文件。如果您收到了解析和配置错误，第一步应该是找到并使用适合您环境的配置模板。这些模板位于 `IDT_ROOT/configs` 目录中。 如果仍有问题，请参阅以下调试过程。 ### 在哪里查找问题？ 首先读取控制台输出以查找信息，例如在此文档中作为 `execution-id` 引用的执行 UUID。 接下来，在 `/results/execution-id` 目录中查找 `FRQ_Report.xml` 文件。此文件包含已运行的所有测试用例以及每次失败的错误代码片段。要获取所有执行日志，请查找每个测试用例的文件 `/results/execution-id/logs/test_group_id__test_case_id.log`。 ### IDT 错误代码 下表说明了适用于 FreeRTOS 的 IDT 生成的错误代码： | 错误代码 | 错误代码名称 | 可能的根源 | 问题排查 | | --- | --- | --- | --- | | 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_cn/freertos/latest/userguide/dt-afr-troubleshooting.html) | | 203 | CopySourceCodeError | 无法将 FreeRTOS 源代码复制到指定的目录中。 | 验证以下内容： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/freertos/latest/userguide/dt-afr-troubleshooting.html) | | 204 | BuildSourceError | 无法编译 FreeRTOS 源代码。 | 验证以下内容： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/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 。 | 确保 `userdata.json` 文件中 `echoServerConfiguration` 下配置的端口未被使用或未被防火墙或网络设置阻止。 | ### 调试配置文件解析错误 有时候，JSON 配置中的输入错误会导致解析错误。大部分情况下，问题是因 JSON 文件中漏掉括号、逗号或引号所导致。适用于 FreeRTOS 的 IDT 执行 JSON 验证并输出调试信息。它输出发生错误的行、行号以及语法错误的列号。这些信息应该足以帮助您修复错误，但是如果您仍然无法找到错误，则可以在IDE、Atom或Sublime等文本编辑器中或通过在线工具（例如Atom）或Sublime中手动进行验证，也可以通过诸如之类 JSONLint的在线工具进行验证。 ### 调试测试结果解析错误 在从 **FullTransportInterfaceTLS、Full \$1C PKCS11 ore [ FreeRTOS-Libraries-Integration-Tests](https://github.com/FreeRTOS/FreeRTOS-Libraries-Integration-Tests)、Full \$1onboard\$1ecc、Full PKCS11 \$1onboard\$1rsa、Full \$1 PKCS11 \$1ECC、Full PKCS11 \$1 \$1RSA 或 **OTACore**Fre PreProvisioned e PreProvisioned RTO** S 的 IDT 等运行测试组时，使用串行连接解析来自测试设备的测试结果。PKCS11有时，设备上的额外串行输出可能会干扰测试结果的解析。 在上述情况下，系统会输出奇怪的测试用例失败原因，例如，输出来自不相关设备输出的字符串。适用于 FreeRTOS 的 IDT 测试用例日志文件（包括适用于 FreeRTOS 的 IDT 在测试过程中收到的所有串行输出）可能显示以下内容： ``` TEST(Full_PKCS11_Capabilities, PKCS11_Capabilities) PASS ``` 在上述示例中，不相关的设备输出会阻止适用于 FreeRTOS 的 IDT 检测到 **PASS** 测试结果。 查看以下内容以确保实现最佳测试。 + 确保设备上使用的日志宏是线程安全的。有关更多信息，请参阅[实现库日志记录宏](https://docs.aws.amazon.com/freertos/latest/portingguide/afr-library-logging-macros.html)。 + 在测试过程中，请确保串行连接的输出尽量少。即使您的日志记录宏是线程安全的，其他设备输出也可能存在问题，因为在测试过程中，测试结果会在单独的调用中输出。 理想情况下，适用于 FreeRTOS 的 IDT 测试用例日志会显示不间断的测试结果输出，如下所示： ``` ---------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，则需要进行以下完整性检查。 在运行 Free RTOSIntegrity 测试组时遇到失败时，请先确保没有修改任何`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 移植，请确保未修改 `checksums.json` 文件的“`exhaustive`”和“`minimal`”部分中列出的文件。要在已配置开发工具包的情况下运行，请确认未修改“`minimal`”部分下的所有文件。 如果您使用开发工具包运行 IDT 且已修改 `freertos` 目录中的某些文件，请确保在 `userdata` 文件中正确配置开发工具包。否则，完整性检查程序将验证 `freertos` 目录中的所有文件。 ### 调试 FullWiFi 测试组故障 如果您使用的是 FRQ 1.x.x，但在 FullWiFi 测试组中遇到故障，而 “`AFQP_WiFiConnectMultipleAP`” 测试失败，则可能是因为两个接入点与运行 IDT 的主机不在同一个子网中。确保两个接入点与运行 IDT 的主机位于同一个子网中。 ### 调试“缺少必需参数”错误 由于在适用于 FreeRTOS 的 IDT 中添加了新功能，所以配置文件可能会发生更改。使用旧配置文件可能会破坏您的配置。如果出现这种情况，`results/execution-id/logs` 目录下的 `test_group_id__test_case_id.log` 文件明确列出了所有缺少的参数。适用于 FreeRTOS 的 IDT 会验证您的 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 看到设备的输出之前运行。如果您看到此错误，可以尝试在*用户数据*配置中增加 `testStartDelayms` 的值。有关更多信息，请参阅 [配置构建、刷写和测试设置](lts-cfg-dt-ud.md)。 ### 调试 “由于限制而未选择 \$1\$1\$1\$1\$1\$1\$1\$1” 错误 ConditionalTests 这意味着您正在与测试不兼容的设备池上运行测试。OTA E2E 测试可能会发生这种情况。例如，在运行 `OTADataplaneMQTT` 测试组和 `device.json` 配置文件中，您选择 OTA 作为 **No**，或者选择 `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`文件中看到 “*user/role*无权访问此资源” 错误`/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 更新失败进行故障排除，首先请确保您使用的是受支持的最新版本的构建系统。 ### `PresignedUrlExpired` 测试用例上的 OTA 测试失败 此测试的一个先决条件是 OTA 更新时间应多于 60 秒，否则测试将失败。如果发生此情况，日志将包含以下错误消息：“Test takes less than 60 seconds (url expired time) to finish。Please reach out to us. (测试在 60 秒(URL 过期时间)内完成。请与我们联系。)” ### 调试设备接口和端口错误 此部分包含有 IDT 连接到设备所用设备接口的信息。 #### 支持的平台 IDT 支持 Linux、macOS 和 Windows。对于连接到其上的串行设备，所有三种平台都有不同的命名方案： + Linux：`/dev/tty*` + macOS： `/dev/tty.*` 或 `/dev/cu.*` + Windows：COM\$1 要查看您的设备端口，请执行以下操作： + 对于 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`，则在您的文件`/dev/ttyUSB1`中使用。`device.json` 对于 Windows，请按照相同的逻辑操作。 #### 读取设备数据 适用于 FreeRTOS 的 IDT 使用单独的设备构建和刷写工具来指定端口配置。如果您测试设备但未获得输出，请尝试以下默认设置： + 波特率：115200 + 数据位：8 + 奇偶校验：无 + 停止位：1 + 流控制：无 这些设置通过适用于 FreeRTOS 的 IDT 处理。您无需设置它们。不过，您可以使用相同的方法手动读取设备输出。在 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 模式启动。 ### 日志记录 适用于 FreeRTOS 的 IDT 日志放在一个位置。从根 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` 目录下。使用适用于 FreeRTOS 的 IDT 控制台的输出以查找失败的测试用例的执行 ID、测试用例 ID 和测试组 ID。然后使用此信息查找并打开名`results/execution-id/logs/test_group_id__test_case_id.log`为的测试用例的日志文件。此文件中的信息包括完整的编译和 Flash 命令输出、测试执行输出以及更详细的 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 费用 当您的`device.JSON`文件`Yes`中将该`Cellular`功能设置为时， FullSecureSockets 将使用 t.micro EC2 实例来运行测试，这可能会给您的 AWS 账户带来额外费用。有关更多信息，请参阅 [Amazon EC2 定价](https://aws.amazon.com/ec2/pricing/)。 ## 资格报告生成策略 资格报告仅由最近两年内发布的支持 FreeRTOS 版本的 AWS IoT Device Tester (IDT) 版本生成。如果您对支持策略有疑问，请联系 [AWS 支持](https://aws.amazon.com/contact-us/)。