2024-11-25 15:29:10 +08:00
# OrbbecSDK ROS2 Wrapper v2
2024-10-21 17:47:54 +08:00
2024-11-25 15:29:10 +08:00
> [!IMPORTANT]
>
2024-12-24 18:05:55 +08:00
> 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](#supported-devices) to verify the compatibility.
2022-06-10 14:24:27 +08:00
2024-11-25 15:29:10 +08:00
OrbbecSDK ROS2 Wrapper provides seamless integration of Orbbec cameras with ROS 2 environment. It supports ROS2 Foxy, Humble, and Jazzy distributions.
2024-11-01 17:14:16 +08:00
2024-11-25 19:42:38 +08:00
With a major update in October 2024, we release the [OrbbecSDK ROS2 Wrapper v2 ](https://github.com/orbbec/OrbbecSDK_ROS2/tree/v2-main ) connected to the open source [OrbbecSDK v2 ](https://github.com/orbbec/OrbbecSDK_v2/releases ) with enhanced flexibility and extensibility. This update ensures compatibility with all Orbbec USB products adhering to UVC standard. However, it no longer supports Orbbec's traditional OpenNI protocol devices. We strongly encourage you to use the v2-main branch if your device is supported.
2024-11-22 14:17:47 +08:00
2025-05-22 19:40:01 +08:00
If you are a user in China, it is recommended to use [gitee Repo ](https://gitee.com/orbbecdeveloper/OrbbecSDK_ROS2 ).
2024-11-25 19:42:38 +08:00
Here is the device support list of main branch (v1.x) and v2-main branch (v2.x):
2024-11-25 15:29:10 +08:00
<table border="1" style="border-collapse: collapse; text-align: left; width: 100%;">
<thead>
<tr style="background-color: #1f4e78 ; color: white; text-align: center;">
<th>Product Series</th>
<th>Product</th>
2024-11-25 19:42:38 +08:00
<th><a href="https://github.com/orbbec/OrbbecSDK_ROS2/tree/main" style="color: black; text-decoration: none;">Branch main</a></th>
<th><a href="https://github.com/orbbec/OrbbecSDK_ROS2/tree/v2-main" style="color: black; text-decoration: none;">Branch v2-main</a></th>
2024-11-25 15:29:10 +08:00
</tr>
</thead>
<tbody>
<tr>
2025-05-22 17:25:25 +08:00
<td style="text-align: center; font-weight: bold;">Gemini 435Le</td>
<td>Gemini 435Le</td>
<td>Not supported</td>
<td>Recommended for new designs</td>
</tr>
<tr>
<td rowspan="8" style="text-align: center; font-weight: bold;">Gemini 330</td>
2024-11-25 15:29:10 +08:00
<td>Gemini 335</td>
2025-05-06 17:41:55 +08:00
<td>Full maintenance</td>
<td>Recommended for new designs</td>
2024-11-25 15:29:10 +08:00
</tr>
<tr>
<td>Gemini 336</td>
2025-05-06 17:41:55 +08:00
<td>Full maintenance</td>
<td>Recommended for new designs</td>
2024-11-25 15:29:10 +08:00
</tr>
<tr>
<td>Gemini 335L</td>
2025-05-06 18:27:19 +08:00
<td>Full maintenance</td>
2025-05-06 17:41:55 +08:00
<td>Recommended for new designs</td>
2024-11-25 15:29:10 +08:00
</tr>
<tr>
<td>Gemini 336L</td>
2025-05-06 17:41:55 +08:00
<td>Full maintenance</td>
<td>Recommended for new designs</td>
2024-11-25 15:29:10 +08:00
</tr>
<tr>
<td>Gemini 335Lg</td>
2025-05-06 17:41:55 +08:00
<td>Not supported</td>
<td>Recommended for new designs</td>
2024-11-25 15:29:10 +08:00
</tr>
2025-04-16 20:31:28 +08:00
<tr>
<td>Gemini 335Le</td>
2025-05-06 17:41:55 +08:00
<td>Not supported</td>
<td>Recommended for new designs</td>
2025-04-16 20:31:28 +08:00
</tr>
2025-05-12 14:32:20 +08:00
<tr>
2025-05-22 17:25:25 +08:00
<td>Gemini 330</td>
<td>Full maintenance</td>
<td>Recommended for new designs</td>
</tr>
<tr>
<td>Gemini 330L</td>
<td>Full maintenance</td>
2025-05-12 14:32:20 +08:00
<td>Recommended for new designs</td>
</tr>
2024-11-25 15:29:10 +08:00
<tr>
<td rowspan="3" style="text-align: center; font-weight: bold;">Gemini 2</td>
<td>Gemini 2</td>
2025-05-06 17:41:55 +08:00
<td>Full maintenance</td>
<td>Recommended for new designs</td>
2024-11-25 15:29:10 +08:00
</tr>
<tr>
<td>Gemini 2 L</td>
2025-05-06 17:41:55 +08:00
<td>Full maintenance</td>
<td>Recommended for new designs</td>
2024-11-25 15:29:10 +08:00
</tr>
<tr>
<td>Gemini 2 XL</td>
2025-05-06 17:41:55 +08:00
<td>Recommended for new designs</td>
<td>To be supported</td>
2024-11-25 15:29:10 +08:00
</tr>
<tr>
<td rowspan="3" style="text-align: center; font-weight: bold;">Femto</td>
<td>Femto Bolt</td>
2025-05-06 17:41:55 +08:00
<td>Full maintenance</td>
<td>Recommended for new designs</td>
2024-11-25 15:29:10 +08:00
</tr>
<tr>
2024-11-28 17:18:57 +08:00
<td>Femto Mega</td>
2025-05-06 17:41:55 +08:00
<td>Full maintenance</td>
<td>Recommended for new designs</td>
2024-11-28 17:18:57 +08:00
</tr>
2024-11-25 15:29:10 +08:00
<tr>
<td>Femto Mega I</td>
2025-05-06 17:41:55 +08:00
<td>Full maintenance</td>
<td>To be supported</td>
2024-11-25 15:29:10 +08:00
</tr>
<tr>
<td rowspan="3" style="text-align: center; font-weight: bold;">Astra</td>
<td>Astra 2</td>
2025-05-06 17:41:55 +08:00
<td>Full maintenance</td>
<td>Recommended for new designs</td>
2024-11-25 15:29:10 +08:00
</tr>
<tr>
<td>Astra+</td>
2025-05-06 17:41:55 +08:00
<td>Limited maintenance</td>
<td>Not supported</td>
2024-11-25 15:29:10 +08:00
</tr>
<tr>
<td>Astra Pro Plus</td>
2025-05-06 17:41:55 +08:00
<td>Limited maintenance</td>
<td>Not supported</td>
2024-11-25 15:29:10 +08:00
</tr>
<tr>
<td style="text-align: center; font-weight: bold;">Astra Mini</td>
<td>Astra Mini Pro</td>
2025-05-06 17:41:55 +08:00
<td>Full maintenance</td>
<td>Not supported</td>
2024-11-25 15:29:10 +08:00
</tr>
</tbody>
</table>
**Note** : If you do not find your device, please contact our FAE or sales representative for help.
2024-11-25 19:42:38 +08:00
2024-11-25 15:29:10 +08:00
**Definition** :
2025-05-06 17:41:55 +08:00
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.
2024-11-22 14:17:47 +08:00
2024-05-14 10:12:54 +08:00
## Table of Contents
2024-06-18 11:57:27 +08:00
2024-11-25 15:29:10 +08:00
- [OrbbecSDK ROS2 Wrapper v2 ](#orbbecsdk-ros2-wrapper-v2 )
- [Table of Contents ](#table-of-contents )
- [Installation Instructions ](#installation-instructions )
- [Supported Devices ](#supported-devices )
2025-05-06 17:41:55 +08:00
- [Getting start ](#getting-start )
- [Usage ](#usage )
- [Launch parameters ](#launch-parameters )
- [All available service for camera control ](#all-available-service-for-camera-control )
- [All available topics ](#all-available-topics )
- [Network device enumeration ](#network-device-enumeration )
- [GMSL device enumeration ](#gmsl-device-enumeration )
- [Multi-Camera ](#multi-camera )
- [Check which profiles the camera supports ](#check-which-profiles-the-camera-supports )
- [Predefined presets ](#predefined-presets )
2025-06-04 09:40:32 +08:00
- [Optional depth presets ](#optional-depth-presets )
2025-05-06 17:41:55 +08:00
- [Depth work mode switch ](#depth-work-mode-switch )
- [Configuration of depth NFOV and WFOV modes ](#configuration-of-depth-nfov-and-wfov-modes )
- [Advanced Usage ](#advanced-usage )
- [Use V4L2 backend ](#use-v4l2-backend )
- [DDS Tuning ](#dds-tuning )
- [Efficient intra-process communication ](#efficient-intra-process-communication )
- [ROS2(Robot) vs Optical(Camera) Coordination Systems ](#ros2robot-vs-opticalcamera-coordination-systems )
- [Camera sensor structure ](#camera-sensor-structure )
- [TF from coordinate A to coordinate B ](#tf-from-coordinate-a-to-coordinate-b )
- [Compressed Image ](#compressed-image )
- [Building a Debian Package ](#building-a-debian-package )
- [Examples ](#examples )
2024-11-25 15:29:10 +08:00
- [Frequently Asked Questions ](#frequently-asked-questions )
- [Unexpected Crash ](#unexpected-crash )
- [No Data Stream from Multiple Cameras ](#no-data-stream-from-multiple-cameras )
- [Additional Troubleshooting ](#additional-troubleshooting )
- [Why Are There So Many Launch Files? ](#why-are-there-so-many-launch-files )
- [Other useful links ](#other-useful-links )
- [License ](#license )
2024-06-18 11:57:27 +08:00
2022-06-10 14:24:27 +08:00
## Installation Instructions
2024-04-28 16:17:20 +08:00
Install ROS 2
2023-03-10 10:19:06 +08:00
2023-02-13 09:54:58 +08:00
- Please refer to the
2023-05-11 10:03:00 +08:00
official [ROS 2 installation guide ](https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debians.html )
2023-02-13 09:54:58 +08:00
guidance
2022-06-10 14:24:27 +08:00
2024-04-28 16:17:20 +08:00
> If your ROS 2 command does not auto-complete, put the following two lines into your `.bashrc`
2023-02-13 10:27:38 +08:00
> or `.zshrc`
2022-06-10 14:24:27 +08:00
```bash
eval " $( register-python-argcomplete3 ros2) "
eval " $( register-python-argcomplete3 colcon) "
```
2023-03-10 10:19:06 +08:00
Create `colcon` workspace
2022-06-10 14:24:27 +08:00
```bash
mkdir -p ~/ros2_ws/src
```
2023-02-13 10:27:38 +08:00
Get source code
2023-05-11 10:32:28 +08:00
```bash
cd ~/ros2_ws/src
2023-09-20 16:23:47 +08:00
git clone https://github.com/orbbec/OrbbecSDK_ROS2.git
2024-10-12 18:45:13 +08:00
cd OrbbecSDK_ROS2
2024-11-25 15:29:10 +08:00
git checkout v2-main
2025-05-06 17:41:55 +08:00
git branch #Check whether the branch switch is successful
2023-05-11 10:32:28 +08:00
```
2022-06-15 15:40:46 +08:00
Install deb dependencies
```bash
2023-03-21 16:20:54 +08:00
# assume you have sourced ROS environment, same blow
2024-06-19 10:40:57 +08:00
sudo apt install libgflags-dev nlohmann-json3-dev \
2024-12-24 13:52:39 +08:00
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 \
2024-08-28 15:27:02 +08:00
ros-$ROS_DISTRO -diagnostic-updater ros-$ROS_DISTRO -diagnostic-msgs ros-$ROS_DISTRO -statistics-msgs \
2024-08-28 15:27:50 +08:00
ros-$ROS_DISTRO -backward-ros libdw-dev
2022-06-15 15:40:46 +08:00
```
2023-02-13 10:41:55 +08:00
Install udev rules.
2022-06-15 15:40:46 +08:00
2023-02-17 15:14:45 +08:00
```bash
2023-07-05 16:07:52 +08:00
cd ~/ros2_ws/src/OrbbecSDK_ROS2/orbbec_camera/scripts
sudo bash install_udev_rules.sh
2022-07-13 12:42:25 +08:00
sudo udevadm control --reload-rules && sudo udevadm trigger
```
2023-02-13 09:54:58 +08:00
2025-05-06 17:41:55 +08:00
## 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.
2025-05-22 17:25:25 +08:00
| Product List | Minimal Firmware Version | **Launch File** |
2025-05-06 17:41:55 +08:00
| :----------- | :----------------------- | :-------------------------- |
2025-05-22 17:25:25 +08:00
| 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 |
2025-05-06 17:41:55 +08:00
| Gemini 330 | 1.2.20 | gemini_330_series.launch.py |
| Gemini 330L | 1.2.20 | gemini_330_series.launch.py |
2025-05-22 17:25:25 +08:00
| Gemini 2 | 1.4.92 | gemini2.launch.py |
| Gemini 2 L | 1.4.53 | gemini2L.launch.py |
2025-05-06 17:41:55 +08:00
| 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 |
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.
2022-06-13 14:58:47 +08:00
## Getting start
2022-06-10 14:24:27 +08:00
```bash
cd ~/ros2_ws/
2022-06-13 14:58:47 +08:00
# build release, Default is Debug
2022-06-27 13:58:35 +08:00
colcon build --event-handlers console_direct+ --cmake-args -DCMAKE_BUILD_TYPE= Release
2022-06-10 14:24:27 +08:00
```
2023-02-13 09:54:58 +08:00
Launch camera node
2023-02-17 15:14:45 +08:00
- On terminal 1
2023-02-13 09:54:58 +08:00
2023-02-17 15:14:45 +08:00
```bash
2024-05-11 18:18:14 +08:00
. ./install/setup.bash
2025-05-06 17:41:55 +08:00
ros2 run orbbec_camera list_devices_node #Check if the camera is connected
2025-05-06 18:27:19 +08:00
ros2 launch orbbec_camera gemini_330_series.launch.py # Or other launch file, see below table
2022-06-10 14:24:27 +08:00
```
2023-02-13 09:54:58 +08:00
2023-02-17 15:14:45 +08:00
- On terminal 2
2022-06-10 14:24:27 +08:00
```bash
2024-05-11 18:18:14 +08:00
. ./install/setup.bash
2023-02-13 14:30:21 +08:00
rviz2
2022-06-10 14:24:27 +08:00
```
2023-02-13 15:34:44 +08:00
2023-02-13 14:30:21 +08:00
Select the topic you want to display
2023-02-13 09:54:58 +08:00
2025-05-08 16:00:38 +08:00
- List topics / services/ parameters ( On terminal 3)
2022-06-10 14:24:27 +08:00
```bash
ros2 topic list
ros2 service list
ros2 param list
```
2022-06-10 15:15:18 +08:00
2023-02-17 15:14:45 +08:00
- Get device info
2022-06-10 15:15:18 +08:00
2023-02-17 15:14:45 +08:00
```bash
2022-06-13 14:58:47 +08:00
ros2 service call /camera/get_device_info orbbec_camera_msgs/srv/GetDeviceInfo '{}'
2022-06-10 15:15:18 +08:00
```
2023-02-13 09:54:58 +08:00
2023-02-17 15:14:45 +08:00
- Get SDK version
2022-06-10 15:15:18 +08:00
```bash
2022-06-13 14:58:47 +08:00
ros2 service call /camera/get_sdk_version orbbec_camera_msgs/srv/GetString '{}'
2022-06-10 15:15:18 +08:00
```
2023-02-17 15:14:45 +08:00
- Get exposure
2022-06-10 15:15:18 +08:00
```bash
2022-06-13 14:58:47 +08:00
ros2 service call /camera/get_color_exposure orbbec_camera_msgs/srv/GetInt32 '{}'
2022-06-10 15:15:18 +08:00
```
2023-02-13 09:54:58 +08:00
2023-02-17 15:14:45 +08:00
> If your check `ir` or `depth`, please change `/camera/get_color_exposure`
2024-05-11 18:18:14 +08:00
> to `/camera/get_ir_exposure` or `/camera/get_depth_exposure`, Same below.
2022-06-10 15:15:18 +08:00
2023-02-17 15:14:45 +08:00
- Get gain
2022-06-10 15:15:18 +08:00
```bash
2022-06-13 14:58:47 +08:00
ros2 service call /camera/get_color_gain orbbec_camera_msgs/srv/GetInt32 '{}'
2022-06-10 15:15:18 +08:00
```
2023-02-13 09:54:58 +08:00
2023-02-17 15:14:45 +08:00
- Get white balance
2022-06-10 15:15:18 +08:00
```bash
2022-06-13 14:58:47 +08:00
ros2 service call /camera/get_white_balance orbbec_camera_msgs/srv/GetInt32 '{}'
2022-06-10 15:16:46 +08:00
```
2023-02-17 15:14:45 +08:00
- Set auto exposure
2022-06-10 15:15:18 +08:00
```bash
ros2 service call /camera/set_color_auto_exposure std_srvs/srv/SetBool '{data: false}'
```
2025-05-06 17:41:55 +08:00
- Set white balance
2022-06-13 16:25:01 +08:00
2022-06-10 15:15:18 +08:00
```bash
ros2 service call /camera/set_white_balance orbbec_camera_msgs/srv/SetInt32 '{data: 4600}'
2022-06-10 15:17:20 +08:00
```
2023-02-13 09:54:58 +08:00
2023-02-17 15:14:45 +08:00
- Set laser enable
2022-06-13 16:25:01 +08:00
2022-06-13 16:10:05 +08:00
```bash
2024-05-11 18:18:14 +08:00
ros2 service call /camera/set_laser_enable std_srvs/srv/SetBool "{data: true}"
2023-02-17 15:14:45 +08:00
```
2022-06-13 14:58:47 +08:00
2023-02-17 15:14:45 +08:00
- toggle sensor
2022-06-13 16:25:01 +08:00
2022-06-13 16:10:05 +08:00
```bash
2023-02-17 15:14:45 +08:00
ros2 service call /camera/toggle_ir std_srvs/srv/SetBool "{data : true}"
2023-09-15 16:59:09 +08:00
```
2024-03-05 14:40:12 +08:00
2023-09-15 16:59:09 +08:00
- save point cloud
```bash
ros2 service call /camera/save_point_cloud std_srvs/srv/Empty "{}"
2023-02-17 15:14:45 +08:00
```
2024-08-27 17:58:12 +08:00
2025-05-06 17:41:55 +08:00
## Usage
2024-10-21 17:47:54 +08:00
2025-05-06 17:41:55 +08:00
### Launch parameters
2024-08-27 17:58:12 +08:00
2025-05-06 17:41:55 +08:00
For the entire list of parameters type `ros2 param list` .
2023-02-13 09:54:58 +08:00
2025-04-28 10:45:46 +08:00
**Modify parameters when launching launch** :
```bash
2025-05-06 17:41:55 +08:00
ros2 launch orbbec_camera gemini_330_series.launch.py enable_color:= true color_width:= 640 color_height:= 480
2025-04-28 10:45:46 +08:00
```
2025-05-06 18:05:42 +08:00
* **[color|depth|left_ir|right_ir|ir]_width,[color|depth|left_ir|right_ir|ir]_height,[color|depth|left_ir|right_ir|ir]_fps,[color|depth|left_ir|right_ir|ir]_format**
* The resolution and frame rate of the sensor stream
2025-05-06 17:41:55 +08:00
* Run `ros2 run orbbec_camera list_camera_profile_mode_node` to get the list of supported profiles
* For example:`color_width:=640 color_height:=480 color_fps:=30 color_format:=MJPG depth_width:=640 depth_height:=480 depth_fps:=30 depth_format:=Y16 ir_width:=640 ir_height:=480 ir_fps:=30 ir_format:=Y8`
2025-05-06 18:05:42 +08:00
* **enable_color_auto_exposure_priority**
* Enable the Color auto exposure priority
2025-05-06 17:41:55 +08:00
* For example:`enable_color_auto_exposure_priority:=true`
2025-05-06 18:05:42 +08:00
* **enable_color_auto_exposure**
* Enable the Color auto exposure
2025-05-06 17:41:55 +08:00
* For example:`enable_color_auto_exposure:=true`
2025-05-06 18:05:42 +08:00
* **color_exposure**
* Set the Color exposure
2025-05-06 17:41:55 +08:00
* For example:`color_exposure:=30`
* Note:To ensure that the `color_exposure` setting takes effect, make sure to set `enable_color_auto_exposure:=false` .
2025-05-06 18:05:42 +08:00
* **color_gain**
* Set the Color gain
2025-05-06 17:41:55 +08:00
* For example:`color_gain:=16`
* Note:To ensure that the `color_gain` setting takes effect, make sure to set `enable_color_auto_exposure:=false` .
2025-05-06 18:05:42 +08:00
* **enable_depth_auto_exposure_priority**
* Enable the Depth auto exposure priority
2025-05-06 17:41:55 +08:00
* For example:`enable_depth_auto_exposure_priority:=true`
2025-08-07 08:33:24 -04:00
* **mean_intensity_set_point**
- Set the target mean intensity of the Depth image
- For example: `mean_intensity_set_point:=100`
> **Note:** This replaces the deprecated `depth_brightness`, which is still supported for backward compatibility.
2024-07-31 14:30:54 +08:00
2025-05-06 17:41:55 +08:00
[...... ](./docs/launch_parameters.md )
2024-05-15 14:18:54 +08:00
2025-05-06 17:41:55 +08:00
Explanation of parameters.Reference:[Launch parameters documentation ](./docs/launch_parameters.md )
2024-10-21 17:47:54 +08:00
2025-05-06 17:41:55 +08:00
### All available service for camera control
2024-10-21 17:47:54 +08:00
2025-05-06 17:41:55 +08:00
For the entire list of service `ros2 service list` .
2024-10-21 17:47:54 +08:00
2025-05-06 17:41:55 +08:00
* `/camera/get_device_info`
2024-10-21 17:47:54 +08:00
```bash
2025-05-06 17:41:55 +08:00
ros2 service call /camera/get_device_info orbbec_camera_msgs/srv/GetDeviceInfo
2024-10-21 17:47:54 +08:00
```
2025-05-06 17:41:55 +08:00
* `/camera/get_sdk_version`
2023-10-11 14:15:17 +08:00
```bash
2025-05-06 17:41:55 +08:00
ros2 service call /camera/get_sdk_version orbbec_camera_msgs/srv/GetString
2023-10-11 14:15:17 +08:00
```
2025-05-06 17:41:55 +08:00
* `/camera/reboot_device`
2024-03-05 14:40:12 +08:00
2025-05-06 17:41:55 +08:00
```bash
ros2 service call /camera/reboot_device std_srvs/srv/Empty '{}'
```
2024-03-05 14:40:12 +08:00
2025-05-06 17:41:55 +08:00
[...... ](./docs/all_available_service_for_camera_control.md )
2023-10-11 14:15:17 +08:00
2025-05-06 17:41:55 +08:00
Explanation of service.Reference:[All available service fo camera control documentation ](./docs/all_available_service_for_camera_control.md )
2024-05-14 10:43:41 +08:00
2025-05-06 17:41:55 +08:00
### All available topics
2024-05-14 10:43:41 +08:00
2025-05-06 17:41:55 +08:00
For the entire list of topic `ros2 topic list` .
2024-05-14 10:43:41 +08:00
- `/camera/color/camera_info` : The color camera info.
- `/camera/color/image_raw` : The color stream image.
2025-05-06 17:41:55 +08:00
- `/camera/depth/camera_info` : The depth stream info.
- `/camera/depth/image_raw` : The depth stream image.
2024-05-14 10:43:41 +08:00
2025-05-06 17:41:55 +08:00
[...... ](./docs/all_available_topics.md )
2024-05-14 10:43:41 +08:00
2025-05-06 17:41:55 +08:00
Explanation of topic.Reference:[All available topics documentation ](./docs/all_available_topics.md )
2024-05-14 10:43:41 +08:00
2025-05-06 17:41:55 +08:00
### Network device enumeration
2024-05-14 10:43:41 +08:00
2025-05-12 14:32:20 +08:00
When using Femto Mega, Gemini 335Le and Gemini 435Le, you can use the network to connect the device.
2024-05-14 10:43:41 +08:00
2025-05-06 17:41:55 +08:00
**Femto Mega:**
2024-05-14 10:43:41 +08:00
```bash
2025-05-06 17:41:55 +08:00
ros2 launch orbbec_camera femto_mega.launch.py enumerate_net_device:= true
2024-05-14 10:43:41 +08:00
```
2025-05-22 11:27:46 +08:00
**Gemini 335Le:**
2024-05-14 10:43:41 +08:00
```bash
2025-05-06 17:41:55 +08:00
ros2 launch orbbec_camera gemini_330_series.launch.py enumerate_net_device:= true
2024-05-14 10:43:41 +08:00
```
2025-05-22 11:27:46 +08:00
**Gemini 435Le:**
```bash
ros2 launch orbbec_camera gemini435_le.launch.py enumerate_net_device:= true
```
2025-05-06 17:41:55 +08:00
For more information about network device enumeration.Reference:[Network device documentation ](./orbbec_camera/examples/net_camera/ )
2024-10-21 17:47:54 +08:00
2025-05-06 17:41:55 +08:00
### GMSL device enumeration
2024-07-31 18:18:39 +08:00
2025-05-06 17:41:55 +08:00
When using Gemini 335Lg, you can use the GMSL to connect the device.
2024-10-21 17:47:54 +08:00
2024-07-31 18:18:39 +08:00
```bash
2025-05-06 17:41:55 +08:00
ros2 launch orbbec_camera gemini_330_gmsl.launch.py
2024-07-31 18:18:39 +08:00
```
2025-05-06 17:41:55 +08:00
For more information about GMSL device enumeration.Reference:[GMSL device documentation ](./orbbec_camera/examples/gmsl_camera/ )
2024-07-31 18:18:39 +08:00
2025-05-06 17:41:55 +08:00
### Multi-Camera
2024-05-14 10:43:41 +08:00
2025-05-06 17:41:55 +08:00
When you have multiple cameras, you can activate all of them at the same time.
2024-05-14 10:43:41 +08:00
2025-05-08 16:00:38 +08:00
For more information about Multi camera.Reference:[Multi camera documentation ](./orbbec_camera/examples/multi_camera/ )
2024-05-14 10:43:41 +08:00
2025-05-06 17:41:55 +08:00
### Check which profiles the camera supports
2023-09-06 21:54:28 +08:00
2024-05-11 18:18:14 +08:00
```bash
ros2 run orbbec_camera list_camera_profile_mode_node
```
2023-02-13 09:54:58 +08:00
2025-05-06 17:41:55 +08:00
### Predefined presets
2024-04-30 15:39:14 +08:00
2025-05-06 17:41:55 +08:00
About the mode settings of Predefined presets.Reference:[Predefined presets documentation ](./docs/predefined_presets.md )
2024-05-08 22:28:27 +08:00
2025-06-04 09:40:32 +08:00
### Optional depth presets
2025-05-06 17:41:55 +08:00
2025-06-04 09:40:32 +08:00
> You can pass the firmware path of the Optional preset into the `preset_firmware_path` launch param.Users can download the appropriate Preset from the [Depth Preset Release](https://www.orbbec.com/docs/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.
2024-05-08 22:28:27 +08:00
2024-04-30 15:39:14 +08:00
```bash
2025-06-04 09:40:32 +08:00
ros2 launch orbbec_camera gemini_330_series.launch.py preset_firmware_path:= /home/orbbec/G336X_AMR_Default_v0.0.5.bin
2024-04-30 15:39:14 +08:00
```
2025-05-06 17:41:55 +08:00
### Depth work mode switch
2024-05-08 22:28:27 +08:00
2025-05-06 17:41:55 +08:00
Gemini 2, Gemini 2 L,and Femto and Femto Bolt cameras setting depth work mode.Reference:[Depth work mode switch documentation ](./docs/depth_work_mode_switch.md )
2024-05-08 22:28:27 +08:00
2025-05-06 17:41:55 +08:00
### Configuration of depth NFOV and WFOV modes
2024-04-30 15:39:14 +08:00
2025-05-06 17:41:55 +08:00
For the Femto Mega and Femto Bolt devices setting NFOV and WFOV modes.Reference:[Configuration of depth NFOV and WFOV modes documentation ](./docs/configuration_of_depth_NFOV_and_WFOV_modes.md )
## Advanced Usage
### Use V4L2 backend
[Setting uvc_backend ](./docs/launch_parameters.md )
Note: The V4L2 backend is not enabled by default.
* Example:
2024-05-08 22:28:27 +08:00
2024-04-30 15:39:14 +08:00
```bash
2025-05-06 17:41:55 +08:00
ros2 launch orbbec_camera gemini_330_series.launch.py uvc_backend:= v4l2
2024-04-30 15:39:14 +08:00
```
2025-05-06 17:41:55 +08:00
### DDS Tuning
2023-02-13 09:54:58 +08:00
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 ](https://docs.ros.org/en/humble/How-To-Guides/DDS-tuning.html )。
● Edit cyclonedds configuration file
```bash
sudo gedit /etc/cyclonedds/config.xml
```
Add
```xml
<?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`
```bash
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 ](https://docs.ros.org/en/humble/Concepts/About-Domain-ID.html )
● Increase UDP receive buffer size
Edit
```bash
/etc/sysctl.d/10-cyclone-max.conf
```
Add
```bash
net.core.rmem_max= 2147483647
net.core.rmem_default= 2147483647
```
2024-07-19 14:09:26 +08:00
If you use Fast DDS, you can refer to the [Fast DDS Configuration ](./docs/fastdds_tuning.md ) file.
2025-05-06 17:41:55 +08:00
### Efficient intra-process communication
Our ROS2 Wrapper node supports zero-copy communications if loaded in the same process as a subscriber node. This can reduce copy times on image/pointcloud topics, especially with big frame resolutions and high FPS.Reference:[Efficient intra-process communication documentation ](./docs/efficient_intra_process_communication.md )
### ROS2(Robot) vs Optical(Camera) Coordination Systems
* Point Of View:
* Imagine we are standing behind of the camera, and looking forward.
* Always use this point of view when talking about coordinates, left vs right IRs, position of sensor, etc..

* ROS2 Coordinate System: (X: Forward, Y:Left, Z: Up)
* Camera Optical Coordinate System: (X: Right, Y: Down, Z: Forward)
* All data published in our wrapper topics is optical data taken directly from our camera sensors.
* static and dynamic TF topics publish optical CS and ROS CS to give the user the ability to move from one CS to other CS.
### Camera sensor structure


### TF from coordinate A to coordinate B:
In Orbbec cameras, the origin point (0,0,0) is taken from the camera_link position
Our wrapper provide static TFs between each sensor coordinate to the camera base (camera_link)
Also, it provides TFs from each sensor ROS coordinates to its corrosponding optical coordinates.
Example of static TFs of RGB sensor and right infra sensor of Gemini335 module as it shown in rviz2:
```bash
ros2 launch orbbec_description view_model.launch.py model:= gemini_335_336.urdf.xacro
```

### 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:
```bash
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.
### Building a Debian Package
If you want to build the Debian package of OrbbecSDK_ROS2.Reference:[Building a Debian Package documentation ](./docs/building_a_Debian_Package.md )
## 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.
2023-02-13 09:54:58 +08:00
## Frequently Asked Questions
2024-08-28 18:05:06 +08:00
### Unexpected Crash
If the camera node crashes unexpectedly, it will generate a crash log in the current running directory: `Log/camera_crash_stack_trace_xx.log` .
Please send this log to the support team or submit it to a GitHub issue for further assistance.
2024-07-19 14:09:26 +08:00
### No Data Stream from Multiple Cameras
2023-02-13 09:54:58 +08:00
2024-07-19 14:09:26 +08:00
**Insufficient Power Supply** :
2024-10-21 17:47:54 +08:00
2024-08-28 18:05:06 +08:00
- Ensure that each camera is connected to a separate hub.
- Use a powered hub to provide sufficient power to each camera.
2024-07-19 14:09:26 +08:00
**High Resolution** :
2024-10-21 17:47:54 +08:00
2024-08-28 18:05:06 +08:00
- Try lowering the resolution to resolve data stream issues.
2023-02-13 09:54:58 +08:00
2024-07-19 14:09:26 +08:00
**Increase usbfs_memory_mb Value** :
2024-10-21 17:47:54 +08:00
- 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:
2024-08-28 18:05:06 +08:00
```bash
2024-07-19 14:09:26 +08:00
echo 128 | sudo tee /sys/module/usbcore/parameters/usbfs_memory_mb
2024-08-28 18:05:06 +08:00
```
2024-10-21 17:47:54 +08:00
2024-08-28 18:05:06 +08:00
- To make this change permanent, check [this link ](https://github.com/OpenKinect/libfreenect2/issues/807 ).
2023-02-13 09:54:58 +08:00
2024-08-28 18:05:06 +08:00
### Additional Troubleshooting
2023-02-13 10:27:38 +08:00
2024-10-21 17:47:54 +08:00
- If you encounter other issues, set the `log_level` parameter to `debug` . This will generate an SDK log file in the running directory: `Log/OrbbecSDK.log.txt` .
Please provide this file to the support team for further assistance.
2024-07-31 11:32:36 +08:00
- If firmware logs are required, set `enable_heartbeat` to `true` to activate this feature.
2024-08-28 18:05:06 +08:00
### Why Are There So Many Launch Files?
- Different cameras have varying default resolutions and image formats.
- To simplify usage, each camera has its own launch file.
2024-08-28 17:56:23 +08:00
2024-05-14 10:12:54 +08:00
## Other useful links
2024-11-01 17:14:16 +08:00
- [OrbbecSDK_v2 ](https://github.com/orbbec/OrbbecSDK_v2/releases )
2024-05-14 10:12:54 +08:00
- [Gemini 330 depth presets ](https://www.orbbec.com/docs/g330-use-depth-presets/ )
2023-02-13 09:54:58 +08:00
## License
2024-05-14 10:03:34 +08:00
Copyright 2024 Orbbec Ltd.
2023-02-13 09:54:58 +08:00
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**