排查 错误 - FreeRTOS
对设备配置进行故障排除超时错误疑难解答蜂窝功能和 Amazon 费用资格报告生成策略
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

排查 错误

每个测试套件执行都有一个唯一的执行 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无权访问此资源”，请确保按照中的规定配置权限创建和配置 Amazon 账户。

  2. 阅读控制台输出以查找信息，例如执行 UUID 和当前正在执行的任务。

  3. 在 FRQ_Report.xml 文件中查找各个测试的错误语句。此目录包含每个测试组执行日志。

  4. 查看 /results/execution-id/logs 下的日志文件。

  5. 调查以下问题领域之一：

    • 设备配置，如 /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 中的字段缺失或格式不正确。

确保在列出的文件中具有所需的字段，并且它们具有所需的格式。有关更多信息，请参阅 首次测试您的微控制器板。

202

ValidationError

device.json、config.json 或 userdata.json 中的字段包含无效的值。

检查报告中的错误代码右侧的错误消息：

  • 无效 Amazon 区域-在config.json文件中指定有效 Amazon 区域。有关 Amazon 区域的更多信息，请参阅区域和终端节点。

  • Amazon 凭据无效-在测试计算机上设置有效的 Amazon 凭据（通过环境变量或凭据文件）。验证是否正确配置了身份验证字段。有关更多信息，请参阅 创建和配置 Amazon 账户。

203

CopySourceCodeError

无法将 FreeRTOS 源代码复制到指定的目录中。

验证以下内容：

  • 检查是否在 userdata.json 文件中指定了有效的 sourcePath。

  • 删除 FreeRTOS 源代码目录中的 build 文件夹（如果存在）。有关更多信息，请参阅 配置构建、刷写和测试设置。

  • Windows 对文件路径名称有字符数限制。文件路径名称过长会引发错误。

204

BuildSourceError

无法编译 FreeRTOS 源代码。

验证以下内容：

  • 检查 userdata.json 文件中的 buildTool 下面的信息是否正确。

  • 如果将 cmake 作为构建工具，请确保在 buildTool 命令中指定了 {{enableTests}}。有关更多信息，请参阅 配置构建、刷写和测试设置。

  • 如果您已将 FreeRTOS 的 IDT 提取到系统上包含空格的文件路径中，例如 C:\Users\My Name\Desktop\，则可能需要在构建命令中添加额外的引号才能确保正确解析路径。刷写命令可能需要执行同样的操作。

205

FlashOrRunTestError

IDT FreeRTOS 无法在 DUT 上刷写或运行 FreeRTOS。

验证 userdata.json 文件中的 flashTool 下面的信息是否正确。有关更多信息，请参阅 配置构建、刷写和测试设置。

206

StartEchoServerError

IDT FreeRTOS 无法启动回声服务器进行或安全套接字测试 WiFi 。

确保 userdata.json 文件中 echoServerConfiguration 下配置的端口未被使用或未被防火墙或网络设置阻止。

调试配置文件解析错误

有时候，JSON 配置中的输入错误会导致解析错误。大部分情况下，问题是因 JSON 文件中漏掉括号、逗号或引号所导致。适用于 FreeRTOS 的 IDT 执行 JSON 验证并输出调试信息。它输出发生错误的行、行号以及语法错误的列号。这些信息应该足以帮助您修复错误，但是如果您仍然无法找到错误，则可以在IDE、Atom或Sublime等文本编辑器中或通过在线工具（例如Atom）或Sublime中手动进行验证，也可以通过诸如之类 JSONLint的在线工具进行验证。

调试测试结果解析错误

在从 FullTransportInterfaceTLS、Full _C PKCS11 ore FreeRTOS-Libraries-Integration-Tests、Full _onboard_ecc、Full PKCS11 _onboard_rsa、Full _ PKCS11 _ECC、Full PKCS11 _ _RSA 或 OTACoreFre PreProvisioned e PreProvisioned RTO S 的 IDT 等运行测试组时，使用串行连接解析来自测试设备的测试结果。PKCS11有时，设备上的额外串行输出可能会干扰测试结果的解析。

在上述情况下，系统会输出奇怪的测试用例失败原因，例如，输出来自不相关设备输出的字符串。适用于 FreeRTOS 的 IDT 测试用例日志文件（包括适用于 FreeRTOS 的 IDT 在测试过程中收到的所有串行输出）可能显示以下内容：


<unrelated device output>
TEST(Full_PKCS11_Capabilities, PKCS11_Capabilities)<unrelated device output>
<unrelated device output>
 PASS

在上述示例中，不相关的设备输出会阻止适用于 FreeRTOS 的 IDT 检测到 PASS 测试结果。

