> ## 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) |