SCAILX-2GS234 V4L commands

Description

This document describes the V4L2 interface commands and the usage guide for the Global shutter MIPI camera for the SCAiLX platform.

TUI - Text User Interface

SCAiLX includes pyvidctrl, a terminal GUI to conveniently adjust V4L2 control values. To use it, open an SSH terminal and execute:

pyvidctrl -d /dev/links/gs_AR0234_mipi_0

User Controls

Command	Code	Type	Controls

Command	Code	Type	Controls
brightness	0x00980900	int	min=-4096 max=4096 step=32 default=0 value=0 flags=slider
contrast	0x00980901	int	min=-32768 max=32767 step=256 default=0 value=0 flags=slider
saturation	0x00980902	int	min=0 max=8192 step=32 default=4096 value=4096 flags=slider
white_balance_automatic	0x0098090c	bool	default=1 value=1
do_white_balance	0x0098090d	button	value=0 flags=write-only, execute-on-write
gamma	0x00980910	int	min=0 max=32767 step=128 default=0 value=0 flags=slider
exposure	0x00980911	int	min=-8192 max=2048 step=40 default=-2192 value=-2199
gain	0x00980913	int	min=256 max=32767 step=1 default=256 value=256
horizontal_flip	0x00980914	bool	default=0 value=0
vertical_flip	0x00980915	bool	default=0 value=0
power_line_frequency	0x00980918	menu	min=0 max=3 default=3 value=0 (Disabled)
white_balance_temperature	0x0098091a	int	min=0 max=65535 step=1 default=6500 value=5000
sharpness	0x0098091b	int	min=-32768 max=32767 step=256 default=0 value=0 flags=slider
backlight_compensation	0x0098091c	int	min=0 max=128 step=1 default=0 value=0
color_effects	0x0098091f	menu	min=0 max=15 default=0 value=0 (None)
noise_reduction	0x009810d0	int	min=-32768 max=32767 step=256 default=0 value=0 flags=slider

Table 1 V4L2 user controls

Brightness

The brightness value ranges from -4096 to 4096, 32.
The format is a two’s complement value.

Contrast

The contrast value ranges from -32768 to 32767, step 256.
The format is a two’s complement value.

Saturation

Saturation ranges from 0x0000 to 0x2000, step 32.
e.g. the default 1.0 is 0x1000.

White balance

White balance value 0 for manual or 1 for automatic.

Gamma

The format is s3.12. Gamma is controllable from 0x600 to 0x8000, step 128.
Gamma values lower than 0x600 result in the sRGB gamma curve.

e.g:
Gamma of 1.0 = 0x1000
Gamma of 2.5 = 0x2800

Exposure

Exposure sets the target level from -8192 to 2024 in steps of 40.

Horizontal Flip

Horizontal flip value 0 to disable or 1 to enable.

Vertical Flip

Vertical flip value 0 to disable or 1 to enable.

Anti Flicker (power line frequency mode)

0        Disable.
1        Force correction to 50 Hz
2        Force correction to 60 Hz
3        Automatic detection

White balance temperature

Set the white balance temperature in Kelvin when the White balance mode is set to manual.

Sharpness

The sharpness value ranges from -32768 to 32767, step 256.
The format is a two’s complement value.

Backlight compensation

The backlight compensation level can be set from 0 to 128.

Color Effects

Set color effects:

0        Normal
1        Black & White
2        Sepia
3        Negative
4        Emboss
5        Sketch
6        Sky Blue
7        Green Grass
8        Skin Whiten (defaults to Normal)
9        Vivid (defaults to Normal)
10      Aqua (defaults to Normal)
11      Art Freeze
12      Silhouette
13      Solarization
14      Antique
15      Set Cb/Cr (defaults to Normal)

Noise Reduction

The noise reduction value ranges from -32768 to 32767, step 256.
The format is a two’s complement value.

Camera controls

Command	Code	Type	Controls

