From 1680236780c9aa2ba90471e2494a7e6c322fecb5 Mon Sep 17 00:00:00 2001 From: obyalian Date: Tue, 23 Sep 2025 17:44:06 +0800 Subject: [PATCH] docs: update README --- README.MD | 120 +++++++++++++++----------------------- README_CN.MD | 159 +++++++++++++++++++++------------------------------ 2 files changed, 109 insertions(+), 170 deletions(-) diff --git a/README.MD b/README.MD index 764b118c..6b0ad689 100644 --- a/README.MD +++ b/README.MD @@ -1,16 +1,17 @@ # 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) -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): @@ -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-diagnostic-updater ros-$ROS_DISTRO-diagnostic-msgs ros-$ROS_DISTRO-statistics-msgs \ ros-$ROS_DISTRO-backward-ros libdw-dev -``` -Optional dependencies: - -```bash +# Optional dependencies: # 435Le writeCustomerDate feature: sudo apt install libssl-dev ``` -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 -``` - -## 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 +build: ```bash 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 ``` +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 - On terminal 1 ```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 ``` @@ -281,41 +254,38 @@ ros2 topic echo /camera/depth/camera_info 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) -## 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 -ros2 run orbbec_camera list_camera_profile_mode_node -``` +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. -### 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 -ros2 launch orbbec_camera gemini_330_series.launch.py preset_firmware_path:=/home/orbbec/G336X_AMR_Default_v0.0.5.bin -``` +## Tutorial -### Use V4L2 backend - -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) +please refer to the official [OrbbecSDK ROS2 documentation](https://orbbec.github.io/OrbbecSDK_ROS2/source/5_advanced_guide/advanced_guide.html) ## Examples diff --git a/README_CN.MD b/README_CN.MD index bfc6b92a..41ae6c75 100644 --- a/README_CN.MD +++ b/README_CN.MD @@ -1,16 +1,16 @@ # OrbbecSDK ROS2 Wrapper v2 -> [!IMPORTANT] -> -> 欢迎使用 OrbbecSDK ROS2 Wrapper v2。在开始使用此版本的 ROS2 wrapper 之前，请务必查看以下 [设备支持列表](#supported-devices)，以确认兼容性。 - [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) 的设备支持列表： @@ -157,30 +157,79 @@ git branch #检查分支是否切换成功 安装依赖包 -``` +```bash # 假设您已经 source ROS 环境，下同 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 -``` -可选依赖： - -``` +# 可选依赖 # 435Le writeCustomerDate 功能需要： sudo apt install libssl-dev ``` 安装 udev 规则 -``` +```bash cd ~/ros2_ws/src/OrbbecSDK_ROS2/orbbec_camera/scripts sudo bash install_udev_rules.sh 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) 分支。 @@ -207,89 +256,9 @@ sudo udevadm control --reload-rules && sudo udevadm trigger 所有启动文件基本相似，主要区别在于针对不同型号的默认参数设置。不同的 USB 标准（如 USB 2.0 和 USB 3.0）可能需要调整这些参数。如果遇到启动失败，请仔细查看规格说明书，特别是启动文件中的分辨率设置以及其他参数，以确保兼容性和最佳性能。 -## 快速开始 +## 教程 -``` -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) +请参考官方 [OrbbecSDK ROS2 文档](https://orbbec.github.io/OrbbecSDK_ROS2/source/5_advanced_guide/advanced_guide.html) ## 示例