准备首次测试微控制器主板 - FreeRTOS
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

准备首次测试微控制器主板

移植 FreeRTOS 界面时,您可以使用适用于 FreeRTOS 的 IDT 进行测试。在移植了针对主板设备驱动程序的 FreeRTOS 界面之后,您可以使用 AWS IoT Device Tester 在微控制器主板上运行资格测试。

添加库移植层

要为您的设备移植 FreeRTOS,请按照 FreeRTOS 移植指南中的说明操作。

配置 AWS 凭证

您需要为 Device Tester 配置 AWS 凭证以便与 AWS 云通信。有关更多信息,请参阅设置用于开发的 AWS 凭证和区域。必须在 devicetester_extract_location/devicetester_afreertos_[win|mac|linux]/configs/config.json 配置文件中指定有效的 AWS 凭证。

在适用于 FreeRTOS 的 IDT 中创建设备池

要测试的设备排列在设备池中。每个设备池包含一个或多个相同的设备。您可以配置适用于 FreeRTOS 的 IDT 来测试某个池中的单个设备或多个设备。为了加快资格测试过程,适用于 FreeRTOS 的 IDT 可以并行测试具有相同规格的设备。它使用轮询方法,在设备池中的各个设备上执行不同的测试组。

您可以通过编辑 configs 文件夹中 device.json 模板的 devices 部分,将一个或多个设备添加到设备池中。

注意

同一个池中的所有设备必须具有相同的技术规格和 SKU。

要允许针对不同测试组并行生成源代码,适用于 FreeRTOS 的 IDT 需要将源代码复制到适用于 FreeRTOS 的 IDT 提取文件夹的结果文件夹中。您的生成或刷写命令中的源代码路径必须使用 testdata.sourcePath 变量来引用。适用于 FreeRTOS 的 IDT 使用所复制源代码的临时路径来替换此变量。有关更多信息,请参阅适用于 FreeRTOS 的 IDT 变量

以下 device.json 示例文件用于创建具有多个设备的设备池:

[{ "id": "pool-id", "sku": "sku", "features": [ { "name": "WIFI", "value": "Yes | No" }, { "name": "OTA", "value": "Yes | No", "configs": [ { "name": "OTADataPlaneProtocol", "value": "HTTP | MQTT | Both" } ] }, { "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" }, { "name": "BLE", "value": "Yes | No" } ], "devices": [{ "id": "device-id1", "connectivity": { "protocol": "uart", "serialPort": "computer_serial_port_1" }, "secureElementConfig": { "publicKeyAsciiHexFilePath":"absolute-path-to-public-key", "secureElementSerialNumber": "optional: serialnumber-of-secure-element" }, "identifiers": [{ "name": "serialNo", "value": "serialNo-value" }] }, { "id": "device-id2", "connectivity": { "protocol": "uart", "serialPort": "computer_serial_port_2" }, "secureElementConfig": { "publicKeyAsciiHexFilePath": "absolute-path-to-public-key", "secureElementSerialNumber": "optional: serialnumber-of-secure-element" }, "identifiers": [{ "name": "serialNo", "value": "serialNo-value" }] }] }]

device.json 文件中使用以下属性:

id

用户定义的字母数字 ID,用于唯一地标识设备池。属于同一个池的设备必须具有相同的类型。运行一组测试时,池中的设备将用于对工作负载进行并行化处理。

sku

唯一标识您正在测试的主板的字母数字值。该 SKU 用于跟踪符合条件的主板。

注意

如果您希望在 AWS 合作伙伴设备目录中列出您的主板,您在此处指定的 SKU 必须与在列出过程中使用的 SKU 相匹配。

features

包含设备支持的功能的数组。Device Tester 使用此信息来选择要运行的资格测试。

支持的值为:

TCP/IP

指示您的主板是否支持 TCP/IP 堆栈,以及是片上 (MCU) 支持还是分载到另一个模块。资格认证需要使用 TCP/IP。

