Orbbec

OrbbecSDK ROS2 Wrapper v2

English | 中文

ROS Foxy ROS Humble ROS Jazzy Ubuntu 20.04 Ubuntu 22.04 Ubuntu 24.04
branch v2-main license Apache-2.0 Gitee mirror
## Introduction The **OrbbecSDK ROS2 Wrapper** provides seamless integration of Orbbec cameras with the ROS 2 ecosystem. It supports ROS2 **Foxy**, **Humble**, and **Jazzy** distributions. - Default branch: **v2-main** - For legacy **OpenNI** devices: use the **main** branch - For users in China: use the [Gitee repository](https://gitee.com/orbbecdeveloper/OrbbecSDK_ROS2) ## branch selection Here is the device support list of main branch (v1.x) and v2-main branch (v2.x):
Product Series Product Branch main Branch v2-main
Gemini 430 Gemini 435Le not supported recommended for new designs
Gemini 301 Gemini 305 not supported recommended for new designs
Gemini 305g not supported recommended for new designs
Gemini 330 Gemini 335 full maintenance recommended for new designs
Gemini 336 full maintenance recommended for new designs
Gemini 330 full maintenance recommended for new designs
Gemini 335L full maintenance recommended for new designs
Gemini 336L full maintenance recommended for new designs
Gemini 330L full maintenance recommended for new designs
Gemini 335Lg not supported recommended for new designs
Gemini 335Le not supported recommended for new designs
Gemini 338Le not supported recommended for new designs
Gemini 338Lg not supported recommended for new designs
Gemini 340 Gemini 345Lg not supported recommended for new designs
Gemini 2 Gemini 2 full maintenance recommended for new designs
Gemini 2 L full maintenance recommended for new designs
Gemini 2 XL recommended for new designs not supported
Gemini 215 not supported recommended for new designs
Gemini 210 not supported recommended for new designs
Femto Femto Bolt full maintenance recommended for new designs
Femto Mega full maintenance recommended for new designs
Femto Mega I full maintenance recommended for new designs
Astra Astra 2 full maintenance recommended for new designs
Astra+ limited maintenance not supported
Astra Pro Plus limited maintenance not supported
Astra Mini Astra Mini Pro full maintenance recommended for new designs
Astra Mini S Pro full maintenance recommended for new designs
LiDAR Pulsar ME450 not supported recommended for new designs
Pulsar SL450 not supported recommended for new designs
**Note**: LiDAR devices are supported in v2.6.3 and later versions. For usage details, please refer to the [LiDAR documentation](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/lidar_devices/index.html). If you do not find your device, please contact our FAE or sales representative for help. **Definition**: 1. Recommended for new designs: we will provide full supports with new features, bug fix and performance optimization; 2. Full maintenance: we will provide bug fix support; 3. Limited maintenance: we will provide critical bug fix support; 4. Not supported: we will not support specific device in this version; 5. To be supported: we will add support in the near future. **Migration Guide** If you need to migrate existing projects from the main (v1.x) branch to the v2-main (v2.x) branch, please refer to the official [migration guide](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/7_developer_guide/migration_guide.html) ## Installation Instructions **Environment configuration** Install ROS 2 according to the official guide: * [ROS 2 installation (Ubuntu)](https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debians.html) Install dependencies: ```bash sudo apt install libgflags-dev nlohmann-json3-dev \ ros-$ROS_DISTRO-image-transport ros-${ROS_DISTRO}-image-transport-plugins ros-${ROS_DISTRO}-compressed-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-xacro \ ros-$ROS_DISTRO-backward-ros libdw-dev libssl-dev mesa-utils libgl1 libgoogle-glog-dev ``` Enable ROS 2 auto-completion: ```bash eval "$(register-python-argcomplete3 ros2)" eval "$(register-python-argcomplete3 colcon)" ``` **Linux Binary Package Installation** Check available packages: ```bash sudo apt update apt list | grep orbbec ``` Install OrbbecSDK ROS2 package: ```bash sudo apt install ros-humble-orbbec-camera ros-humble-orbbec-description ``` After installation, you can use it directly without compilation. **Build from Source** Create a `colcon` workspace: ```bash mkdir -p ~/ros2_ws/src ``` Clone source and checkout `v2-main` branch: ```bash cd ~/ros2_ws/src git clone https://github.com/orbbec/OrbbecSDK_ROS2.git cd OrbbecSDK_ROS2 git checkout v2-main ``` Build: ```bash cd ~/ros2_ws colcon build --event-handlers console_direct+ --cmake-args -DCMAKE_BUILD_TYPE=Release ``` ## Registration Script (Required) To allow the Orbbec cameras to be recognized correctly on Linux, install the udev rules. **Binary Installation** ```bash sudo cp /opt/ros/$ROS_DISTRO/share/orbbec_camera/udev/99-obsensor-libusb.rules /etc/udev/rules.d/ sudo udevadm control --reload-rules && sudo udevadm trigger ``` **Build from Source** ```bash cd ~/ros2_ws/src/OrbbecSDK_ROS2/orbbec_camera/scripts sudo bash install_udev_rules.sh sudo udevadm control --reload-rules && sudo udevadm trigger ``` This step is **mandatory** for Linux users. `Notes:` If this script is not executed, open the device will fail due to permission issues. You need to run the sample with sudo (administrator privileges). ## Getting start Launch camera node - On terminal 1 ```bash source ~/ros2_ws/install/setup.bash ros2 run orbbec_camera list_devices_node # Check if the camera is connected ros2 launch orbbec_camera gemini_330_series.launch.py # Or other launch file, see below table ``` - On terminal 2 ```bash source ~/ros2_ws/install/setup.bash rviz2 ``` Select the topic you want to display - List topics / services/ parameters ( On terminal 3) ```bash ros2 topic list ros2 service list ros2 param list ``` - Echo a topic ```bash ros2 topic echo /camera/depth/camera_info ``` - Call a service ```bash ros2 service call /camera/get_sdk_version orbbec_camera_msgs/srv/GetString '{}' ``` For more usage details, please refer to the official [OrbbecSDK ROS2 documentation](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/4_application_guide/application_guide.html) ## Supported Devices Currently, the following devices are supported by the OrbbecSDK ROS2 Wrapper v2-main branch. More devices support will be added in the near future. If you can not find your device in the table below, try the [main](https://github.com/orbbec/OrbbecSDK_ROS2) branch. For optimal performance, we strongly recommend updating to the latest firmware version. This ensures that you benefit from the most recent enhancements and bug fixes.
Product Series Products List Recommended FW Version Launch File
Gemini 430 Gemini 435Le 1.3.19 gemini435_le.launch.py
Gemini 301 Gemini 305 1.0.70 gemini_301_series.launch.py
Gemini 305g 1.0.70 gemini_301_series.launch.py
Gemini 330 Gemini 335 1.8.10 gemini_330_series.launch.py
Gemini 3361.8.10gemini_330_series.launch.py
Gemini 3301.8.10gemini_330_series.launch.py
Gemini 335L1.8.10gemini_330_series.launch.py
Gemini 336L1.8.10gemini_330_series.launch.py
Gemini 330L1.8.10gemini_330_series.launch.py
Gemini 335Lg1.8.10gemini_330_series.launch.py
Gemini 335Le1.8.10gemini_330_series.launch.py
Gemini 338Le1.8.17gemini_330_series.launch.py
Gemini 338Lg1.8.17gemini_330_series.launch.py
Gemini 340 Gemini 345Lg 1.9.03 gemini345_lg.launch.py
Gemini 2 Gemini 2 1.4.98 gemini2.launch.py
Gemini 2 L 1.5.2 gemini2L.launch.py
Gemini 215 1.0.9 gemini210.launch.py
Gemini 210 1.0.9 gemini210.launch.py
Femto Femto Bolt 1.1.3 femto_bolt.launch.py
Femto Mega 1.3.1 femto_mega.launch.py
Femto Mega I 2.0.4 femto_mega.launch.py
Astra Astra 2 2.8.20 astra2.launch.py
Astra Mini Astra Mini Pro 2.0.03 astra.launch.py
Astra Mini S Pro 2.0.03 astra.launch.py
LiDAR Pulsar ME450 1.0.0.6 lidar.launch.py
Pulsar SL450 2.2.4.5 lidar.launch.py
All launch files are essentially similar, with the primary difference being the default values of the parameters set for different models within the same series. Differences in USB standards, such as USB 2.0 versus USB 3.0, may require adjustments to these parameters. If you encounter a startup failure, please carefully review the specification manual. Pay special attention to the resolution settings in the launch file, as well as other parameters, to ensure compatibility and optimal performance. ## Tutorial please refer to the official [OrbbecSDK ROS2 documentation](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/5_advanced_guide/advanced_guide.html) ## Examples To explore practical examples and gain insight into how to use the camera in ROS, please navigate to the [Examples](./orbbec_camera/examples/) section for more information. ## Other useful links - [OrbbecSDK ROS2 documentation](https://orbbec.github.io/OrbbecSDK_ROS2/en/index.html) - [OrbbecSDK_v2](https://github.com/orbbec/OrbbecSDK_v2/releases) - [Gemini 330 depth presets](https://www.orbbec.com/docs/g330-use-depth-presets/) ## License Copyright 2024 Orbbec Ltd. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project except in compliance with the License. You may obtain a copy of the License at [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0) Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an " AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. **Other names and brands may be claimed as the property of others**