V4L2 Controls

The ESPROS kernel modules implement a subset of the official standard V4L2 controls.
Additionally, device specific controls are introduced to support the specific needs of ToF imaging sensors.

You can list the controls directly on your system using:

v4l2-ctl --device=/run/epc670/subdev --list-ctrls-menus

For general background on V4L2 controls and control types (integer, menu, button, strings, flags), see the Linux kernel documentation on V4L2 controls. For v4l2-ctl usage, see the v4l2-ctl(1) manual page.

Notes on Control Behavior

Some controls include flags that affect how they behave:

  • execute-on-write: applying a new value triggers immediate hardware reconfiguration when the control is set.

  • volatile: the value may change outside userspace (e.g., hardware-driven), so reads may not match the last value written.

  • write-only: the control can be set but not read back.

  • read-only: the control can be read but not set.

  • button: writing “presses” the control (an action), it isn’t a persistent value.

Standard V4L2 Controls

V4L2_CID_EXPOSURE

  • ID: 0x00980911

  • Range: 0 … 167772150 (step 1)

  • Default: 100

  • Flags: volatile, execute-on-write

Controls the sensor integration time (exposure) in microseconds. Because it is execute-on-write, changes take effect immediately when set. The range and step size is effectively dependent on mod_freq_hz. So, the exposure will only be set to the exact given time only when it’s possible. Otherwise, it’ll get the closest possible value.

Example

# Set exposure
v4l2-ctl --device=/run/epc670/subdev -c exposure=123

# Read current exposure
v4l2-ctl --device=/run/epc670/subdev -C exposure

V4L2_CID_ANALOGUE_GAIN

  • ID: 0x009e0903

  • Range: 25 … 400 (step 25)

  • Default: 150

Sets the analogue CDS gain percentage of the device.

Example

v4l2-ctl --device=/run/epc670/subdev -c analogue_gain=200

Extended V4L2 Controls

Defines

EPC_DEVICE_ID_LEN 38

Fixed length of the epc device identifier string.

The device identifier is exposed as a read-only string V4L2 control.

V4L2_CID_USER_EPC_BASE (V4L2_CID_USER_BASE + 0x1000)

Base ID for epc-specific user controls.

All epc private V4L2 controls are defined relative to this base.

V4L2_CID_EPC_TRIGGER_SHUTTER (V4L2_CID_USER_EPC_BASE + 0x1)

Trigger shutter / acquisition event.

This is a button-style control intended for triggered capture workflows. Writing the control initiates a shutter or acquisition event immediately.

Example: 

# Trigger one acquisition event
v4l2-ctl --device=/run/epcxxx/subdev -c trigger_shutter=0

Typical use case:

  • External or software-triggered capture while the video pipeline is already streaming.

Note

This control is typically write-only and execute-on-write.

Note

The device must already be in streaming mode before this control can be used successfully.

V4L2_CID_EPC_ACQUISITION_TYPE (V4L2_CID_USER_EPC_BASE + 0x2)

Select acquisition type.

This control selects the sensor acquisition mode, such as 4DCS, grayscale, or HDR operation.

In HDR mode, the HDR exposure controls become relevant. In non-HDR modes, the standard exposure control is used instead.

Available values are defined by epc_dev_acquisition_type.

Example: 

# Enable HDR acquisition
v4l2-ctl --device=/run/epcxxx/subdev -c acquisition_type=2

# Switch to grayscale mode
v4l2-ctl --device=/run/epcxxx/subdev -c acquisition_type=1

Typical use case:

  • Select 4DCS for standard ToF operation.

  • Select grayscale for non-ToF image intensity capture.

  • Select HDR before programming HDR slice exposures.

V4L2_CID_EPC_MOD_FREQ_HZ (V4L2_CID_USER_EPC_BASE + 0x3)

Set modulation frequency in Hz.

This control configures the modulation frequency used by the ToF illumination system.

The driver or hardware may quantize the requested value to the nearest supported frequency, so the actual applied value may differ from the requested one.

Example: 

# Request 20 MHz modulation
v4l2-ctl --device=/run/epcxxx/subdev -c mod_freq_hz=20000000

# Read back the actually applied value
v4l2-ctl --device=/run/epcxxx/subdev -C mod_freq_hz

Typical use case:

  • Tune ToF operation for a target depth range or operating point.

  • Recalculate exposure settings after changing modulation frequency.

Note

Changing this control affects the effective exposure range and timing granularity.

V4L2_CID_EPC_MOD_CLK_DIV (V4L2_CID_USER_EPC_BASE + 0x4)

