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

# Enable and evaluate Qualcomm Linux overlays on QIR SDK

Qualcomm Linux overlays are modular, value-added components — sources or prebuilt binaries for technologies such as audio, camera, graphics, video, sensors, and vision — that integrate with upstream components.

Overlays let you choose between the upstream and the Qualcomm technology stacks at the platform level. For an introduction to overlays, see [Enable and evaluate Qualcomm Linux overlays](../../Key-Documents/Migration-Guide/enable-and-evaluate-qualcomm-linux-overlays).

Several QIR SDK packages and sample applications are built on top of the Qualcomm technology stacks. These packages don't run on a pure upstream image because the Qualcomm userspace libraries and out-of-tree kernel driver modules they link against are delivered as overlays.

Use the following information to:

* Match each QIR SDK image to an overlay configuration.
* Identify the overlays that each QIR SDK package and sample application depends on.
* Install the QIR SDK packages and sample applications on a device after you enable the corresponding overlays.

<Note>
  **Note**

  This page covers only the QIR SDK-specific part of the workflow. Enabling the overlays themselves is a platform-level task, which includes

  * flashing the base image
  * configuring the package feed
  * installing the overlay RPMs
  * blacklisting upstream driver modules
  * setting the Extensible Firmware Interface (EFI) variable for the camera

  For those instructions, see [Evaluate overlays using supported workflows](/Key-Documents/Migration-Guide/evaluate-overlays-using-supported-workflows).
</Note>

## Overlay configurations for QIR SDK

Qualcomm Linux groups the Qualcomm technology stacks into four verified overlay configurations, `Config #1` through `Config #4`. Each configuration defines whether the upstream or the Qualcomm stack is used for a given technology area. For the definition of each configuration and the corresponding platform image recipe, see [Use overlay configurations to derive image recipes](/Key-Documents/Migration-Guide/use-overlay-configurations-to-derive-image-recipes).

The QIR SDK image recipes are layered on top of these platform configurations. The following table maps each QIR SDK image recipe to its overlay configuration and platform image recipe.

<p style={{ textAlign: 'center', fontWeight: 'bold' }}>
  Table: QIR SDK image recipes and the corresponding overlay configurations
</p>

<table>
  <thead>
    <tr>
      <th style={{ width: '10%' }}>Overlay configuration</th>
      <th style={{ width: '20%' }}>Platform image recipe</th>
      <th style={{ width: '20%' }}>QIR SDK image recipe</th>
      <th style={{ width: '50%' }}>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`Config #1`</td>
      <td>`qcom-multimedia-image`</td>
      <td>`qcom-robotics-image`</td>
      <td><p>Full upstream stack. Includes</p>
      <ul><li>ROS 2 Jazzy</li>
      <li>open-source qrb-ros packages</li>
      <li>simulation samples</li>
      <li>third-party drivers</li>
      <li>QIR SDK artifacts</li></ul>
      No proprietary dependencies.</td>
    </tr>

    <tr>
      <td>`Config #2`</td>
      <td>`qcom-multimedia-proprietary-image`</td>
      <td>`qcom-robotics-proprietary-image`</td>
      <td><p>Full Qualcomm stack. Includes everything in `qcom-robotics-image`, plus the `qrb-ros` packages and AI sample applications that depend on the Qualcomm proprietary libraries.</p></td>
    </tr>
  </tbody>
</table>

## Installation sequence

The overlay workflow has four stages, and each stage depends on the one before it. Complete them in order:

