docs: update the documentation to version 2.8.8

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`**
-    *   启用帧时间戳CSV记录。主要用于分析彩色/深度帧时间戳、发布延迟和同步问题。
+*   **`enable_frame_drop_log`**
+    *   启用帧丢失日志。日志会分别统计 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。
-- **`new_ip`** – 要分配的静态 IP 地址。
+- **`enable_dhcp`** – 在 `set_ip` 或 `force_ip` 子命令中设置是否启用 DHCP。
+- **`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 发布阶段检测到丢帧。
 
 #### 延迟判断