# <span id="system_update"/> 系统镜像烧写

## 概述

系统烧录是将操作系统、应用程序及相关数据写入开发板的存储设备（例如 eMMC 或 NAND Flash），以确保其能够正常运行的过程。该过程主要包括以下几个关键步骤：

1. **准备镜像文件**：

   BSP 必须编译并打包成镜像文件，包括 Bootloader、操作系统和应用程序等内容。有关如何生成镜像文件的详细信息，请查阅 [BSP 开发指南 - 搭建开发环境及编译说明](../linux_development/bsp_develop.md)。

2. **连接开发板**：

   首先，需要使用 USB 或以太网将开发板与计算机连接。

   在特定情况下，可能需要通过串口连接，以便将开发板置于特定模式（例如，直接从存储介质启动或将部分启动镜像通过串口下载到内存中运行），以完成 USB 或以太网的初始化。

3. **选择烧录工具**：

   烧录工具用于将镜像文件写入开发板的存储设备，根据用户需求和操作系统环境的不同，可选择以下几种工具：

   - 图形化工具：`XBurn`

     `XBurn` 提供了直观的图形界面，适合希望通过简单操作完成烧录任务的用户。用户只需点击几步即可完成镜像烧录，非常便捷。

     - **特点**：易于操作，界面友好。
     - **使用说明**：请参阅 [图形化工具烧录介绍](#span-id-xburn)。

   - 命令行工具：`xburn`

     对于更高级或定制化的烧录需求，可以选择 `xburn` 工具。该工具支持通过手动编辑 JSON 配置文件或利用图形化工具生成配置文件后运行命令完成烧录。

     - **特点**：灵活性高，适合需要批量处理或脚本化操作的用户。
     - **使用说明**：请参阅 [命令行工具介绍](#span-id-xburn-cmd)。

   - 手动烧录方式

     对于某些特殊情况或更高自由度的需求，用户可以选择手动方式完成镜像烧录。

     - **特点**：完全自定义操作流程，适合特定开发或调试场景。
     - **使用说明**：请参阅 [手动烧录工具介绍](#span-id-manual)。

4. **设置烧录参数**：

   在烧录工具的图形界面中，需要设置烧录参数，包括目标设备类型、镜像文件路径和烧录方式等。这些参数将直接影响烧录的结果和过程。

5. **执行烧录操作**：

   烧录参数设置完成后，开始执行烧录操作。烧录工具将逐字节地将镜像文件中的数据写入开发板的存储设备（ eMMC 或 NAND Flash），确保操作系统和应用程序能够正确加载。

6. **验证烧录结果**：

   系统烧录完成后，烧录结束后，需进行验证以确保烧录成功。可以通过开发板的串口输出或其他调试接口，检查系统是否能够正确启动，以及应用程序是否能够正常运行。

本章节旨在提供如何使用 `XBurn` 图形化工具、命令行工具以及手动烧录工具的详细操作方法与注意事项。

## 固件烧录协议简介

在本手册的[连接开发板](./connect_board.md)章节中已详细说明串口、网口及USB接口的连接方法。固件烧录过程同样依赖这三类物理接口，并对应三种核心协议：

| 协议       |  <center> 概述 </center>  |       <center> 特点 </center>    | <center> 适用场景 </center>   |
|:------------:|--------------------------|----------------------------------|------------------------------|
| **DFU**    | DFU(Device Firmware Upgrade) 是一种固件更新协议，通常用于设备进入特定的恢复模式，以便通过 USB 连接烧录固件。它在嵌入式系统中广泛应用，尤其适用于设备无法正常启动或处于空板状态时的固件下载。 | 支持低层次的烧录操作，通常用于恢复和初次烧写固件，通常用于与硬件之间的低级交互，不依赖操作系统。 | 设备完全未启动或处于空板状态时，适合通过 USB 进行固件下载和烧录。 |
| **Xmodem** | Xmodem 是一种串口通信协议，最初用于文件传输，常用于通过串口（如 UART）进行固件下载。具有错误检测和自动重传机制，确保传输过程的可靠性。 | 适用于串口连接，通常用于固件的小规模传输，速度相对较慢，但可靠性较高，适用于低带宽或低速环境。 | 常用于设备的初始引导程序（如 BL2、BL3x）的下载，特别是在无法进入高级引导模式时，适合串口传输固件。 |
| **Fastboot** | Fastboot 是一种快速启动下载协议，通过 USB 连接设备并进入引导模式进行快速固件下载。 | 高速固件烧录工具，支持设备快速更新和修复，直接通过设备的 bootloader 进入 fastboot 模式。       | 设备启动后进入 fastboot 模式，适用于已经有基本引导程序的设备，常用于更新系统镜像或固件。     |

## <span id="xburn"/> 图形化工具烧录介绍

XBurn-gui工具集提供丰富的图形化界面，如下:

### 烧录工具界面简介

#### 烧录界面

![img](./_static/_images/update_system_firmware/XBurn_gui_1.png)

说明如下：

- **基本配置**：

   ![img](./_static/_images/update_system_firmware/XBurn_gui_base_config.png)

    1. **产品类型：**
       请选择您要烧录设备的对应产品类型。  
       - 每种产品类型对应一种特定的硬件型号或配置（例如 X5 、 RDKS100 等）。  
       - 请确保选择与设备实际型号一致的选项，以确保刷入的固件与设备兼容，从而避免刷机失败。

    2. **连接类型：**
       请选择设备与主机通信的连接方式，支持串口、 USB 和网口三种方式。  
       - 可以组合使用不同的连接方式，例如串口 +USB，以满足不同的刷机需求。  
       - 连接类型的选择会直接影响刷机过程中的下载模式。  
       - 每种连接方式对应的协议和操作方法可能不同，请根据目标设备的兼容性和使用场景选择合适的连接方式。

    3. **下载模式：**
       根据所选设备的连接类型，系统会自动匹配适用的下载模式。常用的下载模式如下：

       - **fastboot（推荐）：**  
         - 连接类型： USB  
         - 适用于非空板设备，能够实现快速烧录，速度最快。

       - **dfu_fastboot（空板烧录）：**  
         - 连接类型： USB  
         - 适用于空板设备，进行整机烧录。需手动拨码使设备进入 DFU 引导模式，速度较快。

       - **xmodem_fastboot（空板/调试优选）：**  
         - 连接类型：串口 +USB  
         - 适用于空板和非空板设备，支持边烧录边查看日志，适合调试，烧录速度适中。

       - **xmodem_xmodem（应急方案）：**  
         - 连接类型：纯串口  
         - 适用于空板设备，当 USB 和网口功能均异常时可选，只适合烧录小镜像（如 miniboot_all， uboot 等），速度较慢（ 3-10KB/s）。

       - 其他下载模式的详细使用说明，请参考[烧录方式简介](./update_system_firmware.html#span-id-xburn-download-function)章节中的表格。

    4. **镜像文件目录：**  
       请选择要烧录的镜像文件所在的目录。

    5. **批量烧录数量：**  
       设置同时烧录的设备数量。根据电脑性能、硬件连接类型的带宽等因素，合理设置烧录设备数量。  
      **建议最多同时烧录 8 台设备。**

- **高级配置**：
  - **启用分区备份/还原功能**：勾选后，会在烧录前备份分区信息，在烧录后还原分区信息。
  - **烧录指定分区镜像**：勾选后，会烧录指定分区镜像，不勾选则会烧录完整的包含所有分区的镜像。
  - **全盘擦除 eMMC**：勾选后，会在烧录前对 eMMC 进行全盘擦除，耗时较长，请耐心等待。
  - **烧录完成后自动重启**：勾选后，会在烧录完成后自动重启设备。
  - **启用 USB 3.0模式**：勾选后，会使用 USB3.0 接口烧录，默认使用 USB2.0 接口。
  - 详细使用说明请参考[高级配置](./update_system_firmware.html#span-id-advanced-configuration)章节

- **操作按钮**：
  - **恢复默认配置**：恢复到默认设置。
  - **开始升级**：开始烧录操作。

#### 设置界面

![img](./_static/_images/update_system_firmware/XBurn_gui_2.png)

该界面用于设置日志级别，控制日志的输出级别。

- **日志级别**：选择日志的输出级别（例如信息、调试）。

#### 驱动界面

![img](./_static/_images/update_system_firmware/XBurn_gui_3.png)

该界面用于查看和管理驱动程序的状态。

- **驱动名称**：列出已安装的驱动程序名称（例如 USB Driver (ADB, Fastboot, DFU) 和 USB to Serial Driver (CH341)）。
- **当前版本**：显示驱动程序的当前版本。
- **操作**：提供安装和卸载驱动程序的按钮。
- **扫描驱动**：提供扫描驱动程序的按钮，用于检测和安装新的驱动程序。

### <span id="xburn_download_function"/>烧录方式简介

XBurn-gui工具支持的烧录方式如下：

|       连接类型   |    下载模式      |   接线方式     | <center> 烧录步骤说明 </center>|  <center> 备注 </center>  |
| :-------------: | :--------------: | :-----------: | ----------  | -------------------------|
|       USB       |   DFU+Fastboot   |   单 USB 线连接   | 1. 将单板设置为 DFU 启动模式（**将拨码开关 D5 置零， 拨码开关 D[2:0] 置为 010**）下载 `BL2` 和 `BL3x` 至设备并引导至 U-Boot 命令模式。<br>2. 在 U-Boot 下执行 `fastboot 0` 进入 Fastboot 模式。<br>3. 使用 Fastboot 通过 USB 烧写完整镜像。<br>4. 烧录完成将拨码开关改回正常启动模式，如 EMMC 启动模式（**将 D[5][2:0] 置为1001**）。                                                                                |           · 支持空板状态烧录<br>· 需要在上电一分钟内点击 `开始升级` 按钮进行升级，否则会因为 DFU 超时而升级失败          |
|       USB       |     Fastboot     |   单 USB 线连接   | 1. 非空板状态下，确保设备可进入 U-Boot 命令模式，执行 `fastboot 0` 进入 Fastboot 模式：<br>   a. 若设备已在 Fastboot 模式，直接烧录。<br>   b. 否则，若有 ADB 连接 (adb devices)，如果存在 adb devices，通过 `adb shell` 进入单板终端，然后执行 `reboot -m usb2 -f` 使设备进入到 fastboot 模式。<br>2. 使用 Fastboot 通过 USB 烧写完整镜像。 |          · 仅支持非空板状态烧录         |
|    Serial+USB   |     Fastboot     | 串口线 + USB 线连接 | 1. 非空板状态下，板端通过串口进入 U-Boot 命令模式，执行 `fastboot 0` 并进入 Fastboot 模式。<br>2. 使用 Fastboot 通过 USB 烧写完整镜像。                                                                                                                        |          · 仅支持非空板状态烧录         |
|    Serial+USB   |  Xmodem+fastboot | 串口线 + USB 线连接 | 1. 通过串口使用 Xmodem 协议下载 `BL2` 和 `BL3x` 至设备并引导至 U-Boot 命令模式。<br>2. 在 U-Boot 下执行 `fastboot 0` 进入 Fastboot 模式。<br>3. 使用 Fastboot 通过 USB 烧写完整镜像。                                                                          |           · 支持空板状态烧录<br>· 推荐将串口波特率设置为 921600 （拨码开关 D4 置 1）          |
|    Serial+USB   |    Xmodem+DFU    | 串口线 + USB 线连接 | 1. 通过串口使用 Xmodem 协议下载 `BL2` 和 `BL3x` 至设备并引导至 U-Boot 命令模式。<br>2. 进入 U-Boot 命令模式执行 `dfu 0` 命令进入 DFU 模式。<br>3. 使用 DFU 通过 USB 烧写完整镜像。                                                                                   |           · 支持空板状态烧录<br>· 推荐将串口波特率设置为 921600 （拨码开关 D4 置 1）          |
|    Serial+USB   |        DFU       | 串口线 + USB 线连接 | 1. 非空板状态下，板端通过串口进入 U-Boot 命令模式并执行 `dfu 0` 命令进入 DFU 模式。<br>2. 使用 DFU 通过 USB 烧写完整镜像。                                                                                                                                      |          · 仅支持非空板状态烧录         |
| Serial+Ethernet | xmodem+fastboot |   串口线 + 网线连接  | 1. 通过串口使用 Xmodem 协议下载 `BL2` 和 `BL3x` 至设备并引导至 U-Boot 命令模式。<br>2. 在 U-Boot 下执行 `fastboot udp 0` 命令启动 `Fastboot UDP` 服务。<br>3. 在主机端使用 fastboot 的 UDP 模式烧写完整镜像。                                                           |           · 支持空板状态烧录<br>· 推荐将串口波特率设置为 921600 （拨码开关 D4 置 1）          |
| Serial+Ethernet |     fastboot     |   串口线 + 网线连接  | 1. 非空板状态下，通过串口进入 U-Boot 命令模式并执行 `fastboot udp 0` 启动 `Fastboot UDP` 服务。<br>2. 在主机端使用 fastboot 的 UDP 模式烧写完整镜像。                                                                                                              |          · 仅支持非空板状态烧录         |
|      Serial     |  xmodem+xmodem  |     单串口线连接    | 1. 通过串口使用 Xmodem 协议下载 `BL2` 和 `BL3x` 至设备并引导至 U-Boot 命令模式。<br>2. 继续在 U-Boot 下使用串口协议（如 `loady`, `loadx`）下载镜像并烧录。<br>                                                                                                      |  · 支持空板状态烧录<br>· 仅推荐用于小尺寸镜像的烧录<br>· 推荐将串口波特率设置为 921600 （拨码开关 D4 置 1）   |
|      Serial     |      xmodem      |     单串口线连接    | 1. 非空板状态下，通过串口进入 U-Boot 命令模式并使用串口协议（如 `loady`, `loadx`）下载镜像并烧录。<br>2. 下载烧录操作均通过串口进行。                                                                                                                                        | · 仅支持非空板状态烧录<br>· 仅推荐用于小尺寸镜像的烧录<br>· 推荐将串口波特率设置为 921600 （拨码开关 D4 置 1）  |

**注意**：在上述所有使用 Xmodem 协议的下载模式中，推荐将串口波特率改为 921600bps （将拨码开关的 D4 置 1），以提高烧录速度。

### 烧录工具安装与启动说明

#### windows 系统下安装与启动 XBurn

双击安装包 `xburn-gui_1.1.5_x64-setup.exe` 即可进行安装，具体安装步骤如下：

1. 点击 `Next`：

   ![img](./_static/_images/update_system_firmware/XBurn_windows_install_1.png)

2. 选择 `Add/Reinstall components`，然后点击 `Next`：

   ![img](./_static/_images/update_system_firmware/XBurn_windows_install_2.png)

3. 点击 `Browse` 选择安装路径：

   ![img](./_static/_images/update_system_firmware/XBurn_windows_install_3.png)

   **提示**：建议将软件安装到硬盘分区根目录（如 D:\xburn-gui），以便于查找日志文件。

4. 点击 `Install` 进行安装：

   ![img](./_static/_images/update_system_firmware/XBurn_windows_install_4.png)

5. 待进度条满，且出现 `Setup was completed successfully.` 即说明安装成功，此时点击 `Next`：

   ![img](./_static/_images/update_system_firmware/XBurn_windows_install_5.png)

6. 勾选 `Run xburn-gui` 以及 `Create desktop shortcut`，然后点击 `Finish` 完成安装：

   ![img](./_static/_images/update_system_firmware/XBurn_windows_install_6.png)

7. 安装完成后，XBurn-gui界面随后会自动打开：

   ![img](./_static/_images/update_system_firmware/XBurn_windows_install_7.png)

8. 后续可以直接双击桌面上的 `XBurn.exe` 图标即可启动软件。

#### Ubuntu 系统下安装与启动 XBurn

在安装包目录中执行 `sudo dpkg -i xburn-gui_1.1.5_amd64.deb ` 命令即可等待完成安装，安装示例如下：

```bash
(base) hobot@hobot-ThinkPad-T14-Gen-1:~/tools$ sudo dpkg -i xburn-gui_1.1.5_amd64.deb 
[sudo] hobot 的密码： 
正在选中未选择的软件包 xburn-gui。
(正在读取数据库 ... 系统当前共安装有 494898 个文件和目录。)
准备解压 xburn-gui_1.1.5_amd64.deb  ...
正在解压 xburn-gui (1.1.5) ...
正在设置 xburn-gui (1.1.5) ...
Udev rules installed and activated
User nobody added to plugdev group
User hobot added to plugdev group
User snapd-range-524288-root added to plugdev group
User snap_daemon added to plugdev group
User xpj added to plugdev group
正在处理用于 mailcap (3.70+nmu1ubuntu1) 的触发器 ...
正在处理用于 gnome-menus (3.36.0-1ubuntu3) 的触发器 ...
正在处理用于 desktop-file-utils (0.26-1ubuntu3) 的触发器 ...
正在处理用于 hicolor-icon-theme (0.17-2) 的触发器 ...
```

然后执行 `sudo xburn-gui` 命令或者在应用菜单中点击 `xburn-gui` 图标（会弹出输入密码的提示），输入密码即可打开烧录工具界面：

![img](./_static/_images/update_system_firmware/XBurn_ubuntu_install.png)

#### MAC 系统下安装与启动 XBurn

双击安装包 `xburn-gui_1.1.5_universal.dmg` 即可进行安装，具体安装步骤如下：

1. 随即会出现一个弹窗，单击并按住 `xburn-gui` 图标拖到 `Applications` 图标中：

   ![img](./_static/_images/update_system_firmware/XBurn_mac_install_1.png)

   ![img](./_static/_images/update_system_firmware/XBurn_mac_install_2.png)

   ![img](./_static/_images/update_system_firmware/XBurn_mac_install_3.png)

2. `xburn-gui` 便装完成，此时可以双击 `xburn-gui` 的图标来打开该程序：

   ![img](./_static/_images/update_system_firmware/XBurn_mac_install_4.png)

3. 安装过程中若遇到提示缺少一些依赖，需要先安装相应的依赖。

#### 启动时的常见问题

一些常见问题以及解决方案见[FAQ：常见错误对照表](#FAQ)。

### 烧录方式选取说明

连接类型与下载模式的详细说明可以参考[烧录方式简介](./update_system_firmware.html#span-id-xburn-download-function)章节中的表格，本小节重点说明：

1. 存储介质中的镜像为空或者已经损坏，设备已变砖（Bricked Device）；
2. 存储介质中的镜像正常，设备可以正常启动。

这两种情况下**使用烧录软件**的烧录方式的选取。

#### 镜像为空或已损坏时下载模式的选取

镜像为空或已损坏时，板端无法进入 U-Boot，此时仅有 BL1 的镜像，需要将 BL2 镜像以及 BL3X 镜像烧录到板端，烧录这两个镜像可以通过下面模式：

1. 使用 [DFU](./connect_board.html#span-id-use-dfu-dfu) 下载模式：
   - 硬件需具备启动拨码开关，且该拨码开关已设置为 USB 启动模式；
   - 硬件中 BOOT CONFIG 中 DFU 位（一般是 D5 位）需要接地（DFU 置零），如果单板上有拨码开关控制 DFU 则将拨码开关拨为 0；若没有拨码开关控制 DFU 位，则需要根据实际硬件电路拆/装 DFU 位的电阻；
   - 当存储介质中的镜像不存在或已损坏时，可以采用此选项进行升级。  
    USB 启动模式需要将拨码开关设置为如下状态：

      ![USB_Download_Mode](./_static/_images/update_system_firmware/USB_Download_Mode.png)

2. 使用 Xmodem 下载模式：
   - 当存储介质中的镜像不存在或已损坏时，可以采用此选项进行升级；
   - 建议在 Xmodem 下载模式下，对于 X5 EVB 可以将拨码开关的 D4 置 1 （将串口波特率改为 921600bps），这样可以极大地加快烧录速度。  
    Xmodem 启动模式需要将拨码开关设置为如下状态：

      ![UART_Download_Mode](./_static/_images/update_system_firmware/UART_Download_Mode.png)

#### 镜像正常时下载模式的选取

存储设备中镜像正常时可以选取 `Fastboot 下载模式`，该模式需要开发板可以正常进入 U-Boot 命令行：

- 若硬件不具备启动拨码开关，请确保存储介质中存在可正常启动的软件，无需其他操作；
- 若硬件具备启动拨码开关，请确保拨码配置设置为可以正常启动的状态。

<a id="Default_mode"></a>
默认的启动模式为 EMMC 启动，此时拨码开关状态如下：

![EMMC_Download_Mode](./_static/_images/update_system_firmware/EMMC_Download_Mode.png)

其他启动模式可以参考[拨码开关](./x5_evb_1_b_user_guide.html#span-id-dip-switch)章节中的拨码真值表。

注意：在存储介质中软件不存在或已损坏的情况下， X5 芯片将自动切换至 USB 启动模式。

### <span id="USB_mode_upgrade"/> USB 连接方式升级过程说明

**前提条件：**

- 请查阅 [通过 USB 连接](connect_board.html#span-id-connect-by-usb-usb) 完成 USB 驱动的安装。

**适用范围：**

USB 连接方式当前支持 Fastboot、DFU+Fastboot 下载模式。

- **DFU+Fastboot 下载模式**
  - DFU+Fastboot 烧录模式适用于 **开发板上没有可用镜像或镜像已损坏** 的场景，此时需要使用 `out/product/uart_usb` 中的镜像。
  - **有启动拨码器的开发板** 并通过启动拨码开关 **配置启动方式为 USB** 的场景。
  - **需要注意**：本模式需要在上电一分钟内点击 `开始升级` 按钮进行升级，否则会因为 DFU 超时而升级失败。
  - 烧录步骤如下：
    1. 将单板设置为 DFU 启动模式（**将拨码开关 D5 置零， 拨码开关 D[2:0] 置为 010**）下载 BL2 和 BL3x 至设备并引导至 U-Boot 命令模式。
    2. 在 U-Boot 下执行 `fastboot 0` 进入 Fastboot 模式。
    3. 使用 Fastboot 通过 USB 烧写完整镜像。
    4. 烧录完成将拨码开关改回正常启动模式，如 EMMC 启动模式（将 D[5][2:0] 置为1001）。

- **Fastboot 下载模式**
  - Fastboot 下载模式仅适用于非空板状态烧录。
  - 烧录步骤如下：
      1. 非空板状态下，确保设备可进入 U-Boot 命令模式，执行 fastboot 0 进入 Fastboot 模式：
         - I. 若设备已在 Fastboot 模式，直接烧录。
         - II. 否则，若有 ADB 连接 (adb devices)，如果存在 adb devices，通过 `adb shell` 进入单板终端，然后执行 `reboot -m usb2 -f` 使设备进入到 fastboot 模式:

            ```bash
            # Windows PowerShell terminal
            PS C:\Users\xiangqing.shi> adb devices
            List of devices attached
            0x30811a620a494c0f035cefd80000  device

            PS C:\Users\xiangqing.shi> adb shell
            sh-5.1# reboot -m usb2 -f
            ```

         - III. 操作前，如果板端有接入串口，此时可以看到串口日志：

            ```bash
            # board serial terminal
            U-Boot 2022.10-g64e3056741 (Jun 18 2025 - 21:44:29 +0800)

            Model: Horizon X5
            DRAM:  3.9 GiB
            console out start addr:0x0000000087ffc000, end addr:0x0000000087ffe000
            horizon_lsio_pinctrl lsio_iomuxc@34180000: Initialized D-Robotics pinctrl driver
            optee optee: OP-TEE: revision 3.20 (a3b65462)
            ADC calibration: -22
            ADC trimming: 9
            horizon_hsio_pinctrl hsio_iomuxc@35050000: Initialized D-Robotics pinctrl driver
            horizon_dsp_pinctrl dsp_iomuxc@31040014: Initialized D-Robotics pinctrl driver
            Core:  149 devices, 29 uclasses, devicetree: separate
            WDT:   Started watchdog@34250000 with servicing (10s timeout)
            stop watchdog
            MMC:   sdio-host@35040000: 0, sdio-host@35020000: 1
            Loading Environment from MMC... (Tuning Ok!) *** Warning - bad CRC, using default environment

            In:    serial@32120000
            Out:   serial@32120000
            Err:   serial@32120000
            Net:   
            Warning: gmac-tsn@35010000 (eth0) using random MAC address - 92:d9:1f:90:d1:8d
            eth0: gmac-tsn@35010000
            boot action: FASTBOOT USB2.0
            select emmc(0) as flash medium
            do fastboot usb
            ```

      2. 使用 Fastboot 通过 USB 烧写完整镜像。

<a id="USB_mode_wiring"></a>
**接线示意图：**

![USB_UP](./_static/_images/update_system_firmware/USB_UP.jpg)

**USB 连接类型烧录说明：**

以 DFU+Fastboot 下载模式为例对 XBurn-gui烧录工具的使用进行说明。

烧录之前，需要配置启动方式为 USB 启动（将拨码开关 D5 置零， 拨码开关 D[2:0] 置为 010，如果开发板没有拨码开关，需要临时修改硬件电路），此时，板端如果有连接串口，可以在串口终端看到下面日志：

```bash
SNOTICE:  Welcome to Horizon X5 ASIC BOOTROM - V4.1
NOTICE:                 OTP config:
NOTICE:                         otp exist: true
NOTICE:                         test region size: 304
NOTICE:                         secure region size: 120
NOTICE:                         none secure region size: 56
NOTICE:   Enable MMU 
NOTICE:  Booting Trusted Firmware
NOTICE:  BL1: v2.8(release):
NOTICE:  BL1: Built : 17:42:12, Oct 19 2023
NOTICE:  Enter USB2 Mode......
NOTICE:  Currtenly use dfu-util to download file
NOTICE:  Download file via USB
NOTICE:  DFU Start...
```

XBurn-gui烧录工具界面配置如下：

![img](./_static/_images/update_system_firmware/XBurn_USB_DFU_Fastboot_dl.png)

**步骤1：**

选择产品类型。点击在`产品类型`选项列表中，选择型号为 `X5`。

**步骤2：**

选择连接类型。点击`选择连接类型`选项列表，选择 `USB`。

**步骤3：**

选择下载模式。点击`下载模式`选项列表，选择 `DFU+Fastboot` 模式。

**步骤4：**

选择待烧录镜像的目录。点击`浏览`，选择镜像文件所在的目录，通常为系统编译后生成的 out/product 目录，如  `S:\home\sxq\projects\sdk_x5_CS1.0\out\product`。

**步骤5：**

开始烧录。将开发板上电，然后点击`开始升级`，工具将开始烧录。当进度条显示 100% 时，表示升级成功。

![img](./_static/_images/update_system_firmware/XBurn_USB_DFU_Fastboot_dl_end.png)

**步骤6：**

烧录完成将拨码开关改回正常启动模式，如 EMMC 启动模式（将 D[5][2:0] 置为1001）。

<a id="dfu_timeout"></a>
**注意**：点击`开始升级` 按钮需要在单板上电 **1 分钟内**完成，否则单板会因为超时退出 DFU 状态，此时会进入等待 Xmodem 文件传输状态，此时烧录软件一般会报错如下：

```bash
[Burn thread-1][20:09:55] [WARNING] Minimum dfu device detect timeout is 30s!
[Burn thread-1][20:09:55] [INFO] Executing 'tools/windows/dfu-util.exe -l', waiting for 60 seconds for execution to finish...
dfu-util 0.11
......
Determining device status...
error get_status: LIBUSB_ERROR_PIPE
[Burn thread-1][20:09:58] [ERROR] DFU download 'S:\home\sxq\projects\sdk_x5_CS1.0\out\product\uart_usb/bl2_usb2_ddr.bin' failed
......
[Burn thread-1][20:09:58] [ERROR] Step 'dfu_boot' failed
[Burn thread-1][20:09:58] [ERROR] Board-1, burn failed
[Burn thread-1][20:09:58] [ERROR] Board-1 [UID: 1-2.2] [Storage: emmc] Status: FAILED
Process terminated, exit code: 0
```

如果在执行 USB 升级过程中同时接入了串口，打开串口终端可以看到如下日志：

```bash
NOTICE:  Welcome to Horizon X5 ASIC BOOTROM - V4.1
NOTICE:                 OTP config:
NOTICE:                         otp exist: true
NOTICE:                         test region size: 304
NOTICE:                         secure region size: 120
NOTICE:                         none secure region size: 56
NOTICE:   Enable MMU 
NOTICE:  Booting Trusted Firmware
NOTICE:  BL1: v2.8(release):
NOTICE:  BL1: Built : 17:42:12, Oct 19 2023
NOTICE:  Enter USB2 Mode......
NOTICE:  Currtenly use dfu-util to download file
NOTICE:  Download file via USB
NOTICE:  DFU Start...
NOTICE:  USB DFU function timeout and need switch to xmodem download 
NOTICE:   dfu-util timeout, forcily switch xmodem download......
## Ready for (xmodem) download to 0x1ff00000
CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC
```

如果遇到超时退出 DFU 导致升级失败，可以断电重启单板再次点击升级即可。

### <span id="UART_mode_upgrade"/>Serial+USB 连接方式升级过程说明

**前提条件：**

- 请查阅 [通过串口连接](connect_board.html#span-id-connect-by-uart) 完成串口驱动的安装。
- 请查阅 [通过 USB 连接](connect_board.html#span-id-connect-by-usb-usb) 完成 USB 驱动的安装。

**适用范围：**

Serial+USB 连接方式时，支持 Fastboot、Xmodem+fastboot、Xmodem+DFU、 DFU 四种下载模式，这四种下载方式的详细说明可以参考[烧录方式简介](./update_system_firmware.html#span-id-xburn-download-function)章节中的表格。

需要说明：

- 本连接类型适用于能够同时连接串口和 USB 接口的情景；
- 本连接类型中可以选择 Xmodem+fastboot 以及 Xmodem+DFU 下载模式，通过 Xmodem 协议用于**开发板上没有可用镜像或镜像已损坏**场景的烧录，此时需要使用 `out/product/uart_usb` 中的镜像 BL2 以及 BL3X，此时推荐将串口波特率设置为 921600 （拨码开关 D4 置 1）。

下面以 Fastboot 下载模式为例进行说明。

<a id="UART_mode_wiring"></a>
**接线示意图：**

![fastboot_usb](./_static/_images/update_system_firmware/fastboot_usb.jpg)

XBurn-gui烧录工具界面配置如下：

![fastboot_usb](./_static/_images/update_system_firmware/XBurn_Serial_USB_Fastboot_dl.png)

以下是烧录过程的详细描述：

**步骤1：**
选择产品类型。点击`产品类型`选项列表中，选择型号为`X5`。

**步骤2：**
选择连接类型。点击`连接类型`选项列表，选择 `Serial+USB`。

**步骤3：**
选择下载模式。点击`下载模式`选项列表，选择`Fastboot`模式。

**步骤4：**
选择待烧录镜像的目录。点击`浏览`，选择镜像文件所在的目录，通常为系统编译后生成的`out/product`目录，如`S:\home\sxq\projects\sdk_x5_CS1.0\out\product`。

**步骤5：**
点击`刷新`按钮，确保软件识别到正确的串口。

**步骤6：**
选择串口。在`串口`选项中选择正确的 COM 口，如`COM6`。

**步骤7：**
设置波特率。在`波特率`选项中输入或选择正确的波特率，如`921600`（推荐）。

**步骤8：**
开始烧录。将开发板上电，然后点击`开始升级`，工具将开始烧录。当进度条显示100%时，表示升级成功。

![img](./_static/_images/update_system_firmware/XBurn_Serial_USB_Fastboot_dl_end.png)

### <span id="uboot_mode_upgrade"/>Serial+Ethernet 连接方式升级过程说明

**前提条件：**

- 请查阅 [通过串口连接](connect_board.html#span-id-connect-by-uart) 完成串口驱动的安装。
- 请查阅 [通过网络连接](connect_board.html#span-id-connect-by-network) 了解开发板与 PC 连接的方法。

**适用范围：**

Serial+Ethernet 连接方式 Fastboot 以及 Xmodem+fastboot 两种下载模式，这两种下载模式的详细说明可以参考[烧录方式简介](./update_system_firmware.html#span-id-xburn-download-function)章节中的表格。

- 本连接方式适用于能够同时连接串口和以太网口的场景。
- 本连接方式中可以选择 Xmodem+fastboot 下载模式，通过 Xmodem 协议用于**开发板上没有可用镜像或镜像已损坏**场景的烧录，此时需要使用 `out/product/uart_usb` 中的镜像 BL2 以及 BL3X，此时推荐将串口波特率设置为 921600 （拨码开关 D4 置 1）。

下面以 Fastboot 下载模式为例进行说明。

**接线示意图：**

![fastboot_udp](./_static/_images/update_system_firmware/fastboot_udp.jpg)

XBurn-gui烧录工具界面配置如下：

![fastboot_usb](./_static/_images/update_system_firmware/XBurn_Serial_Ethernet_Fastboot_dl.png)

以下是烧录过程的详细描述：

**步骤1：**
选择产品类型。在`产品类型`下拉列表中选择`X5`。

**步骤2：**
选择连接类型。在`连接类型`下拉列表中选择`Serial+Ethernet`。

**步骤3：**
选择下载模式。在`下载模式`下拉列表中选择`Fastboot`。

**步骤4：**
选择镜像所在目录。点击`浏览`按钮，选择镜像文件所在的目录，例如`S:\home\sxq\projects\sdk_x5_CS1.0\out\product`。

**步骤5：**
点击`刷新`按钮，确保软件识别到正确的串口。

**步骤6：**
选择串口。在`串口`下拉列表中选择当前的使用的 COM 口，如 `COM6`。

**步骤7：**
设置波特率。在`波特率`下拉列表中选择当前的串口波特率，如`921600`。

**步骤8：**
设置主机IP。在`主机IP`输入框中输入当前接入的 PC 网口的静态 IP ，如 `192.168.1.101`。

**步骤9：**
设置板子IP。在`板子IP`输入框中输入`192.168.1.10`（默认 IP）。

**步骤10：**
设置子网掩码。在`子网掩码`输入框中输入`255.255.255.0`。

**步骤11：**
设置网关。在`网关`输入框中输入`192.168.1.1`。

**步骤12：**
开始烧录。点击`开始升级`按钮，开始烧录过程。当进度条显示100%时，表示升级成功。

![fastboot_usb](./_static/_images/update_system_firmware/XBurn_Serial_Ethernet_Fastboot_dl_end.png)

### Serial 连接方式升级过程说明

**前提条件：**

- 请查阅 [通过串口连接](connect_board.html#span-id-connect-by-uart) 完成串口驱动的安装。

**适用范围：**

Serial 连接方式 Xmodem 以及 Xmodem+Xmodem 两种下载模式，这两种下载模式的详细说明可以参考[烧录方式简介](./update_system_firmware.html#span-id-xburn-download-function)章节中的表格。

- 本连接方式适用于只能连接串口的场景。
- 本连接方式中支持的下载模式均通过 Xmodem 协议用于**开发板上没有可用镜像或镜像已损坏**场景的烧录，此时需要使用 `out/product/uart_usb` 中的镜像 BL2 以及 BL3X，此时推荐将串口波特率设置为 921600 （拨码开关 D4 置 1）。
- 本连接方式仅推荐用于小尺寸镜像的烧录，Xmodem 传输的速度很慢。

下面以 Xmodem 下载模式为例进行说明。

**接线示意图：**

![Serial_mode](./_static/_images/update_system_firmware/Serial_mode.png)

XBurn-gui烧录工具界面配置如下：

![XBurn_Serial_Ethernet_Fastboot_dl](./_static/_images/update_system_firmware/XBurn_Serial_Xmodem_dl.png)

以下是烧录过程的详细描述：

**步骤1：**
选择产品类型。在`产品类型`下拉列表中选择`X5`。

**步骤2：**
选择连接类型。在`连接类型`下拉列表中选择`Serial`。

**步骤3：**
选择下载模式。在`下载模式`下拉列表中选择`Xmodem`。

**步骤4：**
选择镜像所在目录。点击`浏览`按钮，选择镜像文件所在的目录，例如`S:\home\sxq\projects\sdk_x5_CS1.0\out\product`。

**步骤5：**
选择串口。在`串口`下拉列表中选择`COM6`。

**步骤6：**
点击`刷新`按钮，刷新串口列表以确保选择正确的串口。

**步骤7：**
设置波特率。在`波特率`输入框中输入`921600`。

**步骤8：**
开始烧录。点击`开始升级`按钮，开始烧录过程。Xmodem 传输的速度很慢，请耐心等待。

### <span id="advanced_configuration"/>高级配置

#### 烧录完成后自动重启

勾选`烧录完成后自动重启`选项后，烧录镜像结束时会重启开发板。

- 默认勾选，烧录结束后，开发板会停留在最后的烧录结束时的状态，比如通过fastboot烧录，那么烧录结束后，开发板依然会处在fastboot模式。

![auto_reboot](./_static/_images/update_system_firmware/auto_reboot.png)

勾选后会出现一个 `检查设备是否重启成功` 选项可供勾选。

#### 全盘擦除 eMMC

勾选`全盘擦除 eMMC`后，如果开发板上的主存储介质是 eMMC 时，会在烧录镜像前，全盘擦除整个 eMMC。

- 全盘擦除 eMMC 耗时较长，请耐心等待，16GB 的 eMMC 的全盘擦除需要 3-5 分钟。
- 当选则了`烧录指定分区镜像`模式是，即使勾选 `全盘擦除 eMMC` 也不会生效。

![all_emmc_erase](./_static/_images/update_system_firmware/all_emmc_erase.png)

#### 启用分区备份/还原功能

**简介**

XBurn-gui 烧录工具支持分区备份、还原功能，可以指定分区进行备份，在新镜像烧录结束后，会把备份的分区重写烧录到开发板，保持该分区数据不会因为烧录新镜像而发生变化。

**适用范围**

- 开发板的存储介质中必须已经存在分区。

**使用方式**

- 默认烧录时不会进行分区备份。

  ![partition_backup](./_static/_images/update_system_firmware/partition_backup.png)

- 勾选 `启用分区备份/还原功能` 选项，并选择需要备份的分区，则烧录时会对选择的分区进行分区备份。

烧录步骤和之前介绍的几种连接方式的烧录步骤除了需要额外勾选`启用分区备份/还原功能` 选项之外完全一样。

**额外需要注意**的是烧录完成后，重启开发板并检查分区是否备份成功。

#### 指定烧录分区镜像

![Burn_specified](./_static/_images/update_system_firmware/Burn_specified.png)

- **指定烧录分区镜像：** 本选项支持只烧录镜像中的某一个或多个分区，不影响其他分区内容。适用于以下场景：

  - 只需更新系统中的某个组件（如 miniboot、uboot、system、app 分区等）

  - 需要在不影响用户数据分区的前提下进行系统升级

  - 选择此模式后，您需手动选择要烧录的目标分区。

## <span id="xburn_cmd"/> 命令行工具介绍（工厂版本）

### 简介

命令行工具是图形化工具的核心执行模块，能够独立运行并完成相同的功能，二者的基本原理相同。用户可以根据需要选择适合自己的工具。

镜像准备、环境配置及支持的烧录方式等内容与图形化界面工具一致，此处不再详细说明。

### 命令行环境配置说明

Windows 系统中需要将 xburn-gui 烧录工具的安装目录加入到系统的环境变量中，以方便通过命令行的方式执行烧录操作，例如：

![XBurn_path](./_static/_images/update_system_firmware/XBurn_path.png)

将上述路径 `D:\xburn-gui` 添加到系统的环境变量中，步骤如下：

1. 按下 Win + R 键，打开运行对话框。
2. 输入 `sysdm.cpl`，按下回车。
3. 在`系统属性`窗口中菜单栏选择`高级`，然后点击右下角的`环境变量`。
4. 在`环境变量`窗口中选中`Path`变量，然后点击`编辑`按钮。
5. 在`编辑环境变量`窗口中点击`新建`，将 xburn-gui 烧录工具的安装目录地址粘贴进去即可。
6. 点击`确定`。

在 Ubuntu 系统中 `xburn` 命令会在完成安装后自动集成到 `/usr/bin/` 中，可以直接使用。

### 命令行使用方式

在 PC 端，打开对应系统的命令行界面，执行命令 `sudo xburn` （Ubuntu 以及 macOS 终端中）或 `xburn` （Windows Powershell 中），即可进行烧录，可以执行 `xburn --help` 看到完整的使用方式：

```bash
$ xburn --help
usage: xburn [-h] [-s {product,serial,dfu,adb}] [-c CONFIG] [-v, --version] [-V {debug,info,warning,error,critical}] [-p PRODUCT_TYPE] [-l {usb,ethernet,serial,serial_usb,serial_ethernet}] [-d {fastboot,dfu,dfu_fastboot,xmodem,xmodem_fastboot,xmodem_dfu,xmodem_xmodem}] [-i IMG_FILES] [--erase_scrub]
             [--security {secure,secure_ohp,nosecure}] [--boot_check] [--batch_num BATCH_NUM] [--host_ip HOST_IP] [--board_ip BOARD_IP] [--netmask NETMASK] [--gateway GATEWAY] [--ipv6] [--usb_port {usb2.0,usb3.0}] [--serial SERIAL] [--baudrate BAUDRATE] [--mcu_serial MCU_SERIAL]
             [--hsm_serial HSM_SERIAL] [--erase_part ERASE_PART] [--select_part SELECT_PART] [--backup_part BACKUP_PART] [--reboot]

Command-line interface for the application.

optional arguments:
  -h, --help            show this help message and exit

Status query and other configurations::
  -s {product,serial,dfu,adb}, --scan {product,serial,dfu,adb}
                        Scan serial, dfu, adb and supported product lists.
  -c CONFIG, --config CONFIG
                        Path to the xburn config file.
  -v, --version         Display compiler version information.
  -V {debug,info,warning,error,critical}, --log_level {debug,info,warning,error,critical}
                        Set the logging level (default: info).

Burn configuration Arguments::
  -p PRODUCT_TYPE, --product_type PRODUCT_TYPE
                        Specify the product type.
  -l {usb,ethernet,serial,serial_usb,serial_ethernet}, --link_type {usb,ethernet,serial,serial_usb,serial_ethernet}
                        Specify the hardware link type.
  -d {fastboot,dfu,dfu_fastboot,xmodem,xmodem_fastboot,xmodem_dfu,xmodem_xmodem}, --dl_mode {fastboot,dfu,dfu_fastboot,xmodem,xmodem_fastboot,xmodem_dfu,xmodem_xmodem}
                        Specify the download mode.
  -i IMG_FILES, --img_files IMG_FILES
                        Specify img_files (comma separated).
  --erase_scrub         Enable or disable storage erase scrub.
  --security {secure,secure_ohp,nosecure}, --security_type {secure,secure_ohp,nosecure}
                        Specify the security type.
  --boot_check          Enable or disable boot check.
  --batch_num BATCH_NUM
                        Specify the number of boards to burn in batch.
  --host_ip HOST_IP     Specify the network host IP (comma separated).
  --board_ip BOARD_IP   Specify the network board IP (comma separated).
  --netmask NETMASK     Specify the network netmask (comma separated).
  --gateway GATEWAY     Specify the network gateway (comma separated).
  --ipv6                Enable or disable IPv6 network configuration.
  --usb_port {usb2.0,usb3.0}
                        Specify the usb port.
  --serial SERIAL       Specify the serial port.
  --baudrate BAUDRATE   Specify the serial port baud rate.
  --mcu_serial MCU_SERIAL
                        Specify the MCU serial port.
  --hsm_serial HSM_SERIAL
                        Specify the Hardware Security Module serial port.
  --erase_part ERASE_PART
                        Specify partitions to erase (comma separated).
  --select_part SELECT_PART
                        Specify partitions to select (comma separated).
  --backup_part BACKUP_PART
                        Specify partitions to backup (comma separated).
  --reboot              Enable or disable board reboot after burn.
```

下面对这些参数分别进行简要说明。

#### 状态查询与基础配置

| 参数             | 缩写 | 可选值                              | 作用说明                          | 示例               | 格式要求          |  
|----------------------|----------|----------------------------------------|--------------------------------------|------------------------|-----------------------|  
| `--scan`             | `-s`     | `product`, `serial`, `dfu`, `adb`      | 扫描设备或产品列表                   | `-s serial`            | 单选                 |  
| `--config`           | `-c`     | 文件路径                               | 指定配置文件路径                     | `-c XXX` |           |  -
| `--version`          | `-v`     | 无                                     | 显示编译器版本信息                   | `-v`                   | -                    |  
| `--log_level`        | `-V`     | `debug`, `info`, `warning`, `error`, `critical` | 设置日志级别（默认 `info`）          | `-V debug`              | -                    |  

#### 核心烧录配置

| 参数           | 缩写 | 可选值                                                                 | 作用说明                                                                 | 示例                  | 格式要求          |  
|--------------------|----------|---------------------------------------------------------------------------|-----------------------------------------------------------------------------|---------------------------|-----------------------|  
| `--product_type`   | `-p`     | 产品型号（当前仅支持 `X5`, `RDKS100`）                                            | 必填，指定设备硬件型号                                                  | `-p X5`             | 需与设备一致      |  
| `--link_type`      | `-l`     | `usb`, `ethernet`, `serial`, `serial_usb`, `serial_ethernet`              | 物理连接方式                                                                | `-l serial_usb`          | -                    |  
| `--dl_mode`        | `-d`     | `fastboot`,`dfu`,`dfu_fastboot`,`xmodem`,`xmodem_fastboot`,`xmodem_dfu`,`xmodem_xmodem` | 烧录协议组合（依赖连接类型）                                                | `-d xmodem_fastboot`     | -                    |  
| `--img_files`      | `-i`     | 镜像路径                                                             | 指定待烧录镜像                                                              | `-i boot.img,system.img` | 多块单板并行烧录需要逗号分隔路径      |  
| `--batch_num`      | -        | 整数（建议≤8 ）                                                           | 并行烧录设备数量                                                            | `--batch_num 4`          | -                    |  
| `--reboot`         | -        | -                                                                   | 烧录完成后自动重启设备                                                      | `--reboot`               | -                    |  

**协议选择逻辑**：  

- **空板状态** → 优先 `dfu` 或 `xmodem_xmodem`（串口应急）
- **非空板** → 首选 `fastboot`（ USB 高速）
- **调试需求** → `xmodem_fastboot`（串口日志 +USB 烧录）

#### 分区操作与安全控制

| 参数           | 缩写 | 可选值                      | 作用说明                     | 示例                | 格式要求          |
|--------------------|----------|---------------------------------|---------------------------------|-------------------------|-----------------------|
| `--erase_part`     | -        | 分区名列表                      | 擦除指定分区                    | `--erase_part cache,userdata` | 逗号分隔分区名    |
| `--select_part`    | -        | 分区名列表                      | 仅烧录选中分区                  | `--select_part boot`     | 逗号分隔分区名    |
| `--backup_part`    | -        | 分区名列表                      | 烧录前备份分区                  | `--backup_part recovery` | 逗号分隔分区名    |
| `--erase_scrub`    | -        | 布尔值                          | 启用存储深度擦除（增强安全性）  | `--erase_scrub`         | -                    |
| `--security_type`  | -        | `secure`, `secure_ohp`, `nosecure` | 设备安全模式（影响启动验证）    | `--security secure`     | -                    |
| `--boot_check`     | -        | 布尔值                          | 烧录后校验启动完整性            | `--boot_check`          | -                    |

#### 网络配置

| 参数         | 缩写 | 可选值    | 作用说明                | 示例                      | 格式要求               |
|------------------|----------|---------------|----------------------------|-------------------------------|----------------------------|
| `--host_ip`      | -        | IPv4/IPv6 地址 | 主机 IP 地址                  | `--host_ip 192.168.1.100`     | 逗号分隔 IP（多设备时） |
| `--board_ip`     | -        | IPv4/IPv6 地址 | 设备 IP 地址                  | `--board_ip 192.168.1.101,192.168.1.102` | 逗号分隔 IP（多设备时） |
| `--netmask`      | -        | 子网掩码      | 网络子网掩码                | `--netmask 255.255.255.0`     | -                          |
| `--gateway`      | -        | IPv4/IPv6 地址 | 网关地址                    | `--gateway 192.168.1.1`       | -                          |
| `--ipv6`         | -        | 布尔值        | 启用 IPv6 网络配置            | `--ipv6`                      | -                          |

#### 接口配置

| 参数         | 缩写 | 可选值       | 作用说明               | 示例                     | 格式要求 |
|------------------|----------|------------------|---------------------------|------------------------------|--------------|
| `--usb_port`     | -        | `usb2.0`, `usb3.0` | USB 接口速率选择           | `--usb_port usb3.0`         | -           |
| `--serial`       | -        | 串口设备路径     | 指定串口路径              | `--serial /dev/ttyUSB0`、`--serial COM10`     | -           |
| `--baudrate`     | -        | 当前仅支持 `115200` 和 `921600` | 设置串口波特率                | `--baudrate 115200`         | -           |
| `--mcu_serial`   | -        | 串口设备路径     | MCU 调试串口（特殊设备用） | `--mcu_serial /dev/ttyACM1` | -           |
| `--hsm_serial`   | -        | 串口设备路径     | HSM 安全模块串口           | `--hsm_serial /dev/ttyHS0`  | -           |  

#### 使用示例  

1. 单设备烧录（串口 + USB Fastboot）  

   ```bash  
   xburn -V info -p X5 -l serial_usb -d fastboot -i S:\home\sxq\projects\sdk_x5_CS1.0\out\product --batch_num 1 --baudrate 921600 --serial COM6 --reboot
   ```  

2. 空板调试（串口 + USB xmodem_fastboot）  

   ```bash  
   xburn -V info -p X5 -l serial_usb -d xmodem_fastboot -i S:\home\sxq\projects\sdk_x5_CS1.0\out\product --batch_num 1 --baudrate 921600 --serial COM6 --reboot
   ```  

   执行成功日志如下：

   ```bash
   Finished. Total time: 31.990s
   [Burn thread-1][18:44:37] [INFO] Step 'fastboot_burn' completed successfully

   [Burn thread-1][18:44:37] [PROGRESS] Board 1 burn progress 85.0%
   [Burn thread-1][18:44:37] [INFO] Start step: after_burn

   [Burn thread-1][18:44:37] [PROGRESS] Board 1 burn progress 86.0%
   [Burn thread-1][18:44:37] [INFO] After burn...
   [Burn thread-1][18:44:37] [INFO] Step 'after_burn' completed successfully

   [Burn thread-1][18:44:37] [PROGRESS] Board 1 burn progress 90.0%
   [Burn thread-1][18:44:37] [INFO] Start step: check_burn_result

   [Burn thread-1][18:44:37] [PROGRESS] Board 1 burn progress 91.0%
   [Burn thread-1][18:44:37] [ERROR] Write failed: Write timeout
   [Burn thread-1][18:44:37] [INFO] Reconnected successfully

   [Burn thread-1][18:44:37] [PROGRESS] Board 1 burn progress 100.0%
   [Burn thread-1][18:44:37] [INFO] Step 'check_burn_result' completed successfully

   [Burn thread-1][18:44:37] [PROGRESS] Board 1 burn progress 100.0%
   [Burn thread-1][18:44:37] [INFO] Board-1 [UID: 308064960e30c82402062d570000024] [Storage: emmc] Status:  SUCCESS
   ```

3. 扫描可用串口

   ```bash
   xburn -s serial
   ```

   命令执行日志如下：

   ```bash
   PS C:\Users\xiangqing.shi> xburn -s serial
   Scanning for serial information...
   Detected serial devices:
   Device: COM6, Description: USB-SERIAL CH340 (COM6), HWID: USB VID:PID=1A86:7523 SER= LOCATION=1-2.3
   ```

## <span id="manual"/> 手动烧录工具介绍

### 使用 fastboot 命令烧录镜像

**前提条件：**

- 请查阅 [通过串口连接](connect_board.html#span-id-connect-by-uart) 以完成串口驱动的安装。在 Windows 电脑的设备管理器中，您可以看到对应的 COM 端口；在 Ubuntu 系统的 /dev 目录中，可以找到相应的 tty 串口设备。

- 请查阅 [通过 USB 连接](connect_board.html#span-id-connect-by-usb-usb) 来完成 USB 驱动的安装。在 Windows 电脑上，通常会在设备管理器中显示为 `Android Bootloader Interface` 设备。

**适用范围：**

该烧录方式适用于已经存在镜像且能够正常启动的开发板，不适用于没有镜像或镜像损坏的开发板。

**提示：**

- 图形化的 `xburn-gui` 软件包中已集成 Fastboot 工具。 Windows 版本位于安装目录下的 `xburn-gui\tools\windows` 目录中。
- 在 Windows 系统中，可以将 `fastboot` 工具的路径加入到环境变量中。

当开发板进入 U-Boot 命令行模式后，请执行 `fastboot 0` 命令以使开发板进入 Fastboot 模式。

```bash
U-Boot 2022.10-gca2c6582a0 (Mar 13 2024 - 19:04:15 +0800)

Model: Horizon X5
... （省略） ...
Hobot>fastboot 0
```

接下来，您可以在 Windows 系统的 `emmc_disk.simg` 镜像所在目录中打开 Windows Powershell 终端窗口，在镜像目录中按下 Shift 按键同时鼠标右键即可看到：

![usb_fastboot_usPower_Shellage](./_static/_images/update_system_firmware/Power_Shell.png)


然后在 Windows Powershell 终端窗口中执行以下命令进行整体系统镜像的烧录：

```bash
fastboot flash addr:0x0 emmc_disk.simg
```

烧写完成后，请在 Windows Powershell 终端窗口执行 `fastboot reboot` 命令重启设备，或者可以通过断电重启的方式使升级生效。

整体烧录系统镜像的过程图示如下所示：

![usb_fastboot_usage](./_static/_images/update_system_firmware/usb_fastboot_usage.png)

此外，您也可以选择按传统的分区方式进行烧录。

**烧录 uboot 分区**

```
fastboot flash uboot uboot.img
```

**烧录 boot 分区**

```
fastboot flash boot boot.img
```

**烧录 system 分区**

```
fastboot flash system system.img
```

**烧录 miniboot 分区**

```
fastboot flash miniboot miniboot.img
```

**注意：**
烧录 `miniboot` 分区的另外一种方式，需要 `flash addr:0x0`， 使用以下命令 :

```
fastboot flash addr:0x0 miniboot_all.img
```

miniboot_all.img 是指包含 miniboot 分区及其之前所有镜像的文件，具体包括 miniboot.img、分区表以及 misc 分区。若需同时更新 miniboot 和分区表，必须从 **addr:0x0** 开始进行写入，不能单独指定 miniboot 分区进行烧录。这一操作类似于更新 emmc_disk.simg，因此请确保写入格式的正确性。

### 使用 dfu 命令烧录镜像

**前提条件：**

- 请查阅 [通过 USB 连接](connect_board.html#span-id-connect-by-usb-usb) 来完成 USB 驱动的安装。在 Windows 电脑上，通常会在设备管理器中显示为 `Android Bootloader Interface` 设备。
- 请按照图形化工具 USB 下载模式的[接线方式](#USB_mode_wiring)进行接线。

**适用范围：**

- 该烧录方式主要适用于没有镜像或镜像损坏的开发板。
- 该烧录方式也可用于已经存在镜像且能够正常启动的开发板。

#### Windows 下 dfu 命令烧录说明

Windows 下 dfu 命令详细的使用方式可以参考[使用 dfu](./connect_board.html#span-id-use-dfu-dfu) 章节。

#### Ubuntu 下 dfu 命令烧录说明

1. 前置条件 (udev 规则, plugdev 组)
     - 配置 udev 规则：将 [51-drobotics-usb.rules](https://sunrise.horizon.cc/downloads/software_tools/adb_and_fastboot/) 文件拷贝到 `/etc/udev/rules.d/` 目录中。
     - 激活新规则：

        ```bash
        udevadm control --reload-rules
        udevadm trigger
        ```

        若上述命令激活失败，可以尝试重启电脑。

     - 将当前用户添加到 plugdev 组：

        ```bash
        sudo usermod -aG plugdev $(whoami)
        ```

        重新登录账户并使用 `groups` 命令确认用户已成功加入 plugdev 组。

2. 常见命令
    常用命令与 Windows 平台类似，使用 `dfu-util` 工具进行烧录。

### <span id="serial_manual_upgrade"/>使用串口手动烧录镜像

**前提条件：**

- 请查阅 [通过串口连接](connect_board.html#span-id-connect-by-uart) 以完成串口驱动的安装。在 Windows 电脑的设备管理器中，您可以看到对应的 COM 端口；在 Ubuntu 系统的 /dev 目录中，可以找到相应的 tty 串口设备。
- 请按照图形化工具 UART 下载模式的[接线方式](#UART_mode_wiring)进行接线。
- 有拨码开关的单板，保持拨码开关处于默认启动方式如 [EMMC 启动状态](#Default_mode)。
- 使用串口烧录镜像时，建议将串口波特率调整为 921600bps （对于 X5 EVB 可以将拨码开关的 D4 置 1）以提高烧录速度。

**适用范围：**

- 该烧录方式主要适用于没有镜像或镜像损坏的开发板。
- 该烧录方式也可用于已经存在镜像且能够正常启动的开发板。
- 如果通过图形化烧录工具进行固件升级失败，并且由于缺少日志信息难以准确定位问题，可以参考本章节提供的手动烧录方法。通过将系统启动至 U-Boot 阶段，可以获取更详细的启动信息，帮助判断问题原因。

以下是固件烧录的详细步骤：

**步骤1：**

准备好串口工具。
UART 下载模式需要使用 Xmodem 协议传输镜像，所以需要支持 Xmodem 的串口工具，推荐使用开源工具 [WindTerm](https://github.com/kingToolbox/WindTerm/releases)，该工具在 Windows 系统以及 Linux 系统中均可运行，只需下载对应的软件包即可。

对于 Windows 系统下载 `WindTerm_X.X.X_Windows_Portable_x86_64.zip`，解压后，直接运行 `WindTerm.exe` 即可。

对于 Linux 系统下载 `WindTerm_X.X.X_Linux_Portable_x86_64.zip`，解压后，执行下面命令运行：

```bash
chmod +x ./WindTerm && ./WindTerm
```

**步骤2：**

将设备的串口与电脑连接，务必确保设备处于 **断电状态**（未通电）。

**步骤3：**

使用 WindTerm 连接设备的串口。在 WindTerm 界面依次点击菜单栏 **Session -> New Session** 创建串口窗口，并配置好串口信息：

![WindTerm_Serial_Config1](./_static/_images/update_system_firmware/WindTerm_Serial_Config1.png)

![WindTerm_Serial_Config2](./_static/_images/update_system_firmware/WindTerm_Serial_Config2.png)

![WindTerm_Serial_Xmodem](./_static/_images/update_system_firmware/WindTerm_Serial_Xmodem.png)

配置拖放文件时的协议为 Xmodem，并且推荐选择传输包大小为 1024 以提高文件传输速度。

**步骤4：**

在 WindTerm 界面，依次点击菜单栏中的 **View -> Panes -> Sender** 打开 Sender 窗口：

![WindTerm_Sender](./_static/_images/update_system_firmware/WindTerm_Sender.png)

**步骤5：**

在 Sender 窗口中，输入 `x2dbg` 命令，并设置执行次数为 50 次，间隔时间为 0.01S：

![WindTerm_Sender_cmd](./_static/_images/update_system_firmware/WindTerm_Sender_cmd.png)

**步骤6：**

点击 **run**（绿色三角形按钮）循环执行命令。

**步骤7：**

运行脚本后，**立即** 为开发板上电。上电后，设备将进入串口下载模式，串口将持续打印 `C`，并提示 `Currently use xmodem to download file`。

![WindTerm_Run](./_static/_images/update_system_firmware/WindTerm_Run.png)

<a id="action8"></a>
**步骤8：**

将位于 BSP 编译后的 `out\product\uart_usb` 目录中的 `bl2_uart_ddr.bin` 固件文件拖拽入当前串口窗口中，随后会自动进行 Xmodem 文件传输：

![WindTerm_Xmodem1](./_static/_images/update_system_firmware/WindTerm_Xmodem1.png)

**步骤9：**

当 `bl2_uart_ddr.bin` 载完成并成功运行后，串口日志将如下所示。日志末尾将提示 `Download bl3x fip(bl3x_all.bin)`，此时需要继续使用 `xmodem` 传输固件。串口将再次持续打印字符 `C`，等待下一步操作。

```bash
 100% [====================] 00:00:10 704360 bytes
00 = 704512 Bytes
NOTICE:  Get S1PK
NOTICE:  [verify_signature] pass.
NOTICE:  [verify_hash] pass.
NOTICE:  [verify_hash] pass.
NOTICE:  [auth_decrypt] pass.
NOTICE:  BL1: BL2 memory layout address = 0x1fe9f000
NOTICE:  BL1: Booting BL2
NOTICE:                 OTP config:
NOTICE:                         otp exist: true
NOTICE:                         test region size: 304
NOTICE:                         secure region size: 120
NOTICE:                         none secure region size: 56
NOTICE:  BL2: v2.8(release):v1.0.8-72-g68feecd07
NOTICE:  BL2: Built : 15:17:38, Jan 16 2025
NOTICE:  Enter UART Mode..... 
NOTICE:  Enter media_source_select process(0).
NOTICE:  BL2 config file
NOTICE:  start to load bl2 cfg image
NOTICE:  BL2 CFG ADDR:0x1ff00000, MAGIC:0x474643324c424248
NOTICE:  bypass update efuse
NOTICE:  calibration_offset -22
NOTICE:  trimming_value 9
NOTICE:  ADC read channel[2]: 313mv
NOTICE:  ddr info:[LPDDR4]-[DUAL_RANK]-[ECC OFF]-[DVFS ON]-[4266M]
NOTICE:  JTAG ENABLE
NOTICE:  disable wdt
NOTICE:  Get S1PK
NOTICE:  [verify_signature] pass.
NOTICE:  [verify_hash] pass.
NOTICE:  [verify_signature] pass.
NOTICE:  start to load ddr image
NOTICE:  [verify_hash] pass.
NOTICE:  run ddr Fw
NOTICE:  matching profile: profile_2 from aon config
NOTICE:  type: LP4, freq: 4266, ecc: 0(0x7f), rank: 2, dvfs: 1, version: 9.03
NOTICE:  ddr cost: 146803 us, ddr size: 4 GB, manuid: 0x13
NOTICE:  ddr ready
NOTICE:  Download bl3x fip(bl3x_all.bin) to ddr: 0x84000000
NOTICE:  Currtenly use xmodem to download file
## Ready for (xmodem) download to 0x84000000
CCCCCCCCCCCCCCCCCCCC
```

**步骤10：**

和[步骤 8](#action8) 一样，将位于 BSP 编译后的 `out\product\uart_usb` 目录中的 `bl3x_all.bin` 固件文件拖拽入当前串口窗口中，随后会自动进行 Xmodem 文件传输。该固件较大，如果波特率设置的是 115200bps，传输速度会比较慢，需要耐心等待传输完成。

![WindTerm_Xmodem2](./_static/_images/update_system_firmware/WindTerm_Xmodem2.png)

**步骤11：**

当 `bl3x_all.bin` 传输完成并成功运行后，设备将进入 `U-Boot` 命令行模式。在该模式下，可以选择使用 `fastboot` 命令烧录固件，或手动使用 `tftp` 下载镜像进行烧录操作。

串口日志如下所示：

```bash
100% [====================] 00:00:32 2144940 bytes
00 = 2145280 Bytes
NOTICE:  Get S1PK
NOTICE:  [verify_signature] pass.
NOTICE:  [verify_hash] pass.
NOTICE:  [verify_signature] pass.
NOTICE:  start to load bl31 image
NOTICE:  [verify_hash] pass.
NOTICE:  Get S1PK
NOTICE:  [verify_signature] pass.
NOTICE:  [verify_hash] pass.
NOTICE:  [verify_signature] pass.
NOTICE:  start to load optee image
NOTICE:  [verify_hash] pass.
NOTICE:  [verify_hash] pass.
NOTICE:  start to load uboot image
NOTICE:  BL1: Booting BL31
NOTICE:  multicore_init: sec_entrypoint = 0x2000010c
NOTICE:  BL31: v2.8(release):v1.0.8-67-g40e41bd29
NOTICE:  BL31: Built : 10:40:46, Dec 31 2024
NOTICE:  plat_setup_psci_ops: sec_entrypoint = 0x2000010c
I/TC: 
I/TC: OP-TEE version: 6b9fbbe87 (gcc version 11.3.1 20220712 (Arm GNU Toolchain 11.3.Rel1)) #1 Thu Jan 16 06:59:55 UTC 2025 aarch64
I/TC: WARNING: This OP-TEE configuration might be insecure!
I/TC: WARNING: Please check https://optee.readthedocs.io/en/latest/architecture/porting_guidelines.html
I/TC: Primary CPU initializing
MBEDTLS_CORE  Select regular OTP
MBEDTLS_CORE  SRAM Pool Base: 0x80000000, size: 0x2000, alignment: 0x10
MBEDTLS_CORE   ACA driver init success!
MBEDTLS_CORE  set sw_init_done!
I/TC: Primary CPU switching to normal world boot


U-Boot 2022.10-gd5c668dae2 (Mar 14 2025 - 17:56:43 +0800)

Model: Horizon X5
DRAM:  3.9 GiB
console out start addr:0x0000000087ffc000, end addr:0x0000000087ffe000
horizon_lsio_pinctrl lsio_iomuxc@34180000: Initialized D-Robotics pinctrl driver
optee optee: OP-TEE: revision 3.20 (6b9fbbe8)
ADC calibration: -22
ADC trimming: 9
horizon_hsio_pinctrl hsio_iomuxc@35050000: Initialized D-Robotics pinctrl driver
horizon_dsp_pinctrl dsp_iomuxc@31040014: Initialized D-Robotics pinctrl driver
Core:  149 devices, 29 uclasses, devicetree: separate
WDT:   Started watchdog@34250000 with servicing (10s timeout)
stop watchdog
MMC:   sdio-host@35040000: 0, sdio-host@35020000: 1
Loading Environment from MMC... (Tuning Ok!) *** Warning - bad CRC, using default environment

In:    serial@32120000
Out:   serial@32120000
Err:   serial@32120000
Net:   
Warning: gmac-tsn@35010000 (eth0) using random MAC address - 36:64:fc:52:5e:1e
eth0: gmac-tsn@35010000
boot action: UART
Hobot>
```

请确保按照上述步骤正确执行，以顺利完成固件的烧录与升级。

<a id="FAQ"></a>
## FAQ：常见错误对照表

| 报错信息                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | 措施                                                            |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------|
| [MainThread][19:07:59] [ERROR] Serial port COM6 is NOT available<br>[MainThread][19:07:59] [ERROR] Reason:<br>Port COM6 not found.<br>Please check:<br>1. Is the device properly connected?<br>2. Is the correct port name used?<br>3. Available ports: python -m serial.tools.list_ports<br>[MainThread][19:07:59] [ERROR] Invalid configuration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | 1. 检查板端是否上电<br>2. 检查线束是否连接<br>3. 检查是否正确安装驱动                   |
| [MainThread][19:12:13] [ERROR] No valid storage type found in directory 'S:\home\sxq\projects\sdk_x5_CS1.0\out\'.<br>[MainThread][19:12:13] [ERROR] The img_files parameter validation failed. Exiting...<br>[MainThread][19:12:13] [ERROR] Invalid configuration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | 1. 检查指定镜像路径下是否有所需镜像文件<br>2. 检查镜像路径是否错误                        |
| [Burn thread-1][19:15:23] [ERROR] Timedout for 30s cannot find usb dfu devices<br>......<br>No DFU capable USB device available<br>[Burn thread-1][19:15:23] [ERROR] DFU download 'S:\home\sxq\projects\sdk_x5_CS1.0\out\product\uart_usb/bl2_usb2_ddr.bin' failed<br>[Burn thread-1][19:15:23] [INFO] dfu-util 0.11<br>Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.<br>Copyright 2010-2021 Tormod Volden and Stefan Schmidt<br>This program is Free Software and has ABSOLUTELY NO WARRANTY<br>Please report bugs to http://sourceforge.net/p/dfu-util/tickets/Warning: Invalid DFU suffix signature<br>A valid DFU suffix will be required in a future dfu-util release<br>No DFU capable USB device available<br>[Burn thread-1][19:15:23] [ERROR] Step 'dfu_boot' failed<br>[Burn thread-1][19:15:23] [ERROR] Board-1, burn failed<br>[Burn thread-1][19:15:23] [ERROR] Board-1 [Storage: emmc] Status: FAILED | 1. DFU 超时，检查单板是否将拨码开关设置为 DFU 模式<br>2. 若无拨码开关则需要修改硬件电路为 DFU 模式 |
