i/OrbbecSDK_ROS2
1
0
Fork 0
mirror of https://github.com/orbbec/OrbbecSDK_ROS2.git synced 2026-10-04 20:17:47 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: update README

Browse Source
This commit is contained in:
obyalian
2025-09-23 17:44:06 +08:00
parent f047b82690
commit 1680236780
2 changed files with 109 additions and 170 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.MD
+45 -75
View File
@@ -1,16 +1,17 @@
# OrbbecSDK ROS2 Wrapper v2 # 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](#supported-devices) to verify the compatibility.
[English](./README.MD) | [中文](./README_CN.MD) [English](./README.MD) | [中文](./README_CN.MD)
OrbbecSDK ROS2 Wrapper provides seamless integration of Orbbec cameras with ROS 2 environment. It supports ROS2 Foxy, Humble, and Jazzy distributions. ## Introduction
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. The **OrbbecSDK ROS2 Wrapper** provides seamless integration of Orbbec cameras with the ROS 2 ecosystem.
It supports ROS2 **Foxy**, **Humble**, and **Jazzy** distributions.
If you are a user in China, it is recommended to use [gitee Repo](https://gitee.com/orbbecdeveloper/OrbbecSDK_ROS2). - 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): Here is the device support list of main branch (v1.x) and v2-main branch (v2.x):
@@ -189,51 +190,13 @@ ros-$ROS_DISTRO-image-transport ros-${ROS_DISTRO}-image-transport-plugins ros-${
ros-$ROS_DISTRO-image-publisher ros-$ROS_DISTRO-camera-info-manager \ 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-diagnostic-updater ros-$ROS_DISTRO-diagnostic-msgs ros-$ROS_DISTRO-statistics-msgs \
ros-$ROS_DISTRO-backward-ros libdw-dev ros-$ROS_DISTRO-backward-ros libdw-dev
```
Optional dependencies: # Optional dependencies:
```bash
# 435Le writeCustomerDate feature: # 435Le writeCustomerDate feature:
sudo apt install libssl-dev sudo apt install libssl-dev
``` ```
Install udev rules. build:
```bash
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](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 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
```bash ```bash
cd ~/ros2_ws/ cd ~/ros2_ws/
@@ -242,13 +205,23 @@ source /opt/ros/$ROS_DISTRO/setup.bash
colcon build --event-handlers console_direct+ --cmake-args -DCMAKE_BUILD_TYPE=Release colcon build --event-handlers console_direct+ --cmake-args -DCMAKE_BUILD_TYPE=Release
``` ```
Install udev rules:
```bash
cd ~/ros2_ws/src/OrbbecSDK_ROS2/orbbec_camera/scripts
sudo bash install_udev_rules.sh
sudo udevadm control --reload-rules && sudo udevadm trigger
```
## Getting start
Launch camera node Launch camera node
- On terminal 1 - On terminal 1
```bash ```bash
source ~/ros2_ws/install/setup.bash source ~/ros2_ws/install/setup.bash
ros2 run orbbec_camera list_devices_node #Check if the camera is connected 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 ros2 launch orbbec_camera gemini_330_series.launch.py # Or other launch file, see below table
``` ```
@@ -281,41 +254,38 @@ ros2 topic echo /camera/depth/camera_info
ros2 service call /camera/get_sdk_version orbbec_camera_msgs/srv/GetString '{}' ros2 service call /camera/get_sdk_version orbbec_camera_msgs/srv/GetString '{}'
``` ```
- Record with rosbag2
```bash
ros2 bag record /camera/color/image_raw /camera/depth/image_raw
```
For more usage details, please refer to the official [OrbbecSDK ROS2 documentation](https://orbbec.github.io/OrbbecSDK_ROS2/source/4_application_guide/application_guide.html) For more usage details, please refer to the official [OrbbecSDK ROS2 documentation](https://orbbec.github.io/OrbbecSDK_ROS2/source/4_application_guide/application_guide.html)
## Usage ## Supported Devices
### Check which profiles the camera supports 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.
```bash 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.
ros2 run orbbec_camera list_camera_profile_mode_node
```
### Optional depth presets | 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 |
> 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. 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.
```bash ## Tutorial
ros2 launch orbbec_camera gemini_330_series.launch.py preset_firmware_path:=/home/orbbec/G336X_AMR_Default_v0.0.5.bin
```
### Use V4L2 backend please refer to the official [OrbbecSDK ROS2 documentation](https://orbbec.github.io/OrbbecSDK_ROS2/source/5_advanced_guide/advanced_guide.html)
Note: The V4L2 backend is not enabled by default.
* Example:
```bash
ros2 launch orbbec_camera gemini_330_series.launch.py uvc_backend:=v4l2
```
For more usage details, please refer to the official [OrbbecSDK ROS2 documentation](https://orbbec.github.io/OrbbecSDK_ROS2/source/5_advanced_guide/advanced_guide.html)
## Examples ## Examples
README_CN.MD
+64 -95
View File
@@ -1,16 +1,16 @@
# OrbbecSDK ROS2 Wrapper v2 # OrbbecSDK ROS2 Wrapper v2
> [!IMPORTANT]
>
> 欢迎使用 OrbbecSDK ROS2 Wrapper v2。在开始使用此版本的 ROS2 wrapper 之前，请务必查看以下 [设备支持列表](#supported-devices)，以确认兼容性。
[English](./README.MD) | [中文](./README_CN.MD) [English](./README.MD) | [中文](./README_CN.MD)
OrbbecSDK ROS2 Wrapper 提供 Orbbec 相机与 ROS 2 环境的无缝集成。它支持 ROS2 Foxy、Humble 和 Jazzy 发行版。 ## 简介
默认情况下，我们推荐使用 **v2-main** 分支。对于旧的 OpenNI 设备（v2-main 分支不支持），请使用 **main** 分支。仅由 main 分支支持的设备型号在下表中列出。 OrbbecSDK ROS2 Wrapper 提供 Orbbec 相机与 ROS 2 环境的无缝集成，支持 **ROS2 Foxy、Humble 和 Jazzy** 发行版。
如果您在中国使用，建议使用 [gitee 仓库](https://gitee.com/orbbecdeveloper/OrbbecSDK_ROS2)。 - 默认推荐使用 **v2-main** 分支。
- 对于旧的 **OpenNI** 设备（v2-main 不支持），请使用 **main** 分支。
- 如果您在中国使用，建议使用 [gitee 仓库](https://gitee.com/orbbecdeveloper/OrbbecSDK_ROS2)。
## 分支选择
以下是 main 分支 (v1.x) 和 v2-main 分支 (v2.x) 的设备支持列表： 以下是 main 分支 (v1.x) 和 v2-main 分支 (v2.x) 的设备支持列表：
@@ -157,30 +157,79 @@ git branch #检查分支是否切换成功
安装依赖包 安装依赖包
``` ```bash
# 假设您已经 source ROS 环境，下同 # 假设您已经 source ROS 环境，下同
sudo apt install libgflags-dev nlohmann-json3-dev \ 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-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-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-diagnostic-updater ros-$ROS_DISTRO-diagnostic-msgs ros-$ROS_DISTRO-statistics-msgs \
ros-$ROS_DISTRO-backward-ros libdw-dev ros-$ROS_DISTRO-backward-ros libdw-dev
```
可选依赖： # 可选依赖
```
# 435Le writeCustomerDate 功能需要： # 435Le writeCustomerDate 功能需要：
sudo apt install libssl-dev sudo apt install libssl-dev
``` ```
安装 udev 规则 安装 udev 规则
``` ```bash
cd ~/ros2_ws/src/OrbbecSDK_ROS2/orbbec_camera/scripts cd ~/ros2_ws/src/OrbbecSDK_ROS2/orbbec_camera/scripts
sudo bash install_udev_rules.sh sudo bash install_udev_rules.sh
sudo udevadm control --reload-rules && sudo udevadm trigger sudo udevadm control --reload-rules && sudo udevadm trigger
``` ```
编译
```bash
cd ~/ros2_ws/
source /opt/ros/$ROS_DISTRO/setup.bash
# 编译 release，默认是 Debug
colcon build --event-handlers console_direct+ --cmake-args -DCMAKE_BUILD_TYPE=Release
```
## 快速开始
启动相机节点
- 终端 1
```bash
source ~/ros2_ws/install/setup.bash
ros2 run orbbec_camera list_devices_node #检查相机是否已连接
ros2 launch orbbec_camera gemini_330_series.launch.py # 或其他启动文件，见下表
```
- 终端 2
```bash
source ~/ros2_ws/install/setup.bash
rviz2
```
选择需要显示的 topic
- 列出 topics / services / parameters (终端 3)
```bash
ros2 topic list
ros2 service list
ros2 param list
```
- 查看 topic
```
ros2 topic echo /camera/depth/camera_info
```
- 调用服务
```
ros2 service call /camera/get_sdk_version orbbec_camera_msgs/srv/GetString '{}'
```
更多使用详情，请参考官方 [OrbbecSDK ROS2 文档](https://orbbec.github.io/OrbbecSDK_ROS2/source/4_application_guide/application_guide.html)
## 支持的设备 ## 支持的设备
目前 v2-main 分支支持以下设备。更多设备支持将陆续增加。如果没有找到您的设备，请尝试 [main](https://github.com/orbbec/OrbbecSDK_ROS2) 分支。 目前 v2-main 分支支持以下设备。更多设备支持将陆续增加。如果没有找到您的设备，请尝试 [main](https://github.com/orbbec/OrbbecSDK_ROS2) 分支。
@@ -207,89 +256,9 @@ sudo udevadm control --reload-rules && sudo udevadm trigger
所有启动文件基本相似，主要区别在于针对不同型号的默认参数设置。不同的 USB 标准（如 USB 2.0 和 USB 3.0）可能需要调整这些参数。如果遇到启动失败，请仔细查看规格说明书，特别是启动文件中的分辨率设置以及其他参数，以确保兼容性和最佳性能。 所有启动文件基本相似，主要区别在于针对不同型号的默认参数设置。不同的 USB 标准（如 USB 2.0 和 USB 3.0）可能需要调整这些参数。如果遇到启动失败，请仔细查看规格说明书，特别是启动文件中的分辨率设置以及其他参数，以确保兼容性和最佳性能。
## 快速开始 ## 教程
``` 请参考官方 [OrbbecSDK ROS2 文档](https://orbbec.github.io/OrbbecSDK_ROS2/source/5_advanced_guide/advanced_guide.html)
cd ~/ros2_ws/
source /opt/ros/$ROS_DISTRO/setup.bash
# 编译 release，默认是 Debug
colcon build --event-handlers console_direct+ --cmake-args -DCMAKE_BUILD_TYPE=Release
```
启动相机节点
- 终端 1
```
source ~/ros2_ws/install/setup.bash
ros2 run orbbec_camera list_devices_node #检查相机是否已连接
ros2 launch orbbec_camera gemini_330_series.launch.py # 或其他启动文件，见下表
```
- 终端 2
```
source ~/ros2_ws/install/setup.bash
rviz2
```
选择需要显示的 topic
- 列出 topics / services / parameters (终端 3)
```
ros2 topic list
ros2 service list
ros2 param list
```
- 查看某个 topic
```
ros2 topic echo /camera/depth/camera_info
```
- 调用某个服务
```
ros2 service call /camera/get_sdk_version orbbec_camera_msgs/srv/GetString '{}'
```
- 使用 rosbag2 录制
```
ros2 bag record /camera/color/image_raw /camera/depth/image_raw
```
更多使用详情，请参考官方 [OrbbecSDK ROS2 文档](https://orbbec.github.io/OrbbecSDK_ROS2/source/4_application_guide/application_guide.html)
## 使用方法
### 检查相机支持的 profile
```
ros2 run orbbec_camera list_camera_profile_mode_node
```
### 可选深度预设
> 您可以将可选预设的固件路径传入 `preset_firmware_path` 启动参数。用户可以从 Orbbec 提供的 [Depth Preset Release](https://www.orbbec.com/docs/depth-preset-release/) 页面下载合适的预设，并将其更新到相机中，以在对应场景下获得更好的深度性能。
```
ros2 launch orbbec_camera gemini_330_series.launch.py preset_firmware_path:=/home/orbbec/G336X_AMR_Default_v0.0.5.bin
```
### 使用 V4L2 backend
注意：V4L2 backend 默认未启用。
- 示例：
```
ros2 launch orbbec_camera gemini_330_series.launch.py uvc_backend:=v4l2
```
更多使用详情，请参考官方 [OrbbecSDK ROS2 文档](https://orbbec.github.io/OrbbecSDK_ROS2/source/5_advanced_guide/advanced_guide.html)
## 示例 ## 示例