Device Configuration and Frame Acquisition

This tutorial demonstrates how to configure the epc670 ToF HAT+ and acquire frames using standard V4L2 utilities and explains how to configure acquisition parameters such as:

acquisition modes
integration time
modulation frequency

and then capture frames from the device.

The sensor is controlled through the V4L2 sub-device interface:

/run/epc670/subdev

Frames are streamed through:

/run/epc670/video

Basic Acquisition Workflow 

Typical operation follows this sequence:

Configure sensor parameters
Start streaming
Trigger frames

Example Workflow 

Open two terminals, one for starting a stream and one for triggering an image.

Terminal 1

# configure acquisition
v4l2-ctl --device=/run/epc670/subdev -c acquisition_type=1
v4l2-ctl --device=/run/epc670/subdev -c exposure=100

# Initiate streaming
v4l2-ctl --device /run/epc670/video --stream-mmap --stream-count=1 --stream-to=frame.raw --verbose

Terminal 2

# Trigger shutter
v4l2-ctl --device=/run/epc670/subdev -c trigger_shutter=0

Once the frame is generated, the capture command in Terminal 1 will complete and the frame will be saved to:

frame.raw

Configuring Acquisition Mode 

The sensor supports multiple acquisition modes via acquisition_type.

Mode	Description	Frames per Shutter Trigger
Grayscale	Standard intensity image	1
4DCS	Time-of-Flight acquisition	4
HDR	Multi-exposure HDR capture	12

Set the acquisition mode:

v4l2-ctl --device=/run/epc670/subdev -c acquisition_type=0

Example: grayscale acquisition

v4l2-ctl --device=/run/epc670/subdev -c acquisition_type=1

Example: HDR acquisition

v4l2-ctl --device=/run/epc670/subdev -c acquisition_type=2

The effective exposure resolution depends on the configured mod_freq_hz and clock configuration. If the requested exposure cannot be represented exactly, the driver will apply the closest supported value.

HDR Mode Exposure 

In the HDR more, integration time is controlled by separate HDR frame exposure configurations. The effect is similar to single exposure. The only difference is to be able to set the exposure in microseconds per HDR index.

# Enable HDR and set three exposures
v4l2-ctl --device=/run/epc670/subdev -c hdr_0_exposure=20
v4l2-ctl --device=/run/epc670/subdev -c hdr_1_exposure=320
v4l2-ctl --device=/run/epc670/subdev -c hdr_2_exposure=5132

Configuring Modulation Frequency 

Time-of-Flight operation relies on modulated illumination.

Set the modulation frequency using:

v4l2-ctl --device=/run/epc670/subdev -c mod_freq_hz=20000000

Example: 20 MHz modulation.

The driver will apply the closest supported frequency if the requested value cannot be generated exactly.

Changing modulation frequency affects:

exposure step size
maximum integration time
HDR exposure timing
maximal distance
distance accuracy

Capturing Frames 

Stream 

Frames are captured from the streaming device:

/run/epc670/video

Example: capture a single frame

v4l2-ctl --device /run/epc670/video --stream-mmap --stream-count=1 --stream-to=frame.raw --verbose

Capture multiple frames:

v4l2-ctl --device /run/epc670/video --stream-mmap --stream-count=100 --stream-to=frames.raw --verbose

Note

stream-count specifies the number of frames expected before the streaming command exits. The number of frames generated per trigger depends on the acquisition mode. See the acquisition mode table above.

Trigger Shutter 

The user must trigger the shutter until the total number of frames matches the configured stream-count. Example: If:

stream-count = 12
acquisition_type = 4DCS (4 frames per trigger)

Then 3 shutter triggers are required.

# If stream-count=12 and acquisition mode=4DCS
v4l2-ctl --device=/run/epc670/subdev -c trigger_shutter=0
v4l2-ctl --device=/run/epc670/subdev -c trigger_shutter=0
v4l2-ctl --device=/run/epc670/subdev -c trigger_shutter=0

After the expected number of frames is captured, the streaming command will exit and the data will be written to the output file.

For a detailed description of all available controls, see the V4L2 Controls.