ROS 2 Platform

ROS 2 (Robot Operating System 2) is the second-generation version of the Robot Operating System. It is an open-source robotics software framework designed to provide tools and libraries to simplify the creation and management of robotic applications. Developed and maintained by Open Robotics, ROS 2 inherits many advantages of ROS 2 while improving its architecture and features to meet the needs of modern robotic systems.

Set up Development Environment

1. Install the corresponding ROS 2 development platform based on the Ubuntu version.

• Ubuntu20.04: ROS 2 Foxy

• Ubuntu22.04: ROS 2 Humble

2. Install dependencies.

   ROS 2 FoxyROS 2 Humble

   sudo apt install python3-colcon-common-extensions
   sudo apt install ros-foxy-camera-info-manager
   sudo apt install ros-foxy-image-publisher
   sudo apt install ros-foxy-diagnostic-updater
   

Download Camport ROS 2 SDK

1. Create a workspace directory:

   mkdir -p ~/ros2_ws/src
   cd ~/ros2_ws/src/
   

2. Choose any of the following methods to download Camport ROS 2 SDK:

• Access https://gitee.com/percipioxyz/camport_ros2 using a browser and download the Camport ROS 2 SDK.

• Use the git command to obtain a local copy: Open the terminal, switch to the working directory where the SDK should be stored, and enter the git clone command to clone the remote repository.

  git clone https://gitee.com/percipioxyz/camport_ros2.git
  

The directory structure of Camport ROS 2 SDK is as follows:

Camport ROS 2 SDK Directory

• README.md: Briefly describes the ROS 2 compilation process.

• src/percipio_camera/CMakeLists.txt: CMake build system configuration file.

• src/percipio_camera/camport3: Contains library files and header files for the Percipio SDK.

• src/percipio_camera/include: Contains header files.

• src/percipio_camera/launch: Contains ROS 2 launch files for initializing nodes and setting parameters.

• src/percipio_camera/package.xml: Describes the package manifest, including the name, version, author information, license, and build dependencies.

• src/percipio_camera/src: Contains main source code files, including node implementations and camera drivers.

Configure Environment Variables

ROS 2 FoxyROS 2 Humble

source /opt/ros/foxy/setup.bash
echo "source /opt/ros/foxy/setup.bash" >> ~/.bashrc

Build the Project

cd ~/ros2_ws/src/camport_ros2/
colcon build --event-handlers  console_direct+  --cmake-args  -DCMAKE_BUILD_TYPE=Release
sudo echo "source ./install/setup.bash" >> ~/.bashrc
source ~/.bashrc

Tip

colcon build Instructions:

• –event-handlers console_direct+: This option sets the event handler, where console_direct+ ensures that detailed build event information is streamed directly to the console. This provides a clear, real-time view of each build step and any potential errors, enhancing troubleshooting and process transparency.

• –cmake-args -DCMAKE_BUILD_TYPE=Release: This option passes additional CMake parameters. In this case, -DCMAKE_BUILD_TYPE=Release sets the CMake build type to Release. This means that the build will be optimized and suitable for a release version rather than a debug version.

After compilation, the following folders are generated.

• build: Contains intermediate and object files.

• install: Includes executables, libraries, headers, and other resources.

• log:Contains logs generated during build and runtime.

Modify Camera Parameter Configuration

ROS 2 supports two parameter modification methods.

Method 1

Configure parameters directly in the launch file ( percipio_camera.launch.py / multi_cam.launch.py). This method only supports parameters available in the launch file.

The steps are as follows:

1. Navigate to the path: camport3_ros2/install/percipio_camera/share/percipio_camera/launch.

2. Modify parameter configurations.

   Single CameraMulti Cameras

   For single-camera setups, open the percipio_camera.launch.py file and modify parameter configurations as needed. The description of configurable parameters is shown in the table below.

   • Specify the camera serial number

     DeclareLaunchArgument('serial_number', default_value='"207000106930"'),
     

   • Specify the camera IP address

     DeclareLaunchArgument('device_ip', default_value='192.168.120.112'),
     

   Note

   If neither SN nor IP is specified, the first detected camera is opened by default.