查看以下内容以确保实现最佳测试。

  • 确保设备上使用的日志宏是线程安全的。有关更多信息，请参阅实现库日志记录宏。

  • 在测试过程中，请确保串行连接的输出尽量少。即使您的日志记录宏是线程安全的，其他设备输出也可能存在问题，因为在测试过程中，测试结果会在单独的调用中输出。

理想情况下，适用于 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 的值。有关更多信息，请参阅 配置构建、刷写和测试设置。

调试 “测试失败：预期 __ 结果但看到 ___” 错误

在测试过程中，您可能看到指示测试失败的错误。该测试期望获得一定数量的结果，但在测试过程中没有看到。某些 FreeRTOS 测试会在 IDT 看到设备的输出之前运行。如果您看到此错误，可以尝试在用户数据配置中增加 testStartDelayms 的值。有关更多信息，请参阅 配置构建、刷写和测试设置。

调试 “由于限制而未选择 ________” 错误 ConditionalTests

这意味着您正在与测试不兼容的设备池上运行测试。OTA E2E 测试可能会发生这种情况。例如，在运行 OTADataplaneMQTT 测试组和 device.json 配置文件中，您选择 OTA 作为 No，或者选择 OTADataPlaneProtocol 作为 HTTP。选择运行的测试组必须与您选择的 device.json 的能力相匹配。

在设备输出监控期间调试 IDT 超时

IDT 可能由于多种原因而超时。如果在测试的设备输出监控阶段发生超时，并且您可以在 IDT 测试用例日志中看到结果，则表示 IDT 错误地解析了结果。原因之一可能是测试结果中间有交错的日志消息。如果是这种情况，请参阅《FreeRTOS 移植指南》，了解有关如何设置 UNITY 日志的更多详细信息。

设备输出监控过程中出现超时的另一个原因可能是，设备在单个 TLS 测试用例失败后重新启动。然后，设备会运行刷写的映像并导致无限循环，这在日志中可以看到。如果发生这种情况，请确保您的设备在测试失败后不会重新启动。

调试 “未授权访问资源” 错误

您可能会在终端输出或下的test_manager.log文件中看到 “user/role无权访问此资源” 错误/results/execution-id/logs。要解决此问题，请将 Amazon IoTDeviceTesterForFreeRTOSFullAccess 托管策略附加到您的测试用户。有关更多信息，请参阅 创建和配置 Amazon 账户。

调试网络测试错误

对于基于网络的测试，IDT 启动绑定到主机上非预留端口的 Echo 服务器。如果由于超时 WiFi 或安全套接字测试中的连接不可用而遇到错误，请确保您的网络配置为允许流量流向1024-49151范围内的已配置端口。

安全套接字测试默认使用端口 33333 和 33334。默认情况下， WiFi 测试使用端口 33335。如果这三个端口正在使用或被防火墙或网络阻止，您可以选择使用 userdata.json 中的其他端口进行测试。有关更多信息，请参阅 配置构建、刷写和测试设置。您可以使用以下命令来检查特定端口是否正在使用：

  • 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*

要查看您的设备端口，请执行以下操作：

  • 对于 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 来深入挖掘问题以更好地了解上下文。

控制台错误

运行 Amazon 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 命令输出、测试执行输出以及更详细的 Amazon IoT Device Tester 控制台输出。

S3 存储桶问题

如果在运行 IDT 时按下 CTRL+C，IDT 将启动清理过程。清理工作的一部分是移除在 IDT 测试中创建的 Amazon S3 资源。如果清理无法完成，则可能会遇到已创建的 Amazon S3 存储桶过多的问题。这意味着下次运行 IDT 时，测试将开始失败。

如果您按下 CTRL+C 以停止 IDT，则必须让它完成清理过程才能避免出现此问题。您也可以从您的账户中删除手动创建的 Amazon S3 存储桶。

超时错误疑难解答

如果您在运行测试套件时看到超时错误，请指定超时乘数系数来增大超时值。该系数将应用于默认超时值。为此标志配置的任何值都必须大于或等于 1.0。要使用超时乘数，请在运行测试套件时使用 --timeout-multiplier 标志。

IDT v3.0.0 and later
./devicetester_linux run-suite --suite-id FRQ_1.0.1 --pool-id DevicePool1 --timeout-multiplier 2.5
IDT v1.7.0 and earlier
./devicetester_linux run-suite --suite-id FRQ_1 --pool-id DevicePool1 --timeout-multiplier 2.5

蜂窝功能和 Amazon 费用

当您的device.JSON文件Yes中将该Cellular功能设置为时， FullSecureSockets 将使用 t.micro EC2 实例运行测试，这可能会给您的 Amazon 账户带来额外费用。有关更多信息，请参阅 Amazon EC2 定价。

资格报告生成策略

资格报告仅由最近两年内发布的支持 FreeRTOS 版本的 Amazon IoT Device Tester (IDT) 版本生成。如果您对支持策略有疑问，请联系 Amazon Web Services 支持。