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

# Xilinx Avnet MicroZed 工业 IoT 工具包入门
Xilinx Avnet MicroZed 工业 IoT 工具包

**重要**  <a name="deprecation-message"></a>
该参考集成托管在已弃用的 Amazon-FreeRTOS 存储库中。当您创建新项目时，我们建议[从此处开始](freertos-getting-started-modular.md)。如果您已经有一个基于现已弃用的 Amazon-FreeRTOS 存储库的 FreeRTOS 项目，请参阅 [Amazon-FreeRTOS Github 存储库迁移指南](github-repo-migration.md)。

该教程提供有关 Xilinx Avnet MicroZed 工业 IoT 工具包入门的说明。如果您没有 Xilinx Avnet MicroZed 工业 IoT 工具包，请访问 Amazon 合作伙伴设备目录来从我们的[合作伙伴](https://devices.amazonaws.com/detail/a3G0L00000AANtqUAH/MicroZed-IIoT-Bundle-with-Amazon-FreeRTOS)购买一个。

在开始之前，您必须配置 Amazon IoT 和 FreeRTOS 下载以将您的设备连接到 Amazon 云。有关说明，请参阅[初始步骤](freertos-prereqs.md)：在本教程中，FreeRTOS 下载目录的路径称为 `freertos`。

## 概览


本教程包含有关以下入门步骤的说明：

1. 将主板连接到主机。

1. 在主机上安装软件来开发和调试微控制器主板的嵌入式应用程序。

1. 将 FreeRTOS 演示应用程序交叉编译为二进制映像。

1. 将应用程序二进制映像加载到您的主板上，然后运行该应用程序。

## 设置 MicroZed 硬件


在设置 MicroZed 硬件时，下图可能会很有用：

![\[AVNet 微控制器板的示意图，图中突出显示了电源正常指示灯、用户指示灯以及按钮、JTAG 调试接口、10/100/1000 以太网和 USB 主机、microSD 卡槽、USB-UART、完成指示灯、复位按钮和启动模式跳线。\]](http://docs.amazonaws.cn/freertos/latest/userguide/images/microzed.png)


**设置 MicroZed 主板**

1. 将计算机连接到 MicroZed 主板上的 USB-UART 端口。

1. 将计算机连接到 MicroZed 主板上的 JTAG Access 端口。

1. 将路由器或连接 Internet 的以太网端口连接到 MicroZed 主板上的以太网和 USB-HOST 端口。

## 设置开发环境


要设置 MicroZed 工具包的 FreeRTOS 配置，您必须使用 Xilinx 软件开发工具包 (XSDK)。XSDK 在 Windows 和 Linux 上受支持。

### 下载并安装 XSDK


要安装 Xilinx 软件，您需要一个免费的 Xilinx 账户。

**下载 XSDK**

1. 转至[软件开发工具包独立 WebInstall 客户端](https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/embedded-design-tools/2019-1.html)下载页面。

1. 选择适合您的操作系统的选项。

1. 您将定向到 Xilinx 登录页。

   如果您拥有 Xilinx 账户，请输入您的登录凭证，然后选择**登录**。

   如果您没有账户，请选择 **Create your account (创建账户)**。注册后，您将收到一封电子邮件，其中包含用于激活您的 Xilinx 账户的链接。

1. 在 **Name and Address Verification (名称和地址验证)** 页面上，输入您的信息，然后选择 **Next (下一步)**。下载应可以开始了。

1. 保存 `Xilinx_SDK_version_os` 文件。

**安装 XSDK**

1. 打开 `Xilinx_SDK_version_os`文件。

1. 在 **Select Edition to Install (选择要安装的版本)** 中，选择 **Xilinx Software Development Kit (XSDK) (Xilinx 开发工具包 (XSDK))**，然后选择 **Next (下一步)**。

1. 在安装向导的以下页面上，在 **Installation Options (安装选项)** 下，选择 **Install Cable Drivers (安装电缆驱动程序)**，然后选择 **Next (下一步)**。

如果您的计算机未检测到 MicroZed 的 USB-UART 连接，请手动安装 CP210x USB-to-UART Bridge VCP 驱动程序。有关说明，请参阅 [Silicon Labs CP210x USB-to-UART 安装指南](https://www.xilinx.com/support/documentation/boards_and_kits/install/ug1033-cp210x-usb-uart-install.pdf)。

有关 XSDK 的更多信息，请参阅 Xilink 网站上的 [Xilinx 开发工具包入门](https://www.xilinx.com/html_docs/xilinx2018_2/SDK_Doc/index.html)。

## 在云上监控 MQTT 消息


在运行 FreeRTOS 演示项目之前，您可以在 Amazon IoT 控制台中设置 MQTT 客户端来监控您的设备发送到 Amazon 云的消息。

**使用 Amazon IoT MQTT 客户端订阅 MQTT 主题**

1. 登录 [Amazon IoT 控制台](https://console.amazonaws.cn/iotv2/)。

1. 在导航窗格中选择**测试**，然后选择 **MQTT 测试客户端**，以便打开 MQTT 客户端。

1. 在 **Subscription topic (订阅主题)**中，输入 ***your-thing-name*/example/topic**，然后选择 **Subscribe to topic (订阅主题)**。

## 构建并运行 FreeRTOS 演示项目


### 在 XSDK IDE 中打开 FreeRTOS 演示


1. 启动 XSDK IDE 并将工作区目录设置为 `freertos/projects/xilinx/microzed/xsdk`。

1. 关闭欢迎页面。从菜单中，选择 **Project (项目)**，然后清除 **Build Automatically (自动构建)**。

1. 从菜单中，选择 **File (文件)**，然后选择 **Import (导入)**。

1. 在 **Select (选择)** 页面上，展开 **General (常规)**，选择 **Existing Projects into Workspace (现有项目到工作区)**，然后选择 **Next (下一步)**。

1. 在 **Import Projects (导入项目)** 页面上，选择 **Select root directory (选择根目录)**，然后输入演示项目的根目录：`freertos/projects/xilinx/microzed/xsdk/aws_demos`要浏览目录，请选择 **Browse (浏览)**。

   在指定一个根目录后，该目录中的项目将显示在 **Import Projects (导入项目)** 页面上。默认情况下，将选择所有可用项目。
**注意**  
如果 **Import Projects (导入项目)** 页面顶部显示一条警告（“Some projects cannot be imported because they already exist in the workspace (由于一些项目已在工作区中存在，因此无法导入这些项目)。”），您可以忽略它。

1. 选定所有项目后，选择 **Finish (完成)**。

1. 如果在项目窗格中看不到 `aws_bsp`、`fsbl` 和 `MicroZed_hw_platform_0` 项目，请从 \$13 开始重复上述步骤（但根目录设置为 `freertos/vendors/xilinx`），然后导入 `aws_bsp`、`fsbl` 和 `MicroZed_hw_platform_0`。

1. 从文件菜单中，选择 **Window (窗口)**，然后选择 **Preferences (首选项)**。

1. 在导航窗格中，展开 **Run/Debug (运行/调试)**，选择 **String Substitution (字符串替换项)**，然后选择 **New (新建)**。

1. 在 **New String Substitution Variable (新字符串替换变量)** 中，对于 **Name (名称)**，输入 **AFR\$1ROOT**。对于 **Value (值)**，输入 `freertos/projects/xilinx/microzed/xsdk/aws_demos` 的根路径。选择 **OK (确定)**，然后选择 **OK (确定)** 以保存变量并关闭 **Preferences (首选项)**。

### 构建 FreeRTOS 演示项目


1. 在 XSDK IDE 中，从菜单中选择 **Project (项目)**，然后选择 **Clean (清理)**。

1. 在 **Clean (清理)** 中，将选项保留其默认值，然后选择 **OK (确定)**。XSDK 将清理和构建所有项目，然后生成 `.elf` 文件。
**注意**  
要构建所有项目而不进行清理，请选择 **Project (项目)**，然后选择 **Build All (全部构建)**。  
要构建单个项目，请选择要构建的项目，选择 **Project (项目)**，然后选择 **Build Project (构建项目)**。

### 为 FreeRTOS 演示项目生成启动映像


1. 在 XSDK IDE 中，右键单击 **aws\$1demos**，然后选择 **Create Boot Image (创建启动映像)**。

1. 在 **Create Boot Image (创建启动映像)** 中，选择 **Create new BIF file (创建新的 BIF 文件)**。

1. 在 **Output BIF file path (输出 BIF 文件路径)** 的旁边，选择 **Browse (浏览)**，然后选择 `aws_demos.bif`（位于 `<freertos>/vendors/xilinx/microzed/aws_demos/aws_demos.bif` 中）。

1. 选择**添加**。

1. 在 **Add new boot image partition (添加新的启动映像分区)** 上，在 **File path (文件路径)** 的旁边，选择 **Browse (浏览)**，然后选择 `fsbl.elf`（位于 `vendors/xilinx/fsbl/Debug/fsbl.elf` 中）。

1. 对于 **Partition type (分区类型)**，选择 **bootloader**，然后选择 **OK (确定)**。

1. 在 **Create Boot Image (创建启动映像)** 上，选择 **Create Image (创建映像)**。在 **Override Files (覆盖文件)** 上，选择 **OK (确定)** 以覆盖现有 `aws_demos.bif` 并生成 `BOOT.bin` 文件（位于 `projects/xilinx/microzed/xsdk/aws_demos/BOOT.bin` 中）。

### JTAG 调试


1. 将您的 MicroZed 主板的启动模式跳线设置为 JTAG 启动模式。  
![\[电路板插针连接器和跳线设置。\]](http://docs.amazonaws.cn/freertos/latest/userguide/images/xilinx-jtag.png)

1. 将您的 MicroSD 卡插入位于 USB-UART 端口正下方的 MicroSD 卡槽。
**注意**  
在调试之前，请确保已对 MicroSD 卡上的所有内容进行备份。

   您的主板应与下图类似：  
![\[带连接选项的 FreeRTOS 评估板。\]](http://docs.amazonaws.cn/freertos/latest/userguide/images/xilinx-jtag-full-board.png)

1. 在 XSDK IDE 中，右键单击 **aws\$1demos**，选择 **Debug As (调试方式)**，然后选择 **1 Launch on System Hardware (System Debugger) (1 在系统硬件上启动 (系统调试程序))**。

1. 当调试程序在 `main()` 中的断点停止时，从菜单中选择 **Run (运行)**，然后选择 **Resume (恢复)**。
**注意**  
第一次运行应用程序时，将在非易失性存储器中导入新的证书密钥对。对于后续运行，您可以先在 `vDevModeKeyProvisioning()` 文件中注释 `main.c`，然后再重新构建映像和 `BOOT.bin` 文件。这将阻止每次运行时将证书和密钥复制到存储中。

您可以选择从 MicroSD 卡或 QSPI 闪存启动 MicroZed 主板以运行 FreeRTOS 演示项目。有关说明，请参阅[为 FreeRTOS 演示项目生成启动映像](#xilinx-build-boot-image)和[运行 FreeRTOS 演示项目](#xilinx-run)。

### 运行 FreeRTOS 演示项目


要运行 FreeRTOS 演示项目，您可以从 MicroSD 卡或 QSPI 闪存启动 MicroZed 主板。

在设置 MicroZed 主板以运行 FreeRTOS 演示项目时，请参考[设置 MicroZed 硬件](#xilinx-setup-hardware)中的演示图。确保已将 MicroZed 主板连接到计算机。

#### 从 MicroSD 卡启动 FreeRTOS 项目


格式化 Xilinx Avnet MicroZed 工业 IoT 工具包附带的 MicroSD 卡。

1. 将 `BOOT.bin` 文件复制到 MicroSD 卡中。

1. 将卡插入位于 USB-UART 端口正下方的 MicroSD 卡槽。

1. 将 MicroZed 启动模式跳线设置为 SD 启动模式：  
![\[带有三个插槽（分别标为 JP1、JP2 和 JP3）和一个纽扣电池座的 SD 卡。\]](http://docs.amazonaws.cn/freertos/latest/userguide/images/xilinx-sd.png)

1. 按 RST 按钮以重置设备并开始启动应用程序。您也可以从 USB-UART 端口拔出 USB-UART 电缆，然后重新插入该电缆。

#### 从 QSPI 闪存启动 FreeRTOS 演示项目


1. 将您的 MicroZed 主板的启动模式跳线设置为 JTAG 启动模式。  
![\[电路板插针连接器和跳线设置。\]](http://docs.amazonaws.cn/freertos/latest/userguide/images/xilinx-jtag.png)

1. 确认您的计算机已连接到 USB-UART 和 JTAG Access 端口。绿色电源正常 LED 指示灯应亮起。

1. 在 XSDK IDE 中，从菜单中选择 **Xilinx**，然后选择 **Program Flash (对闪存编程)**。

1. 在 **Program Flash Memory (对闪存编程)** 中，应自动填充硬件平台。对于 **Connection (连接)**，选择 MicroZed 硬件服务器以将主板连接到主机。
**注意**  
如果您使用的是 Xilinx Smart Lync JTAG 电缆，则必须在 XSDK IDE 中创建硬件服务器。选择 **New (新建)**，然后定义您的服务器。

1. 在 **Image File (映像文件)** 中，输入 `BOOT.bin` 映像文件的目录路径。选择 **Browse (浏览)** 以改为浏览文件。

1. 在 **Offset (偏移量)** 中，输入 **0x0**。

1. 在 **FSBL File (FSBL 文件)** 中，输入 `fsbl.elf` 文件的目录路径。选择 **Browse (浏览)** 以改为浏览文件。

1. 选择 **Program (编程)** 以对主板编程。

1. 在 QSPI 编程完成后，拔掉 USB-UART 电缆以使主板断电。

1. 将您的 MicroZed 主板的启动模式跳线设置为 QSPI 启动模式：

1. 将卡插入位于 USB-UART 端口正下方的 MicroSD 卡槽。
**注意**  
确保已对 MicroSD 卡上的所有内容进行备份。

1. 按 RST 按钮以重置设备并开始启动应用程序。您也可以从 USB-UART 端口拔出 USB-UART 电缆，然后重新插入该电缆。

## 故障排除


如果您遇到与错误路径相关的构建错误，请尝试清理并重新构建项目，如[构建 FreeRTOS 演示项目](#xilinx-freertos-build-project)中所述。

如果您使用的是 Windows，请确保在 Windows XSDK IDE 中设置字符串替代变量时使用正斜杠。

有关 FreeRTOS 入门的常规故障排除信息，请参阅[问题排查入门](gsg-troubleshooting.md)。