2.1. Build the package

This section provides a comprehensive guide to installing, compiling, and running the OrbbecSDK_ROS2, covering all necessary steps for setup.

 

2.1.1. Get source code of OrbbecSDK_ROS2

Get source code from github: https://github.com/orbbec/OrbbecSDK_ROS2

mkdir -p ~/ros2_ws/src        # Create colcon workspace on your local disk
cd ~/ros2_ws/src
git clone -b v2-main https://github.com/orbbec/OrbbecSDK_ROS2.git        #Get source code

2.1.2. Install Environment

Install ROS 2 environment, refer to the official documentation: ROS2 installation guide: https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debians.html

# Tips: If your ROS2 command does not auto-complete, put the following two lines into your `.bashrc` or `.zshrc`

eval "$(register-python-argcomplete3 ros2)"
eval "$(register-python-argcomplete3 colcon)"

Install deb dependencies:

# assume you have sourced ROS environment, same blow
sudo apt install libgflags-dev nlohmann-json3-dev  \
ros-$ROS_DISTRO-image-transport ros-$ROS_DISTRO-image-publisher ros-$ROS_DISTRO-camera-info-manager \
ros-$ROS_DISTRO-diagnostic-updater ros-$ROS_DISTRO-diagnostic-msgs ros-$ROS_DISTRO-statistics-msgs \
ros-$ROS_DISTRO-backward-ros libdw-dev ros-$ROS_DISTRO-image-transport \
ros-$ROS_DISTRO-image-transport-plugins ros-$ROS_DISTRO-compressed-image-transport

Install udev rules:

cd  ~/ros2_ws/src/OrbbecSDK_ROS2/orbbec_camera/scripts
sudo bash install_udev_rules.sh
sudo udevadm control --reload-rules && sudo udevadm trigger

DDS Tuning

The default DDS settings (Galactic) may not be optimal for data transmission. Different DDS settings can have varying performance. In this example, we use CycloneDDS. For more detailed information, please refer to the ROS DDS Tuning。

● Edit cyclonedds configuration file

sudo gedit /etc/cyclonedds/config.xml

Add

<?xml version="1.0" encoding="UTF-8"?>
<CycloneDDS xmlns="https://cdds.io/config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="https://cdds.io/confighttps://raw.githubusercontent.com/eclipse-cyclonedds/cyclonedds/master/etc/cyclonedds.xsd">
    <Domain id="any">
        <General>
            <NetworkInterfaceAddress>lo</NetworkInterfaceAddress>
            <AllowMulticast>false</AllowMulticast>
        </General>
        <Internal>
            <MinimumSocketReceiveBufferSize>16MB</MinimumSocketReceiveBufferSize>
        </Internal>
        <Discovery>
            <ParticipantIndex>auto</ParticipantIndex>
            <MaxAutoParticipantIndex>30</MaxAutoParticipantIndex>
            <Peers>
                <Peer address="localhost"/>
            </Peers>
        </Discovery>
    </Domain>
</CycloneDDS>

● Set the environment variables, add to .zshrc or .bashrc

export ROS_DOMAIN_ID=42 # Numbers from 0 to 232
export ROS_LOCALHOST_ONLY=1
export CYCLONEDDS_URI=file:///etc/cyclonedds/config.xml

Tip：to understand why the maximum ROS_DOMAIN_ID is 232, please visit The ROS DOMAIN ID ● Increase UDP receive buffer size Edit

/etc/sysctl.d/10-cyclone-max.conf

Add

net.core.rmem_max=2147483647
net.core.rmem_default=2147483647

If you use Fast DDS, you can refer to the Fast DDS Configuration file.

Increase usbfs_memory_mb Value

  • Increase the usbfs_memory_mb value to 128MB (this is a reference value and can be adjusted based on your system’s needs) by running the following command:

    echo 128 | sudo tee /sys/module/usbcore/parameters/usbfs_memory_mb

  • To make this change permanent, check this link.

  • The permanent steps are as follows:

    Open /etc/default/grub file,Find and replace

GRUB_CMDLINE_LINUX_DEFAULT="quiet splash"

with this

GRUB_CMDLINE_LINUX_DEFAULT="quiet splash usbcore.usbfs_memory_mb=128"

Update grub

$ sudo update-grub

Reboot and check

$ cat /sys/module/usbcore/parameters/usbfs_memory_mb

2.1.3. Common Configurations

2.1.3.1. Use V4L2 backend

To enable the V4L2 backend for the Gemini2 series cameras, follow these steps:

  1. The Gemini2 series cameras support the V4L2 backend.

  2. Open the config/OrbbecSDKConfig_v1.0.xml file.

  3. Set the navigation option to LinuxUVCBackend.

  4. Change the backend setting to V4L2.

Note: The V4L2 backend is not enabled by default.

2.1.3.2. Predefined presets