Configurable Parameters in Launch

Parameter	Description	Value Range
camera_name	Topic name	Customizable; used to distinguish cameras in multi-camera setups
serial_number	Camera serial number (SN)	Can be empty; or specify SN of target camera
device_ip	Camera IP address	Can be empty; or specify IP of target camera
device_workmode	Camera trigger mode (continuous/software/hardware trigger)	trigger_off/trigger_soft/trigger_hard
gvcp_resend	Enable/disable data resend function	true/false
device_auto_reconnect	Enable/disable camera reconnection function	true/false
color_enable	Enable/disable color image output	true/false
color_resolution	Color image resolution	Refer to camera’s fetch_config.xml
color_format	Color image format	Refer to StreamFormatMapper format_mapper_list[] in percipio_device.cpp
color_aec_roi	Color auto-exposure ROI	Format: ‘x,y,width,height’, where (x,y) is top-left corner, width and height are region dimensions
color_qos	Color data QoS	SYSTEM_DEFAULT/DEFAULT/PARAMETER_EVENTS/SERVICES_DEFAULT/PARAMETERS/SENSOR_DATA
color_camera_info_qos	Color camera info QoS	SYSTEM_DEFAULT/DEFAULT/PARAMETER_EVENTS/SERVICES_DEFAULT/PARAMETERS/SENSOR_DATA
depth_enable	Enable/disable depth map output	true/false
depth_resolution	Depth image resolution	Refer to camera’s fetch_config.xml
depth_format	Depth image format	depth16/xyz48
depth_qos	Depth data QoS	SYSTEM_DEFAULT/DEFAULT/PARAMETER_EVENTS/SERVICES_DEFAULT/PARAMETERS/SENSOR_DATA
depth_camera_info_qos	Depth camera info QoS	SYSTEM_DEFAULT/DEFAULT/PARAMETER_EVENTS/SERVICES_DEFAULT/PARAMETERS/SENSOR_DATA
depth_registration_enable	Enable/disable depth-to-color registration	true/false
depth_speckle_filter	Enable/disable depth speckle filter	true/false
max_speckle_size	Speckle filter area threshold	Default: 150, Range: 10-3000
max_speckle_diff	Speckle filter clustering	Default: 64, Range: 5-1500
depth_time_domain_filter	Enable/disable time domain filter	true/false
depth_time_domain_num	time domain filter image count	Default: 3, Range: 2-10
point_cloud_enable	Enable/disable point cloud output	true/false
color_point_cloud_enable	Enable/disable colored point cloud output	true/false
point_cloud_qos	Point cloud QoS	SYSTEM_DEFAULT/DEFAULT/PARAMETER_EVENTS/SERVICES_DEFAULT/PARAMETERS/SENSOR_DATA
left_ir_enable	Enable/disable left IR image output	true/false
left_ir_qos	Left IR data QoS	SYSTEM_DEFAULT/DEFAULT/PARAMETER_EVENTS/SERVICES_DEFAULT/PARAMETERS/SENSOR_DATA
left_ir_camera_info_qos	Left IR camera info QoS	SYSTEM_DEFAULT/DEFAULT/PARAMETER_EVENTS/SERVICES_DEFAULT/PARAMETERS/SENSOR_DATA
tof_depth_quality	ToF depth quality	basic/medium/high (Refer to fetch_config.xml)
tof_modulation_threshold	ToF modulation intensity threshold	Refer to camera specifications
tof_jitter_threshold	ToF jitter filtering threshold	Refer to camera specifications
tof_filter_threshold	ToF outlier filtering threshold	Refer to camera specifications
tof_channel	ToF modulation channel	Refer to camera specifications
tof_HDR_ratio	ToF high dynamic range ratio	Refer to camera specifications

Note

1. Description of Configurable Values for xxx_qos:

• SYSTEM_DEFAULT: Uses the system’s default QoS settings, which are typically defined by the underlying DDS (Data Distribution Service) implementation. The actual effect depends on the specific DDS implementation.

• DEFAULT: Provides reliable message delivery, suitable for most general communication needs. Retains up to 10 of the latest messages.

