docs: add AE/AWB lock test and GigE action command examples; update documentation structure

docs/en/source/camera_devices/4_application_guide/application_guide.rst

@@ -12,3 +12,4 @@ This chapter introduces application development with the SDK, including launch p
     coordinate_and_tf.md
     compressed_image.md
     point_cloud.md
+    examples/ae_awb_lock.md

docs/en/source/camera_devices/4_application_guide/examples/ae_awb_lock.md

@@ -0,0 +1,48 @@
+# AE/AWB Lock Test
+
+The source file is in [ae_awb_lock](https://github.com/orbbec/OrbbecSDK_ROS2/tree/v2-main/orbbec_camera/examples/ae_awb_lock).
+
+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.
+
+Run the camera driver and this sample in the same namespace:
+
+```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 \
+  orbbec_camera_msgs/action/RunAeAwbLockTest \
+  "{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:
+
+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.

docs/en/source/camera_devices/5_advanced_guide/advanced_guide.rst

@@ -26,6 +26,7 @@ Multi-Camera
     multi_camera/multi_camera_synced.md
     multi_camera/multi_camera_synced_verification_tool.md
     multi_camera/gmsl_camera.md
+    multi_camera/gige_action_command.md
 
 
 Configuration & Modes

docs/en/source/camera_devices/5_advanced_guide/multi_camera/gige_action_command.md

@@ -0,0 +1,101 @@
+# GigE Action Command
+
+The source files are in [gige_action_command](https://github.com/orbbec/OrbbecSDK_ROS2/tree/v2-main/orbbec_camera/examples/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.
+
+## Requirements
+
+- Gemini 335Le firmware 1.8.24 or later
+- Orbbec SDK 2.10.2 or later
+- Both cameras and the host on the same network
+
+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
+
+```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:
+
+```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.

docs/en/source/camera_devices/5_advanced_guide/performance/efficient_intra_process_communication.md

@@ -30,12 +30,16 @@ Further details on efficient intra-process communication can be found [here](htt
 
 The [multi_camera_shared_container](https://github.com/orbbec/OrbbecSDK_ROS2/tree/v2-main/orbbec_camera/examples/multi_camera_shared_container) example creates one multithreaded component container and loads two Gemini 330 Series camera components into it. Update the two `usb_port` values in `multi_camera_shared_container.launch.py`, then run:
 
+The default ports are `2-1` and `2-2`. Use `ros2 run orbbec_camera list_devices_node` to find the ports on your system. Give each camera a unique `camera_name`.
+
 ```bash
 ros2 launch orbbec_camera multi_camera_shared_container.launch.py
 ```
 
 The example passes the following arguments to both camera includes:
 
+The top-level launch file starts `shared_orbbec_container` first, then includes the example-specific `gemini_330_series_shared_container.launch.py` for each camera. The second camera starts two seconds after the first. Both includes must use the same container name, and the container must be running before components are loaded.
+
 * `attach_to_shared_component_container=true`: Loads the camera component into an existing container instead of creating another container.
 * `component_container_name=shared_orbbec_container`: Selects the target container. The value must match the name of the container created by the parent launch file.
 * `use_intra_process_comms=true`: Enables intra-process communication for the camera component.