Version

8. Frequently Asked Questions

8.1. Unexpected Crash

If the camera node crashes unexpectedly, it will generate a crash log under ~/.ros/Log/<camera_name>/, with a file name similar to camera_name_crash_stack_trace_xx.log. Please send this log to the support team or submit it to a GitHub issue for further assistance.

8.2. No Data Stream from Multiple Cameras

Insufficient Power Supply:

Ensure that each camera is connected to a separate hub.
Use a powered hub to provide sufficient power to each camera.

High Resolution:

Try lowering the resolution to resolve data stream issues.

Increase usbfs_memory_mb Value:

Increase the usbfs_memory_mb value to 128MB (this is a reference value and can be adjusted based on your system’s needs) by running the following command:

    echo 128 | sudo tee /sys/module/usbcore/parameters/usbfs_memory_mb

To make this change permanent, check this link.

8.3. How to Collect and Save Logs

1. SDK debug logs

Set the launch parameter log_level to debug. After running, the SDK will generate log files under ~/.ros/Log/<camera_name>/. If you want a more recognizable file name for this test, you can set the parameter log_file_name.

The actual SDK log file path is usually ~/.ros/Log/<camera_name>/<log_file_name>.
In multi-camera setups, SDK logs are separated by camera_name, for example ~/.ros/Log/camera_01/camera_01.log and ~/.ros/Log/camera_02/camera_02.log.
SDK logs are appended to the same file: multiple launches will continue writing into the same log file.
Recommendation: before packaging logs to send to technical support, delete old log files, then reproduce the issue and collect new logs. This keeps the logs cleaner and makes troubleshooting more accurate.

2. ROS 2 logs (~/.ros/log)

In the launch file, set the node (or composable node container) parameter output to "log" to save ROS 2 logs locally.

After setting output="log", ROS 2 logs will be stored in the ~/.ros/log/ directory.
Each ros2 launch run creates a timestamped directory under ~/.ros/log/ containing launch.log, and also generates process log files such as component_container_<pid>_<timestamp>.log.
The difference is:
- launch.log contains the merged output from all camera containers.
- component_container_<pid>_<timestamp>.log records the runtime output of a specific container process.
In multi-camera setups, component_container_<pid>_<timestamp>.log is separated by container process.
In one-camera-per-container multi-camera launches, you can treat it as “one camera corresponds to one component_container_*.log”. If multiple cameras are loaded into the same container, that component_container_*.log will also contain logs from multiple cameras.
To identify the exact camera, rely on the namespace or node name in the log content, for example camera_01.camera_01 and camera_02.camera_02.
When submitting an issue, please package both the SDK logs under ~/.ros/Log/ and the corresponding ROS 2 logs under ~/.ros/log/ for the same time period.

8.4. Why Are There So Many Launch Files?

Different cameras have varying default resolutions and image formats.
To simplify usage, each camera has its own launch file.

8.5. How to Launch a Specific Camera When Multiple Cameras Are Connected

While the launch file did not explicitly specify which device to use. In that case, the driver will connect to the default device.

You can check the serial number of your device by running:

ros2 run orbbec_camera list_devices_node

Then launch with the serial number explicitly set, for example:

ros2 launch orbbec_camera femto_bolt.launch.py serial_number:=CL8H741005J

8.6. Why Is It Necessary to Add Delays When Starting Multiple Cameras or Switching Streams?

Multi-camera systems place high demands on USB bandwidth and device initialization timing. If multiple camera streams are started or switched simultaneously, it may cause temporary bandwidth congestion, leading to device initialization failures, stream startup errors, or frame drops. To ensure system stability, the following practices are recommended:

Multi-camera startup phase

When starting multiple cameras, it is recommended to introduce an appropriate delay between each camera startup (e.g., 2 seconds) to avoid instantaneous bandwidth overload or low-level device initialization conflicts.
Stream enable/disable and mode switching phase

When invoking stream control services (such as set_streams_enable, toggle_depth, and toggle_color), avoid triggering multiple service calls at the same time. Instead, introduce a reasonable interval between operations (e.g., 20 ms) to ensure reliable stream state transitions.

Following these timing control guidelines can significantly improve the stability of multi-camera systems during startup and runtime, reducing errors and unexpected behavior.

8.7. femto bolt depth stream no data

This module depends on the OpenGL library at runtime. If OpenGL is not installed or the graphics driver is incomplete, the depth stream may output no data. Please make sure to install the necessary OpenGL libraries first (Ubuntu example below):

  sudo apt update && sudo apt install -y mesa-utils libgl1-mesa-glx libglu1-mesa

After installation, you can check whether OpenGL is available through the following command:

  glxinfo -B

8.8. The image does not reach the preset frame rate

First you need to confirm whether the image does not reach the preset frame rate. There are several ways to view framerate in ROS 2, such as:

ros2 topic hz
rqt
Custom tools (such as the benchmark tool provided by this ROS package)

It should be noted that different tools have different statistical methods and QoS configurations, so the frame rate results obtained may be different. When you find that the frame rate is lower than expected, please prioritize whether the error is caused by the frame rate statistics tool itself.

If you confirm that the image frame rate does not reach the preset value, you can try the following troubleshooting steps:

Reduce the resolution or frame rate to determine whether the frame rate is reduced due to USB/network bandwidth limitations;
Confirm whether the camera firmware version and ROS package version are the latest. Older versions may have performance or compatibility issues.

If the above methods still cannot solve the problem, please contact our company FAE, or submit an issue in GitHub Issue for further support.