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
TriggerMode = Off

• Software triggering is enabled by setting the following parameters:

TriggerSelector = FrameStart
TriggerSource = Software
TriggerMode = On

More information about acquisition modes can be found here. The driver does not currently give access to the AcquisitionMode parameter and if the TriggerSource parameter is not modified, switching from free run to software triggering can be done by setting the TriggerMode parameter from Off to On, and vice versa.

Generally speaking, to increase the acquisition frame rate when using the driver, consider when possible and applicable:

• Switch to free run.
• Changing the image encoding to Bayer or Mono ones.
• Setting a region of interest.
• Decreasing the exposure time.
• Decreasing the inter-packet delay and setting it to 0 if possible.
• Setting the enable_current_params_publisher parameter to false (it is set to false by default).
• Following the additional suggestions specified in the Basler documentation.
• Commenting and modifying the different operations executed in PylonROS2CameraNode::spin(). In addition to grabbing, it checks if the camera is disconnected, publishes images and current settings if there are some subscribers, rectifies images if calibration parameters are available, etc. Beware though that the frame rate increase will not be significant and that the standard driver behaviors will not be guaranteed.

The interested readers can refer to the following discussions for more information: #21, #28, #29, #81, #116, #147, #200.

Image pixel encoding

The pylon ROS2 driver support currently the following ROS2 image pixel formats :

* mono8	        (Basler Format : Mono8)
* mono16	(Basler Format : Mono16, Mono12)        (Notes 1&2)
* bgr8 		(Basler Format : BGR8)
* rgb8 		(Basler Format : RGB8)
* bayer_bggr8 	(Basler Format : BayerBG8)
* bayer_gbrg8 	(Basler Format : BayerGB8)
* bayer_rggb8 	(Basler Format : BayerRG8)
* bayer_grbg8 	(Basler Format : BayerRG8)
* bayer_rggb16	(Basler Format : BayerRG16, BayerRG12)  (Notes 1&2)
* bayer_bggr16 	(Basler Format : BayerBG16, BayerBG12)  (Notes 1&2)
* bayer_gbrg16 	(Basler Format : BayerGB16, BayerGB12)  (Notes 1&2)
* bayer_grbg16 	(Basler Format : BayerGR16, BayerGR12)  (Notes 1&2)

More information about the image encoding can be found in the Basler documentation.

NOTES:

1 : 12-bits image will be remapped to 16-bits using bit shifting to make it work with the ROS2 16-bits sensor standard message.

2 : When the user calls the set_image_encoding service to use 16-bits encoding, the driver will check first for the availability of the requested 16-bits encoding to set it, when the requested 16-bits image encoding is not available, then the driver will check the availability of the equivalent 12-bits encoding to set it. When both 16-bits and 12-bits image encoding are not available then an error message will be returned.

Intrinsic calibration and rectified images