Command	Code	Type	Controls
auto_exposure	0x009a0901	menu	min=0 max=3 default=0 value=0 (Auto Mode)
exposure_time_absolute	0x009a0902	int	min=0 max=65535 step=1 default=333 value=333
pan_absolute	0x009a0908	int	min=0 max=128 step=1 default=64 value=64
tilt_absolute	0x009a0909	int	min=0 max=128 step=1 default=64 value=64
zoom_absolute	0x009a090d	int	min=0 max=10240 step=1 default=256 value=256
white_balance_auto_preset	0x009a0914	menu	min=0 max=9 default=6 value=6 (Daylight)
exposure_metering_mode	0x009a0919	menu	min=0 max=3 default=1 value=1 (Center Weighted)
zoom_speed	0x009a0932	int	min=-128 max=127 step=1 default=-128 value=-128 flags=slider
region_of_interest_bound	0x009a0933	bool	default=0 value=0
region_of_interest_lock	0x009a0934	bool	default=0 value=0
region_of_interest_face	0x009a0935	bool	default=1 value=1
exposure_upper_x_100us	0x009a0936	int	min=0 max=65535 step=1 default=333 value=333 flags=slider
exposure_max_x_100us	0x009a0937	int	min=0 max=65535 step=1 default=333 value=333 flags=slider
gain_upper_value_u8_8	0x009a0938	int	min=0 max=65535 step=1 default=2048 value=2048 flags=slider
gain_max_max_2_value_s7_8	0x009a0939	int	min=0 max=65535 step=1 default=1408 value=1408 flags=slider
blc_window_x0_0_128	0x009a093a	int	min=0 max=128 step=1 default=0 value=0 flags=slider
blc_window_y0_0_128	0x009a093b	int	min=0 max=128 step=1 default=0 value=0 flags=slider
blc_window_x1_0_128	0x009a093c	int	min=0 max=128 step=1 default=128 value=128 flags=slider
blc_window_y1_0_128	0x009a093d	int	min=0 max=128 step=1 default=128 value=128 flags=slider
blc_ratio_0_128	0x009a093e	int	min=0 max=128 step=1 default=128 value=128
blc_face_level_0_128	0x009a093f	int	min=0 max=128 step=1 default=128 value=128 flags=slider
blc_face_weight_0_128	0x009a0940	int	min=0 max=128 step=1 default=128 value=128 flags=slider
blc_roi_level_0_128	0x009a0941	int	min=0 max=128 step=1 default=0 value=0 flags=slider
awb_manual_x	0x009a0942	int	min=-32768 max=32767 step=1 default=0 value=0 flags=slider
awb_manual_y	0x009a0943	int	min=-32768 max=32767 step=1 default=0 value=0 flags=slider
store_registers_to_nvm	0x009a0946	button	value=0 flags=write-only, execute-on-write
restore_registers_from_nvm	0x009a0947	button	value=0 flags=write-only, execute-on-write
restore_to_factory_settings	0x009a0948	button	value=0 flags=write-only, execute-on-write
reboot_camera	0x009a0949	button	value=0 flags=write-only, execute-on-write

Table 2 V4L2 camera controls

Auto Exposure

Sets the Exposure modes:

0        Automatic mode
1        Manual mode
2        Shutter Priority mode
3        Aperture Priority mode (unused, defaults to Automatic mode)

Exposure Time, Absolute

In manual mode the exposure time can be set in steps of 100 us.
e.g.: 333 = 33.3 ms

Pan, Absolute

Allows left/right panning when the zoom factor is greater than 1x.
0        Full left pan
64      Center
128    Full right pan

Tilt, Absolute

Tilt up/down
0 Full up tilt
64 Center
128 Full right tilt

Zoom, Absolute

Zoom factor. Format s7.8., max 40x = 0x2800.
1x       0x0100
1.5x    0x0180
32x     0x2000

White Balance, Auto & Preset

When white balance is in manual mode a preset can be selected
0        Manual
1        Auto (reserved) Do not use!
2        Incandescent
3        Fluorescent
4        Horizon
5        Daylight
6        Flash
7        Cloudy
8        Shade

Exposure, Metering Mode

The metering mode determines how the exposure algorithm uses the picture.
0        Average
1        Center Weighted
2        Spot
3        Matrix

Zoom speed

The zoom speed determines how quickly the camera moves to the set zoom factor.
128 Immediate
0 Stop (when moving toward the set zoom factor the zoom movement can be stopped)
<128 Linear (speed is constant)
>128 Fractional (speed slows down as zoom factor is reached)

Region of Interest (Bound)

The Automatic exposure algorithm will use the ROI. This function can be enabled or disabled.

Region of Interest (Lock)

When using the ROI, once settled the ROI can be locked. This function can be enabled or disabled.

Region of Interest (Face)

The automatic exposure algorithm uses face-based exposure. This function can be enabled or disabled.

Exposure Limits