WIFI

指示您的主板是否具有 Wi-Fi 功能。

TLS

指示您的主板是否支持 TLS。资格认证需要使用 TLS。

PKCS11

指示主板支持的公有密钥加密算法。资格认证需要使用 PKCS11。支持的值为 ECCRSABothNoBoth 表示主板同时支持 ECCRSA 算法。目前没有主板仅支持 RSA,因而选择 RSA 无效。

KeyProvisioning

指示将受信任的 X.509 客户端证书写入主板的方法。有效值为 ImportOnboardNo。资格认证需要进行密钥预置。

  • 如果您的主板允许导入私有密钥,请使用 Import。IDT 将创建一个私有密钥并将其构建为 FreeRTOS 源代码。

  • 如果您的主板支持生成板载私有密钥(例如,如果您的设备具有安全元件,或者如果您希望生成自己的设备密钥对和证书),请使用 Onboard。确保您在每个设备部分中添加一个 secureElementConfig 元素,并将公有密钥文件的绝对路径放在 publicKeyAsciiHexFilePath 字段中。

  • 如果您的主板不支持密钥预置,请使用 No

OTA

指示您的主板是否支持无线 (OTA) 更新功能。OtaDataPlaneProtocol 属性指示设备支持哪个 OTA 数据平面协议。如果设备不支持 OTA 功能,则忽略此属性。在选择 "Both" 后,由于同时运行 MQTT、HTTP 和混合测试,因此 OTA 测试执行时间会延长。

BLE

指示您的主板是否支持低功耗蓝牙 (BLE) 功能。

devices.id

用户定义的测试的设备的唯一标识符。

devices.connectivity.protocol

用于与此设备通信的通信协议。支持的值为:uart

devices.connectivity.serialPort

主机连接到所测试设备时使用的串行端口。

devices.secureElementConfig.PublicKeyAsciiHexFilePath

该文件的绝对路径,包含从板载私有密钥中提取的十六进制字节公有密钥。

devices.secureElementConfig.SecureElementSerialNumber

(可选)安全元件的序列号。如果序列号随设备公有密钥印出,在运行 FreeRTOS 演示/测试项目时,请填写此字段。

identifiers

(可选)任意名称/值对的数组。您可以在下一部分所述的生成和刷写命令中使用这些值。

配置构建、刷写和测试设置

要让适用于 FreeRTOS 的 IDT 自动生成并刷写主板,您必须配置 IDT 针对硬件运行生成和刷写命令。生成和刷写设置在位于 config 文件夹的 userdata.json 模板文件中配置。

为测试设备配置设置

生成、刷写和测试设置在 configs/userdata.json 文件中进行。以下 JSON 示例显示如何配置适用于 FreeRTOS 的 IDT 来测试多个设备:

{ "sourcePath": "/absolute-path-to/freertos", "vendorPath": "{{testData.sourcePath}}/vendors/vendor-name/boards/board-name", "buildTool": { "name": "your-build-tool-name", "version": "your-build-tool-version", "command": [ "/absolute-path-to/build-parallel.sh {{testData.sourcePath}} {{enableTests}}" ] }, "flashTool": { "name": "your-flash-tool-name", "version": "your-flash-tool-version", "command": [ "/absolute-path-to/flash-parallel.sh {{testData.sourcePath}} {{device.connectivity.serialPort}} {{buildImageName}}" ], "buildImageInfo" : { "testsImageName": "tests-image-name", "demosImageName": "demos-image-name" } }, "clientWifiConfig": { "wifiSSID": "ssid", "wifiPassword": "password", "wifiSecurityType": "eWiFiSecurityOpen | eWiFiSecurityWEP | eWiFiSecurityWPA | eWiFiSecurityWPA2" }, "testWifiConfig": { "wifiSSID": "ssid", "wifiPassword": "password", "wifiSecurityType": "eWiFiSecurityOpen | eWiFiSecurityWEP | eWiFiSecurityWPA | eWiFiSecurityWPA2" }, "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" } }