• PARAMETER_EVENTS: Specifically designed for parameter events, ensuring reliable delivery of parameter change events. Retains up to 1000 of the latest messages.

• SERVICES_DEFAULT: The default QoS settings for service communication, ensuring reliable delivery of service requests and responses. Retains all service request and response messages.

• PARAMETERS: Specifically designed for parameters, ensuring reliability in parameter setting and retrieval. Retains up to 1000 of the latest messages.

• SENSOR_DATA: QoS settings for sensor data, suitable for high-frequency, low-latency data streaming. Retains up to 5 of the latest messages.

2. The TL460-S1-E1 camera supports two bayer format color image outputs: CSI_BAYER8RGGB and CSI_BAYER12RGGB. If the camera is set to output bayer format color images by modifying the percipio.launch file, the default output is CSI_BAYER8RGGB, and it is not possible to switch to CSI_BAYER12RGGB by modifying this file.

3. If the camera format or resolution configured through the percipio.launch file is not supported by the camera, the system will use the default configuration for image output.

Method 2

Set Camera Parameters Using Percipio Viewer Software and Camport SDK.

• GigE 2.0 Cameras (all models except PMD series and GM series)

  Use Percipio Viewer or Camport SDK 3.X.X to save parameters to the camera’s Storage area. The ROS system will automatically load the parameter configuration from the Storage area at startup and begin capturing images.

• GigE 2.1 Cameras (PMD series and GM series models)

  Use Camport SDK 4.X.X or the latest version of Percipio Viewer to set the target User Set as the default parameter group at camera startup. The camera will automatically load the configuration of the selected User Set after power-on.

Launch Camera Node

Single CameraMulti Cameras

ros2 launch percipio_camera percipio_camera.launch.py

Note

Do not close the terminal running the service during operation.

If the camera node starts successfully, the terminal will display information such as the camera IP address, SN, depth map format & resolution, and color image format & resolution.

Note

Do not close the terminal running this service during operation.

Subscribe to Topics

The src/percipio_camera/launch directory contains the following sample Python scripts for camera node subscription:

• depth.py: Enables the specified camera to capture depth maps in the designated format and resolution.

  In the percipio.launch file, set depth_enable to true and save. Launch the camera node, open a new terminal and navigate to src/percipio_camera/launch. Execute python3 depth.py to run the script, which will display real-time depth maps from the specified camera in a pop-up window, as shown below:

  

  depth.py Execution Result

  Note

  When depth_registration_enable is true, outputs depth maps aligned to color image space; when false, outputs raw depth maps.

• color.py: Enables the specified camera to capture color images in the designated format and resolution.

  In the percipio.launch file, set color_enable to true and save. Launch the camera node, open a new terminal and navigate to src/percipio_camera/launch. Execute python3 color.py to run the script, which will display real-time color images from the specified camera in a pop-up window, as shown below:

  

  color.py Execution Result

• cloud.py: Enables the specified camera to capture and save point clouds in the designated format and resolution.

  In the percipio.launch file, set depth_enable and point_cloud_enable to true, and color_point_cloud_enable to false. Launch the camera node, open a new terminal and navigate to src/percipio_camera/launch. Execute python3 cloud.py to run the script, which will:

  • Display real-time raw point clouds from the specified camera

  • Print the point cloud save path and point count in the terminal

  

  cloud.py Execution Result

• registered_cloud.py: Enables the specified camera to capture and save colored point clouds in the designated format and resolution.

  In the percipio.launch file, set color_enable, depth_enable, depth_registration_enbale and color_point_cloud_enable to true. Launch the camera node, open a new terminal and navigate to src/percipio_camera/launch. Execute python3 registered_cloud.py to run the script, which will:

  • Display real-time colored point clouds from the specified camera

  • Print the point cloud save path and point count in the terminal

  

  registered_cloud.py Execution Result

• offline_detect.py: Subscribes to the /camera/device_event topic, monitors camera offline, timeout, or reconnection completion events, and prints logs when messages are received.

• send_trigger.py: Subscribes to the /camera/trigger_event topic and sends software trigger signals at a set frequency (only effective when the camera is in software trigger mode).