ROS2 includes a standardised camera intrinsic calibration process through the camera_calibration package. This calibration process generates a file, which can be processed by the pylon ROS2 driver by setting the camera_info_url parameter in the pylon_ros2_camera_wrapper/config/default_2d.yaml file (it is the user parameter file loaded by default through the driver main launch file) to the correct URI (e.g., file:///home/user/data/calibrations/my_calibration.yaml).

If the calibration is valid, the rectified images are published through the [Camera name]/[Node name]/[image_rect] topic, only if a subscriber to this topic has been registered.

Setting device user id

It is easily possible to connect to a specific camera through its user id. This user id can be set through the parameter device_user_id listed in the .yaml user parameter file loaded at launch time (by default pylon_ros2_camera_wrapper/config/default_2d.yaml). It is up to the user to create specific launch files, loading specific .yaml user parameter files, which would specify the user ids of the cameras that need to be connected. If no specific camera is specified, either because the device_user_id parameter is not set or no .yaml user parameter file is loaded, the first available camera is connected automatically.

In addition to being able to do so through the pylon Viewer provided by Basler, it is possible to set the device user id with the command: ros2 run pylon_ros2_camera_component set_device_user_id [-sn SERIAL_NB] your_device_user_id. If no serial number is specified thanks to the option -sn, the specified device user id your_device_user_id will be assigned to the first available camera. USB cameras must be disconnected and then reconnected after setting a new device user id. USB cameras keep their old user id otherwise.

3D cameras

The driver supports the Basler 3D cameras (the blaze, the Stereo ace, and the Stereo mini) in addition to the 2D cameras. A 3D camera is started with the profile:=3d launch argument or with its dedicated launch file. All 3D cameras share the same topics; the camera-specific settings are exposed through additional services.

3D topics

The following topics are published when a subscriber is registered:

Topic	Type	Content
[Camera name]/[Node name]/cloud_3d	sensor_msgs/PointCloud2	3D point cloud
[Camera name]/[Node name]/depth_map_3d	sensor_msgs/Image	Depth map
[Camera name]/[Node name]/depth_map_color_3d	sensor_msgs/Image	Color-coded depth map
[Camera name]/[Node name]/intensity_3d	sensor_msgs/Image	Intensity image
[Camera name]/[Node name]/confidence_3d	sensor_msgs/Image	Per-pixel confidence map
[Camera name]/[Node name]/camera_info_3d	sensor_msgs/CameraInfo	Calibration data of the 3D stream
[Camera name]/[Node name]/intensity_left_3d	sensor_msgs/Image	Left intensity image (stereo cameras)
[Camera name]/[Node name]/intensity_right_3d	sensor_msgs/Image	Right intensity image (stereo cameras)
[Camera name]/[Node name]/imu	sensor_msgs/Imu	IMU readings (Stereo mini, when imu_enabled is true)

3D data acquisition action

A full 3D acquisition can be requested through the ~/grab_3d_data action. The result contains the point clouds, depth maps, color-coded depth maps, intensity maps, confidence maps, and the camera info collected during the acquisition.

Camera-specific settings

Some settings are common to all 3D cameras, while others depend on the camera model. The depth range unit differs per model (millimeters for the blaze and the Stereo mini, meters for the Stereo ace).

Common to all 3D cameras:

Setting	Service
Depth range	set_depth_min, set_depth_max
HDR mode	enable_hdr_mode

blaze:

Setting	Service
Operating mode	set_operating_mode
Fast mode	enable_fast_mode
Confidence threshold	set_confidence_threshold
Spatial filter	enable_spatial_filter
Temporal filter	enable_temporal_filter, set_temporal_filter_strength
Outlier removal	enable_outlier_removal, set_outlier_removal_threshold, set_outlier_removal_tolerance
Ambiguity filter	enable_ambiguity_filter, set_ambiguity_filter_threshold

Stereo ace:

Setting	Service
Illumination mode	set_illumination_mode
Depth quality	set_depth_quality
Confidence threshold	set_confidence_threshold
Static scene	enable_static_scene
Depth smoothing	enable_depth_smooth
Depth fill	set_depth_fill
Depth segmentation	set_depth_seg
HDR sub-exposure selector	set_hdr_exposure_time_selector
HDR sub-exposure time	set_hdr_exposure_time
HDR sub-exposure count	set_hdr_sub_exposures
Auto exposure mode (Off/Continuous/HDR)	set_exposure_auto_mode

Stereo mini:

Setting	Service
Depth preset	set_operating_mode
Projector	enable_projector, set_projector_level
HDR sequence index	set_hdr_sequence_index
HDR sequence preset	set_hdr_sequence_preset, load_hdr_preset
HDR max exposure	set_hdr_max_exposure
HDR frame merging	enable_hdr_merge, enable_hdr_merge_use_ir

Current 3D parameters

When the current parameters publisher is enabled, the current_params topic also reports the current 3D settings (depth range, operating mode, HDR mode, filters, projector, illumination mode, depth quality, and so on). A field that does not apply to the connected camera is set to -1 (or -1.0 for the float fields).

IMU (Stereo mini)

The Stereo mini has a built-in IMU. When imu_enabled is set to true, the driver publishes the accelerometer and gyroscope readings on the imu topic as sensor_msgs/Imu messages. Values are in SI units (m/s² for linear_acceleration, rad/s for angular_velocity). The IMU does not provide orientation, so orientation_covariance[0] is set to -1 following REP 145. The linear_acceleration_covariance and angular_velocity_covariance matrices are left at zero, meaning the covariance is not characterized. Each message is stamped with the IMU hardware timestamp mapped to the ROS clock, not the host arrival time.

The IMU is published from a dedicated thread at its hardware rate, independent of the image acquisition rate, so the samples arrive smoothly even when the 3D frame rate is much lower.

The imu topic uses the default QoS (reliable, queue depth 100).

Parameter	Default	Description
imu_enabled	false	Enables the IMU and the imu topic.
imu_frame_rate	0	IMU sampling rate in Hz (e.g. 200). 0 keeps the camera default.

Both parameters are read once at startup. They are set in the camera configuration file; the launch files do not expose them as launch arguments.

Example: enable the IMU in the Stereo mini config, then read the topic.

Set the parameters in pylon_ros2_camera_wrapper/config/my_stereo_mini.yaml:

    imu_enabled: true
    imu_frame_rate: 200

Start the driver and read the topic:

ros2 launch pylon_ros2_camera_wrapper my_stereo_mini.launch.py

# Print the IMU messages (default QoS):
ros2 topic echo /my_stereo_mini/pylon_ros2_camera_node/imu

# Check the publishing rate:
ros2 topic hz /my_stereo_mini/pylon_ros2_camera_node/imu

The topic name follows the [Camera name]/[Node name]/imu convention, so replace accordingly with this example my_stereo_mini and pylon_ros2_camera_node with the camera_name and node_name you launched with.

Packages

• pylon_ros2_camera_component: the driver itself. The package includes the main pylon_ros2_camera_node developed as a component.
• pylon_ros2_camera_wrapper: wrapper creating the main component pylon_ros2_camera::PylonROS2CameraNode implemented in the pylon_ros2_camera_component package. The wrapper starts the driver in a single process.
• pylon_ros2_camera_interfaces: package implementing pylon_ros2_camera_node interfaces (messages, services and actions).

Parameters

Common parameters

• camera_frame
  The tf2 frame under which the images were published.
  ROS2 provides a library called tf2 (TransForm version 2) to manage the coordinate transformations between the different frames (coordinate systems) defined by the user and assigned to the components of a robotics system.

• device_user_id
  The DeviceUserID of the camera. If empty, the first camera found in the device list will be used.

• camera_info_url
  The CameraInfo URL (Uniform Resource Locator) where the optional intrinsic camera calibration parameters are stored. This URL string will be parsed from the CameraInfoManager.

• image_encoding
  The encoding of the pixels -- channel meaning, ordering, size taken from the list of strings in include file sensor_msgs/image_encodings.h. The supported encodings are 'mono8', 'bgr8', 'rgb8', 'bayer_bggr8', 'bayer_gbrg8' and 'bayer_rggb8'. Default values are 'mono8' and 'rgb8'.

• binning_x & binning_y
  Binning factor to get downsampled images. It refers here to any camera setting which combines rectangular neighborhoods of pixels into larger "super-pixels." It reduces the resolution of the output image to (width / binning_x) x (height / binning_y). The default values binning_x = binning_y = 0 are considered the same as binning_x = binning_y = 1 (no subsampling).

• downsampling_factor_exposure_search
  To speed up the exposure search, the mean brightness is not calculated on the entire image, but on a subset instead. The image is downsampled until a desired window hight is reached. The window hight is calculated out of the image height divided by the downsampling_factor_exposure search.

• frame_rate
  The desired acquisition frame rate corresponding to the driver spinning frame rate. Calling the GrabImages-Action can result in a higher frame rate.

• shutter_mode
  Set mode of camera's shutter if the value is not empty. The supported modes are 'rolling', 'global' and 'global_reset'. Default value is '' (empty)

• white_balance_auto
  Camera white balance auto.

• white_balance_ratio_red & white_balance_ratio_green & white_balance_ratio_blue
  Camera white balance ratio.

• trigger_timeout
  Timeout in ms. Only relevant when using software trigger mode. Limits how long the driver waits for the camera to become ready to accept the next software trigger command. This parameter has no effect for cameras driven by a hardware (external) trigger.

• grab_timeout
  Timeout in ms. Limits how long the driver waits for image data to arrive after a grab is initiated. In free-run mode, must be greater than the inter-frame period (e.g. >100 ms at 10 fps). For external (hardware) trigger mode, must be long enough to cover the maximum expected interval between trigger pulses. Increase this value if triggers arrive less frequently than once per 500 ms (the default), otherwise grab timeouts will occur.

• grab_strategy
  Camera grab strategy: 0 = GrabStrategy_OneByOne / 1 = GrabStrategy_LatestImageOnly / 2 = GrabStrategy_LatestImages

Image Intensity Settings

The following settings do NOT have to be set. Each camera has default values which provide an automatic image adjustment resulting in valid images.

• exposure
  The exposure time in microseconds to be set after opening the camera.

• gain
  The target gain in percent of the maximal value the camera supports. For USB cameras, the gain is in dB, for GigE cameras it is given in so called 'device specific units'.

• gamma
  Gamma correction of pixel intensity. Adjusts the brightness of the pixel values output by the camera's sensor to account for a non-linearity in the human perception of brightness or of the display system (such as CRT).

• brightness
  The average intensity value of the images. It depends on the exposure time as well as the gain setting. If 'exposure' is provided, the interface will try to reach the desired brightness by only varying the gain. (What may often fail, because the range of possible exposure values is many times higher than the gain range). If 'gain' is provided, the interface will try to reach the desired brightness by only varying the exposure time. If 'gain' AND 'exposure' are given, it is not possible to reach the brightness, because both are assumed to be fixed.

• brightness_continuous
  Only relevant, if 'brightness' is set. The brightness_continuous flag controls the auto brightness function. If it is set to false, the brightness will only be reached once. Hence changing light conditions lead to changing brightness values. If it is set to true, the given brightness will be reached continuously, trying to adapt to changing light conditions. This is only possible for values in the possible auto range of the pylon API which is generally [50 - 205].

• exposure_auto & gain_auto
  Only relevant, if 'brightness' is set. If the camera should try to reach and / or keep the brightness, hence adapting to changing light conditions, at least one of the following flags must be set. If both are set, the interface will use the profile that tries to keep the gain at minimum to reduce white noise. The 'exposure_auto' flag indicates, that the desired brightness will be reached by adapting the exposure time. The 'gain_auto' flag indicates, that the desired brightness will be reached by adapting the gain.

Optional and device specific parameter

• exposure_search_timeout
  The timeout while searching the exposure which is connected to the desired brightness. For slow system this has to be increased.

• auto_exposure_upper_limit
  The exposure search can be limited with an upper bound. This is to prevent very high exposure times and resulting timeouts. A typical value for this upper bound is ~2000000us. Beware that this upper limit is only set if startup_user_set is set to Default.

• mtu_size
  The MTU size. Only used for GigE cameras. To prevent lost frames configure the camera has to be configured with the MTU size the network card supports. A value greater 3000 should be good (1500 for single-board computer)

• inter_pkg_delay
  The inter-packet delay in ticks to prevent frame loss, support the network bandwith priorisation. Generally needs to modified if more than one cameras is involved or if hardware is not performing well. Raise inter-packet delay (GevSCPD) for solving error: 'the buffer was incompletely grabbed': https://docs.baslerweb.com/knowledge/troubleshooting-error-code-3774873620-0xe1000014-with-gige-cameras. For most of GigE cameras, a value of 1000 is reasonable. For cameras used on a single-board computer this value should be set to 11772. Beware that the inter-packet delay decrease will result in frame rate reduction.

• frame_transmission_delay
  In most cases, this parameter should be set to 0. However, if your network hardware can't handle spikes in network traffic (e.g., if you are triggering multiple camera simultaneously), you can use the frame transmission delay parameter to stagger the start of image data transmissions from each camera.

• auto_flash
  Flag that indicates if the camera has a flash connected, which should be on exposure. Only supported for GigE cameras. Default: false.

• auto_flash_line_2
  Flag that indicates if the camera has a flash connected on line 2, which should be on exposure. Only supported for GigE cameras. Default: true.

• auto_flash_line_3
  Flag that indicates if the camera has a flash connected on line 3, which should be on exposure. Only supported for GigE cameras. Default: true.

ROS2 pylon node specific parameter

• startup_user_set
  Flag specifying if a given user set is used when starting the camera. Can be set to Default, UserSet1, UserSet2, UserSet3, and CurrentSetting.

• enable_status_publisher
  Flag used to enable/disable the node status publisher.

• enable_current_params_publisher
  Flag used to enable/disable the current camera publisher.

3D camera parameters

• stereo_ace_illumination_mode
  Illumination mode for the Stereo ace IR projector. AlwaysActive (default): the projector is always on; this is the Basler-recommended mode for depth quality, but the IR dot pattern is visible in the intensity images. AlternateActive: exposures alternate with and without the projector, so the intensity images are free of the IR dot pattern. Off: the projector is disabled (passive stereo). This parameter has no effect on the blaze or the Stereo mini.

PTP synchronization

The Precision Time Protocol (PTP) camera feature allows you to synchronize multiple GigE cameras in the same network. It enables a camera to use the following features, if available:

• Scheduled Action Commands & Action Commands
• Synchronous Free Run (applies to ace 1 cameras)
• Periodic Signal (applies to ace 2 cameras)

Refer to the documentation for more info about these features, with multiple code samples.

The pylon driver gives accordingly access through ROS2 services to the following parameters and commands:

ACE 1

PTP configuration & activation

• GevIEEE1588 -> /my_camera/pylon_ros2_camera_node/enable_ptp [std_srvs/srv/SetBool]

Scheduled Action Commands & Action Commands

• ActionDeviceKey -> /my_camera/pylon_ros2_camera_node/set_action_trigger_configuration [pylon_ros2_camera_interfaces/srv/SetActionTriggerConfiguration]
• ActionGroupKey -> /my_camera/pylon_ros2_camera_node/set_action_trigger_configuration [pylon_ros2_camera_interfaces/srv/SetActionTriggerConfiguration]
• ActionGroupMask -> /my_camera/pylon_ros2_camera_node/set_action_trigger_configuration [pylon_ros2_camera_interfaces/srv/SetActionTriggerConfiguration]
• IssueScheduledActionCommand -> /my_camera/pylon_ros2_camera_node/issue_scheduled_action_command [pylon_ros2_camera_interfaces/srv/IssueScheduledActionCommand]
• IssueActionCommand -> /my_camera/pylon_ros2_camera_node/issue_action_command [pylon_ros2_camera_interfaces/srv/IssueActionCommand]

Synchronous Free Run

• SyncFreeRunTimerStartTimeLow -> /my_camera/pylon_ros2_camera_node/set_sync_free_run_timer_start_time_low [pylon_ros2_camera_interfaces/srv/SetIntegerValue]
• SyncFreeRunTimerStartTimeHigh -> /my_camera/pylon_ros2_camera_node/set_sync_free_run_timer_start_time_high [pylon_ros2_camera_interfaces/srv/SetIntegerValue]
• SyncFreeRunTimerTriggerRateAbs -> /my_camera/pylon_ros2_camera_node/set_sync_free_run_timer_trigger_rate_abs [pylon_ros2_camera_interfaces/srv/SetFloatValue]
• SyncFreeRunTimerUpdate -> /my_camera/pylon_ros2_camera_node/update_sync_free_run_timer [std_srvs/srv/Trigger]
• SyncFreeRunTimerEnable -> //my_camera/pylon_ros2_camera_node/enable_sync_free_run_timer [std_srvs/srv/SetBool]

ACE 2

PTP configuration & activation

• BslPtpPriority1 -> /my_camera/pylon_ros2_camera_node/set_ptp_priority [pylon_ros2_camera_interfaces/srv/SetIntegerValue]
• BslPtpProfile -> /my_camera/pylon_ros2_camera_node/set_ptp_profile [pylon_ros2_camera_interfaces/srv/SetIntegerValue]
• BslPtpNetworkMode -> /my_camera/pylon_ros2_camera_node/set_ptp_network_mode [pylon_ros2_camera_interfaces/srv/SetIntegerValue]
• BslPtpUcPortAddrIndex -> /my_camera/pylon_ros2_camera_node/set_ptp_uc_port_address_index [pylon_ros2_camera_interfaces/srv/SetIntegerValue]
• BslPtpUcPortAddr -> /my_camera/pylon_ros2_camera_node/set_ptp_uc_port_address [pylon_ros2_camera_interfaces/srv/SetIntegerValue]
• BslPtpManagementEnable -> /my_camera/pylon_ros2_camera_node/enable_ptp_management_protocol [std_srvs/srv/SetBool]
• BslTwoStep -> /my_camera/pylon_ros2_camera_node/enable_two_step_operation [std_srvs/srv/SetBool]
• PtpEnable -> /my_camera/pylon_ros2_camera_node/enable_ptp [std_srvs/srv/SetBool]

Scheduled Action Commands & Action Commands

• ActionDeviceKey -> /my_camera/pylon_ros2_camera_node/set_action_trigger_configuration [pylon_ros2_camera_interfaces/srv/SetActionTriggerConfiguration]
• ActionGroupKey -> /my_camera/pylon_ros2_camera_node/set_action_trigger_configuration [pylon_ros2_camera_interfaces/srv/SetActionTriggerConfiguration]
• ActionGroupMask -> /my_camera/pylon_ros2_camera_node/set_action_trigger_configuration [pylon_ros2_camera_interfaces/srv/SetActionTriggerConfiguration]
• IssueScheduledActionCommand -> /my_camera/pylon_ros2_camera_node/issue_scheduled_action_command [pylon_ros2_camera_interfaces/srv/IssueScheduledActionCommand]
• IssueActionCommand -> /my_camera/pylon_ros2_camera_node/issue_action_command [pylon_ros2_camera_interfaces/srv/IssueActionCommand]

Periodic Signal

• BslPeriodicSignalDelay -> /my_camera/pylon_ros2_camera_node/set_periodic_signal_delay [pylon_ros2_camera_interfaces/srv/SetFloatValue]
• BslPeriodicSignalPeriod -> /my_camera/pylon_ros2_camera_node/set_periodic_signal_period [pylon_ros2_camera_interfaces/srv/SetFloatValue]

Publishers

Name	Notes
/my_camera/pylon_ros2_camera_node/camera_info	sensor_msgs/msg/CameraInfo
/my_camera/pylon_ros2_camera_node/current_params	current camera parameter
/my_camera/pylon_ros2_camera_node/image_raw	acquired images
/my_camera/pylon_ros2_camera_node/image_rect	rectified images if the camera is calibrated
/my_camera/pylon_ros2_camera_node/status	camera status
/my_camera/pylon_ros2_camera_node/camera_info_3d	sensor_msgs/msg/CameraInfo (3D cameras)
/my_camera/pylon_ros2_camera_node/cloud_3d	3D point clouds from the 3D cameras
/my_camera/pylon_ros2_camera_node/confidence_3d	confidence images from the 3D cameras
/my_camera/pylon_ros2_camera_node/depth_map_3d	depth map images from the 3D cameras
/my_camera/pylon_ros2_camera_node/depth_map_color_3d	depth map color images from the 3D cameras
/my_camera/pylon_ros2_camera_node/intensity_3d	intensity images from the 3D cameras
/my_camera/pylon_ros2_camera_node/intensity_left_3d	left intensity images from stereo cameras (e.g. the Stereo mini)
/my_camera/pylon_ros2_camera_node/intensity_right_3d	right intensity images from stereo cameras (e.g. the Stereo mini)
/my_camera/pylon_ros2_camera_node/imu	IMU readings from the Stereo mini (when imu_enabled is true)

Service servers

Name	Notes
/my_camera/pylon_ros2_camera_node/activate_autoflash_output_[index]	data : false = deactivate, true = activate
/my_camera/pylon_ros2_camera_node/describe_parameters	-
/my_camera/pylon_ros2_camera_node/enable_acquisition_frame_rate	data : false = deactivate, true = activate
/my_camera/pylon_ros2_camera_node/enable_ambiguity_filter	data : false = deactivate, true = activate
/my_camera/pylon_ros2_camera_node/enable_depth_smooth	data : false = deactivate, true = activate (Stereo ace)
/my_camera/pylon_ros2_camera_node/enable_distortion_correction	data : false = deactivate, true = activate
/my_camera/pylon_ros2_camera_node/enable_fast_mode	data : false = deactivate, true = activate
/my_camera/pylon_ros2_camera_node/enable_hdr_merge	data : false = deactivate, true = activate (Stereo mini)
/my_camera/pylon_ros2_camera_node/enable_hdr_merge_use_ir	data : false = deactivate, true = activate (Stereo mini)
/my_camera/pylon_ros2_camera_node/enable_hdr_mode	data : false = deactivate, true = activate
/my_camera/pylon_ros2_camera_node/enable_outlier_removal	data : false = deactivate, true = activate
/my_camera/pylon_ros2_camera_node/enable_projector	data : false = deactivate, true = activate (Stereo mini)
/my_camera/pylon_ros2_camera_node/enable_ptp	data : false = deactivate, true = activate
/my_camera/pylon_ros2_camera_node/get_ptp_status	-
/my_camera/pylon_ros2_camera_node/enable_ptp_management_protocol	data : false = deactivate, true = activate
/my_camera/pylon_ros2_camera_node/enable_spatial_filter	data : false = deactivate, true = activate
/my_camera/pylon_ros2_camera_node/enable_static_scene	data : false = deactivate, true = activate (Stereo ace)
/my_camera/pylon_ros2_camera_node/enable_sync_free_run_timer	data : false = deactivate, true = activate
/my_camera/pylon_ros2_camera_node/enable_temporal_filter	data : false = deactivate, true = activate
/my_camera/pylon_ros2_camera_node/enable_thermal_drift_correction	data : false = deactivate, true = activate
/my_camera/pylon_ros2_camera_node/enable_two_step_operation	data : false = deactivate, true = activate
/my_camera/pylon_ros2_camera_node/execute_software_trigger	-
/my_camera/pylon_ros2_camera_node/get_chunk_counter_value	-
/my_camera/pylon_ros2_camera_node/get_chunk_enable	-
/my_camera/pylon_ros2_camera_node/get_chunk_exposure_time	-
/my_camera/pylon_ros2_camera_node/get_chunk_frame_counter	-
/my_camera/pylon_ros2_camera_node/get_chunk_line_status_all	-
/my_camera/pylon_ros2_camera_node/get_chunk_mode_active	-
/my_camera/pylon_ros2_camera_node/get_chunk_selector	-
/my_camera/pylon_ros2_camera_node/get_chunk_timestamp	-
/my_camera/pylon_ros2_camera_node/get_max_num_buffer	-
/my_camera/pylon_ros2_camera_node/get_parameter_types	-
/my_camera/pylon_ros2_camera_node/get_parameters	-
/my_camera/pylon_ros2_camera_node/get_statistic_buffer_underrun_count	-
/my_camera/pylon_ros2_camera_node/get_statistic_failed_buffer_count	-
/my_camera/pylon_ros2_camera_node/get_statistic_failed_packet_count	-
/my_camera/pylon_ros2_camera_node/get_statistic_missed_frame_count	-
/my_camera/pylon_ros2_camera_node/get_statistic_resend_request_count	-
/my_camera/pylon_ros2_camera_node/get_statistic_resynchronization_count	-
/my_camera/pylon_ros2_camera_node/get_statistic_total_buffer_count	-
/my_camera/pylon_ros2_camera_node/issue_action_command	-
/my_camera/pylon_ros2_camera_node/issue_scheduled_action_command	-
/my_camera/pylon_ros2_camera_node/list_parameters	-
/my_camera/pylon_ros2_camera_node/load_hdr_preset	loads the selected HDR sequence preset (Stereo mini)
/my_camera/pylon_ros2_camera_node/load_user_set	-
/my_camera/pylon_ros2_camera_node/get_pfs	-
/my_camera/pylon_ros2_camera_node/save_pfs	value : '/path/to/your/output.pfs'
/my_camera/pylon_ros2_camera_node/load_pfs	value : '/path/to/your/input.pfs'
/my_camera/pylon_ros2_camera_node/reset_device	-
/my_camera/pylon_ros2_camera_node/save_user_set	-
/my_camera/pylon_ros2_camera_node/set_PGI_mode	data : false = deactivate, true = activate
/my_camera/pylon_ros2_camera_node/set_acquisition_frame_count	value = new targeted frame count
/my_camera/pylon_ros2_camera_node/set_acquisition_frame_rate	value = new targeted frame rate
/my_camera/pylon_ros2_camera_node/set_action_trigger_configuration	-
/my_camera/pylon_ros2_camera_node/set_ambiguity_filter_threshold	value = new ambiguity filter threshold
/my_camera/pylon_ros2_camera_node/set_binning	-
/my_camera/pylon_ros2_camera_node/set_black_level	value = new targeted black level
/my_camera/pylon_ros2_camera_node/set_brightness	-
/my_camera/pylon_ros2_camera_node/set_chunk_enable	data : false = deactivate, true = activate
/my_camera/pylon_ros2_camera_node/set_chunk_exposure_time	-
/my_camera/pylon_ros2_camera_node/set_chunk_mode_active	data : false = deactivate, true = activate
/my_camera/pylon_ros2_camera_node/set_chunk_selector	-
/my_camera/pylon_ros2_camera_node/set_confidence_threshold	value = new confidence threshold (float; the Stereo ace expects a value in 0..1)
/my_camera/pylon_ros2_camera_node/set_demosaicing_mode	value : 0 = Simple, 1 = Basler PGI
/my_camera/pylon_ros2_camera_node/set_depth_fill	value = new depth fill level (Stereo ace)
/my_camera/pylon_ros2_camera_node/set_depth_max	value = new max depth (float; meters for the Stereo ace, millimeters for the blaze and the Stereo mini)
/my_camera/pylon_ros2_camera_node/set_depth_min	value = new min depth (float; meters for the Stereo ace, millimeters for the blaze and the Stereo mini)
/my_camera/pylon_ros2_camera_node/set_depth_quality	value = new depth quality (Stereo ace)
/my_camera/pylon_ros2_camera_node/set_depth_seg	value = new depth segmentation (Stereo ace)
/my_camera/pylon_ros2_camera_node/set_device_link_throughput_limit	value = new targeted throughput limit in Bytes/sec.
/my_camera/pylon_ros2_camera_node/set_device_link_throughput_limit_mode	data : false = deactivate, true = activate
/my_camera/pylon_ros2_camera_node/set_exposure	-
/my_camera/pylon_ros2_camera_node/set_exposure_auto_mode	value : 0 = Off, 1 = Continuous, 2 = HDR (Stereo ace)
/my_camera/pylon_ros2_camera_node/set_exposure_time_selector	value : 1 = Stage1, 2 = Stage2
/my_camera/pylon_ros2_camera_node/set_gain	-
/my_camera/pylon_ros2_camera_node/set_gamma	value: 0 = User, 1 = sRGB
/my_camera/pylon_ros2_camera_node/set_gamma_activation	(For GigE Cameras)
/my_camera/pylon_ros2_camera_node/set_gamma_selector	value : 0 = User, 1 = sRGB (For GigE Cameras)
/my_camera/pylon_ros2_camera_node/set_grab_timeout	-
/my_camera/pylon_ros2_camera_node/set_grabbing_strategy	-
/my_camera/pylon_ros2_camera_node/set_hdr_exposure_time	value = HDR sub-exposure time in microseconds (Stereo ace)
/my_camera/pylon_ros2_camera_node/set_hdr_exposure_time_selector	value : 1 = ExposureTime1 ... 4 = ExposureTime4 (Stereo ace)
/my_camera/pylon_ros2_camera_node/set_hdr_max_exposure	value = HDR sequence max auto-exposure time in microseconds (Stereo mini)
/my_camera/pylon_ros2_camera_node/set_hdr_sequence_index	value : 0 or 1 = HDR sequence to configure (Stereo mini)
/my_camera/pylon_ros2_camera_node/set_hdr_sequence_preset	value : 0 = DepthFromHDR, 1 = LaserOnOff (Stereo mini)
/my_camera/pylon_ros2_camera_node/set_hdr_sub_exposures	value = number of HDR sub-exposures (Stereo ace)
/my_camera/pylon_ros2_camera_node/set_illumination_mode	value = new illumination mode (Stereo ace)
/my_camera/pylon_ros2_camera_node/set_image_encoding	value = mono8, mono16, bgr8, rgb8, bayer_bggr8, bayer_gbrg8, bayer_rggb8, bayer_grbg8, bayer_rggb16, bayer_bggr16, bayer_gbrg16, bayer_grbg16
/my_camera/pylon_ros2_camera_node/set_intensity_calculation	value : 1 = Method1, 2 = Method2
/my_camera/pylon_ros2_camera_node/set_light_source_preset	value : 0 = Off, 1 = Daylight5000K, 2 = Daylight6500K, 3 = Tungsten2800K
/my_camera/pylon_ros2_camera_node/set_line_debouncer_time	value = delay in micro sec
/my_camera/pylon_ros2_camera_node/set_line_inverter	data : false = deactivate, true = activate
/my_camera/pylon_ros2_camera_node/set_line_mode	value : 0 = Input, 1 = Output
/my_camera/pylon_ros2_camera_node/set_line_selector	value : 1 = Line1, 2 = Line2, 3 = Line3, 4 = Line4
/my_camera/pylon_ros2_camera_node/set_line_source	value : 0 = Exposure Active, 1 = FrameTriggerWait, 2 = UserOutput1, 3 = UserOutput2, 4 = UserOutput3, 5 = Timer1Active, 6 = FlashWindow
/my_camera/pylon_ros2_camera_node/set_max_num_buffer	-
/my_camera/pylon_ros2_camera_node/set_max_transfer_size	maximum USB data transfer size in bytes
/my_camera/pylon_ros2_camera_node/set_multi_camera_channel	value = new channel
/my_camera/pylon_ros2_camera_node/set_noise_reduction	value = reduction value
/my_camera/pylon_ros2_camera_node/set_offset_x	value = targeted offset in x-axis
/my_camera/pylon_ros2_camera_node/set_offset_y	value = targeted offset in y-axis
/my_camera/pylon_ros2_camera_node/set_operating_mode	value : blaze operating mode (0 = Long range, 1 = Short range) or Stereo mini depth preset
/my_camera/pylon_ros2_camera_node/set_outlier_removal_threshold	value = new outlier removal threshold
/my_camera/pylon_ros2_camera_node/set_outlier_removal_tolerance	value = new outlier removal tolerance
/my_camera/pylon_ros2_camera_node/set_output_queue_size	-
/my_camera/pylon_ros2_camera_node/set_parameters	-
/my_camera/pylon_ros2_camera_node/set_parameters_atomically	-
/my_camera/pylon_ros2_camera_node/set_periodic_signal_delay	value : delay to be applied to the periodic signal in microseconds
/my_camera/pylon_ros2_camera_node/set_periodic_signal_period	value : length of the periodic signal in microseconds
/my_camera/pylon_ros2_camera_node/set_projector_level	value = new projector level (Stereo mini)
/my_camera/pylon_ros2_camera_node/set_ptp_network_mode	value : 1 = Hybrid, 2 = Multicast, 3 = Unicast
/my_camera/pylon_ros2_camera_node/set_ptp_priority	value = value indicating the priority of the device when determining the master clock
/my_camera/pylon_ros2_camera_node/set_ptp_profile	value : 1 = Delay Request Response Default Profile, 2 = Peer to Peer Default Profile
/my_camera/pylon_ros2_camera_node/set_ptp_uc_port_address	value = unicast port address
/my_camera/pylon_ros2_camera_node/set_ptp_uc_port_address_index	value = unicast port address index
/my_camera/pylon_ros2_camera_node/set_reverse_x	data : false = deactivate, true = activate
/my_camera/pylon_ros2_camera_node/set_reverse_y	data : false = deactivate, true = activate
/my_camera/pylon_ros2_camera_node/set_roi	-
/my_camera/pylon_ros2_camera_node/set_sensor_readout_mode	value : 0 = Normal, 1 = Fast
/my_camera/pylon_ros2_camera_node/set_sharpness_enhancement	value = sharpness value
/my_camera/pylon_ros2_camera_node/set_sleeping	-
/my_camera/pylon_ros2_camera_node/set_sync_free_run_timer_start_time_high	value = high 32 bits of the synchronous free run trigger start time
/my_camera/pylon_ros2_camera_node/set_sync_free_run_timer_start_time_low	value = low 32 bits of the synchronous free run trigger start time
/my_camera/pylon_ros2_camera_node/set_sync_free_run_timer_trigger_rate_abs	value = synchronous free run trigger rate
/my_camera/pylon_ros2_camera_node/set_temporal_filter_strength	value = new temporal filter strength
/my_camera/pylon_ros2_camera_node/set_timer_duration	value = duration of the currently selected timer in microseconds
/my_camera/pylon_ros2_camera_node/set_timer_selector	value : 1 = Timer 1, 2 = Timer 2, 3 = Timer 3, 4 = Timer 4
/my_camera/pylon_ros2_camera_node/set_timer_trigger_source	value = see valid values of TimerTriggerSourceEnums in documentation
/my_camera/pylon_ros2_camera_node/set_trigger_activation	value : 0 = RigingEdge, 1 = FallingEdge
/my_camera/pylon_ros2_camera_node/set_trigger_delay	value = delay in micro sec.
/my_camera/pylon_ros2_camera_node/set_trigger_mode	data : false = deactivate, true = activate
/my_camera/pylon_ros2_camera_node/set_trigger_selector	value : 0 = Frame start, 1 = Frame burst start (ace USB cameras) / Acquisition Start (ace GigE cameras)
/my_camera/pylon_ros2_camera_node/set_trigger_source	value : 0 = Software, 1 = Line 1, 2 = Line 2, 3 = Line 3, 4 = Line 4, 5 = Action 1, 6 = Periodic Signal 1
/my_camera/pylon_ros2_camera_node/set_trigger_timeout	-
/my_camera/pylon_ros2_camera_node/set_user_output_[index]	data : false = deactivate, true = activate
/my_camera/pylon_ros2_camera_node/set_user_set_default_selector	value : 0 = Default, 1 = UserSet1, 2 = UserSet2, 3 = UserSet3, 4 = HighGain, 5 = AutoFunctions, 6 = ColorRaw
/my_camera/pylon_ros2_camera_node/set_user_set_selector	value : 0 = Default, 1 = UserSet1, 2 = UserSet2, 3 = UserSet3, 4 = HighGain, 5 = AutoFunctions, 6 = ColorRaw
/my_camera/pylon_ros2_camera_node/set_white_balance	-
/my_camera/pylon_ros2_camera_node/set_white_balance_auto	value : 0 = Off, 1 = Once, 2 = Continuous
/my_camera/pylon_ros2_camera_node/start_grabbing	-
/my_camera/pylon_ros2_camera_node/stop_grabbing	-
/my_camera/pylon_ros2_camera_node/update_sync_free_run_timer	-
/my_camera/set_camera_info	-

Action servers

Name	Notes
/my_camera/pylon_ros2_camera_node/grab_3d_data	-
/my_camera/pylon_ros2_camera_node/grab_images_raw	-

Depending on the camera model, it is possible to grab one or several images or 3D data sets (3D point cloud, intensity, confidence, depth map, depth color map) through the dedicated action with user-specified parameters (e.g., exposure time, brightness value, etc.). The grab_images_raw action is available for the 2D cameras, and the grab_3d_data action is available for the 3D cameras (the blaze, the Stereo ace, and the Stereo mini).

The camera-characteristic parameter such as height, width, projection matrix (by ROS2 convention, this matrix specifies the intrinsic (camera) matrix of the processed (rectified) image - see the CameraInfo message definition for detailed information) and camera_frame are published over the /camera_info topic. Furthermore, an action-based image grabbing with desired exposure time, gain, gamma and / or brightness is provided. Hence, one can grab a sequence of images with above target settings as well as a single image. Grabbing images through this action can result in a higher frame rate.

Tests

The folder pylon_ros2_camera_wrapper/test includes different test programs. testing specific functionalities implemented by the driver. These programs are for testing purposes and should be adapted according to one's needs.

• test_get_chunk_data: test the access of specific chunk data
• test_grab_3d_data_action_client, test_grab_image_action_client, and test_grab_images_action_client: trigger the image or the 3D data set grabbing through the actions /my_camera/pylon_ros2_camera_node/grab_images_raw or /my_camera/pylon_ros2_camera_node/grab_3d_data, depending on the camera model. Each grabbed image (only the intensity image for the 3D cameras) is displayed in a dedicated popup window.
• test_launch_profiles.py: unit tests for the launch profile resolution (checks that profile:=2d and profile:=3d select the right configuration file). These run without any camera connected.

Integration tests

The pylon_ros2_camera_test package provides automated integration tests that cover the full driver stack for both 2D cameras (GigE, USB) and 3D cameras (Basler blaze, Stereo ace, Stereo mini). Each test run launches the driver, connects to the camera, executes all tests, prints a pass/fail summary, and shuts down automatically.

Building

Build all packages for the first time, including the test package and its dependencies:

cd ~/dev_ws && colcon build --packages-up-to pylon_ros2_camera_test

After the initial build, rebuild only the test package when its source changes:

cd ~/dev_ws && colcon build --packages-select pylon_ros2_camera_test

Source the environment after building:

cd ~/dev_ws && . install/setup.bash

Running the tests

Connect to the first available camera (auto-detect 2D or 3D):

ros2 launch pylon_ros2_camera_test run_tests.launch.py

Connect to a specific camera by Device User ID:

ros2 launch pylon_ros2_camera_test run_tests.launch.py device_user_id:=<device_user_id>

Replace <device_user_id> with the Device User ID configured in the camera. The ROS namespace is set automatically to match the Device User ID.

The test node automatically detects the camera type and runs the appropriate test suite. When both 2D and 3D cameras are connected without specifying a device_user_id, the driver connects to the first available camera and only the matching test node runs.

Test suites

Generic tests (run for all camera types):

Test	Description
test_status_topic	Verifies the driver publishes its status topic
test_get_max_num_buffer	Reads the maximum grab buffer count
test_set_exposure	Sets exposure time and checks the reached value
test_set_gain	Sets gain and checks the reached value
test_set_gamma	Sets gamma and checks the reached value
test_sleeping_mode	Puts the camera to sleep and wakes it back up
test_stop_start_grabbing	Stops and restarts image grabbing

2D-specific tests (GigE, USB cameras):

Test	Description
test_grab_images_raw	Grabs a raw image via the grab_images_raw action
test_set_binning	Sets 2×2 binning and restores 1×1
test_set_roi	Sets a region of interest and restores the full sensor
test_set_image_encoding	Switches pixel encoding (mono8 ↔ bayer_rggb8), grabs a frame after each switch, and verifies the image header encoding matches

3D-specific tests (blaze, Stereo ace, Stereo mini cameras):

The 3D test suite runs the same set of tests for every 3D camera. Many features exist on only one or two models, so the camera each test targets is noted in parentheses. A test skips automatically when the connected camera does not support its feature.

Test	Description
test_grab_3d_data	Grabs a point cloud and intensity map via the grab_3d_data action
test_set_depth_range	Sets depth min/max and restores the original range
test_enable_spatial_filter	Enables and disables the spatial filter (blaze)
test_enable_temporal_filter	Enables and disables the temporal filter (blaze)
test_set_brightness	Sets a target brightness with auto exposure (Stereo ace, Stereo mini)
test_set_confidence_threshold	Writes back the current confidence threshold (blaze, Stereo ace)
test_enable_hdr_mode	Enables HDR mode and restores the original state
test_set_illumination_mode	Sets the illumination mode and restores the original (Stereo ace)
test_set_depth_quality	Sets the depth quality and restores the original (Stereo ace)
test_enable_static_scene	Enables the static-scene mode and restores the original state (Stereo ace)
test_enable_depth_smooth	Enables depth smoothing and restores the original state (Stereo ace)
test_set_depth_fill	Re-applies the current depth-fill value (Stereo ace)
test_set_depth_seg	Re-applies the current depth-segmentation value (Stereo ace)
test_enable_projector	Enables the pattern projector and restores the original state (Stereo mini)
test_set_projector_level	Sets the projector power level (Stereo mini)
test_set_depth_preset	Selects a depth preset and restores the original (Stereo mini)
test_set_hdr_exposure_time_selector	Selects an HDR sub-exposure to configure (Stereo ace)
test_set_hdr_exposure_time	Sets the selected HDR sub-exposure time (Stereo ace)
test_set_hdr_sub_exposures	Sets the number of HDR sub-exposures (Stereo ace)
test_set_exposure_auto_mode	Sets the auto exposure mode Off/Continuous/HDR (Stereo ace)
test_set_hdr_max_exposure	Sets the HDR sequence max exposure (Stereo mini)
test_hdr_sequence_workflow	Runs the full mini HDR preset workflow in Basler's order: select IR source, set preset, load preset, enable HDR, set both sequence indices, enable frame merging, then restore. The mini's sequence/preset/load/merge nodes are only writable in this order, so they are exercised here rather than as standalone tests (Stereo mini)
test_hdr_sub_exposure_workflow	Runs the full HDR sub-exposure ordering: set sub-exposure count, set each sub-exposure time by selector, activate HDR auto exposure, then restore (Stereo ace)

Some tests skip gracefully when a feature is not supported by the connected camera model. A skipped test is reported as [ PASS ] with a [WARN] note in the log.

Interpreting results

A successful run ends with:

=========================================
  RESULTS: 11 / 11 passed  (0 failed)
=========================================
  All tests PASSED.

Actions to take when tests fail

test_status_topic fails The driver did not publish its status topic within the timeout. Check that the driver started correctly and that the camera is accessible. Increase camera_detection_timeout if the network is slow (by 30 for instance) with this command):

