> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs-staging.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 驱动构建。标准的 multimedia 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)                    |