ROS2 Setup on NavQ95

Overview

This guide covers the full ROS2 setup sequence on a NavQ95 platform, from base installation through environment configuration and additional packages. Setup is organized into three steps:

Step	Script	Purpose	Status
1	install_ros2_base	ROS2 base installation	Available
2	install_ros2_env	Environment setup and RMW configuration	Available
3	install_ros2_pkgs	NavQ95-specific ROS2 packages	Available

Note: imx-image-robotics ships without ROS2 pre-installed. Installing ROS2 after deployment aligns with the upstream ROS2 installation model for Ubuntu-based systems.

---

Prerequisites

• imx-image-robotics deployed and booted on the NavQ95.

• The platform must have internet access so that apt can reach packages.ros.org.

---

Quick Install

Note: Please execute the following sequence of steps to ensure full versions compatibility.

# Step 1 — ROS2 base installation (latest upstream version)
install_ros2_base

# Step 2 — Environment setup and RMW configuration (latest upstream version)
install_ros2_env -l

# Step 3 — NavQ95-specific ROS2 packages (latest upstream versions)
install_ros2_pkgs -l ros-jazzy-demo-nodes-cpp ros-jazzy-rosbag2

# Step 4 — NavQ95-specific ROS2 packages (pinned version)
install_ros2_pkgs px4_msgs

Installed versions:

• ROS2 base: ros-jazzy-ros-base - latest available version

• ROS2 environment: ros-jazzy-rmw-zenoh-cpp - latest available version

• ROS2 packages:

  • ros-jazzy-demo-nodes-cpp - latest available version

  • ros-jazzy-rosbag2 - latest available version

  • px4_msgs - default fixed release/1.17

Both install_ros2_env and install_ros2_pkgs support all of the following flags, while install_ros2_base only supports the [-i] [-h] flags. — run <script_name> -h for details:

<script_name> [-i] [-l] [-h]

  (no flags)  Non-interactive: run all steps unattended, installs fixed version(s)
  -i          Interactive: prompt [Y/n] before each step
  -l          Latest: install latest upstream packages (ignoring pinned ROS_FIXED_VERSION)
  -h          Show this help and exit

Flags can be combined, e.g.: <script_name> -i -l

---

Installation — ROS2 Base

Overview

install_ros2_base installs ros-jazzy-ros-base following the official ROS 2 Jazzy deb installation steps. It always installs the latest upstream version if ROS2 is not already installed — no version pinning or apt-mark hold is applied.

Note: If ros-jazzy-ros-base is already installed, the script detects it automatically. If the installed version matches the latest, the install step is skipped. If it is older, the script prompts for an upgrade (auto-upgrade after 10 seconds).

It also installs ros-dev-tools and reports the active ROS2 distro, middleware, and installed package version.

Option A: Automated

Run on the platform:

install_ros2_base

Expected output on success:

ROS2 Jazzy base installer -- mode: non-interactive, version: latest upstream

=== Step 1/7: Set locale (UTF-8) ===
...
=== Step 7/7: Report installation ===
ROS_DISTRO = jazzy
middleware name    : rmw_fastrtps_cpp
ros-jazzy-ros-base installed version: <version>

SUCCESS. All steps completed.
NOTE: ROS2 is not yet active in this shell. Run: source /opt/ros/jazzy/setup.bash

On failure, if a shell command exits with a non-zero status (e.g. apt update fails due to no network), the script exits immediately and prints:

ERROR: Installation aborted at line <N>. Fix the issue above and re-run the script.
Tip: use -i for step-by-step control (prompt before each step).

Fix the reported issue and re-run. The script is idempotent — safe to re-run. Use -i to step through and skip already-completed steps:

install_ros2_base -i

Option B: Manual

Follow the official ROS 2 Jazzy installation guide: https://docs.ros.org/en/jazzy/Installation/Ubuntu-Install-Debs.html

Verification

After completing the base installation:

source /opt/ros/jazzy/setup.bash
printenv | grep ROS_DISTRO                          # -> ROS_DISTRO=jazzy
dpkg-query -W -f='${Version}\n' ros-jazzy-ros-base  # -> <version>
ros2 doctor --report | grep -i "middleware name"    # -> rmw_fastrtps_cpp (default)

Troubleshooting

