Skip to content

External Trigger Mode for Raspberry Pi Cameras

Use an external electrical pulse to control when a supported Arducam global shutter camera captures a frame. This is useful for event-driven inspection and coordinating cameras with other equipment.

This guide covers the Pivariety cameras listed below and drivers that expose the trigger_mode V4L2 control. It walks through wiring, preview verification, and returning to continuous capture.

Preview verification

The commands in this guide verify frame delivery in a preview. They do not automatically save one image file per trigger. Applications that require image files must also implement frame acquisition and storage.

Before you begin

You need:

  • A supported camera, its matching CSI cable, and the appropriate driver and firmware for your Raspberry Pi and OS.
  • A working camera preview in continuous mode.
  • A pulse generator, or a Raspberry Pi GPIO output with the appropriate level shifter.
  • A local display for preview verification, and two terminal windows.

Install the command-line tools and Python dependencies used below:

sudo apt update
sudo apt install v4l-utils wget unzip python3-gpiozero python3-lgpio

Check camera detection and preview before connecting the trigger source:

rpicam-hello --list-cameras
rpicam-hello -t 5000

Expected result: the camera is listed and a live preview appears. Resolve detection or continuous-capture problems before configuring external triggering. If multiple cameras are connected, select the intended camera with --camera N and identify its corresponding subdevice in Step 3.

Supported cameras

Camera SKU Sensor Resolution Image type
B0348 OG02B10 camera B0348 OG02B10 2 MP Color
B0353 AR0234 camera B0353 AR0234 2 MP Color
B0381 OV2311 camera B0381 OV2311 2 MP Monochrome
B0526 Mira220 camera B0526 Mira220 2.2 MP Monochrome

Support depends on the camera board revision, firmware, and driver, not just the sensor name. Check the product documentation for the exact SKU before wiring.

Connector and optical specifications

All four models use an M12 lens with manual focus. Connector contact positions below describe the camera-side connector; they do not specify the Raspberry Pi cable orientation.

SKU Camera connector Field of view (H × V) IR-cut filter
B0348 22-pin, top contact 85° × 69° 650 nm IR-cut filter
B0353 22-pin, top contact 90° × 56° None
B0381 22-pin, top contact 83° × 67.5° None
B0526 15-pin, bottom contact 68° × 53° None

Step 1: Connect the trigger signal

Signal requirements

Check the voltage before connecting GPIO

The trigger interface described here requires a 1.8 V signal. Raspberry Pi GPIO outputs use 3.3 V logic. Use a suitable level shifter between the GPIO output and the camera trigger input; do not connect a 3.3 V or 5 V output directly to a 1.8 V input. Confirm the electrical requirements for your exact camera board revision before applying a signal.

Parameter Requirement
Trigger input Use the input identified in the camera pinout: XVS, FSIN, or Trigger. These labels are board-specific.
Signal level 1.8 V for the interface described here; verify against the camera board documentation.
Pulse width, TTPW At least 2 µs for the documented interface; follow any additional model-specific timing requirements.
Trigger frequency Do not exceed the supported external-trigger rate for the selected sensor mode and exposure.
Ground Connect the trigger source, level shifter, and camera to a common ground.
Polarity and active edge Follow the camera timing specification; do not infer them from the pin label alone.

External trigger timing diagram

Wiring procedure

  1. Shut down the Raspberry Pi and disconnect power from the Pi and trigger source.
  2. Identify the camera's trigger input and GND using its board pinout. Solder headers if required.
  3. Connect the trigger source through the level shifter to the camera trigger input. Configure the level shifter's supply rails and direction for the required signal levels.
  4. Connect the grounds, then check the CSI cable and trigger wiring before restoring power.
Source connection Destination
Raspberry Pi GPIO output Level shifter 3.3 V-side input
Level shifter 1.8 V-side output Camera trigger input
Raspberry Pi / trigger-source GND Camera GND and level shifter GND

If using a pulse generator with a suitable output level, connect its signal output and ground according to the camera's electrical specification.

Match the script to the wiring

The downloadable trigger.py uses BCM GPIO 3, which is physical pin 5 on the Raspberry Pi 40-pin header. BCM numbers and physical pin numbers are different. Confirm LED_PIN in the downloaded script before wiring, and ensure the selected GPIO is not in use by another function, such as I²C.

Pin-location and connection examples