ros2 launch pylon_ros2_camera_test run_tests.launch.py device_user_id:=<id> camera_detection_timeout:=30

test_get_max_num_buffer fails The driver is running but the camera hardware is not fully connected. Check the physical connection (cable, power, USB port) and retry.

test_set_exposure / test_set_gain / test_set_gamma fail These can fail if the driver rejects the service call. Check the driver log for errors. If the camera model does not support the feature the test skips automatically; a genuine failure means the service returned an error.

test_sleeping_mode or test_stop_start_grabbing fail These indicate the driver is not responding to control commands. Restart the driver and try again. If the issue is consistent, check for concurrent clients holding the camera open.

test_grab_images_raw or test_grab_3d_data fail Image/point-cloud acquisition failed. Check that no other process is grabbing from the same camera. For the 3D cameras, ensure the relevant supplementary pylon package is installed and compatible with the installed pylon version.

test_set_binning fails Not all camera models support hardware binning. The test skips automatically on such cameras. A genuine failure means the binning service returned an error unexpectedly.

Camera not detected — error message at startup:

Camera with device_user_id '<id>' was not reachable within the detection timeout (10 s).

Verify that:

1. The device_user_id is spelled correctly (it is case-sensitive).
2. The camera is powered on and connected to the network or USB.
3. No other process has the camera open exclusively.
4. For GigE cameras, the MTU size is configured correctly (add mtu_size:=8192 for jumbo frames).

