04 External Trigger Tutorial

Learn how to build a C++ application that tests external trigger synchronization across multiple Sol3 camera modules.

Warning

Only IMX565 modules (color and mono) support external trigger at this time.

Prerequisites

Overview

This tutorial shows how to build and deploy an external trigger sync tester that runs on Sol3 hardware. The application subscribes to YUV frame streams from multiple cameras and groups frames by trigger event to evaluate timestamp synchronization.

Warning

External trigger support is experimental. Current limitations:

  • Only periodic capture mode is supported. Arbitrary one-off (“still-capture”) triggers are not yet implemented.

  • The client must send a CameraControl capture request no more than 1 second before the external trigger signal arrives. Requests sent earlier will be discarded.

Tutorial Code

The SDK includes a complete external trigger tutorial at:

sol3-sdk/apps/tutorials/04_external_trigger.cpp

Note

This tutorial requires Sol3 hardware (external trigger GPIO and the YUV stream). The x64 mock camera server (see tutorial 01) serves only a single RAW10 camera and cannot exercise this flow.

How It Works

The external trigger application supports two modes of operation:

Passive Mode (Default)

Listens for frames triggered by an external hardware trigger signal.

The client:

  1. Connects to the resized YUV frame shared memory endpoint for each camera

  2. When the first frame of a new trigger event arrives, opens a collection window

  3. Collects frames from all cameras until all report in or the window expires (50 ms)

  4. Evaluates timestamp spread across cameras against a sync threshold (1000 us)

  5. Logs sync/no-sync/timeout status with detailed per-camera timing

  6. Periodically saves synchronized frame groups as JPEG images to /tmp/trigger_test

Active Mode

Generates hardware trigger pulses via GPIO and sends CameraControl requests ahead of each pulse.

The client:

  1. Configures a GPIO output pin for trigger pulse generation

  2. Creates CameraControl message outputs for each camera

  3. Runs a dedicated thread that, at the configured rate:

    • Sends CameraControl requests slightly before each pulse (1 ms ahead)

    • Generates an active-low trigger pulse on the GPIO pin

    • Busy-waits for the configured exposure duration to minimize jitter

  4. Collects and evaluates frames using the same sync monitor as passive mode

Build and Deploy

Step 1: Build Application Image

Build the ARM64 container image for Sol3:

sol3_build_app_image tutorial_04_external_trigger arm64 --cmake-preset arm64 --tag latest

Step 2: Deploy to Sol3 Device

Deploy the image to your Sol3 device:

sol3_deploy_app_image tutorial-04-external-trigger-arm64:latest <USER@HDK_IP>

Step 3: Run on Sol3 Device

SSH to the Sol3 device and run the application. Press Ctrl+C to stop and print a summary.

# SSH to device
ssh <USER@HDK_IP>

# Run the external trigger tester
docker run --rm \
  -v /run/sol3:/run/sol3 \
  -v /dev:/dev \
  -v /tmp/trigger_test:/tmp/trigger_test \
  --privileged \
  localhost:5000/tutorial-04-external-trigger-arm64:latest <ARGS>

Usage Examples

All commands below run on the Sol3 device after SSH connection.

For brevity, the commands below use <EXT-TRIGGER-CMD> to represent:

docker run --rm \
  -v /run/sol3:/run/sol3 \
  -v /dev:/dev \
  -v /tmp/trigger_test:/tmp/trigger_test \
  --privileged \
  localhost:5000/tutorial-04-external-trigger-arm64:latest <ARGS>

Passive Mode with Two Cameras

Listen for externally triggered frames on cameras 1 and 3:

<EXT-TRIGGER-CMD> --camid 1 --camid 3

Active Mode at 10 Hz

Generate trigger pulses at 10 Hz and evaluate sync:

<EXT-TRIGGER-CMD> --camid 1 --camid 3 --active --hz 10

Active Mode with Custom Exposure and ISO

Generate triggers at 15 Hz with 200 us pulse width and ISO 1600:

<EXT-TRIGGER-CMD> --camid 1 --camid 3 --active --hz 15 --exposure_us 200 --iso 1600

Three-Camera Sync Test

Test synchronization across three cameras:

<EXT-TRIGGER-CMD> --camid 1 --camid 2 --camid 3 --active --hz 10

CLI Reference

Flag

Description

Default

--camid

Camera IDs to monitor (repeat for each camera)

Required

--active

Enable active trigger pulse generation via GPIO

Disabled

--hz

Trigger rate in Hz (active mode only)

15

--exposure_us

Active-low pulse width in microseconds (active mode only)

100

--iso

ISO gain (active mode only)

2500

Output

The application logs sync results for each trigger group after an initial settling period (5 groups). Each line includes:

  • SYNC / NOSYNC / TIMEOUT status

  • Number of cameras that reported vs expected

  • Timestamp spread in microseconds (current and rolling average)

  • Cumulative pass/fail counts

  • Per-camera frame number and sensor timestamp

On shutdown (Ctrl+C), a summary is printed with total pass/fail/timeout counts, spread statistics (mean and standard deviation), and per-camera frame counts.

Synchronized frame groups are saved as JPEG images to /tmp/trigger_test at approximately 1-second intervals. Copy them to your host for review:

# On host
scp -r <USER@HDK_IP>:/tmp/trigger_test ./trigger_test