OrbbecSDK ROS2 Wrapper v2
Important
Welcome to the OrbbecSDK ROS2 Wrapper v2. Before you begin using this version of ROS2 wrapper, it's crucial to check the following device support list to verify the compatibility.
OrbbecSDK ROS2 Wrapper provides seamless integration of Orbbec cameras with ROS 2 environment. It supports ROS2 Foxy, Humble, and Jazzy distributions.
By default, we recommend using the v2-main branch. For older OpenNI devices not supported by v2-main, please use the main branch. Device models that are only supported by the main branch are listed in the table below.
If you are a user in China, it is recommended to use gitee Repo.
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 435Le | Gemini 435Le | 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 335L | Full maintenance | Recommended for new designs | |
| Gemini 336L | Full maintenance | Recommended for new designs | |
| Gemini 335Lg | Not supported | Recommended for new designs | |
| Gemini 335Le | Not supported | Recommended for new designs | |
| Gemini 330 | Full maintenance | Recommended for new designs | |
| Gemini 330L | Full maintenance | 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 | To be supported | |
| Femto | Femto Bolt | Full maintenance | Recommended for new designs |
| Femto Mega | Full maintenance | Recommended for new designs | |
| Femto Mega I | Full maintenance | To be supported | |
| 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 | Full maintenance |
Note: If you do not find your device, please contact our FAE or sales representative for help.
Definition:
- Recommended for new designs: we will provide full supports with new features, bug fix and performance optimization;
- Full maintenance: we will provide bug fix support;
- Limited maintenance: we will provide critical bug fix support;
- Not supported: we will not support specific device in this version;
- To be supported: we will add support in the near future.
Installation Instructions
Install ROS 2
- Please refer to the official ROS 2 installation guide guidance
If your ROS 2 command does not auto-complete, put the following two lines into your
.bashrcor.zshrc
eval "$(register-python-argcomplete3 ros2)"
eval "$(register-python-argcomplete3 colcon)"
Create colcon workspace
mkdir -p ~/ros2_ws/src
Get source code
cd ~/ros2_ws/src
git clone https://github.com/orbbec/OrbbecSDK_ROS2.git
cd OrbbecSDK_ROS2
git checkout v2-main
git branch #Check whether the branch switch is successful
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-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-backward-ros libdw-dev
Optional dependencies:
# 435Le writeCustomerDate feature:
sudo apt install libssl-dev
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
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 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 List | Minimal Firmware Version | Launch File |
|---|---|---|
| Gemini 435Le | 1.2.04 | gemini435_le.launch.py |
| Gemini 335 | 1.2.20 | gemini_330_series.launch.py |
| Gemini 336 | 1.2.20 | gemini_330_series.launch.py |
| Gemini 335L | 1.2.20 | gemini_330_series.launch.py |
| Gemini 336L | 1.2.20 | gemini_330_series.launch.py |
| Gemini 335Lg | 1.3.46 | gemini_330_series.launch.py |
| Gemini 335Le | 1.5.31 | gemini_330_series.launch.py |
| Gemini 330 | 1.2.20 | gemini_330_series.launch.py |
| Gemini 330L | 1.2.20 | gemini_330_series.launch.py |
| Gemini 2 | 1.4.92 | gemini2.launch.py |
| Gemini 2 L | 1.4.53 | gemini2L.launch.py |
| Femto Bolt | 1.1.2 | femto_bolt.launch.py |
| Femto Mega | 1.3.0 | femto_mega.launch.py |
| Astra 2 | 2.8.20 | astra2.launch.py |
| Astra Mini Pro | 2.0.01 | astra.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.
Getting start
cd ~/ros2_ws/
source /opt/ros/$ROS_DISTRO/setup.bash
# build release, Default is Debug
colcon build --event-handlers console_direct+ --cmake-args -DCMAKE_BUILD_TYPE=Release
Launch camera node
- On terminal 1
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
source ~/ros2_ws/install/setup.bash
rviz2
Select the topic you want to display
- List topics / services/ parameters ( On terminal 3)
ros2 topic list
ros2 service list
ros2 param list
- Echo a topic
ros2 topic echo /camera/depth/camera_info
- Call a service
ros2 service call /camera/get_sdk_version orbbec_camera_msgs/srv/GetString '{}'
- Record with rosbag2
ros2 bag record /camera/color/image_raw /camera/depth/image_raw
For more usage details, please refer to the official OrbbecSDK ROS2 documentation
Usage
Check which profiles the camera supports
ros2 run orbbec_camera list_camera_profile_mode_node
Optional depth presets
You can pass the firmware path of the Optional preset into the
preset_firmware_pathlaunch param.Users can download the appropriate Preset from the Depth Preset Release page provided by Orbbec based on their specific application scenarios and update it to the camera for better depth performance in corresponding scenarios.
ros2 launch orbbec_camera gemini_330_series.launch.py preset_firmware_path:=/home/orbbec/G336X_AMR_Default_v0.0.5.bin
Use V4L2 backend
Note: The V4L2 backend is not enabled by default.
- Example:
ros2 launch orbbec_camera gemini_330_series.launch.py uvc_backend:=v4l2
For more usage details, please refer to the official OrbbecSDK ROS2 documentation
Examples
To explore practical examples and gain insight into how to use the camera in ROS, please navigate to the Examples section for more information.
Other useful links
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
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