i/OrbbecSDK_ROS2
1
0
Fork 0
mirror of https://github.com/orbbec/OrbbecSDK_ROS2.git synced 2026-10-09 14:27:02 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: update example READMEs for clarity and consistency, add usage guides in multiple languages

Browse Source
This commit is contained in:
ob-yalian
2026-09-28 17:46:08 +08:00
parent 31a0181f6a
commit db5404d1fe
5 changed files with 47 additions and 168 deletions
Download Patch File Download Diff File Expand all files Collapse all files
orbbec_camera/examples/README.MD
+13 -11
View File
@@ -1,20 +1,22 @@
# OrbbecSDK ROS2 Examples
This directory contains practical launch and tool examples. Full usage,
configuration, and troubleshooting are maintained on the official documentation
site so that instructions have a single source of truth.
This directory contains practical launch and tool examples. Most example READMEs
contain local setup and run commands; their full usage, configuration, and
troubleshooting are maintained on the official documentation site. The Gemini
435Le example keeps its complete instructions next to its source code.
For command-line maintenance and diagnostic utilities, see the official
[Tool Index](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/6_benchmark/tools.html).
## Example Index
| Source | Purpose | Experience Level | Official Guide |
| Source | Purpose | Experience Level | Usage Guide |
| :---: | --- | :---: | --- |
| [Multi-camera network](./multi_net_camera) | Launch multiple supported Orbbec network cameras. | ⭐️ | [Network camera guide](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/5_advanced_guide/configuration/net_camera.html) |
| [GigE Action Command](./gige_action_command) | Configure and trigger a Gemini 335Le camera group over GVCP. | ⭐️⭐️ | [README](./gige_action_command/README.md) |
| [GMSL camera](./gmsl_multi_camera_sync) | Synchronize two GMSL-connected Gemini 330 Series cameras. | ⭐️⭐️ | [README](./gmsl_multi_camera_sync/README.md) |
| [Shared component container](./multi_camera_shared_container) | Load multiple Gemini 330 Series cameras into one component container. | ⭐️⭐️ | [README](./multi_camera_shared_container/README.md) |
| [AE/AWB lock test](./ae_awb_lock) | Verify AE/AWB convergence, frame-metadata capture, and manual lock-in through ROS 2. | ⭐️⭐️ | [README](./ae_awb_lock/README.md) |
| [Benchmark](./benchmark) | Benchmark the performance of different camera configurations. | ⭐️⭐️ | [Performance benchmark tools](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/6_benchmark/benchmark_tools.html) |
| [Multi-camera synchronization verification](./multi_camera_synced_verification_tool) | Verify synchronization accuracy across multiple cameras. | ⭐️⭐️⭐️ | [Synchronization verification guide](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/5_advanced_guide/multi_camera/multi_camera_synced_verification_tool.html) |
| [Multi-camera network](./multi_net_camera) | Launch multiple supported Orbbec network cameras. | ⭐️ | [EN](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/5_advanced_guide/configuration/net_camera.html) / [中文](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/5_advanced_guide/configuration/net_camera.html) |
| [GigE Action Command](./gige_action_command) | Configure and trigger a Gemini 335Le camera group over GVCP. | ⭐️⭐️ | [EN](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/5_advanced_guide/multi_camera/gige_action_command.html) / [中文](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/5_advanced_guide/multi_camera/gige_action_command.html) |
| [GMSL camera](./gmsl_multi_camera_sync) | Synchronize two GMSL-connected Gemini 330 Series cameras. | ⭐️⭐️ | [EN](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/5_advanced_guide/multi_camera/gmsl_camera.html) / [中文](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/5_advanced_guide/multi_camera/gmsl_camera.html) |
| [Shared component container](./multi_camera_shared_container) | Load multiple Gemini 330 Series cameras into one component container. | ⭐️⭐️ | [EN](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/5_advanced_guide/performance/efficient_intra_process_communication.html) / [中文](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/5_advanced_guide/performance/efficient_intra_process_communication.html) |
| [AE/AWB lock test](./ae_awb_lock) | Verify AE/AWB convergence, frame-metadata capture, and manual lock-in through ROS 2. | ⭐️⭐️ | [EN](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/4_application_guide/examples/ae_awb_lock.html) / [中文](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/4_application_guide/examples/ae_awb_lock.html) |
| [Gemini 435Le example node](./Gemini_435Le_example_node) | Try camera services and inspect device status through an interactive menu. | ⭐️⭐️ | [Example README](./Gemini_435Le_example_node/README.MD) |
| [Benchmark](./benchmark) | Benchmark the performance of different camera configurations. | ⭐️⭐️ | [EN](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/6_benchmark/benchmark_tools.html) / [中文](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/6_benchmark/benchmark_tools.html) |
| [Multi-camera synchronization verification](./multi_camera_synced_verification_tool) | Verify synchronization accuracy across multiple cameras. | ⭐️⭐️⭐️ | [EN](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/5_advanced_guide/multi_camera/multi_camera_synced_verification_tool.html) / [中文](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/5_advanced_guide/multi_camera/multi_camera_synced_verification_tool.html) |
orbbec_camera/examples/ae_awb_lock/README.md
+10 -36
View File
@@ -1,46 +1,20 @@
# AE/AWB Lock Test
This sample exposes a test-only ROS 2 action that verifies the AE/AWB capture and manual
lock-in flow through the camera driver's services and color-frame metadata.
This test-only ROS 2 action checks the AE/AWB capture and manual lock-in flow through the camera driver's services and color-frame metadata.
Run the camera driver and this sample in the same namespace:
## Before running
Start the camera driver with the color stream enabled. The sample must run in the same namespace as the driver, and `color/metadata` must be available.
## Run
```bash
ros2 run orbbec_camera ae_awb_lock_test_node --ros-args -r __ns:=/camera
```
Send a goal and print feedback:
```bash
ros2 action send_goal \
/camera/run_ae_awb_lock_test \
ros2 action send_goal /camera/run_ae_awb_lock_test \
orbbec_camera_msgs/action/RunAeAwbLockTest \
"{timeout_ms: 10000}" \
--feedback
"{timeout_ms: 10000}" --feedback
```
The sample subscribes to the relative `color/metadata` topic. It enables auto exposure and auto
white balance, waits until the SDK status equals `1`, captures exposure, color gain, and color
temperature from the latest color-frame metadata, and reads AWB R/B/G gains through the structured
property service. It then disables the auto controls and writes the captured values back in this
order:
## Full guide
1. Color exposure
2. Color gain
3. AWB R/B/G gains
4. Color temperature
The final AWB gain readback must exactly match the captured value. Other readback differences are
reported as warnings because the device may quantize those controls. On failure or cancellation,
the sample restores auto exposure and auto white balance.
Every feedback phase contains a fresh status value read from the camera service. The
`waiting_for_services` feedback is published after all required services become available, because
the status cannot be read before its service is ready.
The color stream must be enabled, and `/camera/color/metadata` must be available when using the
`/camera` namespace. The action fails instead of writing default values if no metadata arrives
before the goal timeout or if `exposure`, `gain`, or `white_balance` is missing. The goal timeout
covers the main workflow, including service discovery, service calls, convergence, capture,
writeback, and verification. Restoring auto exposure and auto white balance after a failure uses a
separate best-effort timeout.
[AE/AWB lock test (English)](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/4_application_guide/examples/ae_awb_lock.html) · [中文指南](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/4_application_guide/examples/ae_awb_lock.html)
orbbec_camera/examples/gige_action_command/README.md
+6 -88
View File
@@ -1,99 +1,17 @@
# GigE Action Command
This example starts two Gemini 335Le cameras in Group Actions synchronization mode and one
host-side Action Command sender. The sender is intentionally created once at the top level because
a GVCP Action Command can trigger multiple cameras.
This example starts two Gemini 335Le cameras in Group Actions synchronization mode and one host-side Action Command sender.
## Requirements
## Before running
- Gemini 335Le firmware 1.8.24 or later
- Orbbec SDK 2.10.2 or later
- Both cameras and the host on the same network
Use Gemini 335Le firmware 1.8.24 or later and Orbbec SDK 2.10.2 or later. Connect both cameras and the host to the same network, then set the two `net_device_ip` values in `multi_gige_action_command.launch.py` to the camera IP addresses.
Before running the example, change the two `net_device_ip` values in
`multi_gige_action_command.launch.py` to match the cameras.
## Start the cameras and sender
## Run
```bash
ros2 launch orbbec_camera multi_gige_action_command.launch.py
```
The launch file creates these device-scoped configuration services and one network-scoped sender:
## Full guide
```text
/camera_01/get_action_config
/camera_01/set_action_config
/camera_02/get_action_config
/camera_02/set_action_config
/gige_action_command_node/send_action_command
```
## Configure the cameras
Configure Action Signal block 0 on both cameras with matching keys and masks:
```bash
ros2 service call /camera_01/set_action_config \
orbbec_camera_msgs/srv/SetActionConfig \
"{device_key: 1, selector: 0, group_key: 1, group_mask: 1}"
ros2 service call /camera_02/set_action_config \
orbbec_camera_msgs/srv/SetActionConfig \
"{device_key: 1, selector: 0, group_key: 1, group_mask: 1}"
```
Read the configuration back when needed:
```bash
ros2 service call /camera_01/get_action_config \
orbbec_camera_msgs/srv/GetActionConfig \
"{selector: 0}"
```
## Trigger the group
The service exposes three trigger modes. Every camera whose device key, group key, and group mask
match the request will be triggered.
### Immediate trigger
Set `trigger_mode` to `0`. The delay and scheduled time fields must be zero:
```bash
ros2 service call /gige_action_command_node/send_action_command \
orbbec_camera_msgs/srv/SendActionCommand \
"{device_key: 1, group_key: 1, group_mask: 1, broadcast_ip: '255.255.255.255', trigger_mode: 0, delay_ms: 0, scheduled_time: 0}"
```
### Relative-delay trigger
Set `trigger_mode` to `1` and provide a positive delay in milliseconds. The node reads the host
system clock, adds the delay, and converts the result to the absolute GVCP/PTP timestamp expected by
the SDK. This example schedules the command one second in the future:
```bash
ros2 service call /gige_action_command_node/send_action_command \
orbbec_camera_msgs/srv/SendActionCommand \
"{device_key: 1, group_key: 1, group_mask: 1, broadcast_ip: '255.255.255.255', trigger_mode: 1, delay_ms: 1000, scheduled_time: 0}"
```
The host `CLOCK_REALTIME` must be synchronized to the same PTP domain as the cameras, for example
by using `phc2sys`. The launch file enables camera PTP synchronization, but it does not configure
the host PTP services. Choose a delay long enough for the command to reach the cameras before its
target time.
### Absolute PTP-time trigger
Set `trigger_mode` to `2`, leave `delay_ms` at zero, and provide a future encoded PTP timestamp. The
upper 32 bits contain seconds and the lower 32 bits contain nanoseconds:
```bash
ros2 service call /gige_action_command_node/send_action_command \
orbbec_camera_msgs/srv/SendActionCommand \
"{device_key: 1, group_key: 1, group_mask: 1, broadcast_ip: '255.255.255.255', trigger_mode: 2, delay_ms: 0, scheduled_time: <PTP_TIMESTAMP>}"
```
The response returns `encoded_scheduled_time`, the exact 64-bit value sent to the SDK. For delayed
triggering this is the timestamp calculated by the node. `success: true` means the host dispatched
the GVCP command; the protocol does not return a device acknowledgment.
[GigE Action Command (English)](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/5_advanced_guide/multi_camera/gige_action_command.html) · [中文指南](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/5_advanced_guide/multi_camera/gige_action_command.html)
orbbec_camera/examples/gmsl_multi_camera_sync/README.md
+9 -13
View File
@@ -1,22 +1,18 @@
# GMSL Multi-Camera Synchronization
This example starts two GMSL-connected Gemini 330 Series cameras in hardware synchronization
mode. It uses the package's standard `gemini_330_series.launch.py` file.
This example synchronizes two GMSL-connected Gemini 330 Series cameras using the standard `gemini_330_series.launch.py` file.
Before starting the cameras, grant access to the camera synchronization device:
## Before running
Grant access to `/dev/camsync` and update the `usb_port` values in `multi_gmsl_camera_synced.launch.py` to match your GMSL links. The default ports are `gmsl2-1` and `gmsl2-3`.
## Run
```bash
sudo chmod 777 /dev/camsync
```
Before starting the example, update the `usb_port` values in
`multi_gmsl_camera_synced.launch.py` if your system reports different GMSL links. The default
values are `gmsl2-1` and `gmsl2-3`.
```bash
ros2 launch orbbec_camera multi_gmsl_camera_synced.launch.py
```
Both cameras use `secondary_synced` mode. `camera_01` enables the host-side GMSL trigger at
30 fps (`gmsl_trigger_fps=3000`), while `camera_02` receives the same trigger. The receiving
camera is started first, followed by the trigger-generating camera after two seconds.
## Full guide
[GMSL multi-camera synchronization (English)](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/5_advanced_guide/multi_camera/gmsl_camera.html) · [中文指南](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/5_advanced_guide/multi_camera/gmsl_camera.html)
orbbec_camera/examples/multi_camera_shared_container/README.md
+9 -20
View File
@@ -1,28 +1,17 @@
# Attach Cameras to a Shared Component Container
# Shared Component Container
This example shows how to load two Gemini 330 Series camera components into one externally
created ROS 2 component container.
This example loads two Gemini 330 Series camera components into one ROS 2 component container.
Before starting the example, update the `usb_port` values in
`multi_camera_shared_container.launch.py` to match your two cameras. The default values are
`2-1` and `2-2`.
## Before running
Update both `usb_port` values in `multi_camera_shared_container.launch.py` to match your cameras. The defaults are `2-1` and `2-2`. Give each camera a unique `camera_name`.
## Run
```bash
ros2 launch orbbec_camera multi_camera_shared_container.launch.py
```
The example performs three steps:
## Full guide
1. Starts one multithreaded component container named `shared_orbbec_container`.
2. Includes the example-specific `gemini_330_series_shared_container.launch.py` once for each
camera.
3. Passes `attach_to_shared_component_container=true` and the same
`component_container_name` to both includes, so neither include creates its own container.
`use_intra_process_comms=true` enables intra-process communication for the loaded camera
components. Keep every `camera_name` unique, and make sure the shared container is running
before a camera component is loaded.
The package's main `launch/gemini_330_series.launch.py` is not modified by this example. The
example-specific launcher mirrors its Gemini 330 Series parameters and adds only the component
container selection controls needed for this demonstration.
[Efficient intra-process communication (English)](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/5_advanced_guide/performance/efficient_intra_process_communication.html) · [中文指南](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/5_advanced_guide/performance/efficient_intra_process_communication.html)