Set modulation clock divider.

This control configures the divider applied to the modulation clock source.

Although the effective modulation frequency may remain unchanged, changing the divider can alter the underlying clocking configuration and therefore influence valid exposure timing and step size.

Example: 

# Set modulation clock divider to 2
v4l2-ctl --device=/run/epcxxx/subdev -c mod_clk_div=2

# Read back the current divider
v4l2-ctl --device=/run/epcxxx/subdev -C mod_clk_div

Typical use case:

  • Fine-tune the internal modulation clocking path while preserving the intended modulation frequency.

V4L2_CID_EPC_HDR_0_EXPOSURE (V4L2_CID_USER_EPC_BASE + 0x5)

HDR exposure time for slice 0.

This control specifies the first HDR sub-exposure time, typically in microseconds.

It is intended for use when the acquisition mode is set to HDR.

Example: 

# Enable HDR mode and set first exposure slice
v4l2-ctl --device=/run/epcxxx/subdev -c acquisition_type=2
v4l2-ctl --device=/run/epcxxx/subdev -c hdr_0_exposure=20

Typical use case:

  • Configure the shortest HDR slice for bright regions.

V4L2_CID_EPC_HDR_1_EXPOSURE (V4L2_CID_USER_EPC_BASE + 0x6)

HDR exposure time for slice 1.

This control specifies the second HDR sub-exposure time, typically in microseconds.

It is intended for use when the acquisition mode is set to HDR.

Example: 

# Set second HDR exposure slice
v4l2-ctl --device=/run/epcxxx/subdev -c hdr_1_exposure=320

Typical use case:

  • Configure the medium HDR slice for mid-tone regions.

V4L2_CID_EPC_HDR_2_EXPOSURE (V4L2_CID_USER_EPC_BASE + 0x7)

HDR exposure time for slice 2.

This control specifies the third HDR sub-exposure time, typically in microseconds.

It is intended for use when the acquisition mode is set to HDR.

Example: 

# Set third HDR exposure slice
v4l2-ctl --device=/run/epcxxx/subdev -c hdr_2_exposure=5132

Typical use case:

  • Configure the longest HDR slice for darker regions.

V4L2_CID_EPC_LED_SELECT (V4L2_CID_USER_EPC_BASE + 0x8)

Select active illumination LED channel.

This control chooses which LED output channel is used for illumination. The available values are defined by the driver implementation.

Example: 

# Select LED channel 1
v4l2-ctl --device=/run/epcxxx/subdev -c led_select=1

Typical use case:

  • Switch between multiple illumination paths during board bring-up, calibration, or hardware validation.

V4L2_CID_EPC_LED_DELAY (V4L2_CID_USER_EPC_BASE + 0x9)

Adjust LED timing delay.

This control applies a programmable delay to the LED timing path.

The configured value is represented as implementation-defined delay steps rather than a directly meaningful time unit, because the effective delay depends on analog characteristics of the hardware.

Example: 

# Increase LED delay by 5 steps
v4l2-ctl --device=/run/epcxxx/subdev -c led_delay=5

Typical use case:

  • Tune illumination timing during sensor alignment, characterization, or image quality optimization.

V4L2_CID_EPC_DEVICE_ID (V4L2_CID_USER_EPC_BASE + 0xA)

Read-only unique device identifier.

This string control returns the unique identifier of the epc die.

The string length is fixed to EPC_DEVICE_ID_LEN characters.

Example: 

# Read the device identifier
v4l2-ctl --device=/run/epcxxx/subdev -C device_id

Typical use case:

  • Associate captured data, calibration, or production records with a specific physical sensor die.

Enums

enum epc_dev_acquisition_type

Supported epcxxx acquisition modes.

These values are used with V4L2_CID_EPC_ACQUISITION_TYPE.

Values:

enumerator EPC_ACQUISITION_TYPE_4DCS

Standard 4DCS acquisition mode.

Typical use case:

  • Default ToF capture mode for phase-based depth acquisition.

enumerator EPC_ACQUISITION_TYPE_GRAYSCALE

Grayscale acquisition mode.

Typical use case:

  • Intensity-only capture without HDR processing.

enumerator EPC_ACQUISITION_TYPE_HDR

High dynamic range acquisition mode.

Typical use case:

  • Scenes with both very bright and very dark regions requiring multiple exposure slices.

enumerator EPC_ACQUISITION_TYPE_MAX

Number of defined acquisition types / upper bound marker.

This is not a selectable acquisition mode.