ROS2-Driver for Basler Cameras

The official pylon ROS2 driver under Jazzy Jalisco for Basler GigE Vision and USB3 Vision 2D cameras, and for Basler 3D cameras (the blaze, the Stereo ace and the Stereo mini).

This driver provides many functionalities available through the Basler pylon Camera Software Suite C++ API.

Please Note: This project is offered with no technical support by Basler AG. You are welcome to post any questions or issues on GitHub

Installation

Prerequisites

• From Ubuntu 24.04 Noble Numbat
• From ROS2 Jazzy Jalisco. Your ROS2 environment must be configured, your workspace created, and colcon, used to build the packages, installed.
• rosdep. rosdep must be installed as a debian package (sudo apt update && sudo apt install python3-rosdep && sudo rosdep init && rosdep update).
• From pylon Camera Software Suite version 26.07 or newer.
• (3D cameras only) Each Basler 3D camera (blaze, Stereo ace, and Stereo mini) needs its own pylon Supplementary Package, installed in addition to the pylon Camera Software Suite: pylon Supplementary Package for blaze (version 1.7.3 or newer for the blaze, version 1.2.2 or newer for the Stereo ace, and version 1.0.8 or newer for the Stereo mini). Compatibility with the installed pylon Camera Software Suite must be ensured (please refer to the documentation). The API libraries must be installed manually: download and install the corresponding Linux Debian Installer Package for your architecture.
• Git. Git must be installed as a debian package (sudo apt update && sudo apt install git).
• xterm. The xterm terminal emulator must be installed (refer to the Known Issues section below) as a debian package (sudo apt update && sudo apt install xterm).

Install and build the packages

This repository including the pylon ROS2 packages must be cloned in your workspace (e.g., dev_ws for instance):

cd ~/dev_ws/src && git clone -b jazzy https://github.com/basler/pylon-ros-camera pylon_ros2_camera

Install the ROS2 dependencies required by the pylon ROS2 packages:
cd ~/dev_ws && rosdep install --from-paths src --ignore-src -r -y
You may experience some problems with the diagnostic_updater and pcl_ros dependencies. In this case, install them by executing the following commands:

sudo apt install ros-jazzy-diagnostic-updater
sudo apt install ros-jazzy-pcl-ros

Compile the workspace using colcon:
cd ~/dev_ws && colcon build

Note: The –symlink-install flag can be added to the colcon build command. This allows the installed files to be changed by changing the files in the source space (e.g., Python files or other not compiled resources) for faster iteration (refer to the ROS2 documentation).

Note: The packages are built in Release by default. The build type can be modified by using the --cmake-args flag (for instance colcon build --symlink-install --cmake-args=-DCMAKE_BUILD_TYPE=Debug).

Source the environment:
cd ~/dev_ws && . install/setup.bash

Note: This step can be skipped if the setup.bash file is sourced in your .bashrc.

Start the driver:
ros2 launch pylon_ros2_camera_wrapper pylon_ros2_camera.launch.py to start the acquisition from a 2D camera, or
ros2 launch pylon_ros2_camera_wrapper pylon_ros2_camera.launch.py profile:=3d to start the acquisition from a 3D camera.

Docker

Ready-to-use Docker images are available for Humble, Jazzy, and Kilted.
They bundle the driver and all its dependencies into a self-contained container, so no local ROS 2 installation is required.

For build instructions, run options, and troubleshooting, refer to the docker/README.md.

Usage in a nutshell

Starting the pylon_ros2_camera_node starts the acquisition from a given Basler camera. The nodes allow as well to access many camera parameters and parameters related to the grabbing process itself.

The pylon_ros2_camera_node can be started thanks to a dedicated launch file thanks to the command:
ros2 launch pylon_ros2_camera_wrapper pylon_ros2_camera.launch.py
The profile launch argument selects the camera type: profile:=2d (default) starts a 2D camera and profile:=3d starts a 3D camera.
Several parameters can be set through the launch file and the user parameter file loaded through it. profile:=2d loads pylon_ros2_camera_wrapper/config/default_2d.yaml (default); profile:=3d loads pylon_ros2_camera_wrapper/config/default_3d.yaml. Per-camera launch files can load their own file, such as my_blaze.yaml, my_stereo_ace.yaml, and my_stereo_mini.yaml (these are launch file examples and should adapted accordingly).

Acquisition from a specific camera is possible by setting the device_user_id parameter. If no specific camera is specified, the first available camera is connected automatically.

The pylon node defines the different interface names according to the following convention:
[Camera name (= my_camera by default)]/[Node name (= pylon_ros2_camera_node)]/[Interface name]
The camera and the node names can be set thanks respectively to the camera_name and node_name parameters.

Acquired images and point clouds are published through the [Camera name]/[Node name]/[image_raw/confidence_3d/depth_map_3d/depth_map_color_3d/intensity_3d/intensity_left_3d/intensity_right_3d/cloud_3d] topics, only if a subscriber to these topics has been registered.
To visualize the images and point clouds, rqt and rviz2 can be used. Beware that rviz2 is not able to vizualize correctly images encoded in Bayer.

When available, specific user set can be specified thanks to the startup_user_set parameter.
ros2 launch pylon_ros2_camera_wrapper pylon_ros2_camera.launch.py startup_user_set:=Default or ros2 launch pylon_ros2_camera_wrapper pylon_ros2_camera.launch.py startup_user_set:=UserSet1 or ros2 launch pylon_ros2_camera_wrapper pylon_ros2_camera.launch.py startup_user_set:=UserSet2 or ros2 launch pylon_ros2_camera_wrapper pylon_ros2_camera.launch.py startup_user_set:=UserSet3

Beware that some parameters implemented by the driver, like for instance the parameter startup_user_set, can be set through 1. the pylon_ros2_camera_wrapper/config/default_2d.yaml user parameter file, 2. the pylon_ros2_camera.launch.py driver launch file, and 3. the command line arguments of the launch command to start the driver. A parameter value set as an argument of the launch command to start the driver will overwrite the value set in the driver launch file itself, that will overwrite the value set in the user parameter file.

Acquisition mode and frame rate

From version 3.1.0, the driver allows free run as well as sequentially triggered acquisition by software trigger.

When starting the driver, the maximum acquisition frame rate that can be reached according to the current camera settings is displayed (for further information, please refer to the Basler documentation). If this frame rate is lower than the one specified in the driver configuration file, the latter is updated accordingly. It is generally not possible to change the acquisition frame rate when the driver is running.

Free run acquisition is set when the driver starts and loads the Default user set. Otherwise, if another user set is loaded, including CurrentSetting, the driver does not modify any parameter related to the acquisition, keeping the ones defined by the user. Setting a specific user set can be specified in the driver launch file. By default, the driver load the CurrentSetting user set.

• Free run is enabled by setting the following parameters:

``` AcquisitionMode = Continuous TriggerSelector = FrameStart

File truncated at 100 lines see the full file