The exposure limits: “exposure upper” and “exposure max” are used by the AEX algorithm to limit the exposure time. Setting these limits beyond the framerate will lower the framerate to maintain the wanted brightness level.

Minimum gain is used from start and AE is increasing exposure time up to "upper exposure".
Once "upper exposure" is exhausted AE starts increasing gain up to "upper gain". Best performing gain is always used first, so analog gain will typically be used up before digital gain.
Once "upper gain" is exhausted AE again starts increasing exposure time up to "max exposure".
After that gain is increased up to max gain.
(this value is logarithmic, e.g., gain max = 3.0 means 8x gain).

Figure 1 Exposure and Gain

Exposure Upper (x 100 us)

The upper exposure limit can be set in steps of 100us.

Exposure Max (x 100 us)

The maximum exposure limit can be set in steps of 100us.

Gain Upper (value = u8.8)

The upper gain limit can be set. Format u8.8.
e.g:
0x10 Gain = 1.0x
0x18 Gain = 1.5x

Gain Max (max = 2^value, s7.8)

The upper gain limit can be set. Format s7.8.
This value is logarithmic.
e.g.: gain max = 3.0 means max 8x gain.

BLC Window

Command	Code
BLC window X0 (0~128)	BLC (or ROI) x-start position
BLC window Y0 (0~128)	BLC (or ROI) y-start position
BLC window X1 (0~128)	BLC (or ROI) x-end position
BLC window Y1 (0~128)	BLC (or ROI) y-end position
BLC ratio (0~128)	Sets the ratio of the exposure algorithm uses between the ROI and the main picture.
BLC face Level (0~128)	Sets the amount of BLC level used for faces.
BLC face weight (0~128)	Sets the weight (or ratio) value between faces and ROI.
BLC ROI level (0~128)	Sets the amount of BLC level used for the ROI.

AWB manual white point (X, Y)

White balance must be set to manual!
White Balance, Auto & Preset must be set to manual!

AWB Manual X: Sets the X coordinate for the white point. From Blue to RED
AWB manual Y: Sets the Y coordinate for the white point. From GREEN to VIOLET

Figure 2 White point x,y graph

Store Registers (User Settings) to NVM

Set to store registers to non-volatile memory. After reboot or re-power, the stored register values will be used.

Restore Registers (User settings) from NVM

Set to restore the register values when register values have been changed by the user. Instead of rebooting or re-powering.

Restore to Factory Settings

Set to restore factory settings.

Reboot Camera

Set to reboot the camera.

After restoring registers (user settings) from the NVM, the stream should be re-started to make sure the stream uses the restored settings. In case the pyvidctrl python tool was used also restart this tool.
After a camera reboot, the stream should be re-started

Image Processing Controls

Command	Code	Type	Controls
test_pattern	0x009f0903	menu	min=0 max=1 default=0 value=0 (Disabled)

Table 3 V4L2 image processing controls

Test pattern

Set value 0 to disable or 1 to enable.

Figure 3 Test Pattern

Detection Controls

Command	Code	Type	Controls

Command	Code	Type	Controls
face_detection_enable	0x00a30932	bool	default=0 value=0
face_detection_rectangles	0x00a30933	bool	default=0 value=0
face_detection_saturated	0x00a30934	bool	default=0 value=0
face_detection_speed_x_0_1s	0x00a30935	int	min=0 max=255 step=1 default=0 value=0 flags=slider
face_detection_theshold	0x00a30936	int	min=0 max=255 step=1 default=128 value=128 flags=slider
face_chroma_theshold	0x00a30937	int	min=0 max=31 step=1 default=12 value=12 flags=slider
face_minimum_size	0x00a30938	int	min=0 max=16384 step=1 default=1024 value=1024 flags=slider
face_maximum_size	0x00a30939	int	min=0 max=16384 step=1 default=16384 value=16384 flags=slider

Table 4 V4L2 detection controls

Detection controls description

Command	Description
Face detection (enable)	Set value 0 to disable or 1 to enable.
Face detection (rectangles)	Show rectangle around faces. Set value 0 to disable or 1 to enable.
Face detection (saturated)	Show saturated regions. Set value 0 to disable or 1 to enable.
Face detection speed (x 0.1s)	Sets the face detection speed in steps of 0.1 seconds.
Face detection threshold	Sets the face detection threshold.
Face chroma threshold	Sets the face detection threshold.
Face minimum size	Sets the minimum face size detection threshold.
Face maximum size	Sets the maximum face size detection threshold.