i/OrbbecSDK_ROS2
1
0
Fork 0
mirror of https://github.com/orbbec/OrbbecSDK_ROS2.git synced 2026-10-07 21:37:46 +08:00
Code Issues Packages Projects Releases Wiki Activity

[docs]Update docs

Browse Source
This commit is contained in:
jj
2024-12-18 18:35:58 +08:00
parent eca5beffcc
commit 0fcf1ea16f
152 changed files with 4338 additions and 589 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/5_advanced/advanced.rst
Executable
+35
View File
@@ -0,0 +1,35 @@
.. 这一页是模块目录树
.. .. image:: ../image/product_h9.png
.. image:: ../image/product_h5.png
======================================================
Advanced
======================================================
This section explores the advanced usage of Orbbec SDK ROS2, specifically tailored for product application scenarios. It offers comprehensive guidance on how to fully harness the SDK's capabilities, enabling you to unlock the potential of your robotics projects. Discover the optimal ways to enhance your projects using the cutting-edge features provided by Orbbec SDK ROS2 environments.
======================================================
.. toctree::
:maxdepth: 2
:caption: This Section Covers:
multi_camera_sync.md
component_node.md
zero_copy.md
gdb_debug.md
backward_ros.md
cyclonedds_tuning.md
fastdds_tuning.md
======================================================
.. image:: ../image/product_h1.png
docs/source/5_advanced/backward_ros.md
Executable
+44
View File
@@ -0,0 +1,44 @@
# Backward ros
To use the `backward_ros` package for debugging your ROS2 project named `OrbbecSDK_ROS2`, you can follow these steps:
## Add `backward_ros` as a dependency:
In your `package.xml`, add `backward_ros` as a dependency:
xml
```
<depend>backward_ros</depend>
```
## Configure `CMakeLists.txt`:
In your `CMakeLists.txt`, find the `backward_ros` package and link it to your executable:
cmake
```
find_package(backward_ros REQUIRED)
include_directories(${backward_INCLUDE_DIRS})
add_executable(your_node src/your_node.cpp)
target_link_libraries(your_node ${backward_LIBRARIES})
```
## Build your project with debug information:
Use `colcon build` with the `RelWithDebInfo` or `Debug` option to ensure that your executable is built with debug information:
```
colcon build --cmake-args '-DCMAKE_BUILD_TYPE=RelWithDebInfo'
```
## Run your node:
After building, you can run your node as you normally would with ROS 2. If your node crashes, `backward_ros` will automatically generate a stack trace with detailed information, including line numbers, to help you debug the issue.
## Example `backward_ros`
When your program crashes, you can go to the Log folder under the workspace to find the stack trace of the crash.
![Multi_camera1](../image/backward_ros.png)
docs/source/5_advanced/component_node.md
Executable
+157
View File
@@ -0,0 +1,157 @@
# Component node
In ROS2, component nodes enable efficient resource management and modularity by allowing multiple nodes to be loaded into a single process, called a component container. Here’s an overview of setting up a component node and adding it to a container, both for a single node and through a `launch.py` file.
### Creating a component node
To define a node as a component, the following steps are required:
1. **Create a node class**: The node class should inherit from `rclcpp::Node` (C++) or `Node` (Python) and implement the core functionalities within it.
2. **Add plugin export**: In `CMakeLists.txt`, export the node as a plugin by adding it to a component library using `rclcpp_components`. For example:
```cmake
# CMakeLists.txt
find_package(rclcpp_components REQUIRED)
add_library(my_component SHARED src/my_component.cpp)
target_link_libraries(my_component PUBLIC rclcpp::rclcpp)
ament_target_dependencies(my_component rclcpp rclcpp_components)
rclcpp_components_register_nodes(my_component "mypackage::MyComponent")
```
3. **Declare the plugin in package.xml**: Add the node as a plugin in the package manifest:
```xml
<export>
<rclcpp_components>
<node plugin="mypackage::MyComponent" />
</rclcpp_components>
</export>
```
### Loading a single node into a component container
To load a node directly into a component container, use the ComponentManager node. Run the command:
```bash
ros2 run rclcpp_components component_container
```
Then load the component into this container with the load_component service:
```bash
ros2 component load /ComponentManager mypackage my_component
```
Replace /ComponentManager with the actual name of your container, if different.
3. Adding Component Nodes via a Launch File
In launch.py, you can define a component container and load nodes into it. Here’s an example launch.py file:
```python
from launch import LaunchDescription
from launch_ros.actions import ComposableNodeContainer
from launch_ros.descriptions import ComposableNode
def generate_launch_description():
container = ComposableNodeContainer(
name='my_container',
namespace='',
package='rclcpp_components',
executable='component_container_mt', # use 'component_container' for single-threaded
composable_node_descriptions=[
ComposableNode(
package='mypackage',
plugin='mypackage::MyComponent',
name='my_component'
),
ComposableNode(
package='another_package',
plugin='another_package::AnotherComponent',
name='another_component'
)
],
output='screen',
)
return LaunchDescription([container])
```
**explanation**
- ComposableNodeContainer: This creates a component container to hold nodes. Use component_container_mt for multi-threading or component_container for - single-threaded operation.
- ComposableNode: Specifies each component to load, with arguments for the package name, plugin type, and node name.
- output: Set to 'screen' to display output in the terminal.
Running the Launch File
To run the launch file, use the command:
```bash
ros2 launch mypackage my_launch_file.launch.py
```
This starts the component container and loads the specified nodes into it, enabling efficient component management in ROS2.
### Loading a launch.py into a component container
```python
from launch import LaunchDescription
from launch.actions import DeclareLaunchArgument
from launch.conditions import UnlessCondition
from launch_ros.actions import Node, IncludeLaunchDescription
from launch.launch_description_sources import PythonLaunchDescriptionSource
import os
def generate_launch_description():
bringup_dir = os.path.join(get_package_share_directory('mypackage'))
# Define the shared container name
shared_container_name = "shared_nvblox_container"
# Create the shared component container
shared_container = Node(
name=shared_container_name,
package='rclcpp_components',
executable='component_container_mt', # or 'component_container' for single-threaded
output='screen'
)
# Include another launch file to attach nodes to the shared container
orbbec_launch = IncludeLaunchDescription(
PythonLaunchDescriptionSource([os.path.join(
bringup_dir, 'launch', 'sensors', 'orbbec.launch.py')]),
launch_arguments={
'attach_to_shared_component_container': 'True',
'component_container_name': shared_container_name
}.items(),
condition=UnlessCondition(LaunchConfiguration('from_bag'))
)
# Declare any required launch arguments
from_bag_arg = DeclareLaunchArgument(
'from_bag',
default_value='false',
description='Condition to use data from a bag file'
)
# Return LaunchDescription with shared container and nodes attached
return LaunchDescription([from_bag_arg, shared_container, orbbec_launch])
```
**Explanation**
- **shared_container_name**: The name of the shared container, which other nodes can reference for attaching.
- **shared_container**: Defines the shared container as a `Node`, using `component_container_mt` for multi-threading. This container will host multiple component nodes.
- **IncludeLaunchDescription**: Loads and attaches nodes from another launch file (in this example, orbbec.launch.py) to the shared container.
- launch_arguments: The arguments passed to the included launch file.
- **attach_to_shared_component_container**: Set to `'True'`, specifying that nodes in `orbbec.launch.py` should be added to the existing shared container.
- **component_container_name**: References the `shared_container_name`, linking nodes from the included launch file to the shared container.
- **condition**: Only includes the `orbbec.launch.py` nodes in the shared container if the `from_bag` parameter is `false`.
**Running the launch File**
Execute the following command to start the launch file:
```
ros2 launch mypackage my_main_launch_file.launch.py
```
This command will start the shared component container and attach the nodes specified in `orbbec.launch.py` to it if the `from_bag` condition is not met.
docs/source/5_advanced/cyclonedds_tuning.md
Executable
+56
View File
@@ -0,0 +1,56 @@
# CycloneDDS tuning
● 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
```
Tips: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
```
docs/source/5_advanced/fastdds_tuning.md
Executable
+154
View File
@@ -0,0 +1,154 @@
# FastDDS tuning
When operating with the default configuration, FastDDS exhibits suboptimal transmission efficiency, resulting in
significant image transmission delays when used with the Orbbec camera in ROS2. This document provides guidance on
optimizing FastDDS to enhance image transfer efficiency.
## Adjusting system parameters
### IP fragmentation time
- **Path**: `/proc/sys/net/ipv4/ipfrag_time` (default: 30 seconds)
- **Purpose**: Defines the duration that IP fragments are kept in memory.
- **Adjustment**: Decrease this value to reduce the time window where no fragments are received, which can help reduce
delays. Consider the specific needs of your environment as this setting affects all incoming fragments.
**Example**: Set to 3 seconds.
```bash
sudo sysctl net.ipv4.ipfrag_time=3
```
### IP fragmentation memory threshold
- **Path**: `/proc/sys/net/ipv4/ipfrag_high_thresh` (default: 262144 bytes)
- **Purpose**: Sets the maximum memory used to reassemble IP fragments.
- **Adjustment**: Increase this value to allow more memory for fragment reassembly, which can improve handling of larger
data packets.
**Example**: Increase to 128 MB.
```bash
sudo sysctl net.ipv4.ipfrag_high_thresh=134217728
```
### Maximum buffer sizes
- **Purpose**: Configures the maximum buffer sizes for receiving and sending data, which is critical for high-throughput
data transmission.
- **Adjustment**: Set the maximum buffer sizes for both receiving and sending operations.
**Commands**:
```bash
sudo sysctl -w net.core.rmem_max=2147483647
sudo sysctl -w net.core.rmem_default=2147483647
sudo sysctl -w net.core.wmem_max=2147483647
sudo sysctl -w net.core.wmem_default=2147483647
```
Alternatively, make these settings permanent by adding them to the `/etc/sysctl.d/10-fastrtps-max.conf` file.
```bash
sudo gedit /etc/sysctl.d/10-fastrtps-max.conf
```
add blow lines to the file:
```bash
net.core.rmem_max=2147483647
net.core.rmem_default=2147483647
net.core.wmem_max=2147483647
net.core.wmem_default=2147483647
```
then save and exit the file. run `sudo sysctl -p` to apply the changes.
For detailed guidance, refer
to [ROS 2 DDS Tuning Documentation](https://docs.ros.org/en/foxy/How-To-Guides/DDS-tuning.html).
## 2. FastDDS configuration
Below is an example of a FastDDS configuration file optimized for ROS2 usage with the Orbbec camera. This configuration
enhances the overall data transmission by adjusting buffer sizes and transport settings.
### Configuration file: `shm_fastdds.xml`
Place this file in the `$HOME` directory.
```xml
<?xml version="1.0" encoding="UTF-8"?>
<profiles xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
<transport_descriptors>
<transport_descriptor>
<transport_id>UDP_transport</transport_id>
<type>UDPv4</type>
<maxInitialPeersRange>10</maxInitialPeersRange>
<maxMessageSize>65000</maxMessageSize>
<sendBufferSize>1048576</sendBufferSize>
<receiveBufferSize>1048576</receiveBufferSize>
</transport_descriptor>
</transport_descriptors>
<participant profile_name="participant_profile_ros2" is_default_profile="true">
<rtps>
<name>profile_for_ros2_context</name>
<userTransports>
<transport_id>UDP_transport</transport_id>
</userTransports>
<useBuiltinTransports>false</useBuiltinTransports>
<sendSocketBufferSize>1048576</sendSocketBufferSize>
<listenSocketBufferSize>1048576</listenSocketBufferSize>
<builtin>
<initialPeersList>
<locator>
<udpv4>
<address>127.0.0.1</address>
</udpv4>
</locator>
</initialPeersList>
</builtin>
</rtps>
</participant>
<data_writer profile_name="default publisher profile" is_default_profile="true">
<qos>
<publishMode>
<kind>ASYNCHRONOUS</kind>
</publishMode>
<latencyBudget>
<duration>
<sec>0</sec>
<nanosec>1000000</nanosec>
</duration>
</latencyBudget>
</qos>
<historyMemoryPolicy>PREALLOCATED_WITH_REALLOC</historyMemoryPolicy>
</data_writer>
<data_reader profile_name="default subscription profile" is_default_profile="true">
<qos>
<data_sharing>
<kind>AUTOMATIC</kind>
</data_sharing>
<latencyBudget>
<duration>
<sec>0</sec>
<nanosec>1000000</nanosec>
</duration>
</latencyBudget>
</qos>
<historyMemoryPolicy>PREALLOCATED_WITH_REALLOC</historyMemoryPolicy>
</data_reader>
</profiles>
```
### Environment variables
Set the following environment variables to use the custom FastDDS profile:
```bash
export RMW_IMPLEMENTATION=rmw_fastrtps_cpp
export FASTRTPS_DEFAULT_PROFILES_FILE=$HOME/shm_fastdds.xml
export RMW_FASTRTPS_USE_QOS_FROM_XML=1
```
This configuration aims to optimize the data flow and reduce transmission delays, improving the responsiveness and
reliability of the Orbbec camera system in a ROS2 environment.
docs/source/5_advanced/gdb_debug.md
Executable
+23
View File
@@ -0,0 +1,23 @@
# GDB debug
Debugging ROS 2 programs with GDB involves several steps:
## Config debug
Set `CMAKE_BUILD_TYPE` to `Debug` in ` orbbec_camera/CMakeLists.txt`
```
set(CMAKE_BUILD_TYPE Debug)
```
## Use xterm terminal to open gdb debugging
Install xterm
```bash
sudo apt install xterm
```
Take gemini_330_series.launch.py as an example to use xterm terminal to open gdb
![Multi_camera1](../image/gdb_1.png)
docs/source/5_advanced/image/multi_camera_sync/1731474090291.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 74 KiB

docs/source/5_advanced/multi_camera_sync.md
Executable
+128
View File
@@ -0,0 +1,128 @@
<!-- docs/source/6_advanced/multi_camera_sync.md -->
# Multiple cameras synchronization
- Table of contents
- [Preparation](#preparation)
- [Check the camera usb port](#check-the-camera-usb-port)
- [Configure multi_camera_synced.launch.py](#configure-multi_camera_synced.launch.py)
- [Run multi_camera_synced.launch.py](#run-multi_camera_synced.launch.py)
- [Advanced Parameters](#advanced-parameters)
- [Gmsl example](#gmsl-example)
- [suggestions for multiple cameras synchronization](#suggestions for multiple cameras synchronization)
## Preparation
First, please read the user documentation:[https://www.orbbec.com/docs/set-up-cameras-for-external-synchronization_v1-2/](https://www.orbbec.com/docs/set-up-cameras-for-external-synchronization_v1-2/)
Secondly,make sure the cameras are properly connected to the multi-camera synchronizer
![Multi_camera1](../image/Sync_connect.png)
## Check the camera usb port
```bash
ros2 run orbbec_camera list_devices_node
```
Output:
![Multi_camera1](../image/Multi_camera1.png)
## Configure multiple cameras synced
Open `orbbec_multicamera.launch.py`, the camera configuration is as shown below
You can replace `multicamera.yaml `with other yaml files, such as `multicamera_synced.yaml`
![Multi_camera1](../image/Multi_camera5.png)
Open `multicamera_synced.yaml`，the camera configuration is as shown below
![Multi_camera1](../image/Multi_camera6.png)
```
note: gemini330_series_sync_front_camera.yaml is the camera configuration file.
```
**When configuring multiple cameras sync, you need to pay attention to the following parameters:**
1.**camera_name**
camera_name is set to front_camera, for example, the color image topic name is /front_camera/color/image_raw"
2.**usb_port**
The `usb_port` parameter specifies the USB port number to which the camera is connected. In your example, "2-7" indicates that the camera devices connected to USB ports 2 through 7 are started. You can use the command `ros2 run orbbec_camera list_devices_node` to view the device port numbers.
Please ensure that these port numbers match your actual hardware cameras. If you have more cameras or cameras connected to different ports, you need to configure the corresponding port number for each device.
3.**device_num**
The device_num parameter indicates the number of cameras to be started. Please ensure that this value matches the number of cameras you want to start and does not exceed the number of cameras actually connected or the system's processing capacity.
4.**sync_mode**
sync_mode is set to software_triggering, indicating that the 2-7 camera device is set to software trigger mode, and the selection of multiple cameras synchronization mode can refer to the following table.
Please refer to the[multi-camera synchronization mode definition description](https://www.orbbec.com/docs-general/set-up-cameras-for-external-synchronization_v1-2/#) for details.
![Multi_camera1](../image/Multi_camera7_1.png)
![Multi_camera1](../image/Multi_camera7_2.png)
`multicamera_synced.yaml` describes the camera startup order, the host must be started last
![Multi_camera1](../image/Multi_camera6.png)
## Run `multicamera_synced.launch.py`
```bash
ros2 launch orbbec_camera multicamera_synced.launch.py
```
## Advanced sync parameters
Some camera parameters are related to multi-camera sync
| Camera parameters | action |
| ----------------------- | ------------------------------------------------------------- |
| trigger_out_enabled | Trigger signal switch setting |
| trigger2image_delay_us | Configure the secondarydepth delay and secondarycolor delay |
| trigger_out_delay_us | Trigger signal delay |
| frames_per_trigger | Software trigger frequency(used with software_trigger_period) |
| software_trigger_period | Software trigger interval(used with frames_per_trigger) |
## GMSL camera example
**Key Distinctions Between GMSL and USB Devices:**
**1.usb_port Configuration:**
• For USB cameras, the port is specified as: usb_port: "2-3"
• For GMSL cameras, the port should be designated as: usb_port: "gmsl2-3"
**2.Color Stream Format Compatibility:**
• It is important to note that GMSL devices do not support the MJPG color format. Consequently, the format must be switched to YUYV when utilizing GMSL equipment.
## suggestions for multiple cameras synchronization
When configuring multiple cameras, there are several additional points to consider:
1.Power Supply: Ensure that each camera receives sufficient power supply. Simultaneous operation of multiple high-power devices can put strain on the USB bus.
2.Bandwidth Limitations: Simultaneous data transfer from multiple cameras can strain the USB bus or network bandwidth. Consider using higher bandwidth connections (such as USB 3.0 or higher) or optimizing data transfer settings.
3.Synchronization Issues: If you require time synchronization between multiple cameras, ensure that your system supports and is properly configured for camera synchronization.
4.Software Configuration: In ROS, you may need to configure separate nodes and topics for each camera to ensure they do not conflict. Using namespaces and the parameter server can help manage these configurations.
Finally, do not forget to conduct thorough testing before deployment to ensure that all cameras function correctly and that system performance meets expectations.
docs/source/5_advanced/zero_copy.md
Executable
+54
View File
@@ -0,0 +1,54 @@
# Zero-copy communications
## Efficient intra-process communication:
[](https://github.com/orbbec/OrbbecSDK_ROS2?tab=readme-ov-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.
You will need to launch a component container and launch our node as a component together with other component nodes. Further details on "Composing multiple nodes in a single process" can be found [here](https://docs.ros.org/en/rolling/Tutorials/Composition.html).
Further details on efficient intra-process communication can be found [here](https://docs.ros.org/en/humble/Tutorials/Intra-Process-Communication.html#efficient-intra-process-communication).
## Zero-copy example
[](https://github.com/orbbec/OrbbecSDK_ROS2?tab=readme-ov-file#example)
## Manually loading multiple components into the same process
[](https://github.com/orbbec/OrbbecSDK_ROS2?tab=readme-ov-file#manually-loading-multiple-components-into-the-same-process)
* Start the component:
```shell
ros2 run rclcpp_components component_container
```
* Add the wrapper:
```shell
ros2 component load /ComponentManager orbbec_camera orbbec_camera::OBCameraNodeDriver -e use_intra_process_comms:=true
```
Load other component nodes (consumers of the wrapper topics) in the same way.
## Using a launch file
[](https://github.com/orbbec/OrbbecSDK_ROS2?tab=readme-ov-file#using-a-launch-file)
```shell
ros2 launch orbbec_camera orbbec_camera.launch.py use_intra_process_comms:=true
```
```bash
$ ros2 component list
/camera/camera_container
1 /camera/camera
2 /camera/frame_latency
```
## Limitations
[](https://github.com/orbbec/OrbbecSDK_ROS2?tab=readme-ov-file#limitations)
* Node components are currently not supported on RCLPY
* Compressed images using `image_transport` will be disabled as this isn't supported with intra-process communication