Known issues

User input in terminal when starting node through launch files

The ros2 launch mechanism doesn't allow to access stdin through a terminal (see here and here). This is solved in this implementation by installing and using xterm to emulate a terminal with possible user interaction.

Service shutdown

In the ROS pylon implementation, the activate_autoflash_output and set_user_output service servers are shutdowned when the connection with a camera is lost. It is not possible for now to do so with ROS2 without shutting down the whole node (see here). There is no way to overcome this issue at the moment.

Troubleshooting

Some classes includes in their constructor the following command, commented by default: rcutils_ret_t __attribute__((unused)) res = rcutils_logging_set_logger_level(LOGGER_BASE.get_name(), RCUTILS_LOG_SEVERITY_DEBUG); Uncomment it to display on your terminal more detailed debug information.

With pylon 7.5.0, if the pylon viewer does not start, this is due to a Qt dependency missing. Try installing the xcb-cursor0 library with the following command: sudo apt install libxcb-cursor0. If it does not solve your issue, try starting the pylon viewer from the bin directory of pylon: cd /opt/pylon/bin/ && ./pylonviewer. Report then the error message to the pylon support team.

To increase performance and to minimize CPU usage when grabbing images, the following settings should be considered:

Slow frame rate

Please refer to the dedicated chapter ("Acquisition mode and frame rate") in this documentation for more information.