These illustrations show example board layouts. Verify the pinout for your board revision, and include the required level conversion even if it is not shown in an illustration. Use the GPIO selected in your script.

XVS — UC-788 board examples

Some OV9281, OG02B10, and OV2311 camera revisions use the UC-788 board and an XVS connection. An OV9281 pin-location example does not establish compatibility with the software procedure on this page.

XVS connection example for a UC-788 camera board

FSIN — pin-label examples

The following images illustrate FSIN labels on other Arducam boards. They are not pinout diagrams for every camera in the supported-camera table.

Example board with an FSIN label FSIN connection detail on an example board

Trigger — B0526

Trigger pin location on the B0526 camera

Raspberry Pi connection example

Raspberry Pi and camera trigger connection example

Step 2: Prepare the trigger source

Skip the Python setup if you are using a separate pulse generator. Configure its signal level, timing, and frequency before enabling its output.

For the Raspberry Pi example, download and inspect the script:

mkdir -p "$HOME/arducam-external-trigger"
cd "$HOME/arducam-external-trigger"
wget -O trigger.py.zip https://cdn.arducam.com/downloads/trigger.py.zip
unzip trigger.py.zip trigger.py
nano trigger.py

The example uses GPIO Zero and contains these settings:

LED_PIN = 3
INITIAL_FREQUENCY = 30.0
FIXED_ON_TIME = 0.001
Setting Meaning
LED_PIN = 3 BCM GPIO 3, physical pin 5. Match this to your wiring.
INITIAL_FREQUENCY = 30.0 Starts generating pulses at 30 Hz immediately when the script runs. Reduce this before running if the selected camera mode requires a lower rate.
FIXED_ON_TIME = 0.001 Nominal HIGH pulse duration of 1 ms. This is not the camera exposure setting.

Do not start the script yet. First configure the camera timeout and start the preview as described below.

Timing accuracy

This Python example is intended for functional testing. For precise timing or repeatable synchronization, use a suitable hardware pulse generator and measure the signal at the camera input. A requested pulse rate does not guarantee the same delivered frame rate.

Step 3: Identify the camera subdevice

In Terminal 2, list the controls on the available subdevices:

for device in /dev/v4l-subdev*; do
    [ -e "$device" ] || continue
    printf '\n%s\n' "$device"
    v4l2-ctl -d "$device" --list-ctrls
done

Find the camera subdevice that exposes trigger_mode. If more than one does, inspect the media topology to associate the subdevice with the intended camera:

for device in /dev/media*; do
    [ -e "$device" ] || continue
    media-ctl -d "$device" -p
done

Subdevice numbering depends on the system configuration. Pi 5 / CM5 setups may use /dev/v4l-subdev2, while other setups may use /dev/v4l-subdev0; neither path is guaranteed.

Set the variable below to the node you identified. This example uses /dev/v4l-subdev2:

CAMERA_SUBDEV=/dev/v4l-subdev2
v4l2-ctl -d "$CAMERA_SUBDEV" --get-ctrl=trigger_mode

Keep Terminal 2 open. The variable is local to this shell, and the enable/disable commands below must target the same camera.

Step 4: Increase the frame-wait timeout

While waiting for a trigger, the camera may produce no frames. Increase the pipeline timeout so that this wait does not immediately stop the application.

In Terminal 1, create a working directory:

mkdir -p "$HOME/arducam-external-trigger"

Copy one configuration file, according to the Raspberry Pi model.

Raspberry Pi 5 or Compute Module 5:

cp /usr/share/libcamera/pipeline/rpi/pisp/example.yaml \
    "$HOME/arducam-external-trigger/timeout.yaml"

Other Raspberry Pi models using the VC4 pipeline:

cp /usr/share/libcamera/pipeline/rpi/vc4/rpi_apps.yaml \
    "$HOME/arducam-external-trigger/timeout.yaml"

Edit the copy:

nano "$HOME/arducam-external-trigger/timeout.yaml"

Find camera_timeout_value_ms, remove its leading # if commented out, and set its value to 100000 (100 seconds). Keep the surrounding configuration structure and punctuation intact. Edit the existing entry rather than adding a second one.

Timeout configuration example

Example showing the camera timeout configuration entry

Use a timeout longer than the expected delay before the first trigger and the longest gap between triggers. If the camera waits beyond this period, the application can still time out.

