docs: update the documentation to version 2.8.8

docs/en/source/camera_devices/1_overview/introduction.md

@@ -25,7 +25,7 @@ Here is the device support list of main branch (v1.x) and v2-main branch (v2.x):
       <td>recommended for new designs</td>
     </tr>
     <tr>
-      <td rowspan="2" style="text-align: center; font-weight: bold;">Gemini 301</td>
+      <td rowspan="3" style="text-align: center; font-weight: bold;">Gemini 301</td>
       <td>Gemini 305</td>
       <td>not supported</td>
       <td>recommended for new designs</td>
@@ -35,6 +35,11 @@ Here is the device support list of main branch (v1.x) and v2-main branch (v2.x):
       <td>not supported</td>
       <td>recommended for new designs</td>
     </tr>
+    <tr>
+      <td>Gemini 309g</td>
+      <td>not supported</td>
+      <td>recommended for new designs</td>
+    </tr>
     <tr>
       <td rowspan="8" style="text-align: center; font-weight: bold;">Gemini 330</td>
       <td>Gemini 335</td>
@@ -200,15 +205,20 @@ To learn how to obtain and upgrade the latest firmware, [please click here](../3
       <td>gemini435_le.launch.py</td>
     </tr>
     <tr>
-      <td rowspan="2" style="text-align: center; font-weight: bold;">Gemini 301</td>
+      <td rowspan="3" style="text-align: center; font-weight: bold;">Gemini 301</td>
       <td>Gemini 305</td>
       <td><a href="https://doc.orbbec.com/documentation/Gemini%20305%20Documentation/Firmware%20Release%20of%20Gemini%20305">1.0.70</a></td>
-      <td>gemini305.launch.py</td>
+      <td>gemini_301_series.launch.py</td>
     </tr>
     <tr>
       <td>Gemini 305g</td>
       <td><a href="https://doc.orbbec.com/documentation/Gemini%20305%20Documentation/Firmware%20Release%20of%20Gemini%20305">1.0.70</a></td>
-      <td>gemini305_g.launch.py</td>
+      <td>gemini_301_series.launch.py</td>
+    </tr>
+    <tr>
+      <td>Gemini 309g</td>
+      <td>-</td>
+      <td>gemini_301_series.launch.py</td>
     </tr>
     <tr>
       <td rowspan="8" style="text-align: center; font-weight: bold;">Gemini 330</td>
@@ -309,8 +319,9 @@ To learn how to obtain and upgrade the latest firmware, [please click here](../3
   </thead>
   <tbody>
     <tr><td style="text-align: center; font-weight: bold;">Gemini 430</td><td>Gemini 435Le</td><td>-</td></tr>
-    <tr><td rowspan="2" style="text-align: center; font-weight: bold;">Gemini 301</td><td>Gemini 305</td><td>-</td></tr>
+    <tr><td rowspan="3" style="text-align: center; font-weight: bold;">Gemini 301</td><td>Gemini 305</td><td>-</td></tr>
     <tr><td>Gemini 305g</td><td>-</td></tr>
+    <tr><td>Gemini 309g</td><td>-</td></tr>
     <tr><td rowspan="8" style="text-align: center; font-weight: bold;">Gemini 330</td><td>Gemini 335</td><td>gemini_335_336.urdf.xacro</td></tr>
     <tr><td>Gemini 336</td><td>gemini_335_336.urdf.xacro</td></tr>
     <tr><td>Gemini 330</td><td>-</td></tr>
@@ -319,7 +330,8 @@ To learn how to obtain and upgrade the latest firmware, [please click here](../3
     <tr><td>Gemini 330L</td><td>-</td></tr>
     <tr><td>Gemini 335Lg</td><td>gemini_335_Lg.urdf.xacro</td></tr>
     <tr><td>Gemini 335Le</td><td>gemini_335_Le.urdf.xacro</td></tr>
-    <tr><td style="text-align: center; font-weight: bold;">Gemini 340</td><td>Gemini 345Lg</td><td>gemini_345_Lg.urdf.xacro</td></tr>
+    <tr><td rowspan="2" style="text-align: center; font-weight: bold;">Gemini 340</td><td>Gemini 345</td><td>gemini_345.urdf.xacro</td></tr>
+    <tr><td>Gemini 345Lg</td><td>gemini_345_Lg.urdf.xacro</td></tr>
     <tr><td rowspan="4" style="text-align: center; font-weight: bold;">Gemini 2</td><td>Gemini 2</td><td>gemini_2.urdf.xacro</td></tr>
     <tr><td>Gemini 2 L</td><td>gemini_2_L.urdf.xacro</td></tr>
     <tr><td>Gemini 215</td><td>-</td></tr>

docs/en/source/camera_devices/4_application_guide/launch_parameters.md

@@ -15,7 +15,7 @@ The following are the launch parameters available:
 *   **`device_num`**
     *   The number of devices. This must be filled in if multiple cameras are required.
 * **`device_preset`**
-    * The default value is `Default`. You can use the following command to view the configurable mode
+    * The default value is determined by the launch file. You can use the following command to view the configurable modes; the tool also prints the preset list and preset version information.
     ```bash
     ros2 run orbbec_camera list_camera_profile_mode_node
     ```
@@ -177,10 +177,11 @@ The following are the launch parameters available:
   > **Supported Modules**: Gemini 305
 * **`enable_false_positive_filter`**
   * Enable this option to reduce ghosting noise.
-  > **Supported Modules**: DaBaiA / DaBaiAL / Gemini345 / Gemini345Lg
+  > **Supported Modules**: DaBaiA / DaBaiAL / Gemini 330 series / Gemini345 / Gemini345Lg
 #### Disparity
 *   **`disparity_to_depth_mode`**
-    *   `HW`: use hardware disparity to depth conversion. `SW`: use software disparity to depth conversion.
+    *   `HW`: use hardware disparity to depth conversion. `SW`: use software disparity to depth conversion. Use `disable` to turn it off.
+    *   This parameter is case-insensitive. Invalid values are reported and replaced with the default value.
 *   **`disparity_range_mode`**, **`disparity_search_offset`**, **`disparity_offset_config`**
     *   Parameters for disparity search offset. Used for [disparity search offset](../5_advanced_guide/configuration/disparity_search_offset.md).
 
@@ -199,11 +200,13 @@ The following are the launch parameters available:
   *   Enable alignment of the depth frame to the color frame. This field is required when the `enable_colored_point_cloud` is set to `true`.
 - **`align_mode`**
   *   The alignment mode to be used. Options are `HW` for hardware alignment and `SW` for software alignment.
+  *   This parameter is case-insensitive. Invalid values are reported and replaced with the default value.
 - **`align_target_stream`**
   *   Set align target stream mode.
   *   The possible values are `COLOR`, `DEPTH`.
   *   `COLOR`: Align depth to color.
   *   `DEPTH`: Align color to depth.
+  *   This parameter is case-insensitive. Hardware D2C only supports `COLOR` as the target stream; use `align_mode:=SW` if you need to align to `DEPTH`.
 - **`intra_camera_sync_reference`**
   - Sets the reference point for intra-camera synchronization. Applicable for Gemini 330 series devices when `sync_mode` is set to **software** or **hardware trigger** mode. **Options:** `Start`, `Middle`, `End`. When set to empty, the long baseline device defaults to End, and the short baseline device defaults to Middle.
 
@@ -228,24 +231,27 @@ The following are the launch parameters available:
     *   Enable the extrinsics publish.
 *   **`ir_info_url`** / **`color_info_url`**
     *   Set URL of the IR/color camera info.
-*   **`enable_color_undistortion`**
+*   **`enable_[color|depth|ir|left_ir|right_ir]_undistortion`**
-    *   Enable the Color undistortion.
+    *   Enable the SDK undistortion filter for the selected image stream. Dual-IR devices use `enable_left_ir_undistortion` / `enable_right_ir_undistortion`; single-IR devices use `enable_ir_undistortion`.
 
 #### Time Synchronization
 * **`enable_sync_host_time`**
   * Enable synchronization of the host time with the camera time. The default value is `true`. If using global time, set to `false`.
 * **`time_domain`**
   * Select timestamp type: `device`, `global`, and `system`.
+  * This parameter is case-insensitive. Invalid values are reported and replaced with the default value.
+* **`timestamp_clock_type`**
+  * Set the SDK timestamp clock type. Optional values: `realtime`, `monotonic`. The default is `realtime`.
 * **`time_sync_period`**
   * Interval (in seconds) for synchronizing the camera time with the host system.
   > **Note**: This parameter only needs to be set when `enable_sync_host_time = true` and `time_domain = device`.
 
 * **`enable_frame_sync`**
   * Enable the frame synchronization.
-* **`enable_frame_timestamp_csv`**
+* **`enable_frame_drop_log`**
-  * Enable frame timestamp CSV logging. This is mainly used to analyze Color/Depth frame timestamps, publish latency, and synchronization issues.
+  * Enable frame drop logging. The log reports drops detected at both the SDK receive stage and the ROS publish stage.
 * **`frame_timestamp_csv_file`**
-  * Path of the frame timestamp CSV file. If empty, the default path is used; specify a writable path when debugging.
+  * CSV output path for frame timestamp statistics. If empty, no CSV file is written; set a path such as `/tmp/frame_timestamp.csv` to save CSV data.
 
 #### Logging & Diagnostics
 * **`log_level`**
@@ -263,8 +269,13 @@ The following are the launch parameters available:
 #### Miscellaneous
 *   **`config_file_path`**
     *   The path to the YAML configuration file. Default is `""`. If not specified, default parameters from the launch file will be used.
+*   **`load_config_json_file_path`**
+    *   SDK JSON configuration import path. When set, the node imports the JSON configuration during initialization. For Gemini 330 series, use `gemini_330_series_sdk_json.launch.py` as the dedicated SDK JSON launch file.
+*   **`export_config_json_file_path`**
+    *   SDK JSON configuration export path. When set, the node exports the current device configuration to JSON after initialization. You can also export at runtime with the `/camera/export_config_json` service.
 *   **`frame_aggregate_mode`**
     *   Set frame aggregate output mode. Optional values: `full_frame`, `color_frame`, `ANY`, `disable`.
+    *   This parameter is case-insensitive. Invalid values are reported and replaced with the default value.
 *   **`enable_d2c_viewer`**
     *   Publishes the D2C overlay image (for testing only).
 

docs/en/source/camera_devices/4_application_guide/services.md

@@ -161,6 +161,10 @@
     ```bash
     ros2 service call /camera/get_sdk_version orbbec_camera_msgs/srv/GetString
     ```
+*   `/camera/export_config_json`
+    ```bash
+    ros2 service call /camera/export_config_json orbbec_camera_msgs/srv/SetString "{data: '/tmp/orbbec_camera_config.json'}"
+    ```
 *   `/camera/reboot_device`
     ```bash
     ros2 service call /camera/reboot_device std_srvs/srv/Empty '{}'
@@ -191,7 +195,9 @@
 
 *   `/camera/set_filter`
     ```bash
-    # filter_name is the filter name, filter_enable indicates whether the filter is enabled or disabled, and filter_param represents the filter parameters.
+    # filter_name is the filter name, and filter_enable indicates whether the filter is enabled.
+    # filter_param is the legacy positional parameter form; filter_config is the new named parameter form.
+    # filter_param and filter_config cannot be used at the same time.
 
     # Set DecimationFilter: [scale]
     ros2 service call /camera/set_filter orbbec_camera_msgs/srv/SetFilter '{filter_name: DecimationFilter, filter_enable: false, filter_param: [5]}'
@@ -222,6 +228,11 @@
     # Set MgcNoiseRemovalFilter / LutNoiseRemovalFilter: []
     ros2 service call /camera/set_filter orbbec_camera_msgs/srv/SetFilter '{filter_name: MgcNoiseRemovalFilter, filter_enable: true, filter_param: []}'
     ros2 service call /camera/set_filter orbbec_camera_msgs/srv/SetFilter '{filter_name: LutNoiseRemovalFilter, filter_enable: true, filter_param: []}'
+
+    # Tune filters with named parameters
+    ros2 service call /camera/set_filter orbbec_camera_msgs/srv/SetFilter "{filter_name: NoiseRemovalFilter, filter_enable: true, filter_config: [{name: min_diff, value: '256'}, {name: max_size, value: '80'}]}"
+    ros2 service call /camera/set_filter orbbec_camera_msgs/srv/SetFilter "{filter_name: HardwareNoiseRemovalFilter, filter_enable: true, filter_config: [{name: threshold, value: '0.2'}]}"
+    ros2 service call /camera/set_filter orbbec_camera_msgs/srv/SetFilter "{filter_name: SpatialAdvancedFilter, filter_enable: true, filter_config: [{name: alpha, value: '0.5'}, {name: disp_diff, value: '160'}, {name: magnitude, value: '1'}, {name: radius, value: '8'}]}"
     ```
 
     Filter status is updated after service calls on `/camera/depth_filter_status` and `/camera/depth_filters/status`. `/camera/depth_filters/status` uses the structured `orbbec_camera_msgs/msg/DepthFiltersStatus` message and includes each filter's enabled state and parameters.

docs/en/source/camera_devices/4_application_guide/topics.md

@@ -9,7 +9,9 @@ Topics are organized by stream and function. By default, all topics are publishe
 These topics provide the raw image data and corresponding calibration information for each enabled camera stream. The pattern is consistent for `color`, `depth`, `ir`, `left_ir`, and `right_ir` streams.
 
 *   `/camera/color/image_raw`
-    *   Raw image data from the color stream.
+    *   Raw image data from the color stream. Subscribe to this topic for non-MJPG color formats such as RGB or YUYV.
+*   `/camera/color/image_raw/compressed`
+    *   Compressed image data from the MJPG color stream. When `color_format:=MJPG` is used, subscribe to this topic to avoid extra decoding in the ROS wrapper and reduce CPU usage.
 *   `/camera/color/camera_info`
     *   Camera calibration data and metadata for the color stream.
 *   `/camera/color/metadata`

docs/en/source/camera_devices/5_advanced_guide/configuration/firmware_update_tool.md

@@ -32,3 +32,12 @@ ros2 run orbbec_camera firmware_update_tool -- \
 --firmware_path /path/to/firmware.bin \
 --continue_on_error
 ```
+
+To enable SDK file logs and also attempt to enable firmware logs, add `--sdk_log_level`. Optional values are `debug`, `info`, `warn`, `error`, `fatal`, and `off`; the default is `off`.
+
+```bash
+ros2 run orbbec_camera firmware_update_tool -- \
+--serial_number <SN> \
+--preset_path /path/to/preset.bin \
+--sdk_log_level debug
+```

docs/en/source/camera_devices/5_advanced_guide/configuration/net_camera.md

@@ -44,13 +44,19 @@ For [multi_net_camera.launch.py](https://github.com/orbbec/OrbbecSDK_ROS2/blob/v
 ros2 launch orbbec_camera multi_net_camera.launch.py
 ```
 
-Use `list_devices_node` to inspect connected devices. Since v2.8.x, this tool also prints firmware version, local network interface name for Ethernet devices, and IP source type (`NONE`, `LLA`, `DHCP`, `PERSISTENT`).
+Use `list_devices_node` to inspect connected devices. Since v2.8.x, this tool also prints firmware version, preset list, preset version, local network interface name for Ethernet devices, and IP source type (`NONE`, `LLA`, `DHCP`, `PERSISTENT`). If one device fails during enumeration, the tool continues enumerating the remaining devices.
+
+To enable SDK and firmware logs, add `--sdk_log_level debug`:
+
+```bash
+ros2 run orbbec_camera list_devices_node -- --sdk_log_level debug
+```
 
 ## ip_config_tool Utility
 
 The **`ip_config_tool`** executable allows you to configure network camera IP settings directly from ROS 2, including DHCP, static IP, Force IP, and DHCP address assignment timeout. This is useful for quickly assigning or updating IP addresses without modifying launch files.
 
-> **Note:** Configuration applied with `dhcp` or `set_ip` is written to the device. `force_ip` is temporary and must be applied again after the device is powered off or restarted.
+> **Note:** DHCP / persistent IP configuration applied with `set_ip` is written to the device. `force_ip` is temporary and must be applied again after the device is powered off or restarted.
 > **Compatibility**: `set_device_ip` is still kept as a legacy alias and calls `ip_config_tool`. The old `old_ip` argument has been renamed to `current_ip`.
 
 **Example Usage**
@@ -65,17 +71,33 @@ Enable DHCP:
 
 ```bash
 ros2 run orbbec_camera ip_config_tool -- \
-dhcp \
+set_ip \
 --current_ip 192.168.1.10 \
---enable_dhcp true
+--enable_dhcp true \
+--enable_persistent_ip false
 ```
 
-Disable DHCP and set a static IP:
+Disable DHCP and set a persistent IP:
 
 ```bash
 ros2 run orbbec_camera ip_config_tool -- \
 set_ip \
 --current_ip 192.168.1.10 \
+--enable_dhcp false \
+--enable_persistent_ip true \
+--new_ip 192.168.1.11 \
+--mask 255.255.255.0 \
+--gateway 192.168.1.1
+```
+
+Enable both DHCP and persistent IP (requires a device/firmware that supports IP config V2):
+
+```bash
+ros2 run orbbec_camera ip_config_tool -- \
+set_ip \
+--current_ip 192.168.1.10 \
+--enable_dhcp true \
+--enable_persistent_ip true \
 --new_ip 192.168.1.11 \
 --mask 255.255.255.0 \
 --gateway 192.168.1.1
@@ -104,12 +126,14 @@ set_dhcp_timeout \
 **Parameters**
 
 - **`current_ip`** – Current IP address of the device.
-- **`enable_dhcp`** – Enable or disable DHCP for the `dhcp` or `force_ip` subcommand.
+- **`enable_dhcp`** – Enable or disable DHCP for the `set_ip` or `force_ip` subcommand.
-- **`new_ip`** – Static IP address to assign.
+- **`enable_persistent_ip`** – Enable or disable persistent IP for the `set_ip` subcommand.
+- **`new_ip`** – Persistent IP or Force IP address to assign.
 - **`mask`** – Subnet mask for the new IP.
 - **`gateway`** – Gateway address for the new IP.
 - **`force_ip_mac`** – Target MAC address for Force IP.
 - **`timeout`** / **`dhcp_assign_ip_timeout`** – DHCP address assignment timeout in seconds.
+- **`sdk_log_level`** – SDK file log level. Optional values: `debug`, `info`, `warn`, `error`, `fatal`, `off`. Any non-`off` value also attempts to enable firmware logs.
 
 > **Version notes**: The `LLA` switch was supported only by Gemini 335Le firmware `1.7.05` and above and Gemini 435Le firmware `1.3.17` and above.
 

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

@@ -14,6 +14,14 @@ To achieve the lowest possible CPU usage in OrbbecSDK_ROS2, it is recommended to
 | `color_format` |                `RGB`                |         Lower CPU usage than `MJPG`         |
 |    `filter`    | Only `hardware_noise_removal_filter` | Other filters significantly increase CPU usage |
 
+### Color Stream Format and Subscription
+
+v2.8.8 optimizes the color image publishing path:
+
+- For non-MJPG color formats such as RGB or YUYV, subscribe to `/camera/color/image_raw`.
+- When `color_format:=MJPG` is used, subscribe to `/camera/color/image_raw/compressed`. The ROS wrapper publishes the compressed image directly, avoiding extra host-side decoding and significantly reducing CPU usage for MJPG streams.
+- If you subscribe to `/camera/color/image_raw`, MJPG still needs to be decoded on the host, which increases CPU usage.
+
 ### Launch Files Used for Testing
 
 * `gemini_330_series_lower_cpu_usage.launch.py`
@@ -93,4 +101,3 @@ Based on the test results, using only the `hardware_noise_removal_filter` result
 |     `depth_registration`     | `false` or `true` with `align_mode=HW` |      Software alignment consumes more CPU      |
 |     `enable_point_cloud`     |                    `false`                    |     Disabling point cloud reduces CPU usage     |
 | `enable_colored_point_cloud` |                    `false`                    | Disabling colored point cloud reduces CPU usage |
-

docs/en/source/camera_devices/6_benchmark/othertools.md

@@ -1,16 +1,16 @@
 # Other Tools
 
-## Frame Timestamp CSV Logging
+## Frame Drop Logging and Frame Timestamp CSV Logging
 
-When `enable_frame_timestamp_csv` is enabled, the camera node records Color and Depth frame timestamp data to a CSV file. This is useful for frame synchronization, publish latency, and timestamp debugging.
+When `enable_frame_drop_log` is enabled, the camera node prints Color and Depth frame drop statistics to the log. The log helps distinguish drops detected at the SDK receive stage from drops detected at the ROS publish stage. When `frame_timestamp_csv_file` is set, the camera node also records Color and Depth frame timestamp data to a CSV file for frame continuity, publish latency, and timestamp debugging.
 
 ```bash
 ros2 launch orbbec_camera gemini_330_series.launch.py \
-enable_frame_timestamp_csv:=true \
+enable_frame_drop_log:=true \
 frame_timestamp_csv_file:=/tmp/frame_timestamp.csv
 ```
 
-The CSV includes SDK frame index, hardware frame number, sensor timestamp, device/global/system timestamp, arrival timestamp, publish timestamp, inter-frame delta values, and SDK delay fields.
+The CSV includes SDK frame index, hardware frame number, sensor timestamp, device/global/system timestamp, steady arrival/publish delta values, ROS publish latency, and SDK delay fields.
 
 ### Field Description
 
@@ -28,15 +28,8 @@ The current CSV contains two sets of homogeneous fields with the prefixes `color
 | `_global_ts_delta_us` | Delta between adjacent global timestamps | us |
 | `_system_ts_sec` | SDK system timestamp | Seconds |
 | `_system_ts_delta_us` | Delta between adjacent SDK system timestamps | us |
-| `_arrival_system_sec` | System time sampled when the frame arrives at the node | Seconds |
-| `_arrival_system_delta_us` | Delta between adjacent arrival system timestamps | us |
-| `_arrival_steady_sec` | Host steady time sampled when the frame arrives at the node | Seconds |
 | `_arrival_steady_delta_us` | Delta between adjacent arrival steady timestamps | us |
-| `_publish_system_sec` | System time sampled before publishing the image | Seconds |
-| `_publish_system_delta_us` | Delta between adjacent publish system timestamps | us |
-| `_publish_steady_sec` | Host steady time sampled before publishing the image | Seconds |
 | `_publish_steady_delta_us` | Delta between adjacent publish steady timestamps | us |
-| `_arrival_to_publish_system_us` | Time from frame arrival to publish on the ROS side (system) | `publish_system - arrival_system` |
 | `_arrival_to_publish_steady_us` | Time from frame arrival to publish on the ROS side (steady) | `publish_steady - arrival_steady` |
 | `_sdk_delay_from_global_us` | SDK publish delay referenced to global time | `arrival_system - global_ts` |
 | `_sdk_delay_from_system_us` | SDK publish delay referenced to system time | `arrival_system - sdk_system_ts` |
@@ -49,11 +42,11 @@ The current CSV contains two sets of homogeneous fields with the prefixes `color
 - Plot `_sensor_ts_delta_us` as a line chart or scatter plot and look for obvious jumps.
 - For example, at 30 fps, the interval between adjacent frames should usually be close to 33333 us.
 
-#### SDK Frame Drop Detection
+#### SDK / ROS Frame Drop Detection
 
 - Check whether `_sdk_frame_index` is continuous.
 - Plot `_device_ts_delta_us`, `_global_ts_delta_us`, and `_system_ts_delta_us` to see whether any of them show abnormal jumps.
-- If the SDK frame index or the inter-frame deltas from multiple clock sources become abnormal, this can help locate frame loss at the SDK layer.
+- When `enable_frame_drop_log` is enabled, `stage=SDK_RECEIVE` means drops were detected at the SDK receive stage, and `stage=ROS_PUBLISH` means drops were detected at the ROS publish stage.
 
 #### Latency Analysis
 

docs/zh/source/camera_devices/1_overview/introduction.md

@@ -25,7 +25,7 @@ OrbbecSDK ROS2 封装为 Orbbec 相机与 ROS 2 环境提供无缝集成。它
       <td>recommended for new designs</td>
     </tr>
     <tr>
-      <td rowspan="2" style="text-align: center; font-weight: bold;">Gemini 301</td>
+      <td rowspan="3" style="text-align: center; font-weight: bold;">Gemini 301</td>
       <td>Gemini 305</td>
       <td>not supported</td>
       <td>recommended for new designs</td>
@@ -35,6 +35,11 @@ OrbbecSDK ROS2 封装为 Orbbec 相机与 ROS 2 环境提供无缝集成。它
       <td>not supported</td>
       <td>recommended for new designs</td>
     </tr>
+    <tr>
+      <td>Gemini 309g</td>
+      <td>not supported</td>
+      <td>recommended for new designs</td>
+    </tr>
     <tr>
       <td rowspan="8" style="text-align: center; font-weight: bold;">Gemini 330</td>
       <td>Gemini 335</td>
@@ -200,15 +205,20 @@ OrbbecSDK ROS2 封装为 Orbbec 相机与 ROS 2 环境提供无缝集成。它
       <td>gemini435_le.launch.py</td>
     </tr>
     <tr>
-      <td rowspan="2" style="text-align: center; font-weight: bold;">Gemini 301</td>
+      <td rowspan="3" style="text-align: center; font-weight: bold;">Gemini 301</td>
       <td>Gemini 305</td>
       <td><a href="https://doc.orbbec.com/documentation/Gemini%20305%20Documentation/Firmware%20Release%20of%20Gemini%20305">1.0.70</a></td>
-      <td>gemini305.launch.py</td>
+      <td>gemini_301_series.launch.py</td>
     </tr>
     <tr>
       <td>Gemini 305g</td>
       <td><a href="https://doc.orbbec.com/documentation/Gemini%20305%20Documentation/Firmware%20Release%20of%20Gemini%20305">1.0.70</a></td>
-      <td>gemini305_g.launch.py</td>
+      <td>gemini_301_series.launch.py</td>
+    </tr>
+    <tr>
+      <td>Gemini 309g</td>
+      <td>-</td>
+      <td>gemini_301_series.launch.py</td>
     </tr>
     <tr>
       <td rowspan="8" style="text-align: center; font-weight: bold;">Gemini 330</td>
@@ -309,8 +319,9 @@ OrbbecSDK ROS2 封装为 Orbbec 相机与 ROS 2 环境提供无缝集成。它
   </thead>
   <tbody>
     <tr><td style="text-align: center; font-weight: bold;">Gemini 430</td><td>Gemini 435Le</td><td>-</td></tr>
-    <tr><td rowspan="2" style="text-align: center; font-weight: bold;">Gemini 301</td><td>Gemini 305</td><td>-</td></tr>
+    <tr><td rowspan="3" style="text-align: center; font-weight: bold;">Gemini 301</td><td>Gemini 305</td><td>-</td></tr>
     <tr><td>Gemini 305g</td><td>-</td></tr>
+    <tr><td>Gemini 309g</td><td>-</td></tr>
     <tr><td rowspan="8" style="text-align: center; font-weight: bold;">Gemini 330</td><td>Gemini 335</td><td>gemini_335_336.urdf.xacro</td></tr>
     <tr><td>Gemini 336</td><td>gemini_335_336.urdf.xacro</td></tr>
     <tr><td>Gemini 330</td><td>-</td></tr>
@@ -319,7 +330,8 @@ OrbbecSDK ROS2 封装为 Orbbec 相机与 ROS 2 环境提供无缝集成。它
     <tr><td>Gemini 330L</td><td>-</td></tr>
     <tr><td>Gemini 335Lg</td><td>gemini_335_Lg.urdf.xacro</td></tr>
     <tr><td>Gemini 335Le</td><td>gemini_335_Le.urdf.xacro</td></tr>
-    <tr><td style="text-align: center; font-weight: bold;">Gemini 340</td><td>Gemini 345Lg</td><td>gemini_345_Lg.urdf.xacro</td></tr>
+    <tr><td rowspan="2" style="text-align: center; font-weight: bold;">Gemini 340</td><td>Gemini 345</td><td>gemini_345.urdf.xacro</td></tr>
+    <tr><td>Gemini 345Lg</td><td>gemini_345_Lg.urdf.xacro</td></tr>
     <tr><td rowspan="4" style="text-align: center; font-weight: bold;">Gemini 2</td><td>Gemini 2</td><td>gemini_2.urdf.xacro</td></tr>
     <tr><td>Gemini 2 L</td><td>gemini_2_L.urdf.xacro</td></tr>
     <tr><td>Gemini 215</td><td>-</td></tr>

docs/zh/source/camera_devices/4_application_guide/launch_parameters.md

@@ -15,7 +15,7 @@
 *   **`device_num`**
     *   设备数量。如果需要多个相机，必须填写此参数。
 *   **`device_preset`**
-    *   默认值为 `Default`。可以使用下面命令查看可设置模式
+    *   默认值由启动文件决定。可以使用下面命令查看可设置模式；该工具会同时打印 preset 列表和 preset 版本信息。
     ```bash
     ros2 run orbbec_camera list_camera_profile_mode_node
     ```
@@ -177,11 +177,12 @@
   > **支持模组**：Gemini 305。
 * **`enable_false_positive_filter`**
   * 启用鬼影滤波。可减少重影噪声。
-  > **支持模组**： DaBaiA/DaBaiAL/Gemini345/Gemini345Lg.
+  > **支持模组**：DaBaiA / DaBaiAL / Gemini 330 系列 / Gemini345 / Gemini345Lg。
 
 #### 视差
 *   **`disparity_to_depth_mode`**
-    *   `HW`：使用硬件视差到深度转换。`SW`：使用软件视差到深度转换。
+    *   `HW`：使用硬件视差到深度转换。`SW`：使用软件视差到深度转换。也可以设置为 `disable` 关闭。
+    *   该参数大小写不敏感；非法值会报错并回退默认值。
 *   **`disparity_range_mode`**、**`disparity_search_offset`**、**`disparity_offset_config`**
     *   视差搜索偏移参数。用于 [视差搜索偏移](../5_advanced_guide/configuration/disparity_search_offset.md)。
 
@@ -200,11 +201,13 @@
   *   启用深度帧与彩色帧的对齐。当 `enable_colored_point_cloud` 设置为 `true` 时需要此字段。
 - **`align_mode`**
   *   要使用的对齐模式。选项为 `HW`（硬件对齐）和 `SW`（软件对齐）。
+  *   该参数大小写不敏感；非法值会报错并回退默认值。
 - **`align_target_stream`**
   *   设置对齐目标流模式。
   *   可能的值为 `COLOR`、`DEPTH`。
   *   `COLOR`：将深度对齐到彩色。
   *   `DEPTH`：将彩色对齐到深度。
+  *   该参数大小写不敏感。硬件 D2C 仅支持 `COLOR` 作为对齐目标；如需对齐到 `DEPTH`，请使用 `align_mode:=SW`。
 - **`intra_camera_sync_reference`**
   - 设置相机内同步的参考点。适用于Gemini 330系列设备，当 `sync_mode` 设置为**软件**或**硬件触发**模式时。**选项：** `Start`、`Middle`、`End`。设置为空时，长基线设备默认End，短基线设备默认Middle。
 
@@ -229,23 +232,26 @@
     *   启用外参发布。
 *   **`ir_info_url`** / **`color_info_url`**
     *   设置IR/彩色相机信息的URL。
-*   **`enable_color_undistortion`**
+*   **`enable_[color|depth|ir|left_ir|right_ir]_undistortion`**
-    *   启用彩色去畸变。
+    *   启用对应图像流的 SDK 去畸变滤波器。双 IR 设备使用 `enable_left_ir_undistortion` / `enable_right_ir_undistortion`，单 IR 设备使用 `enable_ir_undistortion`。
 
 #### 时间同步
 *   **`enable_sync_host_time`**
     *   启用主机时间与相机时间的同步。默认值为 `true`。如果使用全局时间，设置为 `false`。
 *   **`time_domain`**
     *   选择时间戳类型：`device`、`global` 和 `system`。
+    *   该参数大小写不敏感；非法值会报错并回退默认值。
+*   **`timestamp_clock_type`**
+    *   设置 SDK 时间戳时钟类型。可选值：`realtime`、`monotonic`。默认使用 `realtime`。
 * **`time_sync_period`**
   * 相机时间与主机系统同步的间隔（秒）。
   > **注意**：仅当 **`enable_sync_host_time = true`** 且 **`time_domain = device`** 时需要设置此参数。
 *   **`enable_frame_sync`**
     *   启用帧同步。
-*   **`enable_frame_timestamp_csv`**
+*   **`enable_frame_drop_log`**
-    *   启用帧时间戳CSV记录。主要用于分析彩色/深度帧时间戳、发布延迟和同步问题。
+    *   启用帧丢失日志。日志会分别统计 SDK 接收阶段和 ROS 发布阶段检测到的丢帧。
 *   **`frame_timestamp_csv_file`**
-    *   帧时间戳CSV文件路径。为空时使用默认路径；建议在排查时指定到可写目录。
+    *   帧时间戳 CSV 输出路径。为空时不写 CSV；如需保存 CSV，请指定文件路径，例如 `/tmp/frame_timestamp.csv`。
 
 #### 日志与诊断
 *   **`log_level`**
@@ -263,8 +269,13 @@
 #### 其他
 *   **`config_file_path`**
     *   YAML配置文件的路径。默认为 `""`。如果未指定，将使用启动文件中的默认参数。
+*   **`load_config_json_file_path`**
+    *   SDK JSON 配置导入路径。设置后节点会在初始化时调用 SDK 导入 JSON 配置。Gemini 330 系列可使用 `gemini_330_series_sdk_json.launch.py` 作为专用启动文件。
+*   **`export_config_json_file_path`**
+    *   SDK JSON 配置导出路径。设置后节点会在初始化完成后将当前设备配置导出为 JSON。也可以通过 `/camera/export_config_json` 服务运行时导出。
 *   **`frame_aggregate_mode`**
     *   设置帧聚合输出模式。可选值：`full_frame`、`color_frame`、`ANY`、`disable`。
+    *   该参数大小写不敏感；非法值会报错并回退默认值。
 *   **`enable_d2c_viewer`**
     *   发布D2C叠加图像（仅用于测试）。
 

docs/zh/source/camera_devices/4_application_guide/services.md

@@ -161,6 +161,10 @@
     ```bash
     ros2 service call /camera/get_sdk_version orbbec_camera_msgs/srv/GetString
     ```
+*   `/camera/export_config_json`
+    ```bash
+    ros2 service call /camera/export_config_json orbbec_camera_msgs/srv/SetString "{data: '/tmp/orbbec_camera_config.json'}"
+    ```
 *   `/camera/reboot_device`
     ```bash
     ros2 service call /camera/reboot_device std_srvs/srv/Empty '{}'
@@ -191,7 +195,9 @@
 
 *   `/camera/set_filter`
     ```bash
-    # filter_name 为滤波器名称，filter_enable 表示是否开启滤波器开关，filter_param 表示滤波参数
+    # filter_name 为滤波器名称，filter_enable 表示是否开启滤波器开关。
+    # filter_param 为旧的按位置传参方式；filter_config 为新的命名参数方式。
+    # filter_param 和 filter_config 不能同时使用。
 
     # 设置 DecimationFilter: [scale]
     ros2 service call /camera/set_filter orbbec_camera_msgs/srv/SetFilter '{filter_name: DecimationFilter, filter_enable: false, filter_param: [5]}'
@@ -223,6 +229,11 @@
     # 设置 MgcNoiseRemovalFilter / LutNoiseRemovalFilter: []
     ros2 service call /camera/set_filter orbbec_camera_msgs/srv/SetFilter '{filter_name: MgcNoiseRemovalFilter, filter_enable: true, filter_param: []}'
     ros2 service call /camera/set_filter orbbec_camera_msgs/srv/SetFilter '{filter_name: LutNoiseRemovalFilter, filter_enable: true, filter_param: []}'
+
+    # 使用 filter_config 按参数名调参
+    ros2 service call /camera/set_filter orbbec_camera_msgs/srv/SetFilter "{filter_name: NoiseRemovalFilter, filter_enable: true, filter_config: [{name: min_diff, value: '256'}, {name: max_size, value: '80'}]}"
+    ros2 service call /camera/set_filter orbbec_camera_msgs/srv/SetFilter "{filter_name: HardwareNoiseRemovalFilter, filter_enable: true, filter_config: [{name: threshold, value: '0.2'}]}"
+    ros2 service call /camera/set_filter orbbec_camera_msgs/srv/SetFilter "{filter_name: SpatialAdvancedFilter, filter_enable: true, filter_config: [{name: alpha, value: '0.5'}, {name: disp_diff, value: '160'}, {name: magnitude, value: '1'}, {name: radius, value: '8'}]}"
     ```
 
     滤波状态会在服务调用后同步更新到 `/camera/depth_filter_status` 和 `/camera/depth_filters/status`。其中 `/camera/depth_filters/status` 使用结构化消息 `orbbec_camera_msgs/msg/DepthFiltersStatus`，包含每个滤波器的使能状态和参数。

docs/zh/source/camera_devices/4_application_guide/topics.md

@@ -9,7 +9,9 @@
 这些话题提供每个启用的相机数据流的原始图像数据和相应的校准信息。对于 `color`、`depth`、`ir`、`left_ir` 和 `right_ir` 数据流，模式是一致的。
 
 *   `/camera/color/image_raw`
-    *   彩色流的原始图像数据。
+    *   彩色流的原始图像数据。彩色格式为 RGB/YUYV 等非 MJPG 时，通常订阅该话题。
+*   `/camera/color/image_raw/compressed`
+    *   来自 MJPG 彩色流的压缩图像数据。使用 `color_format:=MJPG` 时建议订阅该话题，以避免 ROS wrapper 侧额外解码并降低 CPU 占用。
 *   `/camera/color/camera_info`
     *   彩色流的相机校准数据和元数据。
 *   `/camera/color/metadata`

docs/zh/source/camera_devices/5_advanced_guide/configuration/firmware_update_tool.md

@@ -32,3 +32,12 @@ ros2 run orbbec_camera firmware_update_tool -- \
 --firmware_path /path/to/firmware.bin \
 --continue_on_error
 ```
+
+如需开启 SDK 文件日志并同时尝试开启固件日志，可增加 `--sdk_log_level`。可选值为 `debug`、`info`、`warn`、`error`、`fatal`、`off`，默认 `off`。
+
+```bash
+ros2 run orbbec_camera firmware_update_tool -- \
+--serial_number <SN> \
+--preset_path /path/to/preset.bin \
+--sdk_log_level debug
+```

docs/zh/source/camera_devices/5_advanced_guide/configuration/net_camera.md

@@ -44,13 +44,19 @@ ros2 launch orbbec_camera femto_mega.launch.py enumerate_net_device:=false net_d
 ros2 launch orbbec_camera multi_net_camera.launch.py
 ```
 
-可以使用 `list_devices_node` 查看当前连接设备。v2.8.x 之后，该工具会额外输出固件版本、网口设备本地网卡名和 IP 来源类型（`NONE`、`LLA`、`DHCP`、`PERSISTENT`）。
+可以使用 `list_devices_node` 查看当前连接设备。v2.8.x 之后，该工具会额外输出固件版本、preset 列表、preset 版本、网口设备本地网卡名和 IP 来源类型（`NONE`、`LLA`、`DHCP`、`PERSISTENT`）。当某个设备枚举失败时，工具会继续枚举其他设备。
+
+如需开启 SDK 和固件日志，可添加 `--sdk_log_level debug`：
+
+```bash
+ros2 run orbbec_camera list_devices_node -- --sdk_log_level debug
+```
 
 ## ip_config_tool 工具
 
 **`ip_config_tool`** 可执行文件允许您直接从 ROS 2 配置网络相机的 IP 设置，包括 DHCP、静态 IP、Force IP 和 DHCP 分配 IP 超时时间。这对于快速分配或更新 IP 地址而无需修改启动文件非常有用。
 
-> **注意：** 通过 `dhcp` 或 `set_ip` 应用的配置会写入设备。`force_ip` 是临时强制 IP，设备断电或重启后需要重新应用。
+> **注意：** 通过 `set_ip` 应用的 DHCP / persistent IP 配置会写入设备。`force_ip` 是临时强制 IP，设备断电或重启后需要重新应用。
 > **兼容说明**：`set_device_ip` 仍作为兼容别名保留，实际调用 `ip_config_tool`。旧参数 `old_ip` 已更名为 `current_ip`。
 
 **示例用法**
@@ -65,17 +71,33 @@ ros2 run orbbec_camera ip_config_tool -- --help
 
 ```bash
 ros2 run orbbec_camera ip_config_tool -- \
-dhcp \
+set_ip \
 --current_ip 192.168.1.10 \
---enable_dhcp true
+--enable_dhcp true \
+--enable_persistent_ip false
 ```
 
-关闭 DHCP 并设置静态 IP：
+关闭 DHCP 并设置 persistent IP：
 
 ```bash
 ros2 run orbbec_camera ip_config_tool -- \
 set_ip \
 --current_ip 192.168.1.10 \
+--enable_dhcp false \
+--enable_persistent_ip true \
+--new_ip 192.168.1.11 \
+--mask 255.255.255.0 \
+--gateway 192.168.1.1
+```
+
+同时开启 DHCP 和 persistent IP（仅支持 IP 配置 V2 的设备/固件）：
+
+```bash
+ros2 run orbbec_camera ip_config_tool -- \
+set_ip \
+--current_ip 192.168.1.10 \
+--enable_dhcp true \
+--enable_persistent_ip true \
 --new_ip 192.168.1.11 \
 --mask 255.255.255.0 \
 --gateway 192.168.1.1
@@ -104,12 +126,14 @@ set_dhcp_timeout \
 **参数**
 
 - **`current_ip`** – 设备的当前 IP 地址。
-- **`enable_dhcp`** – 在 `dhcp` 或 `force_ip` 子命令中设置是否启用 DHCP。
+- **`enable_dhcp`** – 在 `set_ip` 或 `force_ip` 子命令中设置是否启用 DHCP。
-- **`new_ip`** – 要分配的静态 IP 地址。
+- **`enable_persistent_ip`** – 在 `set_ip` 子命令中设置是否启用 persistent IP。
+- **`new_ip`** – 要分配的 persistent IP 或 Force IP 地址。
 - **`mask`** – 新 IP 的子网掩码。
 - **`gateway`** – 新 IP 的网关地址。
 - **`force_ip_mac`** – Force IP 目标设备 MAC 地址。
 - **`timeout`** / **`dhcp_assign_ip_timeout`** – DHCP 分配 IP 超时时间，单位为秒。
+- **`sdk_log_level`** – SDK 文件日志级别，可选值：`debug`、`info`、`warn`、`error`、`fatal`、`off`。非 `off` 时会同时尝试开启固件日志。
 
 > **版本说明**：`LLA` 开关仅 Gemini 335Le 固件 `1.7.05` 及以上、Gemini 435Le 固件 `1.3.17` 及以上支持。
 

docs/zh/source/camera_devices/5_advanced_guide/performance/lower_cpu_usage.md

@@ -14,6 +14,14 @@
 | `color_format` |                `RGB`                |         CPU使用率低于 `MJPG`         |
 |    `filter`    | 仅使用 `hardware_noise_removal_filter` | 其他滤波器会显著增加CPU使用率 |
 
+### 彩色流格式与订阅方式
+
+v2.8.8 优化了彩色流图像发布流程：
+
+- 当 `color_format` 为 RGB/YUYV 等非 MJPG 格式时，订阅 `/camera/color/image_raw`。
+- 当 `color_format:=MJPG` 时，建议订阅 `/camera/color/image_raw/compressed`。ROS wrapper 会直接发布压缩图像，避免额外解码，从而显著降低 MJPG 场景下的 CPU 占用。
+- 如果订阅 `/camera/color/image_raw`，MJPG 仍需要在主机侧解码，CPU 占用会更高。
+
 ### 用于测试的启动文件
 
 * `gemini_330_series_lower_cpu_usage.launch.py`

docs/zh/source/camera_devices/6_benchmark/othertools.md

@@ -1,16 +1,16 @@
 # 其他工具
 
-## 帧时间戳 CSV 记录
+## 帧丢失日志与时间戳 CSV 记录
 
-开启 `enable_frame_timestamp_csv` 后，相机节点会记录彩色和深度帧的时间戳数据到 CSV 文件，用于分析帧同步、发布延迟和时间戳异常。
+开启 `enable_frame_drop_log` 后，相机节点会在日志中输出彩色和深度帧丢失统计，用于定位 SDK 接收阶段和 ROS 发布阶段的丢帧。设置 `frame_timestamp_csv_file` 后，相机节点会额外记录彩色和深度帧的时间戳数据到 CSV 文件，用于分析帧连续性、发布延迟和时间戳异常。
 
 ```bash
 ros2 launch orbbec_camera gemini_330_series.launch.py \
-enable_frame_timestamp_csv:=true \
+enable_frame_drop_log:=true \
 frame_timestamp_csv_file:=/tmp/frame_timestamp.csv
 ```
 
-CSV 中包含 SDK frame index、hardware frame number、sensor timestamp、device/global/system timestamp、arrival timestamp、publish timestamp、相邻帧 delta 以及 SDK delay 等字段。
+CSV 中包含 SDK frame index、hardware frame number、sensor timestamp、device/global/system timestamp、steady arrival/publish delta、ROS 发布耗时以及 SDK delay 等字段。
 
 ### 字段说明
 
@@ -28,15 +28,8 @@ CSV 中包含 SDK frame index、hardware frame number、sensor timestamp、devic
 | `_global_ts_delta_us` | global 时间戳相邻帧差值 | us |
 | `_system_ts_sec` | SDK 的 system 时间戳 | 秒 |
 | `_system_ts_delta_us` | SDK system 时间戳相邻帧差值 | us |
-| `_arrival_system_sec` | 帧到达节点时采样的系统时间 | 秒 |
-| `_arrival_system_delta_us` | 到达系统时间相邻帧差值 | us |
-| `_arrival_steady_sec` | 帧到达节点时采样的主机 steady 时间 | 秒 |
 | `_arrival_steady_delta_us` | 到达主机 steady 时间相邻帧差值 | us |
-| `_publish_system_sec` | 发布图像前采样的系统时间 | 秒 |
-| `_publish_system_delta_us` | 发布前系统时间相邻帧差值 | us |
-| `_publish_steady_sec` | 发布图像前采样的主机 steady 时间 | 秒 |
 | `_publish_steady_delta_us` | 发布前主机 steady 时间相邻帧差值 | us |
-| `_arrival_to_publish_system_us` | ROS 收到帧到发布的耗时（system） | `publish_system - arrival_system` |
 | `_arrival_to_publish_steady_us` | ROS 收到帧到发布的耗时（steady） | `publish_steady - arrival_steady` |
 | `_sdk_delay_from_global_us` | SDK 发布延迟（global 参照） | `arrival_system - global_ts` |
 | `_sdk_delay_from_system_us` | SDK 发布延迟（system 参照） | `arrival_system - sdk_system_ts` |
@@ -49,11 +42,11 @@ CSV 中包含 SDK frame index、hardware frame number、sensor timestamp、devic
 - 查看 `_sensor_ts_delta_us` 的折线图或散点图，观察是否存在明显跳变。
 - 例如在 30 fps 下，相邻帧时间差通常应接近 33333 us。
 
-#### SDK 丢帧判断
+#### SDK/ROS 丢帧判断
 
 - 查看 `_sdk_frame_index` 是否连续。
 - 查看 `_device_ts_delta_us`、`_global_ts_delta_us` 和 `_system_ts_delta_us` 的折线图或散点图，观察是否存在跳变。
-- 如果 SDK 帧序号或多种时钟源的相邻帧差值出现异常，可进一步定位 SDK 层是否有丢帧。
+- 开启 `enable_frame_drop_log` 后，日志中的 `stage=SDK_RECEIVE` 表示 SDK 接收阶段检测到丢帧，`stage=ROS_PUBLISH` 表示 ROS 发布阶段检测到丢帧。
 
 #### 延迟判断