No internet access — the platform requires internet access to reach packages.ros.org. Verify connectivity before running any script:

curl -I https://packages.ros.org

Re-running after a failure — all scripts are idempotent, safe to re-run after fixing the reported issue. Use -i to be prompted before each step:

install_ros2_base -i
# Answer [Y/n] before each step; press Enter to run, n to skip

---

Installation — ROS2 Environment

Overview

install_ros2_env configures the ROS2 Jazzy environment for the NavQ95 by:

1. Installing ros-jazzy-rmw-zenoh-cpp (Zenoh RMW middleware).

2. Generating a persistent ROS2 environment config file (~/.ros2rc) that sources ROS2 Jazzy and sets RMW_IMPLEMENTATION=rmw_zenoh_cpp.

3. Reporting the installed versions and active configuration.

Option A: Automated

Run on the platform:

install_ros2_env

The script installs the following NavQ95-validated fixed version of ros-jazzy-rmw-zenoh-cpp (arm64):

ros-jazzy-rmw-zenoh-cpp=0.2.9-1noble.20260612.051449

To install a specific build, override the fixed version before running:

export ZENOH_FIXED_VERSION=<version>
install_ros2_env

To install the latest upstream version instead, use the -l (latest) flag — it will ignore the pinned ZENOH_FIXED_VERSION:

install_ros2_env -l

The generated ~/.ros2rc file activates ROS2 Jazzy and selects the Zenoh RMW:

# Activate ROS2 Jazzy
source /opt/ros/jazzy/setup.bash

# Use Zenoh as the RMW implementation
export RMW_IMPLEMENTATION=rmw_zenoh_cpp

To change the output path, override ROS2RC_PATH before running:

export ROS2RC_PATH=/custom/path/ros2rc
install_ros2_env

Expected output on success:

ROS2 Jazzy env configurator -- mode: non-interactive, version: fixed ros-jazzy-rmw-zenoh-cpp (<version>)

=== Step 1/3: Install ros-jazzy-rmw-zenoh-cpp (fixed <version>) ===
...
ros-jazzy-rmw-zenoh-cpp set on hold.

=== Step 2/3: Generate ros2rc environment config ===
Generating /home/<user>/.ros2rc ...
ros2rc written to /home/<user>/.ros2rc

=== Step 3/3: Report installation ===
ROS_DISTRO            = jazzy
RMW_IMPLEMENTATION    = rmw_zenoh_cpp
ros-jazzy-rmw-zenoh-cpp installed version: <version>
ros2rc path           = /home/<user>/.ros2rc

SUCCESS. All steps completed.
To activate the ROS2 Zenoh environment, run:
  source /home/<user>/.ros2rc

To activate automatically on every login, add it to the shell startup script:
  echo "source /home/<user>/.ros2rc" >> ~/.bashrc

On failure, the script exits immediately and prints:

ERROR: Installation aborted at line <N>. Fix the issue above and re-run the script.
Tip: use -i for step-by-step control (prompt before each step).

Fix the reported issue and re-run. The script is idempotent — safe to re-run. Use -i to step through and skip already-completed steps:

install_ros2_env -i

Option B: Manual

Install the Zenoh RMW package manually:

sudo apt update
sudo apt install ros-jazzy-rmw-zenoh-cpp=<version>
sudo apt-mark hold ros-jazzy-rmw-zenoh-cpp

Then create ~/.ros2rc:

cat > ~/.ros2rc <<'EOF'
# ros2rc -- NavQ95 ROS2 environment configuration
source /opt/ros/jazzy/setup.bash
export RMW_IMPLEMENTATION=rmw_zenoh_cpp
EOF
chmod 644 ~/.ros2rc

Verification

After completing the environment setup:

source ~/.ros2rc
printenv | grep RMW_IMPLEMENTATION                              # -> RMW_IMPLEMENTATION=rmw_zenoh_cpp
dpkg-query -W -f='${Version}\n' ros-jazzy-rmw-zenoh-cpp        # -> <version>

Troubleshooting

/opt/ros/jazzy/setup.bash not found — the ROS2 base installation must be completed first:

install_ros2_base

Re-running after a failure — the script is idempotent, safe to re-run after fixing the reported issue. Use -i to be prompted before each step:

install_ros2_env -i
# Answer [Y/n] before each step; press Enter to run, n to skip

---

Installation — ROS2 Packages

Overview

install_ros2_pkgs installs a set of NavQ95-specific ROS2 packages on top of the ROS2 base and environment setup. Each package is installed at a NavQ95-validated fixed version and held to prevent unintended upgrades.

Packages installed:

ros-jazzy-demo-nodes-cpp      (0.33.11-1noble.20260612.180159)   # demo nodes (talker/listener)
ros-jazzy-rosbag2             (0.26.11-1noble.20260612.202546)   # record and play back topics
px4_msgs                      (release/1.17)                     # PX4 uORB message definitions

Prerequisite: ROS2 base must be installed first (install_ros2_base). Some packages may also require the ROS2 environment setup (install_ros2_env).

Note: px4_msgs build scope. px4_msgs is built from source on the board. By default, only the message definitions required by the T1 usecase (DistanceSensor.msg and Sensor*.msg) are compiled, instead of the full set of 200+ messages. This reduces build time by roughly 90%, down to about 3 minutes (versus 30-60 minutes for the full set). Use the --all-px4-msgs flag to build every message definition instead.

Install

Run on the platform:

install_ros2_pkgs

Each package is installed at its fixed version and held via apt-mark hold to prevent unintended upgrades.

To install a specific build, override the fixed version before running (one variable per package, ROS2PKG_<ID>_VERSION):

export ROS2PKG_<ID>_VERSION=<version>
install_ros2_pkgs

To install the latest upstream versions instead, use the -l (latest) flag — it will ignore the fixed versions:

install_ros2_pkgs -l

To build px4_msgs with every message definition (instead of only the T1-required subset), use the --all-px4-msgs flag:

install_ros2_pkgs --all-px4-msgs

By default all packages are installed; pass package names to install only a subset. Examples:

install_ros2_pkgs                          # install all packages
install_ros2_pkgs ros-jazzy-rosbag2        # install only the named package
install_ros2_pkgs -i                       # prompt before each package
install_ros2_pkgs -i -l px4_msgs           # flags and packages combine
install_ros2_pkgs --all-px4-msgs           # build all px4_msgs messages

Run install_ros2_pkgs -h to see the available packages and usage.

On success, the script prints each package it installed, a version report, and any post-install usage tips, ending with a SUCCESS line:

ROS2 Jazzy package installer -- mode: <mode>, version: <version-mode>

=== Install <package-name> (<version-mode>) ===
...

=== Report installation ===
<package-name> installed version: <version>

SUCCESS. All packages completed.

=== Usage: <package-name> ===
<post-install usage tips>

On failure it aborts immediately and prints the failing step. Fix the reported issue and re-run — the script is idempotent. Use -i to be prompted before each package:

install_ros2_pkgs -i

Verification

Confirm each package is installed at the expected version:

dpkg-query -W -f='${Version}\n' <package-name>

For a functional check, follow the usage tips printed by the script at the end of the installation.

Troubleshooting

Re-running after a failure — the script is idempotent, safe to re-run after fixing the reported issue. Use -i to be prompted before each package:

install_ros2_pkgs -i
# Answer [Y/n] before each package; press Enter to run, n to skip

---

Known issues

Some of the ROS2 components containing fixed versions in the scripts are obsolete and failing to install, for full compatibility please execute the scripts as instructed in the quick install section and check which versions have been tested in the build release notes.

---

Version History

Version	Description
v7	install_ros2_base: remove fixed-version and apt-mark hold; script installs latest version install_ros2_env, install_ros2_pkgs: add note to use -l flag as fixed versions are no longer available for installation
v6	install_ros2_pkgs: px4_msgs now builds only T1-required messages (DistanceSensor, Sensor*) by default. Add --all-px4-msgs flag to build all messages
v5	install_ros2_base: add early version conflict check; apt-mark hold only applied in fixed-version mode
v4	install_ros2_pkgs: NavQ95-specific ROS2 packages (available)
v3	install_ros2_base: add Overview section
v2	install_ros2_env: environment setup and Zenoh RMW configuration (available)
v1	Doc restructure (platform terminology, quick install) install_ros2_base: add -l (latest) and -h flags
v0	Initial release — install_ros2_base (base ROS2 installation)