下面列出了在 userdata.json 中使用的属性:

sourcePath

移植的 FreeRTOS 源代码的根目录的路径。

vendorPath

供应商特定 FreeRTOS 代码的路径。对于串行测试,vendorPath 可以设置为绝对路径。例如:

{ "vendorPath":"C:/path-to-freertos/vendors/espressif/boards/esp32" }

对于并行测试,vendorPath 可以使用 {{testData.sourcePath}} 占位符进行设置。例如:

{ "vendorPath":"{{testData.sourcePath}}/vendors/espressif/boards/esp32" }
注意

并行运行测试时,vendorPathbuildToolflashTool 字段中必须使用 {{testData.sourcePath}} 占位符。使用单个设备运行测试时,vendorPathbuildToolflashTool 字段中必须使用绝对路径。

buildTool

您的生成脚本(.bat 或 .sh)的完整路径,该脚本包含用于生成源代码的命令。在构建命令中对源代码路径的所有引用必须使用 AWS IoT Device Tester 变量 {{testdata.sourcePath}} 进行替换。

  • buildImageInfo

    • testsImageName:从 freertos-source/tests 文件夹构建测试时由构建命令生成的文件的名称。

    • demosImageName:从 freertos-source/demos 文件夹构建测试时由构建命令生成的文件的名称。

 

buildTool.buildImageInfo.testsImageName

freertos-source-code/tests 文件夹中构建测试时,构建命令输出的文件的名称。

buildTool.buildImageInfo.demosImageName

freertos-source-code/demos 文件夹中构建演示时,构建命令输出的文件的名称。

flashTool

您的刷写脚本(.sh 或 .bat)的完整路径,该脚本应该包含您设备的刷写命令。在刷写命令中对源代码路径的所有引用必须使用适用于 FreeRTOS 的 IDT 变量 {{testdata.sourcePath}} 进行替换。

clientWifiConfig

客户端 Wi-Fi 配置。Wi-Fi 库测试要求 MCU 主板连接到两个接入点。(两个接入点可以是相同的。) 此属性配置第一个接入点的 Wi-Fi 设置。一些 Wi-Fi 测试用例需要接入点有一定的安全性,不能处于开放状态。

  • wifi_ssid

    Wi-Fi SSID。

  • wifi_password

    Wi-Fi 密码。

  • wifiSecurityType

    使用的 Wi-Fi 安全类型。以下值之一:

    • eWiFiSecurityOpen

    • eWiFiSecurityWEP

    • eWiFiSecurityWPA

    • eWiFiSecurityWPA2

注意

如果您的主板不支持 Wi-Fi,您仍须在 device.json 文件中包含 clientWifiConfig 部分,但您可以忽略这些属性的值。

testWifiConfig

测试 Wi-Fi 配置。Wi-Fi 库测试要求 MCU 主板连接到两个接入点。(两个接入点可以是相同的。) 此属性配置第二个接入点的 Wi-Fi 设置。一些 Wi-Fi 测试用例需要接入点有一定的安全性,不能处于开放状态。

  • wifiSSID

    Wi-Fi SSID。

  • wifiPassword

    Wi-Fi 密码。

  • wifiSecurityType

    使用的 Wi-Fi 安全类型。以下值之一:

    • eWiFiSecurityOpen

    • eWiFiSecurityWEP

    • eWiFiSecurityWPA

    • eWiFiSecurityWPA2

注意

如果您的主板不支持 Wi-Fi,您仍须在 device.json 文件中包含 testWifiConfig 部分,但您可以忽略这些属性的值。

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

位于 afr-source/vendors/vendor/boards/board/aws_demos/config_files/ 中的 aws_demo_config.h 的完整路径。这些文件包含在 FreeRTOS 提供的移植代码模板中。

codeSigningConfiguration

代码签名配置。

signingMethod

代码签名方法。可能的值为 AWSCustom