Beware as well that starting rviz2 or rqt before the driver may result in a slower frame rate. Start the driver starts followed by rqt or rviz2.

No connection with connected camera (GigE devices)

To be sure to be able to connect to a specific camera, its network configuration must be manually set through Basler's pylon IP configurator. To do so, click on the camera in the list of connected devices, select the Static IP option, set an IP Address within the same range as the one of your computer, and set the same Subnet Mask as the one from your computer.

Problems acquiring frames

Maximum UDP Socket Buffer Size (GigE devices)

The system's maximum UDP receive buffer size should be increased to ensure a stable image acquisition. A maximum size of 2 MB is recommended. This can be achieved by issuing the sudo sysctl net.core.rmem_max=2097152 command. To make this setting persistent, you can add the net.core.rmem_max setting to the /etc/sysctl.conf file.

Enable Jumbo Frames (GigE devices)

Many GigE network adapters support so-called jumbo frames, i.e., network packets larger than the usual 1500 bytes. To enable jumbo frames, the maximum transfer unit (MTU) size of the PC's network adapter must be set to a high value. We recommend using a value of 8192.

Increase the packet size (GigE devices)

If your network adapter supports jumbo frames, you set the adapter's MTU to 8192 as described above. In order to take advantage of the adapter's jumbo frame capability, you must also set the packet size used by the camera to 8192.

