> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 机器人镜像与 overlay

> 机器人镜像是一个独立的 Qualcomm Linux 产品，使用自己的发行版、meta 层、内核更改和镜像配方构建。您无法将机器人 overlay 添加到普通的 QLI 2.0 镜像上。

**机器人镜像**是 QIR SDK 的操作系统交付物。它是一个独立的 Qualcomm Linux 产品：使用自己的 Yocto 发行版、自己的 meta 层、自己的内核配置和设备树补丁，以及自己的镜像配方构建。它**不是**在普通 Qualcomm Linux (QLI) 2.0 镜像上添加几个 ROS 软件包而成的。

<Warning>
  您无法拿一个普通的 QLI 2.0 镜像然后"直接添加机器人 overlay"。机器人镜像使用不同的发行版、内核、设备树、overlay 配置和 meta 层。复现它所需的构建期更改列在下方的[为什么不能直接添加机器人 overlay](#why-you-cannot-just-add-the-robotics-overlays) 中。
</Warning>

## 机器人镜像与普通 QLI 2.0 镜像的区别

这些差异是结构性的，而非简单叠加：

| 方面          | 普通 QLI 2.0 镜像                                                 | 机器人镜像                                                                                                            |
| ----------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| 发行版（DISTRO） | `qcom-distro`                                                 | `qcom-robotics-distro` / `qcom-robotics-ros2-jazzy`，它依赖 `qcom-distro.conf` 并将 `ros2-jazzy` 追加到 `DISTRO_FEATURES` |
| Meta 层      | `meta-qcom` BSP 层                                             | 增加 `meta-qcom-robotics-sdk`（标签 `qli-2.0`），它将 Qualcomm Linux 1.0 的三个机器人层合并为一个                                     |
| 内核          | Qualcomm Linux 内核                                             | 相同的基础内核，外加机器人层的内核配置片段和设备树（DTS）补丁；您需要选择内核提供者（`linux-qcom-6.18` 或实时版 `linux-qcom-rt-6.18`）                         |
| 镜像配方        | `qcom-multimedia-image` / `qcom-multimedia-proprietary-image` | `qcom-robotics-image` / `qcom-robotics-proprietary-image`                                                        |
| ROS 2       | 不包含                                                           | ROS 2 Jazzy 加上 `qrb-ros` 软件包，以及 Navigation2、MoveIt 和 Cartographer 配方适配                                           |

您可以在已刷写的设备上确认正在运行的发行版：

```bash theme={null}
cat /etc/os-release
# ID=qcom-robotics-ros2-jazzy
# NAME="Qualcomm Linux Robotics Reference Distro with ROS"
```

## 两种机器人镜像配方

QIR SDK 提供两种镜像配方，各自使用不同的 Qualcomm Linux **overlay 配置**构建。Overlay 是模块化、增值的 Qualcomm 技术栈（摄像头、视频、音频、图形、传感器、视觉），它们与上游组件集成，让您可以在上游技术栈和 Qualcomm 技术栈之间进行选择。有关 overlay 机制本身，请参见[使用 overlay 配置派生镜像配方](/zh/Key-Documents/Migration-Guide/use-overlay-configurations-to-derive-image-recipes)。

| 镜像配方                              | Overlay 配置 | 内容                                                                                                                     |
| --------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------- |
| `qcom-robotics-image`             | 配置 1（上游）   | 开源镜像：ROS 2 Jazzy、开源 `qrb-ros` 软件包、仿真示例、第三方驱动，以及 QIR SDK 产物。无专有依赖。                                                      |
| `qcom-robotics-proprietary-image` | 配置 2（专有）   | 包含 `qcom-robotics-image` 的全部内容，外加依赖 Qualcomm 专有库的 `qrb-ros` 软件包（摄像头、视频、音频和色彩空间转换）以及所有 AI 示例应用。这是 Qualcomm 以预构建形式发布的镜像。 |

## 为什么不能直接添加机器人 overlay

机器人 overlay 不是可以直接安装到已完成的根文件系统上的即插即用软件包集合。复现机器人镜像需要在构建期完成以下全部工作：

1. **添加 `meta-qcom-robotics-sdk` 层**（克隆标签 `qli-2.0`）并使用 KAS 驱动构建。普通的多媒体 KAS 片段不包含它。
2. **切换发行版**为 `qcom-robotics-distro` / `qcom-robotics-ros2-jazzy`，它会将 `ros2-jazzy` 特性引入 `DISTRO_FEATURES`。普通的 `qcom-distro` 构建没有 ROS 发行版特性。
3. **选择内核提供者并接受机器人内核更改。** 该层的 `recipe-kernel` bbappend 会添加内核配置片段和设备树（DTS）补丁，您可以选择 `linux-qcom-6.18` 或实时版 `linux-qcom-rt-6.18`。这会对内核和设备树重新打补丁，无法通过在预构建 rootfs 上安装软件包实现。
4. **使用匹配的 overlay 配置构建正确的镜像配方**，然后在设备上启用 overlay。设备端的启用工作包括驱动模块黑名单设置，以及对于摄像头，需要将 `VendorDtbOverlays` EFI 变量设置为 `camx`。参见 [Overlay 功能与驱动模块黑名单](/zh/Key-Documents/Migration-Guide/overlay-functionality-and-driver-module-blacklisting-overview)。
5. **引入 ROS 2 技术栈及其适配：** ROS 2 Jazzy 加上 `qrb-ros`、Navigation2、MoveIt 和 Cartographer 配方及 `.bbappend` 适配，普通镜像既不声明也不构建这些内容。

有关 Qualcomm Linux 2.0 中底层平台、内核和设备树的更改，请参见 [Qualcomm Linux 内核中的更改](/zh/Key-Documents/Migration-Guide/changes-in-the-qualcomm-linux-kernel)。

## 如何获取机器人镜像

### 使用预构建镜像（推荐）

刷写预构建的机器人镜像是最快且推荐的路径。

| 步骤                      | 页面                                                                           |
| ----------------------- | ---------------------------------------------------------------------------- |
| 下载预构建软件包                | [下载预构建软件包](/zh/SDKs/QIR-SDK-2.0/download-the-prebuilt-packages)              |
| 使用 Qualcomm Launcher 刷写 | [使用 Qualcomm Launcher 刷写](/zh/SDKs/QIR-SDK-2.0/flash-with-qualcomm-launcher) |
| 通过 QDL 刷写               | [刷写机器人镜像](/zh/SDKs/QIR-SDK-2.0/flash-the-robotics-image)                     |
| 设置环境                    | [设置运行示例应用的环境](/zh/SDKs/QIR-SDK-2.0/set-up-env-for-sample-app)                |

### 自行构建（可选）

<Note>
  重新构建 QIR SDK 较为复杂，大多数开发者无需这样做。除非您需要自定义镜像，否则请优先使用预构建镜像或预构建 eSDK。
</Note>

| 路径                    | 页面                                                                                                     |
| --------------------- | ------------------------------------------------------------------------------------------------------ |
| 使用 GitHub (KAS) 工作流构建 | [使用 GitHub 工作流构建](/zh/SDKs/QIR-SDK-2.0/build-with-git-hub-workflow)                                    |
| 使用 QSC-CLI 构建         | [使用 QSC-CLI 构建](/zh/SDKs/QIR-SDK-2.0/build-with-qsc-cli)                                               |
| 使用预构建机器人 eSDK 构建      | [使用预构建机器人 eSDK 构建机器人镜像](/zh/SDKs/QIR-SDK-2.0/build-the-robotics-image-with-the-prebuilt-robotics-esdk) |

### 从 Qualcomm Linux 1.0 迁移

如果您正在从 Qualcomm Linux 1.0 的机器人构建迁移，发行版、层和镜像组成模型都已发生变化。

| 主题                   | 页面                                                                               |
| -------------------- | -------------------------------------------------------------------------------- |
| 迁移概述                 | [迁移概述](/zh/SDKs/QIR-SDK-2.0/migration-overview)                                  |
| 机器人 OpenEmbedded 层更改 | [机器人 OpenEmbedded 层更改](/zh/SDKs/QIR-SDK-2.0/migration-robotics-oe-layer-changes) |
| 机器人镜像组成更改            | [机器人镜像组成更改](/zh/SDKs/QIR-SDK-2.0/migration-image-composition)                    |
| 机器人层规范               | [机器人层规范](/zh/SDKs/QIR-SDK-2.0/robotics-layers-specifications)                    |