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.

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

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

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.

Configure Environment Variables

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 Parameter Configurations

Parameters to be loaded at camera start up can be configured in the percipio_camera.launch.py or multi_cam.launch.py launch file.

Important

Through the launch file, only part of the 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: Manage Parameter Configuration.

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.

    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 List

    Argument

    Description

    default_value Configurable Range

    camera_name

    Topic name

    Customizable; used to distinguish between cameras in multi-camera setups.

    serial_number

    Camera serial Number (SN)

    Can be left empty; or filled with the SN 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

    To enable color data output

    true/false

    color_resolution

    Color image resolution

    Refer to the camera’s fetch_config.xml file for the parameter setting options.

    color_format

    Color image format

    Refer to StreamFormatMapper format_mapper_list[] in the camport3_ros2/src/percipio_camera/src/percipio_device.cpp file for the parameter setting options.

    color_qos

    Quality of service (QoS)

    of the color data

    SYSTEM_DEFAULT、DEFAULT、PARAMETER_EVENTS、SERVICES_DEFAULT、PARAMETERS、SENSOR_DATA

    color_camera_info_qos

    Quality of service (QoS)

    of the color camera info data

    SYSTEM_DEFAULT、DEFAULT、PARAMETER_EVENTS、SERVICES_DEFAULT、PARAMETERS、SENSOR_DATA

    depth_enable

    To enable depth data_skip output

    true/false

    depth_resolution

    depth map resolution

    Refer to the camera’s fetch_config.xml file for the parameter setting options.

    depth_format

    depth map format

    Refer to StreamFormatMapper format_mapper_list[] in the camport3_ros2/src/percipio_camera/src/percipio_device.cpp file for the parameter setting options.

    depth_qos

    Quality of service (QoS)

    of the depth data

    SYSTEM_DEFAULT、DEFAULT、PARAMETER_EVENTS、SERVICES_DEFAULT、PARAMETERS、SENSOR_DATA

    depth_camera_info_qos

    Quality of service (QoS)

    of the depth camera info data

    SYSTEM_DEFAULT、DEFAULT、PARAMETER_EVENTS、SERVICES_DEFAULT、PARAMETERS、SENSOR_DATA

    depth_registration_enable

    To enable the depth-to-color registration

    true/false

    point_cloud_enable

    To enable point cloud output

    true/false

    color_point_cloud_enable

    To enable colored point cloud output

    true/false

    point_cloud_qos

    Quality of service (QoS)

    of the point cloud data

    SYSTEM_DEFAULT、DEFAULT、PARAMETER_EVENTS、SERVICES_DEFAULT、PARAMETERS、SENSOR_DATA

    left_ir_enable

    To enable left IR data output

    true/false

    left_ir_resolution

    Left IR image resolution

    Refer to the camera’s fetch_config.xml file for the parameter setting options.

    left_ir_format

    Left IR image format

    Refer to StreamFormatMapper format_mapper_list[] in the camport3_ros2/src/percipio_camera/src/percipio_device.cpp file for the parameter setting options.

    left_ir_qos

    Quality of service (QoS)

    of the left IR data

    SYSTEM_DEFAULT、DEFAULT、PARAMETER_EVENTS、SERVICES_DEFAULT、PARAMETERS、SENSOR_DATA

    left_ir_camera_info_qos

    Quality of service (QoS)

    of the left IR camera info data

    SYSTEM_DEFAULT、DEFAULT、PARAMETER_EVENTS、SERVICES_DEFAULT、PARAMETERS、SENSOR_DATA

    right_ir_enable

    To enable right IR data output

    true/false

    right_ir_resolution

    Right IR image resolution

    Refer to the camera’s fetch_config.xml file for the parameter setting options.

    right_ir_format

    Right IR image format

    Refer to StreamFormatMapper format_mapper_list[] in the camport3_ros2/src/percipio_camera/src/percipio_device.cpp file for the parameter setting options.

    right_ir_qos

    Quality of service (QoS)

    of the right IR data

    SYSTEM_DEFAULT、DEFAULT、PARAMETER_EVENTS、SERVICES_DEFAULT、PARAMETERS、SENSOR_DATA

    right_ir_camera_info_qos

    Quality of service (QoS)

    of the right IR camera info data

    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 the parameter setting options.

    tof_modulation_threshold

    ToF camera laser modulation intensity

    Refer to the camera’s fetch_config.xml file for the parameter setting range.

    tof_jitter_threshold

    ToF camera jitter filtering threshold

    Refer to the camera’s fetch_config.xml file for the parameter setting range.

    tof_filter_threshold

    ToF camera outlier filtering threshold

    Refer to the camera’s fetch_config.xml file for the parameter setting range.

    tof_channel

    ToF camera modulation frequency

    Refer to the camera’s fetch_config.xml file for the parameter setting range.

    tof_HDR_ratio

    ToF camera high dynamic range ratio

    Refer to the camera’s fetch_config.xml file for the parameter setting 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 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.

Publish

ros2 launch percipio_camera percipio_camera.launch.py

Note

Do not close the terminal running the service during operation.

Run

  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.

    Global Options Settings

    1. Add depth map Display.

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

        Add Depth Camera

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

        Add Depth Camera

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

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

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

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

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