If you are working with the pylon Viewer application, you can set the packet size by first selecting a camera from the tree in the "Device" pane. In the "Features" pane, expand the features group that shows the camera's name, expand the "Transport Layer" parameters group, and set the "Packet Size" parameter to 8192. If you write your own application, use the camera API to set the PacketSize parameter to 8192.

It is possible to change the packet size by changing the default value of the mtu_size parameter in the pylon ROS2 wrapper launch file. When the camera is grabbing, it is not possible to modify this parameter.

Real-time Priority (GigE devices)

The GigE Vision implementation of Basler pylon software uses a thread for receiving image data. Basler pylon tries to set the thread priority for the receive thread to real-time thread priority. This requires certain permissions. The 'Permissions for Real-time Thread Priorities' section of the pylon INSTALL document describes how to grant the required permissions.

Increase Packet Size (U3V devices)

For faster USB transfers you should increase the packet size. You can do this by changing the "Stream Parameters" -> "Maximum Transfer Size" value from inside the pylon Viewer or by setting the corresponding value via the API. After increasing the packet size you will likely run out of kernel space and see corresponding error messages on the console. The default value set by the kernel is 16 MB. To set the value (in this example to 1000 MB) you can execute as root: echo 1000 > /sys/module/usbcore/parameters/usbfs_memory_mb This would assign a maximum of 1000 MB to the USB stack.