Multi-Device Synchronization Example

Demonstrates multi-device synchronization. This sample supports network devices, USB devices, and GMSL devices.

• The primary purpose of this repository is to demonstrate the multi-device synchronization functionality of different types of Orbbec devices, including detailed instructions for hardware connections and software configuration.
• The v2-main branch is based on the multi device sync sample and gmsl trigger sample provided by Orbbec SDK v2. If there are any updates or changes to the samples in Orbbec SDK v2, please refer to the official implementation in Orbbec SDK v2 as the authoritative version.
• The legacy main branch is based on Orbbec SDK v1 and only demonstrates multi-device synchronization for Femto Mega.

This project builds two standalone executables:

• Notes: GMSL devices require two applications: MultiDeviceSync and MultiDeviceSyncGmslTrigger. The MultiDeviceSyncGmslTrigger application is responsible for sending trigger signals, while USB and Ethernet devices only require the MultiDeviceSync application.

cd Multi-Device-Synchronization-Example
mkdir build && cd build
cmake ..
cmake --build . --config Release

Build artifacts are in the build/bin/ directory:

• Windows: MultiDeviceSync.exe
• Linux: MultiDeviceSync, MultiDeviceSyncGmslTrigger

The program reads ./MultiDeviceSyncConfig.json from the current working directory by default. Device serial numbers can be found using the OrbbecViewer tool or in the program log after connecting devices.

The following example includes all optional fields; use as needed based on your device series:

{
    "version": "1.0.1",
    "configTime": "2026/05/07",
    "devices": [
        {
            "sn": "CP123456789",
            "syncConfig": {
                "syncMode": "OB_MULTI_DEVICE_SYNC_MODE_PRIMARY",
                "depthDelayUs": 0,
                "colorDelayUs": 0,
                "trigger2ImageDelayUs": 0,
                "triggerOutEnable": true,
                "triggerOutDelayUs": 0,
                "framesPerTrigger": 1
            }
        }
    ]
}

Field descriptions:

syncMode available values:

./MultiDeviceSync

• Enter 0: Configure device sync mode and start streaming
• Enter 1: Start streaming directly (use when devices are already configured)

Keyboard shortcuts:

Run without the OpenCV preview window, suitable for remote sessions (SSH) or headless servers:

./MultiDeviceSync --headless

• Timestamp recording and sync monitor output run exactly as in normal mode
• No preview window is created
• Press Ctrl+C to stop: the program catches SIGINT, flushes all CSV data, and shuts down streams before exiting

For GMSL2 connections to NVIDIA Jetson platforms. Devices must be configured as HARDWARE_TRIGGERING mode.

./MultiDeviceSyncGmslTrigger

• Enter 0: Set trigger frequency (FPS)
• Enter 1: Start PWM trigger signal
• Enter 2: Stop PWM trigger signal
• Enter 3: Exit

During streaming, each device and each sensor (depth/color) records its own timestamp CSV file under ./output/:

output/
  sync_depth_dev0_<SN>.csv
  sync_color_dev0_<SN>.csv
  sync_depth_dev1_<SN>.csv
  sync_color_dev1_<SN>.csv
  ...

Each file contains one row per captured frame:

Note: Some devices do not provide a global timestamp (global_ts_us is all 0) or a hardware frame number (hw_frame_num is -1). This is normal and expected.

A standalone Python script evaluates multi-device synchronization accuracy from the recorded CSV files:

• Script: scripts/analyze_sync.py
• No third-party dependencies (Python standard library only)

Run it from the directory containing the CSV files (typically output/):

cd build/bin/output
python analyze_sync.py

Or analyze any folder:

python analyze_sync.py /path/to/csv_dir [options]

Options:

Time base selection:

• global (recommended): uses global_ts_us, all devices share the host clock domain.
• device: uses device_ts_us, for devices that do not support a global timestamp.
• auto: uses global when valid; otherwise degrades to device.

Output:

1. Femto series and Gemini 2 series sync configurations are written to Flash and persist after power-off; frequent configuration will reduce Flash lifespan. Gemini 305 and Gemini 330 sync configurations do not persist after power-off and must be reconfigured each time the device is powered on.
2. MultiDeviceSyncGmslTrigger only provides PWM trigger signal source and does not include data stream acquisition or preview functionality.
3. When exiting MultiDeviceSyncGmslTrigger, select 3 to ensure the /dev/camsync device is properly closed.

Multi-Device-Synchronization-Example/
|-- CMakeLists.txt                              # Build configuration
|-- MultiDeviceSync/                            # Standard USB/Ethernet multi-device sync
|   `-- MultiDeviceSync.cpp                     #   Main program
|-- MultiDeviceSyncGmslTrigger/                 # GMSL PWM hardware trigger
|   `-- MultiDeviceSyncGmslTrigger.cpp          #   Main program
|-- common/                                     # Shared core modules
|   |-- PipelineHolder.hpp/cpp                  #   Per-device pipeline wrapper
|   |-- FramePairingManager.hpp/cpp             #   Per-device per-sensor timestamp CSV logging
|   `-- utils/                                  #   Utility library
|       |-- cJSON.c/h                           #     JSON parser
|       |-- utils.cpp/hpp                       #     Basic utility functions
|       |-- utils_c.c/h                         #     C utility functions
|       |-- utils_opencv.cpp/hpp                #     OpenCV visualization windows
|       `-- utils_types.h                       #     Common type definitions
|-- scripts/                                    # Sync accuracy analyzer
|   `-- analyze_sync.py                         #   Standalone, no third-party dependencies
|-- config/
|   |-- OrbbecSDKConfig.xml                     # SDK device configuration
|   `-- MultiDeviceSyncConfig.json              # Current sync configuration
|-- docs/                                       # Per-series documentation
|   |-- Astra2.md
|   |-- FemtoSeries.md
|   |-- Gemini2Series.md
|   |-- Gemini301Series.md
|   |-- Gemini330Series.md
|   `-- Gemini435Le.md
|-- res/                                        # Documentation image resources
`-- 3rdparty/orbbecsdk/                         # OrbbecSDK
    |-- win_x64/
    |-- linux_x86_64/
    `-- linux_arm64/