Skip to main content
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. 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.
NoteThis 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.

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

Table: QIR SDK image recipes and the corresponding overlay configurations

Overlay configurationPlatform image recipeQIR SDK image recipeDescription
Config #1qcom-multimedia-imageqcom-robotics-image

Full upstream stack. Includes

  • ROS 2 Jazzy
  • open-source qrb-ros packages
  • simulation samples
  • third-party drivers
  • QIR SDK artifacts
No proprietary dependencies.
Config #2qcom-multimedia-proprietary-imageqcom-robotics-proprietary-image

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.

​
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 — enable the platform audio, camera, video, and graphics stacks.
  2. 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 qrb-ros packages that depend on the overlays.
  4. 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
  2. Flash a qcom-robotics-image on your device. For instructions, see Flash the robotics image.
  3. Obtain the QIR SDK RPMs for your target, using one of the following methods:

​
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:
NoteRestart 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.

​
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.
    Note
    • /etc/yum.repos.d/ is the directory that stores the repository configuration files. Ensure that this directory exists; if not, create it.
  3. To refresh the package index, run the following command:
  4. To install a package, run the dnf install command with the package name:
    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.
    The dnf install commands for the robotics overlay packages are listed in 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 Run the commands for your technology area on the device.
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.

​
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.
NoteInstall the packages listed in 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.
Table: Sample applications, dependencies, and installation commands

​
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.
  2. To verify that a QIR SDK package is installed, run the following command:
  3. To verify that the ROS 2 nodes provided by the package are available, run the following commands:
  4. Run the corresponding sample application to confirm the end-to-end pipeline. For instructions, see 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.

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

​
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.
  2. To clone meta-qcom-robotics-sdk, run the following command:
  3. To build the image for Config #1, qcom-robotics-image, run the following command:
  4. To build the image for Config #2, qcom-robotics-proprietary-image, and all the packages, run the following command:
    Noteqcom-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.
  5. Flash the qcom-robotics-image image built in step 3. For instructions, see Flash the robotics image.
  6. Collect the RPMs generated by the qcom-robotics-proprietary-image build from the rpm directory of the build workspace:
    The rpm directory contains the following subdirectories:
  7. Copy the RPMs to the device, and install them by following the steps in Set up the robotics DNF repository on the device and Install the robotics overlay packages.