注意

对于 北京和宁夏区域,使用 Custom。这些区域不支持 AWS 代码签名。

signerHashingAlgorithm

设备所支持的哈希算法。可能的值为 SHA1SHA256

signerSigningAlgorithm

设备所支持的签名算法。可能的值为 RSAECDSA

signerCertificate

用于 OTA 的可信证书。

对于 AWS 代码签名方法,使用上传到 AWS Certificate Manager 的可信证书的 Amazon 资源名称 (ARN)。

对于自定义代码签名方法,请使用签署人证书文件的绝对路径。

有关创建可信证书的更多信息,请参阅 创建代码签名证书

signerCertificateFileName

代码签名证书在设备上的位置。

compileSignerCertificate

如果代码签署人签名验证证书未预置或刷写,从而必须编译到项目中,则此项设置为 true。AWS IoT Device Tester 提取可信证书并将其编译为 aws_codesigner_certifiate.h

untrustedSignerCertificateArn

上传到 ACM 的代码签名证书的 ARN。

signerPlatform

AWS Code Signer 在创建 OTA 更新作业时使用的签名和哈希算法。目前,此字段的可能值为 AmazonFreeRTOS-TI-CC3220SFAmazonFreeRTOS-Default

  • 如果为 SHA1RSA,则选择 AmazonFreeRTOS-TI-CC3220SF

  • 如果为 SHA256ECDSA,则选择 AmazonFreeRTOS-Default

如果您的配置需要 SHA256 | RSASHA1 | ECDSA,请与我们联系以获取进一步的支持。

如果您为 signingMethod 选择 Custom,则配置 signCommand

signCommand

用于执行自定义代码签名的命令。您可以在 /configs/script_templates 目录中找到模板。

命令中需要两个占位符 {{inputImageFilePath}}{{outputSignatureFilePath}}{{inputImageFilePath}} 是要签名的由 IDT 构建的映像的文件路径。{{outputSignatureFilePath}} 是将由脚本生成的签名的文件路径。

otaDemoConfigFilePath

位于 afr-source/vendors/vendor/boards/board/ aws_demos/config_files/ 中的 aws_demo_config.h 的完整路径。这些文件包含在 FreeRTOS 提供的移植代码模板中。

cmakeConfiguration

CMake 配置 [可选]

boardName

要测试的主板的名称。主板名称应该与 path/to/afr/source/code/vendors/vendor/boards/board 下的文件夹名称相同。

vendorName

所测试主板的供应商的名称。供应商名称应该与 path/to/afr/source/code/vendors/vendor 下的文件夹名称相同。

compilerName

编译器名称。

frToolchainPath

编译器工具链的全限定路径

cmakeToolchainPath

CMake 工具链的全限定路径。此字段为可选项

注意

要执行 CMake 测试案例,您必须提供主板名称、供应商名称和 afrToolchainPathcompilerName。如果您的 CMake 工具链使用自定义路径,则还需要提供 cmakeToolchainPath

适用于 FreeRTOS 的 IDT 变量

用于生成代码和刷写设备的命令可能需要连接或者有关设备的其他信息才能成功运行。AWS IoT Device Tester 允许您使用 JsonPath,在刷写和构建命令中引用设备信息。通过使用简单 JsonPath 表达式,您可以按照 device.json 文件中的指定内容提取所需的信息。

路径变量

适用于 FreeRTOS 的 IDT 定义了可在命令行和配置文件中使用的以下路径变量:

{{testData.sourcePath}}

扩展到到源代码路径。如果使用该变量,则必须在刷写和构建命令中使用该变量。

{{device.connectivity.serialPort}}

扩展到串行端口。

{{device.identifiers[?(@.name == 'serialNo')].value}}

扩展到您设备的序列号。

{{enableTests}}

整数值,指明构建适用于测试(值为 1)还是演示(值为 0)。

{{buildImageName}}

构建命令构建的映像的文件名。