Step 5: Start the preview and enable triggering

In Terminal 1, load the configuration and start the preview:

export LIBCAMERA_RPI_CONFIG_FILE="$HOME/arducam-external-trigger/timeout.yaml"
rpicam-still -t 0 --shutter 1000

--shutter 1000 requests a 1,000 µs (1 ms) exposure. -t 0 keeps the application running; it does not disable the pipeline's frame-wait timeout. The exported setting applies only to applications launched from this terminal.

Expected result: the camera initially shows a continuous preview.

In Terminal 2, enable external trigger mode:

v4l2-ctl -d "$CAMERA_SUBDEV" --set-ctrl=trigger_mode=1
v4l2-ctl -d "$CAMERA_SUBDEV" --get-ctrl=trigger_mode

Expected result: the control reports 1, and the preview stops updating while the camera waits for a trigger. Start the trigger source before the configured timeout expires.

Step 6: Send pulses and verify frame delivery

In Terminal 2, start the prepared script, or enable your external pulse generator:

cd "$HOME/arducam-external-trigger"
python3 trigger.py

The script starts pulsing immediately at INITIAL_FREQUENCY. Enter a new frequency in hertz at its prompt to change the rate. Stay within the camera's supported trigger rate. Enter q or press Ctrl+C to stop.

Verify the following:

  1. The preview updates while valid trigger pulses arrive.
  2. Changing the pulse rate changes the preview update rate, within the camera and processing limits.
  3. Stopping pulses causes the preview to stop updating. Resume pulses or disable trigger mode before the frame-wait timeout expires.

A paused preview without pulses is expected. A preview that remains paused while valid pulses are present requires troubleshooting.

Step 7: Return to continuous capture

Stop the trigger script or pulse generator. In Terminal 2, disable trigger mode on the same subdevice:

v4l2-ctl -d "$CAMERA_SUBDEV" --set-ctrl=trigger_mode=0
v4l2-ctl -d "$CAMERA_SUBDEV" --get-ctrl=trigger_mode

Expected result: the control reports 0 and the preview resumes continuous updates. If the application has already timed out, restart it after disabling trigger mode.

In Terminal 1, press Ctrl+C to stop the preview. Clear the custom configuration when it is no longer needed:

unset LIBCAMERA_RPI_CONFIG_FILE

Troubleshooting

Symptom Check and action
Camera is not detected, or continuous preview fails Check the CSI cable, camera configuration, driver, and firmware first. Verify normal capture before testing the trigger input.
trigger_mode is missing or reported as an unknown control Recheck the subdevice and installed driver. Confirm that the camera SKU and firmware support this control. Do not assume that another board with the same sensor uses this procedure.
Camera times out while waiting Confirm that the edited configuration is loaded in the terminal launching rpicam-still. Increase the timeout if the expected trigger interval exceeds it, then restart the application.
Preview remains paused while pulses are present Check the selected GPIO, common ground, level-shifter direction, signal voltage, pulse polarity, and pulse width at the camera input. Confirm that trigger_mode reports 1.
Frame rate is below the requested pulse rate Lower the trigger frequency and check exposure and sensor-mode limits. Measure the actual waveform; the Python script's requested rate is not a timing guarantee.
Python reports an import, GPIO backend, or pin-access error Check the GPIO Zero and lgpio packages, OS support, GPIO permissions, and pin conflicts. On Pi 5 / CM5, use a GPIO backend that supports the platform.
timeout.yaml cannot be loaded Confirm the source configuration exists for your installed pipeline. Check the absolute path, file permissions, and edited syntax.
No image files are created The preview test does not save images. Use an acquisition application that explicitly writes captured frames.
Continuous capture does not resume Verify trigger_mode=0 on the same camera subdevice, then restart the preview if it has timed out.

Information to include in a support request

Provide the camera SKU and board revision, Raspberry Pi model, driver and firmware versions, wiring photos, trigger voltage/frequency/pulse width, exact commands, and complete error output. Include whether continuous capture works.

Collect the system and camera information:

cat /etc/os-release
uname -a
rpicam-hello --version
rpicam-hello --list-cameras

From Terminal 2, also collect the selected device and its controls:

printf 'Camera subdevice: %s\n' "$CAMERA_SUBDEV"
v4l2-ctl -d "$CAMERA_SUBDEV" --list-ctrls