1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
3.. _flash-controls:
4
5***********************
6Flash Control Reference
7***********************
8
9The V4L2 flash controls are intended to provide generic access to flash
10controller devices. Flash controller devices are typically used in
11digital cameras.
12
13The interface can support both LED and xenon flash devices. As of
14writing this, there is no xenon flash driver using this interface.
15
16
17.. _flash-controls-use-cases:
18
19Supported use cases
20===================
21
22
23Unsynchronised LED flash (software strobe)
24------------------------------------------
25
26Unsynchronised LED flash is controlled directly by the host as the
27sensor. The flash must be enabled by the host before the exposure of the
28image starts and disabled once it ends. The host is fully responsible
29for the timing of the flash.
30
31Example of such device: Nokia N900.
32
33
34Synchronised LED flash (hardware strobe)
35----------------------------------------
36
37The synchronised LED flash is pre-programmed by the host (power and
38timeout) but controlled by the sensor through a strobe signal from the
39sensor to the flash.
40
41The sensor controls the flash duration and timing. This information
42typically must be made available to the sensor.
43
44
45LED flash as torch
46------------------
47
48LED flash may be used as torch in conjunction with another use case
49involving camera or individually.
50
51
52.. _flash-control-id:
53
54Flash Control IDs
55-----------------
56
57``V4L2_CID_FLASH_CLASS (class)``
58    The FLASH class descriptor.
59
60``V4L2_CID_FLASH_LED_MODE (menu)``
61    Defines the mode of the flash LED, the high-power white LED attached
62    to the flash controller. Setting this control may not be possible in
63    presence of some faults. See V4L2_CID_FLASH_FAULT.
64
65
66
67.. flat-table::
68    :header-rows:  0
69    :stub-columns: 0
70
71    * - ``V4L2_FLASH_LED_MODE_NONE``
72      - Off.
73    * - ``V4L2_FLASH_LED_MODE_FLASH``
74      - Flash mode.
75    * - ``V4L2_FLASH_LED_MODE_TORCH``
76      - Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY.
77
78
79
80``V4L2_CID_FLASH_STROBE_SOURCE (menu)``
81    Defines the source of the flash LED strobe.
82
83.. tabularcolumns:: |p{7.5cm}|p{10.0cm}|
84
85.. flat-table::
86    :header-rows:  0
87    :stub-columns: 0
88
89    * - ``V4L2_FLASH_STROBE_SOURCE_SOFTWARE``
90      - The flash strobe is triggered by using the
91	V4L2_CID_FLASH_STROBE control.
92    * - ``V4L2_FLASH_STROBE_SOURCE_EXTERNAL``
93      - The flash strobe is triggered by an external source. Typically
94	this is a sensor, which makes it possible to synchronise the
95	flash strobe start to exposure start.
96
97
98
99``V4L2_CID_FLASH_STROBE (button)``
100    Strobe flash. Valid when V4L2_CID_FLASH_LED_MODE is set to
101    V4L2_FLASH_LED_MODE_FLASH and V4L2_CID_FLASH_STROBE_SOURCE
102    is set to V4L2_FLASH_STROBE_SOURCE_SOFTWARE. Setting this
103    control may not be possible in presence of some faults. See
104    V4L2_CID_FLASH_FAULT.
105
106``V4L2_CID_FLASH_STROBE_STOP (button)``
107    Stop flash strobe immediately.
108
109``V4L2_CID_FLASH_STROBE_STATUS (boolean)``
110    Strobe status: whether the flash is strobing at the moment or not.
111    This is a read-only control.
112
113``V4L2_CID_FLASH_TIMEOUT (integer)``
114    Hardware timeout for flash. The flash strobe is stopped after this
115    period of time has passed from the start of the strobe.
116
117``V4L2_CID_FLASH_INTENSITY (integer)``
118    Intensity of the flash strobe when the flash LED is in flash mode
119    (V4L2_FLASH_LED_MODE_FLASH). The unit should be milliamps (mA)
120    if possible.
121
122``V4L2_CID_FLASH_TORCH_INTENSITY (integer)``
123    Intensity of the flash LED in torch mode
124    (V4L2_FLASH_LED_MODE_TORCH). The unit should be milliamps (mA)
125    if possible. Setting this control may not be possible in presence of
126    some faults. See V4L2_CID_FLASH_FAULT.
127
128``V4L2_CID_FLASH_INDICATOR_INTENSITY (integer)``
129    Intensity of the indicator LED. The indicator LED may be fully
130    independent of the flash LED. The unit should be microamps (uA) if
131    possible.
132
133``V4L2_CID_FLASH_FAULT (bitmask)``
134    Faults related to the flash. The faults tell about specific problems
135    in the flash chip itself or the LEDs attached to it. Faults may
136    prevent further use of some of the flash controls. In particular,
137    V4L2_CID_FLASH_LED_MODE is set to V4L2_FLASH_LED_MODE_NONE
138    if the fault affects the flash LED. Exactly which faults have such
139    an effect is chip dependent. Reading the faults resets the control
140    and returns the chip to a usable state if possible.
141
142.. tabularcolumns:: |p{8.4cm}|p{9.1cm}|
143
144.. flat-table::
145    :header-rows:  0
146    :stub-columns: 0
147
148    * - ``V4L2_FLASH_FAULT_OVER_VOLTAGE``
149      - Flash controller voltage to the flash LED has exceeded the limit
150	specific to the flash controller.
151    * - ``V4L2_FLASH_FAULT_TIMEOUT``
152      - The flash strobe was still on when the timeout set by the user ---
153	V4L2_CID_FLASH_TIMEOUT control --- has expired. Not all flash
154	controllers may set this in all such conditions.
155    * - ``V4L2_FLASH_FAULT_OVER_TEMPERATURE``
156      - The flash controller has overheated.
157    * - ``V4L2_FLASH_FAULT_SHORT_CIRCUIT``
158      - The short circuit protection of the flash controller has been
159	triggered.
160    * - ``V4L2_FLASH_FAULT_OVER_CURRENT``
161      - Current in the LED power supply has exceeded the limit specific to
162	the flash controller.
163    * - ``V4L2_FLASH_FAULT_INDICATOR``
164      - The flash controller has detected a short or open circuit
165	condition on the indicator LED.
166    * - ``V4L2_FLASH_FAULT_UNDER_VOLTAGE``
167      - Flash controller voltage to the flash LED has been below the
168	minimum limit specific to the flash controller.
169    * - ``V4L2_FLASH_FAULT_INPUT_VOLTAGE``
170      - The input voltage of the flash controller is below the limit under
171	which strobing the flash at full current will not be possible.The
172	condition persists until this flag is no longer set.
173    * - ``V4L2_FLASH_FAULT_LED_OVER_TEMPERATURE``
174      - The temperature of the LED has exceeded its allowed upper limit.
175
176
177
178``V4L2_CID_FLASH_CHARGE (boolean)``
179    Enable or disable charging of the xenon flash capacitor.
180
181``V4L2_CID_FLASH_READY (boolean)``
182    Is the flash ready to strobe? Xenon flashes require their capacitors
183    charged before strobing. LED flashes often require a cooldown period
184    after strobe during which another strobe will not be possible. This
185    is a read-only control.
186