ROS1 platform

ROS (Robot Operating System, hereinafter referred to as ROS) is an open-source meta-operating system suitable for robots. It provides the services that an operating system should have, including hardware abstraction, underlying device control, implementation of common functions, inter-process messaging, and package management.

Setting up ROS1 development environment

Install the corresponding ROS1 development platform according to the Ubuntu version.

Ubuntu16.04: ROS Kinetic
Ubuntu18.04: ROS Melodic
Ubuntu20.04: ROS Noetic

Downloading Camport ROS1 SDK

ROS1 SDK supports the ROS Kinetic, ROS Melodic and ROS Noetic platforms.

Choose any of the following methods to download the Camport ROS1 SDK:

Access https://github.com/percipioxyz/ using a browser and download the Camport ROS 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://github.com/percipioxyz/camport_ros.git
```

The directory of Camport ROS1 SDK is shown in the following figure:

Camport ROS1 SDK目录 — Camport ROS1 SDK directory

percipio_camera: includes source files and configuration files.
percipio_launch: launch package.

Compiling sample programs

To compile the sample programs, execute the following command in the root directory of the development package:

catkin_make

Tip

If the catkin command is not installed, you need to install catkin first.

After compilation, the build folder (containing intermediate files) and the devel folder (containing header files, dynamic/static libraries and executable files) will be generated.

Configuring environment variables

To configure the environment variables, execute the following command in the root directory of the development package:

echo "source <the root directory of the development package>/camport_ros/devel/setup.bash" >> ~/.bashrc

Modifying Launch Configuration

To configure the parameters loaded when the camera starts in the percipio.launch file, do the following:

Execute the following command to open the percipio.launch file:

cd src/percipio_launch/launch/
gedit percipio.launch

Modify the configuration as needed.

Specify camera SN in default:
<arg name="device_id" default="207000106930" />
Tip

The device_id is set to #1 by default, which means the first camera found will be opened by default.
Set the switch for exposure synchronization of left and right infrared images in the default:
<arg name="cmos-sync" default="true" />
Set the switch for alignment of depth and color images in the default:
<arg name="depth_registration" default="true" />
Note

This enable switch will only take effect when the color image and the depth map are both captured. This setting is invalid for cameras without RGB modules.

Modifying Percipio.cfg configuration

The parameters in the Percipio.cfg file support dynamic adjustment. After modifying the maximum and minimum values of the Percipio.cfg parameters, refer to the running section to bring up the rqt_reconfigure_Param page and make adjustments.

Execute the following command in the root directory of the software package to open the Percipio.cfg file.
```
cd src/percipio_camera/cfg/
gedit Percipio.cfg
```
Set the minimum and maximum values for the parameters in gen.add( ).
Tip
1. gen.add (name, type, level, description, default, min, max) represents the feature name, type, level, description, default value, minimum value, and maximum value.
2. Boolean values must be written as True or False (with the first letter capitalized).
Note
1. If you don’t know the minimum and maximum values of camera features, you can view the supported components and features of the camera by one of the following steps:
  - Run the SDK sample program DumpAllFeatures to view the components and features supported by the camera in the listed information.
  - Run the SDK sample program DumpAllFeatures -d and check the supported components and features of the camera in the generated fetch_config.xml file.
2. The setting range of the following parameters can be customized:
  - depth_speckle_filter: Speckle filter switch. Speckle filtering is used to filter out small speckle noise in the depth map.
  - max_speckle_size: The maximum size of speckle noise. Speckles larger than this setting are considered not to be noise. It is recommended to set the range between [10, 3000].
  - max_speckle_diff: The maximum depth difference between adjacent pixels in the same speckle. If the depth difference between adjacent pixels is greater than this set value, then those adjacent pixels are considered to belong to two different speckles. It is recommended to set the range between [10, 1500].
  - data_skip: Frame skipping. For example, if the publishing node of Percipio is actually 30fps, but the receiving node of ROS only wants to receive 10fps, you can set data_skip to 3. It is recommended to set the range between [0,20].
  - z_scaling: the depth value unit of the pixel in the depth map. It is recommended to set the range to [0,8].
  - use_device_time: Default setting is True, indicating the use of the camera’s internal timestamp; when set to False, it indicates the use of ROS timestamp.
Execute the following commands to recompile. After compilation, the changes made to Percipio.cfg will take effect.
```
catkin_make
```

Subscribing

Execute the following command in the root directory of the development package to subscribe to the service:

roslaunch percipio_launch percipio.launch

Note

During operation, please do not close this service terminal.

Running

Open a new terminal and execute the following command to run RViz:
```
rosrun rviz rviz
```
Add image display.
1. In the left side of the page, in the Global Options settings, set “Fixed Frame” to “camera_depth_frame”.
2. Add depth map display.
  1. Click on add, add “Camera”, name it “Depth Camera”.
  2. In the newly added Depth Camera settings on the left side of the page, set “Image Topic” to “/camera/depth/image”.
3. Add color image display.
  1. Click on add, add “Camera”, and name it “Color Camera”.
  2. Check the newly added Color Camera on the left side of the page and set the “Image Topic” to “/camera/rgb/image_raw” in the settings.
4. Add IR image display.
  1. Click on add, add “Image”, name it “IR Camera”.
  2. Check the newly added IR Camera on the left side of the page and set the “Image Topic” to “/camera/ir/image” in the settings.
5. Add point cloud display.
  1. Click on add, add “DepthCloud”, name it “Point Cloud”.
  2. Check the newly added Point Cloud on the left side of the page and set the “Depth map Topic” to “/camera/depth/image”.
According to the imaging situation, dynamically adjust the camera parameters.

Execute the following command to bring up the rqt_reconfigure_Param page. Select the driver and adjust the parameters on the page.
rosrun rqt_reconfigure rqt_reconfigure

Solution for multi-device simultaneous access

Edit .launch file.

Refer to the percipio.launch document to create multiple .launch. Configure “camera” and “device_id” with different values in each .launch file. For example, to run two devices simultaneously, create two .launch files, namely percipio_camera1.launch and percipio_camera2.launch.

percipio_camera1.launch contains the following content:
```
<arg name="camera" default="camera1">
......
<arg name="device_id" default="207000010443">
......
```
percipio_camera2.launch contains the following content:
```
<arg name="camera" default="camera2">
......
<arg name="device_id" default="207000010113">
......
```
Execute the following command in the root directory of the development package to reconfigure the environment variables:
```
source ./devel/setup.bash
```
Open the device with serial number 207000010443 by running the command roslaunch percipio_launch percipio_camera1.launch.

Open the device with serial number 207000010113 by running the command roslaunch percipio_launch percipio_camera2.launch.