diff --git a/README.MD b/README.MD index b4e36f6a..817e922f 100644 --- a/README.MD +++ b/README.MD @@ -136,43 +136,6 @@ Here is the device support list of main branch (v1.x) and v2-main branch (v2.x): 4. Not supported: we will not support specific device in this version; 5. To be supported: we will add support in the near future. -## Table of Contents - -- [OrbbecSDK ROS2 Wrapper v2](#orbbecsdk-ros2-wrapper-v2) - - [Table of Contents](#table-of-contents) - - [Installation Instructions](#installation-instructions) - - [Supported Devices](#supported-devices) - - [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) - - [Optional depth presets](#optional-depth-presets) - - [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) - - [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) - ## Installation Instructions Install ROS 2 @@ -262,6 +225,7 @@ for different models within the same series. Differences in USB standards, such ```bash 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 ``` @@ -271,7 +235,7 @@ Launch camera node - On terminal 1 ```bash -. ./install/setup.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 ``` @@ -279,7 +243,7 @@ ros2 launch orbbec_camera gemini_330_series.launch.py # Or other launch file, se - On terminal 2 ```bash -. ./install/setup.bash +source ~/ros2_ws/install/setup.bash rviz2 ``` @@ -293,210 +257,34 @@ ros2 service list ros2 param list ``` -- Get device info +- Echo a topic ```bash -ros2 service call /camera/get_device_info orbbec_camera_msgs/srv/GetDeviceInfo '{}' +ros2 topic echo /camera/depth/camera_info ``` -- Get SDK version +- Call a service ```bash ros2 service call /camera/get_sdk_version orbbec_camera_msgs/srv/GetString '{}' ``` -- Get exposure +- Record with rosbag2 ```bash -ros2 service call /camera/get_color_exposure orbbec_camera_msgs/srv/GetInt32 '{}' +ros2 bag record /camera/color/image_raw /camera/depth/image_raw ``` -> If your check `ir` or `depth`, please change `/camera/get_color_exposure` -> to `/camera/get_ir_exposure` or `/camera/get_depth_exposure`, Same below. - -- Get gain - -```bash -ros2 service call /camera/get_color_gain orbbec_camera_msgs/srv/GetInt32 '{}' -``` - -- Get white balance - -```bash -ros2 service call /camera/get_white_balance orbbec_camera_msgs/srv/GetInt32 '{}' -``` - -- Set auto exposure - -```bash -ros2 service call /camera/set_color_auto_exposure std_srvs/srv/SetBool '{data: false}' -``` - -- Set white balance - -```bash -ros2 service call /camera/set_white_balance orbbec_camera_msgs/srv/SetInt32 '{data: 4600}' -``` - -- Set laser enable - -```bash -ros2 service call /camera/set_laser_enable std_srvs/srv/SetBool "{data: true}" -``` - -- toggle sensor - -```bash -ros2 service call /camera/toggle_ir std_srvs/srv/SetBool "{data : true}" - -``` - -- save point cloud - -```bash -ros2 service call /camera/save_point_cloud std_srvs/srv/Empty "{}" -``` +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 -### Launch parameters - -For the entire list of parameters type `ros2 param list`. - -**Modify parameters when launching launch**: - -```bash -ros2 launch orbbec_camera gemini_330_series.launch.py enable_color:=true color_width:=640 color_height:=480 -``` - -* **[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 - * 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` -* **enable_color_auto_exposure_priority** - - * Enable the Color auto exposure priority - * For example:`enable_color_auto_exposure_priority:=true` -* **enable_color_auto_exposure** - - * Enable the Color auto exposure - * For example:`enable_color_auto_exposure:=true` -* **color_exposure** - - * Set the Color exposure - * For example:`color_exposure:=30` - * Note:To ensure that the `color_exposure` setting takes effect, make sure to set `enable_color_auto_exposure:=false`. -* **color_gain** - - * Set the Color gain - * For example:`color_gain:=16` - * Note:To ensure that the `color_gain` setting takes effect, make sure to set `enable_color_auto_exposure:=false`. -* **enable_depth_auto_exposure_priority** - - * Enable the Depth auto exposure priority - * For example:`enable_depth_auto_exposure_priority:=true` -* **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. - > - -[......](./docs/launch_parameters.md) - -Explanation of parameters.Reference:[Launch parameters documentation](./docs/launch_parameters.md) - -### All available service for camera control - -For the entire list of service `ros2 service list`. - -* `/camera/get_device_info` - -```bash -ros2 service call /camera/get_device_info orbbec_camera_msgs/srv/GetDeviceInfo -``` - -* `/camera/get_sdk_version` - -```bash -ros2 service call /camera/get_sdk_version orbbec_camera_msgs/srv/GetString -``` - -* `/camera/reboot_device` - -```bash -ros2 service call /camera/reboot_device std_srvs/srv/Empty '{}' -``` - -[......](./docs/all_available_service_for_camera_control.md) - -Explanation of service.Reference:[All available service fo camera control documentation](./docs/all_available_service_for_camera_control.md) - -### All available topics - -For the entire list of topic `ros2 topic list`. - -- `/camera/color/camera_info` : The color camera info. -- `/camera/color/image_raw`: The color stream image. -- `/camera/depth/camera_info`: The depth stream info. -- `/camera/depth/image_raw`: The depth stream image. - -[......](./docs/all_available_topics.md) - -Explanation of topic.Reference:[All available topics documentation](./docs/all_available_topics.md) - -### Network device enumeration - -When using Femto Mega, Gemini 335Le and Gemini 435Le, you can use the network to connect the device. - -**Femto Mega:** - -```bash -ros2 launch orbbec_camera femto_mega.launch.py enumerate_net_device:=true -``` - -**Gemini 335Le:** - -```bash -ros2 launch orbbec_camera gemini_330_series.launch.py enumerate_net_device:=true -``` - -**Gemini 435Le:** - -```bash -ros2 launch orbbec_camera gemini435_le.launch.py enumerate_net_device:=true -``` - -For more information about network device enumeration.Reference:[Network device documentation](./orbbec_camera/examples/net_camera/) - -### GMSL device enumeration - -When using Gemini 335Lg, you can use the GMSL to connect the device. - -```bash -ros2 launch orbbec_camera gemini_330_gmsl.launch.py -``` - -For more information about GMSL device enumeration.Reference:[GMSL device documentation](./orbbec_camera/examples/gmsl_camera/) - -### Multi-Camera - -When you have multiple cameras, you can activate all of them at the same time. - -For more information about Multi camera.Reference:[Multi camera documentation](./orbbec_camera/examples/multi_camera/) - ### Check which profiles the camera supports ```bash ros2 run orbbec_camera list_camera_profile_mode_node ``` -### Predefined presets - -About the mode settings of Predefined presets.Reference:[Predefined presets documentation](./docs/predefined_presets.md) - ### Optional depth presets > 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. @@ -505,20 +293,8 @@ About the mode settings of Predefined presets.Reference:[Predefined presets docu ros2 launch orbbec_camera gemini_330_series.launch.py preset_firmware_path:=/home/orbbec/G336X_AMR_Default_v0.0.5.bin ``` -### Depth work mode switch - -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) - -### Configuration of depth NFOV and WFOV modes - -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: @@ -527,168 +303,12 @@ Note: The V4L2 backend is not enabled by default. ros2 launch orbbec_camera gemini_330_series.launch.py uvc_backend:=v4l2 ``` -### DDS Tuning - -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 - - - - - lo - false - - - 16MB - - - auto - 30 - - - - - - -``` - -● 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 -``` - -If you use Fast DDS, you can refer to the [Fast DDS Configuration](./docs/fastdds_tuning.md) file. - -### 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 and Camera Coordinate System](./docs/images/image0.png) - -* 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 - -![module in rviz2](./docs/images/image3.png) - -![module in rviz2](./docs/images/image1.png) - -### 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 -``` - -![module in rviz2](./docs/images/image2.png) - -### 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) +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 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. -## Frequently Asked Questions - -### 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. - -### No Data Stream from Multiple Cameras - -**Insufficient Power Supply**: - -- Ensure that each camera is connected to a separate hub. -- Use a powered hub to provide sufficient power to each camera. - -**High Resolution**: - -- Try lowering the resolution to resolve data stream issues. - -**Increase usbfs_memory_mb Value**: - -- 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: - -```bash - echo 128 | sudo tee /sys/module/usbcore/parameters/usbfs_memory_mb -``` - -- To make this change permanent, check [this link](https://github.com/OpenKinect/libfreenect2/issues/807). - -### Additional Troubleshooting - -- 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. -- If firmware logs are required, set `enable_heartbeat` to `true` to activate this feature. - -### 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. - ## Other useful links - [OrbbecSDK_v2](https://github.com/orbbec/OrbbecSDK_v2/releases)