docs: add SDK bag recording and playback instructions to quickstart and services documentation

2026-10-04 03:57:46 +08:00 · 2026-06-22 15:03:55 +08:00
parent e61cc482a5
commit 7ac59879ae
6 changed files with 118 additions and 0 deletions
@@ -94,3 +94,33 @@ ros2 service call /camera/get_device_info orbbec_camera_msgs/srv/GetDeviceInfo '
 ```bash
 ros2 bag record /camera/color/image_raw /camera/depth/image_raw
 ```
+
+#### 使用 SDK bag 录制和回放
+
+SDK bag 会通过 Orbbec SDK 录制设备数据，适合后续用 wrapper 作为回放设备重新启动。启动时录制：
+
+```bash
+ros2 launch orbbec_camera gemini_330_series.launch.py bag_record_filename:=/tmp/orbbec_record.bag
+```
+
+也可以在节点运行时通过服务开始或停止录制：
+
+```bash
+ros2 service call /camera/set_bag_recording orbbec_camera_msgs/srv/SetBagRecording "{enable: true, file_path: '/tmp/orbbec_record.bag'}"
+```
+
+```bash
+ros2 service call /camera/set_bag_recording orbbec_camera_msgs/srv/SetBagRecording "{enable: false, file_path: ''}"
+```
+
+回放 SDK bag：
+
+```bash
+ros2 launch orbbec_camera gemini_330_series.launch.py bag_filename:=/tmp/orbbec_record.bag
+```
+
+如果需要循环回放：
+
+```bash
+ros2 launch orbbec_camera gemini_330_series.launch.py bag_filename:=/tmp/orbbec_record.bag bag_loop:=true
+```
@@ -88,6 +88,12 @@
  * 启用右红外图像传输插件。默认值：`["image_transport/compressed", "image_transport/raw", "image_transport/theora"]`。压缩图像订阅方法参考 [压缩图像](compressed_image.md)。
 * **`point_cloud_decimation_filter_factor`**
  * 点云下采样因子。范围：`1–8`，`1`表示不下采样，数值越大下采样倍数越大。
+* **`bag_record_filename`**
+  * 启动后使用 SDK 录制设备数据到指定 `.bag` 文件。为空时不自动录制。开始录制时会同时导出同名 JSON preset 文件，例如 `record.bag` 对应 `record.json`。
+* **`bag_filename`**
+  * 使用 SDK 回放指定 `.bag` 文件。设置后节点从 bag 文件创建回放设备，而不是连接真实相机。
+* **`bag_loop`**
+  * SDK bag 回放结束后是否循环播放。默认值：`false`。仅在设置 `bag_filename` 时生效。

 ## 传感器控制

@@ -176,6 +182,9 @@
    *   启用软件触发输出信号 / 设置软件触发周期（毫秒）。
 *   **`frames_per_trigger`**
    *   触发模式下每次触发后每个流的帧数。
+*   **`sync_io_voltage_level`**
+    *   设置同步 IO 电压等级。默认值为 `-1`，表示不设置。仅支持具备该属性的设备；可通过 `/camera/set_sync_io_voltage_level` 服务在运行时修改。
+    > **支持模组**：Gemini 305 系列。

 ### 网络相机
 * **`enumerate_net_device`**
@@ -309,8 +318,10 @@
    *   YAML配置文件的路径。默认为 `""`。如果未指定，将使用启动文件中的默认参数。部分 preset 或特殊模式会通过 YAML 配置，示例参考 [设备预设](../5_advanced_guide/configuration/predefined_presets.md)。
 *   **`load_config_json_file_path`**
    *   SDK JSON 配置导入路径。设置后节点会在初始化时调用 SDK 导入 JSON 配置。Gemini 330 系列可使用 `gemini_330_series_sdk_json.launch.py` 作为专用启动文件。
+    *   如果 JSON 中包含 `application_config`，节点会在未被 launch 参数显式覆盖时同步其中的流开关、分辨率、帧率、格式、去畸变、点云、HDR 合并和设备级下采样配置。
 *   **`export_config_json_file_path`**
    *   SDK JSON 配置导出路径。设置后节点会在初始化完成后将当前设备配置导出为 JSON。也可以通过 `/camera/export_config_json` 服务运行时导出。
+    *   导出前会把当前 ROS 参数中的传感器流、点云和 HDR 合并配置同步到 SDK `application_config`（设备支持时）。
 *   **`frame_aggregate_mode`**
    *   设置帧聚合输出模式。可选值：`full_frame`、`color_frame`、`ANY`、`disable`。
    *   该参数大小写不敏感；非法值会报错并回退默认值。
@@ -157,6 +157,11 @@
    ```bash
    ros2 service call /camera/get_device_info orbbec_camera_msgs/srv/GetDeviceInfo
    ```
+*   `/camera/get_device_config`
+    获取当前生效的设备配置状态，例如 preset、对齐模式、时间域、同步模式、帧聚合模式等。
+    ```bash
+    ros2 service call /camera/get_device_config orbbec_camera_msgs/srv/GetDeviceConfig '{}'
+    ```
 *   `/camera/get_sdk_version`
    ```bash
    ros2 service call /camera/get_sdk_version orbbec_camera_msgs/srv/GetString
@@ -165,6 +170,14 @@
    ```bash
    ros2 service call /camera/export_config_json orbbec_camera_msgs/srv/SetString "{data: '/tmp/orbbec_camera_config.json'}"
    ```
+*   `/camera/set_bag_recording`
+    使用 SDK bag 录制当前设备数据。`enable: true` 开始录制，`enable: false` 停止录制；`file_path` 为空时使用当前工作目录下的默认文件名。
+    ```bash
+    ros2 service call /camera/set_bag_recording orbbec_camera_msgs/srv/SetBagRecording "{enable: true, file_path: '/tmp/orbbec_record.bag'}"
+    ```
+    ```bash
+    ros2 service call /camera/set_bag_recording orbbec_camera_msgs/srv/SetBagRecording "{enable: false, file_path: ''}"
+    ```
 *   `/camera/reboot_device`
    ```bash
    ros2 service call /camera/reboot_device std_srvs/srv/Empty '{}'
@@ -190,6 +203,11 @@
    # 仅在interleave_ae_mode为'laser'且interleave_frame_enable为true时可用
    ros2 service call /camera/set_sync_interleaverlaser orbbec_camera_msgs/srv/SetInt32 '{data: 0}'
    ```
+*   `/camera/set_sync_io_voltage_level`
+    设置同步 IO 电压等级。仅支持具备该属性的设备。
+    ```bash
+    ros2 service call /camera/set_sync_io_voltage_level orbbec_camera_msgs/srv/SetInt32 '{data: 0}'
+    ```

 ### 深度滤波器配置