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

2026-09-13 03:30:18 +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
 ```
+
+#### Record and play back with SDK bag
+
+SDK bag recording uses the Orbbec SDK to record device data. It is useful when you want to restart the wrapper later with the recording as a playback device. Record when launching:
+
+```bash
+ros2 launch orbbec_camera gemini_330_series.launch.py bag_record_filename:=/tmp/orbbec_record.bag
+```
+
+You can also start or stop recording while the node is running:
+
+```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: ''}"
+```
+
+Play back an SDK bag:
+
+```bash
+ros2 launch orbbec_camera gemini_330_series.launch.py bag_filename:=/tmp/orbbec_record.bag
+```
+
+Loop playback:
+
+```bash
+ros2 launch orbbec_camera gemini_330_series.launch.py bag_filename:=/tmp/orbbec_record.bag bag_loop:=true
+```
@@ -88,6 +88,12 @@ The following are the launch parameters available:
  * Enable Right IR image transport plugins. Default: `["image_transport/compressed", "image_transport/raw", "image_transport/theora"]`. See [Compressed Image](compressed_image.md) for subscribing to compressed images.
 * **`point_cloud_decimation_filter_factor`**
  * Point cloud downsampling factor. Range: `1–8`. `1` means no downsampling.
+* **`bag_record_filename`**
+  * Record device data to the specified SDK `.bag` file after startup. Leave empty to disable automatic recording. When recording starts, a JSON preset file with the same base name is also exported, for example `record.bag` creates `record.json`.
+* **`bag_filename`**
+  * Play back the specified SDK `.bag` file. When set, the node creates a playback device from the bag file instead of connecting to a physical camera.
+* **`bag_loop`**
+  * Loop SDK bag playback after the file reaches the end. Default: `false`. This only takes effect when `bag_filename` is set.

 ## Sensor Controls

@@ -175,6 +181,9 @@ The following are the launch parameters available:
    *   Enable the software trigger out signal / set the software trigger period in ms.
 *   **`frames_per_trigger`**
    *   The frame number of each stream after each trigger in triggering mode.
+*   **`sync_io_voltage_level`**
+    *   Set the sync IO voltage level. Default: `-1`, which means do not set it. This is only supported on devices that expose the property; it can also be changed at runtime with `/camera/set_sync_io_voltage_level`.
+    > **Supported Modules**: Gemini 305 series.

 ### Network Cameras
 * **`enumerate_net_device`**
@@ -310,8 +319,10 @@ The following are the launch parameters available:
    *   The path to the YAML configuration file. Default is `""`. If not specified, default parameters from the launch file will be used. Some presets or special modes are configured through YAML. See [predefined presets](../5_advanced_guide/configuration/predefined_presets.md).
 *   **`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.
+    *   If the JSON contains `application_config`, the node syncs stream enable states, resolution, frame rate, format, undistortion, point cloud, HDR merge, and device-level decimation from it when those values are not explicitly overridden by launch parameters.
 *   **`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.
+    *   Before export, the node syncs the current ROS sensor stream, point cloud, and HDR merge settings into the SDK `application_config` when the device supports it.
 *   **`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.
@@ -157,6 +157,11 @@
    ```bash
    ros2 service call /camera/get_device_info orbbec_camera_msgs/srv/GetDeviceInfo
    ```
+*   `/camera/get_device_config`
+    Get the currently effective device configuration state, such as preset, alignment mode, time domain, sync mode, and frame aggregate mode.
+    ```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`
+    Record current device data with SDK bag recording. `enable: true` starts recording and `enable: false` stops recording. When `file_path` is empty, the default file name is created in the current working directory.
+    ```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 @@
    # Only available if interleave_ae_mode is 'laser' and interleave_frame_enable is true
    ros2 service call /camera/set_sync_interleaverlaser orbbec_camera_msgs/srv/SetInt32 '{data: 0}'
    ```
+*   `/camera/set_sync_io_voltage_level`
+    Set the sync IO voltage level. This is only supported on devices that expose the property.
+    ```bash
+    ros2 service call /camera/set_sync_io_voltage_level orbbec_camera_msgs/srv/SetInt32 '{data: 0}'
+    ```

 ### Depth Filter Configuration

@@ -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}'
+    ```

 ### 深度滤波器配置