1. [Install the multimedia overlay packages](#install-the-multimedia-overlay-packages) — enable the platform audio, camera, video, and graphics stacks.
2. [Set up the robotics DNF repository on the device](#set-up-the-robotics-dnf-repository-on-the-device) — point the device at the robotics package feed.
3. [Install the robotics overlay packages](#install-the-robotics-overlay-packages) — install the `qrb-ros` packages that depend on the overlays.
4. [Install the robotics sample applications that depend on overlays](#install-the-robotics-sample-applications-that-depend-on-overlays) — install the samples built on those packages.

## Prerequisites

Before you install the QIR SDK packages described on this page, complete the following:

1. Download prebuilt `qcom-robotics-image` (Overlay `Config #1`). For instructions, see [Download the prebuilt packages](./download-the-prebuilt-packages)
2. Flash a `qcom-robotics-image` on your device. For instructions, see [Flash the robotics image](./flash-the-robotics-image).
3. Obtain the QIR SDK RPMs for your target, using one of the following methods:
   * Download them from the Qualcomm Linux package feed. For instructions, see [Install packages from the Qualcomm Linux reference package server](../../Key-Documents/Migration-Guide/evaluate-overlays-using-supported-workflows#install-packages-from-the-qualcomm-linux-reference-package-server).
   * Build them from source. For instructions, see [Set up a local workspace](#set-up-a-local-workspace).

## Install the multimedia overlay packages

The QIR SDK packages described on this page are built on top of the Qualcomm multimedia stacks — audio, camera, video, and graphics. Qualcomm Linux delivers these stacks as platform-level multi-media overlay packages, so install the multi-media overlay packages for your target overlay configuration before you install any QIR SDK package.

Multi-media overlay setup is a platform-level task. It includes configuring the platform DNF repository, installing the overlay RPMs, blacklisting the corresponding upstream kernel modules, and — for the camera overlay — selecting the CamX device tree blob (DTB) overlay through an EFI variable.

For the `dnf install` commands, the module blacklist entries, and the EFI variable settings for each multi-media overlay, see the following sections in the Qualcomm Linux Migration Guide:

* [Install packages from the Qualcomm Linux reference package server](/Key-Documents/Migration-Guide/evaluate-overlays-using-supported-workflows#install-packages-from-the-qualcomm-linux-reference-package-server)
* [Run DNF installation commands to derive Config #2, Config #3 and Config #4](/Key-Documents/Migration-Guide/evaluate-overlays-using-supported-workflows#run-dnf-installation-commands-to-derive-config-2-config-3-and-config-4)
* [Verify the installation of RPM and driver packages](/Key-Documents/Migration-Guide/evaluate-overlays-using-supported-workflows#verify-the-installation-of-rpm-and-driver-packages)

<Note>
  **Note**

  Restart the device after you install the overlay RPMs and update the blacklist or EFI variable. The QIR SDK packages fail to load their runtime dependencies if the overlay kernel modules aren't loaded.
</Note>

## Set up the robotics DNF repository on the device

Install the QIR SDK RPMs on the device with DNF. DNF resolves the dependencies of a package from the repositories that are configured in `/etc/yum.repos.d/`. Therefore, configure the robotics repository before you run any `dnf install` command. The following steps point the device at the remote Qualcomm Linux robotics package feed on CodeLinaro.

1. Ensure that the device has network access to `https://artifacts.codelinaro.org`.

2. Create the `/etc/yum.repos.d/overlay.repo` file, and append the configuration for your target.

   * The first block is the architecture-specific feed, which is common to all the supported targets.
   * The second block is the target-specific feed.

   <CodeGroup>
     ```text IQ-9075-EVK theme={null}
     [overlay-armv8_2a]
     name = Qualcomm Overlay Repository (armv8_2a)
     baseurl = https://artifacts.codelinaro.org/qli-robotics-yocto-rpm-signed/qli-2.1/rpm/armv8_2a/
     enabled = 1
     gpgcheck = 0
     repo_gpgcheck=0

     [overlay-iq-9075-evk]
     name = Qualcomm Overlay Repository IQ-9075 EVK
     baseurl = https://artifacts.codelinaro.org/qli-robotics-yocto-rpm-signed/qli-2.1/rpm/iq-9075-evk/
     enabled = 1
     gpgcheck = 0
     repo_gpgcheck=0
     ```

     ```text IQ-8275-EVK theme={null}
     [overlay-armv8_2a]
     name = Qualcomm Overlay Repository (armv8_2a)
     baseurl = https://artifacts.codelinaro.org/qli-robotics-yocto-rpm-signed/qli-2.1/rpm/armv8_2a/
     enabled = 1
     gpgcheck = 0
     repo_gpgcheck=0

     [overlay-iq-8275-evk]
     name = Qualcomm Overlay Repository IQ-8275 EVK
     baseurl = https://artifacts.codelinaro.org/qli-robotics-yocto-rpm-signed/qli-2.1/rpm/iq-8275-evk/
     enabled = 1
     gpgcheck = 0
     repo_gpgcheck=0
     ```
   </CodeGroup>

   <Note>
     **Note**

     * `/etc/yum.repos.d/` is the directory that stores the repository configuration files. Ensure that this directory exists; if not, create it.
   </Note>

3. To refresh the package index, run the following command:

   ```bash theme={null}
   dnf update
   ```

4. To install a package, run the `dnf install` command with the package name:

   ```bash theme={null}
   # Install by package name. DNF selects the package from the configured repositories.
   dnf install <package_name> -y
   ```

   <Note>
     **Note**

     * Use `dnf install` instead of `rpm -i` so that the dependencies of the package are resolved and installed automatically.
     * To list the packages available in the configured repositories, run `dnf list available`.
   </Note>

   The `dnf install` commands for the robotics overlay packages are listed in [Install the robotics overlay packages](#install-the-robotics-overlay-packages).

## Install the robotics overlay packages

The robotics overlay packages are the QIR SDK `qrb-ros` packages that link against the Qualcomm multi-media stacks. Install them after the corresponding multi-media overlay packages are in place.

The following table lists each robotics overlay package and the multi-media overlay it depends on.

**Table: Robotics overlay packages and overlay dependencies**

| **Technology area** | **QIR SDK package**                                                                                 | **Overlay dependency**                           |
| :------------------ | :-------------------------------------------------------------------------------------------------- | :----------------------------------------------- |
| Audio               | [`qrb-ros-audio`](./enable-core-audio-with-qrb-ros-audio-service)                                   | Audio overlay (AudioReach)                       |
| Camera              | [`qrb-ros-camera`](./run-a-zero-copy-camera-with-qrb-ros-camera)                                    | Camera overlay (CamX)                            |
| Video               | [`qrb-ros-video`](./encode-and-decode-video-with-qrb-ros-video)                                     | Video overlay (`iris-video-dlkm`)                |
| Graphics            | [`qrb-ros-colorspace-convert`](./convert-between-nv-12-and-rgb-888-with-qrb-ros-colorspace-convert) | Graphics overlay (`kgsl-dlkm` and `qcom-adreno`) |
| AI inference        | [`qrb-ros-nn-inference`](./execute-ai-model-inference-with-qrb-ros-nn-inference)                    | Qualcomm AI Engine Direct SDK (`qairt-sdk`)      |

Run the commands for your technology area on the device.

<CodeGroup>
  ```bash title="Audio" theme={null}
  dnf install libqrb-audio-common-lib1 -y
  dnf install libqrb-audio-manager1 -y
  dnf install qrb-ros-audio-service-msgs -y
  dnf install qrb-ros-audio-service -y
  ```

  ```bash title="Camera" theme={null}
  # Install the packages
  dnf install qrb-camera qrb-ros-camera -y

  # Select the CamX device tree blob (DTB) overlay through the EFI variable
  echo -n "camx" > /tmp/overlay
  efivar -n 882f8c2b-9646-435f-8de5-f208ff80c1bd-VendorDtbOverlays -w -f /tmp/overlay
  efivar -n 882f8c2b-9646-435f-8de5-f208ff80c1bd-VendorDtbOverlays -p
  sync
  reboot
  ```

  ```bash title="Video" theme={null}
  dnf install qrb-ros-video -y
  dnf install libv4l2codecs1 -y
  dnf install iris-video-dlkm -y
  ```

  ```bash title="Graphics" theme={null}
  dnf install qrb-colorspace-convert-lib -y
  dnf install qrb-ros-colorspace-convert -y
  ```

  ```bash title="AI inference" theme={null}
  dnf install qairt-sdk -y
  ```
</CodeGroup>

<Note>
  **Note**

  * The preceding commands install the packages by name, so DNF resolves the version and the target-specific build from the configured repositories. If you install a local RPM file instead, the file name also includes the package version and the target-specific suffix, such as `iq_9075_evk`. Replace the version and the suffix with the values that match your release snapshot and target.
  * The `armv8_2a` packages are architecture-specific and are common to all the supported targets.
</Note>

## Install the robotics sample applications that depend on overlays

The following table lists the QIR SDK sample applications that depend on overlays, their dependencies, and the commands to install them on the device.

<Note>
  **Note**

  Install the packages listed in [Install the robotics overlay packages](#install-the-robotics-overlay-packages) before you install a sample application that depends on them. For example, `sample-apriltag` requires `qrb-ros-camera` and `qrb-ros-nn-inference`, which in turn require the camera and AI inference overlays.
</Note>

**Table: Sample applications, dependencies, and installation commands**

| **Sample application**                                                                     | **Overlay dependency**                         | **Installation command**                      |
| :----------------------------------------------------------------------------------------- | :--------------------------------------------- | :-------------------------------------------- |
| [`sample-hand-detection`](./detect-hands-with-sample-hand-detection)                       | `qrb-ros-camera`, `qrb-ros-nn-inference`       | `dnf install sample-hand-detection -y`        |
| [`sample-resnet101`](./classify-images-with-sample-resnet101)                              | `qrb-ros-camera`, `qrb-ros-nn-inference`       | `dnf install sample-resnet101 -y`             |
| [`sample-object-detection`](./detect-objects-with-sample-object-detection)                 | `qrb-ros-camera`, `qrb-ros-nn-inference`       | `dnf install sample-object-detection -y`      |
| [`sample-object-segmentation`](./segment-objects-with-sample-object-segmentation)          | `qrb-ros-camera`, `qrb-ros-nn-inference`       | `dnf install sample-object-segmentation -y`   |
| [`sample-hrnet-pose-estimation`](./estimate-human-poses-with-sample-hrnet-pose-estimation) | `qrb-ros-camera`, `qrb-ros-nn-inference`       | `dnf install sample-hrnet-pose-estimation -y` |
| [`sample-face-detection`](./detect-faces-with-sample-face-detection)                       | `qrb-ros-camera`, `qrb-ros-nn-inference`       | `dnf install sample-face-detection -y`        |
| [`sample-depth-estimation`](./estimate-image-depth-values-with-sample-depth-estimation)    | `qrb-ros-camera`, `qrb-ros-nn-inference`       | `dnf install sample-depth-estimation -y`      |
| [`sample-apriltag`](./enable-april-tag-pipeline-with-sample-apriltag)                      | `qrb-ros-camera`, `qrb-ros-colorspace-convert` | `dnf install sample-apriltag -y`              |

## Verify the installation

1. To verify that the overlay driver modules are loaded, use the `lsmod` commands listed in [Verify the installation of RPM and driver packages](../../Key-Documents/Migration-Guide/evaluate-overlays-using-supported-workflows#verify-the-installation-of-rpm-and-driver-packages).

2. To verify that a QIR SDK package is installed, run the following command:

   ```bash theme={null}
   dnf list installed | grep <package_name>
   ```

3. To verify that the ROS 2 nodes provided by the package are available, run the following commands:

   ```bash theme={null}
   source /usr/share/qirp-setup.sh
   ros2 pkg list | grep <package_name>
   ```

4. Run the corresponding sample application to confirm the end-to-end pipeline. For instructions, see [Sample applications](./qir-sdk-sample-applications).

## Uninstall the overlays

To remove the downstream RPM packages for an overlay configuration and switch back to the upstream drivers, see [Uninstall overlay configurations and switch to upstream drivers](../../Key-Documents/Migration-Guide/uninstall-overlays).

## Build the QIR SDK image and RPM packages from source

Instead of installing the prebuilt RPMs from a package feed, you can build the QIR SDK images and packages from source. Use this workflow when you want to integrate your own changes, and then flash a Config #1 image and install the overlay and QIR SDK packages generated from the Config #2 build. This is the QIR SDK equivalent of the platform workflow described in [Build locally, flash images, and use packages from the local build](../../Key-Documents/Migration-Guide/evaluate-overlays-using-supported-workflows#build-locally-flash-images-and-use-packages-from-the-local-build).

### Set up a local workspace

1. Prepare your host computer, and install the KAS tool. For instructions, see [Set up the host computer for build](./build-with-git-hub-workflow#set-up-the-host-computer-for-build).

2. To clone `meta-qcom-robotics-sdk`, run the following command:

   ```shell theme={null}
   git clone https://github.com/qualcomm-linux/meta-qcom-robotics-sdk \
   -b qli-2.1
   ```

3. To build the image for Config #1, `qcom-robotics-image`, run the following command:

   <CodeGroup>
     ```bash IQ-9075-EVK theme={null}
     kas build meta-qcom-robotics-sdk/ci/iq-9075-evk.yml:meta-qcom-robotics-sdk/ci/qcom-robotics-distro.yml:meta-qcom-robotics-sdk/ci/qcom-robotics-image.yml:meta-qcom-robotics-sdk/ci/linux-qcom-6.18.yml:meta-qcom-robotics-sdk/ci/performance.yml
     ```

     ```bash IQ-8275-EVK theme={null}
     kas build meta-qcom-robotics-sdk/ci/iq-8275-evk.yml:meta-qcom-robotics-sdk/ci/qcom-robotics-distro.yml:meta-qcom-robotics-sdk/ci/qcom-robotics-image.yml:meta-qcom-robotics-sdk/ci/linux-qcom-6.18.yml:meta-qcom-robotics-sdk/ci/performance.yml
     ```
   </CodeGroup>

4. To build the image for Config #2, `qcom-robotics-proprietary-image`, and all the packages, run the following command:

   <CodeGroup>
     ```bash IQ-9075-EVK theme={null}
     kas build meta-qcom-robotics-sdk/ci/iq-9075-evk.yml:meta-qcom-robotics-sdk/ci/qcom-robotics-distro.yml:meta-qcom-robotics-sdk/ci/qcom-robotics-proprietary-image.yml:meta-qcom-robotics-sdk/ci/linux-qcom-6.18.yml:meta-qcom-robotics-sdk/ci/performance.yml
     ```

     ```bash IQ-8275-EVK theme={null}
     kas build meta-qcom-robotics-sdk/ci/iq-8275-evk.yml:meta-qcom-robotics-sdk/ci/qcom-robotics-distro.yml:meta-qcom-robotics-sdk/ci/qcom-robotics-proprietary-image.yml:meta-qcom-robotics-sdk/ci/linux-qcom-6.18.yml:meta-qcom-robotics-sdk/ci/performance.yml
     ```
   </CodeGroup>

   <Note>
     **Note**

     `qcom-robotics-distro.yml` sets the DISTRO to `qcom-robotics-distro`, which enables package management using DNF and allows the RPMs to be installed. For the full list of supported MACHINE, DISTRO, TARGET, and KERNEL combinations, see [Build the robotics image](./build-with-git-hub-workflow#build-the-robotics-image).
   </Note>

5. Flash the `qcom-robotics-image` image built in step 3. For instructions, see [Flash the robotics image](./flash-the-robotics-image).

6. Collect the RPMs generated by the `qcom-robotics-proprietary-image` build from the `rpm` directory of the build workspace:

   ```shell theme={null}
   build/tmp/deploy/rpm
   ```

   The `rpm` directory contains the following subdirectories:

   | **Subdirectory**                 | **Content**                                                                  |
   | :------------------------------- | :--------------------------------------------------------------------------- |
   | `armv8_2a/`                      | Architecture-specific packages that are common to all the supported targets. |
   | `iq_9075_evk/` or `iq_8275_evk/` | Target-specific packages.                                                    |
   | `noarch/`                        | Architecture-independent packages.                                           |

7. Copy the RPMs to the device, and install them by following the steps in [Set up the robotics DNF repository on the device](#set-up-the-robotics-dnf-repository-on-the-device) and [Install the robotics overlay packages](#install-the-robotics-overlay-packages).