ROS2 Platform

ROS2 (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, ROS2 inherits many advantages of ROS1 while improving its architecture and features to meet the needs of modern robotic systems.

Setting Up ROS2 Development Environment

1. Install the corresponding ROS2 development platform based on the Ubuntu version.

   • Ubuntu20.04: ROS2 Foxy

   • Ubuntu22.04: ROS2 Humble

2. Install dependencies.

   ROS2 FoxyROS2 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
   

Downloading Camport ROS2 SDK

1. Create a workspace directory.

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

2. Download Camport ROS2.

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

The directory structure of Camport ROS2 SDK is as follows:

Camport ROS2 SDK Directory

• README.md: Briefly describes the ROS2 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 ROS2 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.

Configuring Environment Variables

ROS2 FoxyROS2 Humble

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

Building 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 the build will be optimized for production use, rather than for debugging purposes.

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.

Modifying Parameter Configurations

Parameters to be loaded at camera start up can be configured in the launch files (percipio_camera.launch.py / multi_cam.launch.py).

Important

Through the launch file, only a subset of parameters can be configured. To configure all parameters of the camera, you may opt to use Percipio Viewer to write the camera settings into Storage in advance. Subsequently, when the camera is powered on, the parameters will already be in the configured state. For the setup procedure, please refer to the Percipio Viewer User Guide.

Follow the steps below to configure parameters in the launch file.

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 table

   Parameter Name	Description	default_value Configurable Range
   camera_name	Topic name	Customizable; used to distinguish between cameras in multi-camera setups.
   serial_number	Camera SN number	Can be left empty; or filled with the SN number of the camera to be connected.
   device_ip	Camera IP address	Can be left empty; or filled with the IP address of the camera to be connected.
   color_enable	Color image enable	true/false
   color_resolution	Color image resolution	Refer to the camera’s fetch_config.xml file for the configurable range.
   color_format	Color image format	Refer to camport3_ros2/src/percipio_camera/src/percipio_device.cpp StreamFormatMapper format_mapper_list[].
   color_qos	Color quality of service	SYSTEM_DEFAULT、DEFAULT、PARAMETER_EVENTS、SERVICES_DEFAULT、PARAMETERS、SENSOR_DATA
   color_camera_info_qos	Color camera info quality of service	SYSTEM_DEFAULT、DEFAULT、PARAMETER_EVENTS、SERVICES_DEFAULT、PARAMETERS、SENSOR_DATA
   depth_enable	Depth component enable	true/false
   depth_resolution	Depth image resolution	Refer to the camera’s fetch_config.xml file for the configurable range.
   depth_format	Depth image format	Refer to camport3_ros2/src/percipio_camera/src/percipio_device.cpp StreamFormatMapper format_mapper_list[].
   depth_qos	Depth quality of service	SYSTEM_DEFAULT、DEFAULT、PARAMETER_EVENTS、SERVICES_DEFAULT、PARAMETERS、SENSOR_DATA
   depth_camera_info_qos	Depth camera info quality of service	SYSTEM_DEFAULT、DEFAULT、PARAMETER_EVENTS、SERVICES_DEFAULT、PARAMETERS、SENSOR_DATA
   depth_registration_enable	Depth to Color alignment enable	true/false
   point_cloud_enable	Point cloud enable	true/false
   color_point_cloud_enable	Color point cloud enable	true/false
   point_cloud_qos	Point cloud quality of service	SYSTEM_DEFAULT、DEFAULT、PARAMETER_EVENTS、SERVICES_DEFAULT、PARAMETERS、SENSOR_DATA
   left_ir_enable	Left IR image enable	true/false
   left_ir_resolution	Left IR image resolution	Refer to the camera’s fetch_config.xml file for the configurable range.
   left_ir_format	Left IR image format	Refer to camport3_ros2/src/percipio_camera/src/percipio_device.cpp StreamFormatMapper format_mapper_list[].
   left_ir_qos	Left IR quality of service	SYSTEM_DEFAULT、DEFAULT、PARAMETER_EVENTS、SERVICES_DEFAULT、PARAMETERS、SENSOR_DATA
   left_ir_camera_info_qos	Left IR camera info quality of service	SYSTEM_DEFAULT、DEFAULT、PARAMETER_EVENTS、SERVICES_DEFAULT、PARAMETERS、SENSOR_DATA
   right_ir_enable	Right IR component enable	true/false
   right_ir_resolution	Right IR image resolution	Refer to the camera’s fetch_config.xml file for the configurable range.
   right_ir_format	Right IR image format	Refer to camport3_ros2/src/percipio_camera/src/percipio_device.cpp StreamFormatMapper format_mapper_list[].
   right_ir_qos	Right IR quality of service	SYSTEM_DEFAULT、DEFAULT、PARAMETER_EVENTS、SERVICES_DEFAULT、PARAMETERS、SENSOR_DATA
   right_ir_camera_info_qos	Right IR camera info quality of service	SYSTEM_DEFAULT、DEFAULT、PARAMETER_EVENTS、SERVICES_DEFAULT、PARAMETERS、SENSOR_DATA
   tof_depth_quality	ToF camera depth quality	basic/medium/high; refer to the camera’s fetch_config.xml file for the configurable range.
   tof_modulation_threshold	ToF camera laser modulation intensity	Refer to the camera’s fetch_config.xml file for the configurable range.
   tof_jitter_threshold	ToF camera jitter filtering	Refer to the camera’s fetch_config.xml file for the configurable range.
   tof_filter_threshold	ToF camera flying point filtering	Refer to the camera’s fetch_config.xml file for the configurable range.
   tof_channel	ToF camera modulation frequency	Refer to the camera’s fetch_config.xml file for the configurable range.
   tof_HDR_ratio	ToF camera high dynamic range ratio	Refer to the camera’s fetch_config.xml file for the configurable range.

   Note

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

Deployment

Single CameraMulti Cameras

ros2 launch percipio_camera percipio_camera.launch.py

Note

Do not close the terminal running the service during operation.

Running

1. Open a new terminal and run RViz:

   ros2 run rviz2 rviz2
   

2. Add Image Display.

   1. In the Global Options on the left panel, set “Fixed Frame” to “camera_depth_frame”.

   

   2. Add Depth Image Display.

      1. Click add, select “Camera”, and name it Depth Camera.

         

      2. In the settings for the newly added Depth Camera on the left panel, set “Image Topic” to “/camera/depth/image”.

         

   3. Add Color Image Display.

      1. Click add, select “Camera”, and name it Color Camera.

      2. Check the newly added Color Camera on the left panel and set “Image Topic” to “/camera/color/image_raw”.

   4. Add Left IR Image Display.

      1. Click add, select “Camera”, and name it Left IR Camera.

      2. Check the newly added Left IR Camera on the left panel and set “Image Topic” to “/camera/left_ir/image_raw”.

   5. Add Right IR Image Display.

      1. Click add, select “Camera”, and name it Right IR Camera.

      2. Check the newly added Right IR Camera on the left panel and set “Image Topic” to “/camera/right_ir/image_raw”.

   6. Add Raw Point Cloud Display.

      1. Click add, select “PointCloud2”, and name it Point Cloud.

      2. Check the newly added Point Cloud on the left panel and set “PointCloud2 Topic” to “/camera/depth/points”.

   7. Add Registered Point Cloud Display.

      1. Click add, select “PointCloud2”, and name it Registered Point Cloud.

      2. Check the newly added Registered Point Cloud on the left panel and set “PointCloud2 Topic” to “/camera/depth_registered/points”.