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 for robot development, simplifying the creation and management of robotic applications. Developed and maintained by Open Robotics, ROS 2 inherits many advantages from ROS 1 while making architectural and functional improvements to meet the requirements of modern robotic systems.

Setting Up the ROS 2 Development Environment

Install the corresponding ROS 2 development platform based on your Ubuntu version.
- Ubuntu 20.04: ROS 2 Foxy
- Ubuntu 22.04: ROS 2 Humble

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

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

Set environment variables

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

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

Download Camport ROS 2 SDK

Create a working directory

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

Choose any of the following methods to download the Camport ROS 2 SDK:
- Download via browser: https://github.com/percipioxyz/camport_ros2.git.
- Use git command to get a local copy: Open a terminal, navigate to the working directory where you want to store the SDK, and enter the git clone command to clone the remote repository.
```
git clone https://github.com/percipioxyz/camport_ros2.git
```

The directory structure of the Camport ROS 2 SDK is shown below:

camport_ros2/
├── 📂 src/                           # ROS 2 source code directory
│   └── 📂 percipio_camera/          # ROS 2 camera driver package
│       ├── 📂 camport4/             # Camport4 SDK integration
│       ├── 📂 include/              # Header files directory
│       ├── 📂 launch/               # ROS 2 launch configuration files
│       ├── 📂 src/                  # C++ source files directory
│       ├── 📄 CMakeLists.txt        # CMake build configuration file
│       └── 📄 package.xml           # ROS 2 package definition file
└── 📄 README.md                      # ROS 2 compilation instructions document

src/percipio_camera/camport4: Contains Percipio SDK library files and header files.
src/percipio_camera/include: Contains header files.
src/percipio_camera/launch: Contains ROS 2 launch files for starting nodes and configuring parameters. percipio_camera.launch.py is used to start a single camera, while multi_cam.launch.py is used to start multiple cameras. Additionally, several Python scripts included in the package can be used to subscribe to nodes and display image data, send software triggers, perform offline detection, etc. For details, refer to Subscribe to Camera Node.
src/percipio_camera/src: Contains main source code files, including node implementation and camera drivers.
src/percipio_camera/CMakeLists.txt: CMake build system configuration file.
src/percipio_camera/package.xml: Package manifest file describing the package name, version, author information, license information, build dependencies, etc.
README.md: Briefly describes the ROS 2 compilation process.

Compilation

cd ~/ros2_ws/src/camport_ros2/
colcon build --event-handlers  console_direct+  --cmake-args  -DCMAKE_BUILD_TYPE=Release

Tip

colcon build explanation:

--event-handlers console_direct+: This option specifies the event handler. console_direct+ means detailed information about build events is output directly to the console. This allows you to see each step of the build process and any potential error messages more clearly.
--cmake-args -DCMAKE_BUILD_TYPE=Release: This option passes additional CMake arguments. In this case, -DCMAKE_BUILD_TYPE=Release sets the CMake build type to Release. This means the build will be optimized for a release version, not a debug version.

The following folders are generated after compilation:

build: Intermediate files and target files.
install: Executables, library files, header files, and other resource files.
log: Contains log files generated during compilation and runtime.

Configure Environment Variables

sudo echo "source ./install/setup.bash" >> ~/.bashrc
source ~/.bashrc

Modify Parameter Configuration

ROS 2 supports three ways to modify camera parameters.

Method 1: Pre-configure parameters using Viewer software and save them to the camera (Recommended)

GigE2.1 Cameras (PMD Series and GM Series Cameras)

Use Viewer software to save parameter settings to a UserSet attribute group and set this group as the default User Set attribute group to load. The camera will automatically load the parameter configuration from this User Set attribute group upon power-up.
GigE2.0 Cameras (Cameras other than PMD Series and GM Series)

Use Percipio Viewer software to save parameter settings to the camera’s Storage area. ROS will automatically load the parameter configuration from the Storage area upon startup and begin image acquisition.

Method 2: Edit launch.py configuration file

Configure parameters to be loaded when the camera node starts in percipio_camera.launch.py / multi_cam.launch.py. This method is only applicable to parameters included in the configuration file. Specific steps are as follows:

Navigate to “camport_ros2/install/percipio_camera/share/percipio_camera/launch”.
Modify parameter configuration.

If using a single camera, open the percipio_camera.launch.py file and modify parameter configurations as needed.

Example: Specifying a Camera
Specify camera by SN
DeclareLaunchArgument('serial_number', default_value='"207000106930"'),
Specify camera by IP address
DeclareLaunchArgument('device_ip', default_value='192.168.120.112'),
Note

If a camera is not specified by SN or IP, the first camera found will be opened by default.

For more parameter configuration descriptions, refer to the table below.
If using multiple cameras, open the multi_cam.launch.py file and modify parameter configurations as needed.