Preset Features Recommended use cases
Default - Best visual perception``- Overall good performance in accuracy, fill rate, tiny objects, etc. - Generic <br>- Robotics
Hand - Clear hand and finger edges - Gesture recognition
High Accuracy - Depth of high confidence <br>- Barely noise depth values <br>- Lower fill rate - Collision avoidance <br>- Object scanning
High Density - Higher fill rate <br>- More tiny objects <br>- May suffer from noise depth values - Object recognition <br>- Pick & place <br>- Foreground & background animation
Medium Density - Balanced performance in fill rate and accuracy <br>- In comparison to Default: lower fill rate, better edge quality - Generic and alternative to Default
Custom - User defined Preset <br>- Derived from Presets above, with customized modifications, e.g. a new configuration for the post-processing pipeline, modified mean intensity set point of depth AE function, etc. - Better depth performance achieved using customized configurations in comparison to using predefined presets <br>- For well-established custom configurations

Choose the appropriate preset name based on your specific use case and set it as the value for the device_preset parameter.

2.1.3.3. Depth work mode switch

OrbbecSDK_ROS2 supports the depth work mode switch. The depth work mode switch is supported by Gemini 2, Gemini 2 L, and Femto and Femto Bolt cameras.

  • Before starting the camera, depth work mode (depth_work_mode) can be configured for the corresponding xxx.launch.py file’s support.

  • The depth work mode switch is supported by Gemini 2, Gemini 2 L, and Gemini 2 XL cameras.

  • The default depth work mode configuration of xxx.launch.py is the camera’s default configuration. If you need to modify it, you can switch to the corresponding mode as needed.

  • The specific camera depth work mode support types can be found in the comments of the depth mode.

# Depth work mode support is as follows:
# Unbinned Dense Default
# Unbinned Sparse Default
# Binned Sparse Default
# Obstacle Avoidance
DeclareLaunchArgument('depth_work_mode', default_value='')

  • View depth work modes:

ros2 run orbbec_camera list_depth_work_mode_node

2.1.3.4. Configuration of depth NFOV and WFOV modes

For the Femto Mega and Femto Bolt devices, the NFOV and WFOV modes are implemented by configuring the resolution of Depth and IR in the launch file. In launch file, depth_width、depth_height、ir_width、ir_height represents the resolution of the depth and the resolution of the IR. The frame fps and resolution of IR must be consistent with the depth. The correspondence between different modes and resolutions is as follows:

  • NFOV unbinned: 640 x 576.

  • NFOV binned: 320 x 288.

  • WFOV unbinned: 1024 x 1024.

  • WFOV binned: 512 x 512.

2.1.3.5. Network device enumeration

Currently, the network device enumeration function is supported only by the Femto Mega device. When accessing this device over the network, if enumerate_net_device is set to true, the device will be automatically enumerated, eliminating the need to configure the IP address in advance or set the enable switch to true. The specific configuration methods are as follows:

  • enumerate_net_device: enumeration network device automatically, only supported by Femto Mega. if enumerate_net_device set to true, the device will be enumerated automatically,No need to set the net_device_ip and net_device_port parameters.

  • net_device_ip: The IP address of the device.

  • net_device_port: The port number of the device.

2.1.3.6. Compressed Image

You can use image_transport to compress the image using jpeg. Below is an example of how to use it: To access the compressed color image, you can use the following command:

ros2 topic echo /camera/color/image_raw/compressed --no-arr

This command will allow you to receive the compressed color image from the specified topic.

Note: The compressed topic for depth is /camera/depth/image_raw/compressedDepth. The compressed topics for color and IR are /camera/color/image_raw/compressed and /camera/ir/image_raw/compressed, respectively.

2.1.4. Build project

cd ~/ros2_ws/
# build release, Default is Debug
colcon build --event-handlers console_direct+ --cmake-args -DCMAKE_BUILD_TYPE=Release

2.1.5. Building a Debian Package

Preparing the Environment

Before starting, install the required tools:

sudo apt install debhelper fakeroot python3-bloom

Configuring ROS Dependencies

Add the following YAML file to your system at /etc/ros/rosdep/sources.list.d/00-orbbec.yaml. Make sure to replace focal with the codename of your Ubuntu version and humble with your ROS2 distribution name:

orbbec_camera_msgs:
  ubuntu:
    focal: [ ros-humble-orbbec-camera-msgs ]

Next, create a new file /etc/ros/rosdep/sources.list.d/50-orbbec.list and add this line to specify the path to the YAML file:

yaml file:///etc/ros/rosdep/sources.list.d/00-orbbec.yaml

Update the rosdep database to reflect these changes:

rosdep update

Building the Package

Navigate to your workspace and build the project:

cd ~/ros2_ws/
colcon build --event-handlers console_direct+ --cmake-args -DCMAKE_BUILD_TYPE=Release
. install/setup.bash
cd src/OrbbecSDK_ROS2/
bash .make_deb.sh