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 | 2 MP | Color |
![]() |
B0353 | AR0234 | 2 MP | Color |
![]() |
B0381 | OV2311 | 2 MP | Monochrome |
![]() |
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. |
Wiring procedure¶
- Shut down the Raspberry Pi and disconnect power from the Pi and trigger source.
- Identify the camera's trigger input and GND using its board pinout. Solder headers if required.
- 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.
- 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.
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.
Trigger — B0526
Raspberry Pi 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.
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:
- The preview updates while valid trigger pulses arrive.
- Changing the pulse rate changes the preview update rate, within the camera and processing limits.
- 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








.jpg)

