故障排除 - FreeRTOS
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

故障排除

每个测试套件执行都有一个唯一的执行 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 is not authorized to access this resource (用户/角色无权访问此资源)”,请确保您按照 创建和配置 AWS 账户 中的说明配置权限。

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

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

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

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

    • 设备配置,如 /configs/ 文件夹中的 JSON 配置文件。

    • 设备接口。检查日志以确定哪些接口失败。

    • 设备工具。确保已正确安装和配置用于生成和刷写设备的工具链。

    • 确保您有干净的 FreeRTOS 源代码的克隆版本。FreeRTOS 发布版本根据 FreeRTOS 版本进行标记。要克隆代码的特定版本,请使用 git clone --branch version-number https://github.com/aws/amazon-freertos.git

解决设备配置问题

使用适用于 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.jsonconfig.jsonuserdata.json 中的字段缺失或格式不正确。

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

202

ValidationError

device.jsonconfig.jsonuserdata.json 中的字段包含无效的值。

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

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

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

203

CopySourceCodeError

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

验证以下内容:

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

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

204

BuildSourceError

无法编译 FreeRTOS 源代码。

验证以下内容:

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

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

205

FlashOrRunTestError

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

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

206

StartEchoServerError

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

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

调试解析错误

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

调试缺少必需参数错误

由于将新功能添加到适用于 FreeRTOS 的 IDT 中,可能会对配置文件进行更改。使用旧配置文件可能会破坏您的配置。如果出现这种情况,results/execution-id/logs 目录下的 test_group_id__test_case_id.log 文件明确列出了所有缺少的参数。适用于 FreeRTOS 的 IDT 验证您的 JSON 配置文件架构,确保使用了支持的最新版本。

调试无法开始测试错误

在测试启动期间,您可能看到指示失败的错误。由于有多种可能的原因,请检查以下地方正确与否:

  • 确保您包括在执行命令中的池名称实际存在。这会从您的 device.json 文件直接引用。

  • 确保池中的设备具有正确的配置参数。

无权访问资源错误

您可能会在终端输出或 /results/execution-id/logs 下面的 test_manager.log 文件中看到错误“user/role is not authorized to access this resource (用户/角色无权访问此资源)”。要解决此问题,请将 AWSIoTDeviceTesterForFreeRTOSFullAccess 托管策略附加到您的测试用户。有关更多信息,请参阅创建和配置 AWS 账户

调试网络测试错误

对于基于网络的测试,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,请在 device.json 文件中使用 /dev/ttyUSB1

    对于 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.xmllogs/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 控制台输出。

超时错误故障排除

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

IDT v3.0.0 and later
./devicetester_linux run-suite --suite-id FRQ_1.0.0 --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