The multi_cam.launch.py file is configured for two cameras by default. To configure more cameras, add launch x (x=3,4…n) following the content of launch 1 and launch 2.

For parameter configuration descriptions, refer to the table below.
Configurable Parameters in launch.py

Parameter Name

Description

Value Range

camera_name

Node name

Customizable, can be used to distinguish cameras in multi-camera scenarios

serial_number

Camera SN

Can be empty; or fill in the SN of the camera to connect

device_ip

Camera IP address

Can be empty; or fill in the IP address of the camera to connect

device_log_enable

SDK log switch

true/false

device_log_level

SDK log level

VERBOSE / DEBUG / INFO / WARNING / ERROR / NEVER

device_log_server_port

SDK log server port

Default: 9001

frame_rate_control

Frame rate control switch

true/false

frame_rate

Set output frame rate

Float, Default: 5.0

device_workmode

Camera trigger mode

trigger_off/trigger_soft/trigger_hard

(Corresponding to: continuous output, software trigger, and hardware trigger modes respectively)

device_auto_reconnect

Camera offline reconnection

true/false

color_enable

Color image enable

true/false

color_resolution

Color image resolution

Setting range, refer to the camera’s fetch_config.xml file

color_qos

Color 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

Depth image enable

true/false

depth_resolution

Depth image resolution

Setting range, refer to the camera’s fetch_config.xml file

depth_qos

Depth 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

Depth to Color alignment enable

true/false

depth_speckle_filter

Depth image speckle filter switch

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

max_physical_size

Maximum physical size

Default: 20.0

depth_time_domain_filter

Temporal filter switch

true/false

depth_time_domain_num

Temporal filter count

Default: 3, Range: 2-10

point_cloud_enable

Point cloud image enable

true/false

color_point_cloud_enable

Colored point cloud image enable

true/false

point_cloud_qos

Point cloud QoS

SYSTEM_DEFAULT/DEFAULT/PARAMETER_EVENTS/SERVICES_DEFAULT/PARAMETERS/SENSOR_DATA

ir_enhancement

Infrared enhancement mode

off/linear/multi_linear/std_linear/log/hist

ir_enhancement_coefficient

Infrared enhancement coefficient

Default: 9; multi_linear: 1-20; std_linear: 3-10; log: 10-30

ir_undistortion

Infrared distortion correction

true/false

left_ir_enable

Left IR image enable

true/false

left_ir_qos

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

Note

Explanation of xxx_qos configurable values:

SYSTEM_DEFAULT: Uses the system’s default QoS settings, typically defined by the underlying DDS (Data Distribution Service) implementation. The 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: QoS settings specifically for parameter events, ensuring reliable delivery of parameter change events. Retains up to 1000 of the latest messages.

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

PARAMETERS: QoS settings specifically for parameters, ensuring reliability for 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 stream transmission. Retains up to 5 of the latest messages.

If a camera outputs images with a resolution not supported as configured in the percipio.launch file, the camera will output images with the default configuration.

Method 3: Edit parameters.xml configuration file

Navigate to “camport_ros2/install/percipio_camera/share/percipio_camera/launch” to configure parameters loaded when the camera node starts. This method is only applicable to parameters included in the configuration file.

Parameter setting instructions are as follows:

Float type parameter

<feature name="DepthScaleUnit">0.125</feature> // Replace 0.125 with the target parameter value

Int type parameter

<feature name="DepthSgbmImageNumber">1</feature> // Replace 1 with the target parameter value

Bool type parameter

<feature name="ExposureAuto">1</feature> // Replace with 1 or 0, do not use true or false

Enum type parameter

<feature name="DepthStreamTofChannel">0</feature> // Replace 0 with the integer value corresponding to the enumeration value

Start Camera Node

ros2 launch percipio_camera percipio_camera.launch.py

ros2 launch percipio_camera multi_cam.launch.py

If the camera node starts normally, the terminal will print information such as camera IP, SN, depth and color image formats and resolutions.

Attention

Do not close the service terminal during operation.

Auxiliary Tools Description

list_devices Enumerate Cameras

Run the following code to enumerate Percipio cameras connected to the computer.

ros2 run percipio_camera list_devices

network_ip_config Set Camera IP Address

Run the following code and follow the prompts to set the camera IP address. Supports setting static and dynamic IP addresses.

ros2 run percipio_camera network_ip_config

ROS 2 Platform

Setting Up the ROS 2 Development Environment

Download Camport ROS 2 SDK

Compilation

Configure Environment Variables

Modify Parameter Configuration

Start Camera Node

Subscribe to Topics

Available Topics

Preview Images

Camera Software Reset

Monitor Camera Events

Dynamically Modify Camera Parameters

Send Camera Software Trigger

Auxiliary Tools Description

list_devices Enumerate Cameras

network_ip_config Set Camera IP Address

Frequently Asked Questions