mirror of
https://github.com/orbbec/OrbbecSDK_ROS2.git
synced 2026-10-11 15:09:48 +08:00
docs: Simplify README
This commit is contained in:
obyalian
@@ -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
|
||||
<?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
|
||||
```
|
||||
|
||||
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 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)
|
||||
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)
|
||||
|
||||
Reference in New Issue
Block a user