1 .. Permission is granted to copy, distribute and/or modify this
2 .. document under the terms of the GNU Free Documentation License,
3 .. Version 1.1 or any later version published by the Free Software
4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
5 .. and no Back-Cover Texts. A copy of the license is included at
6 .. Documentation/media/uapi/fdl-appendix.rst.
8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
12 ***********************
13 Flash Control Reference
14 ***********************
16 The V4L2 flash controls are intended to provide generic access to flash
17 controller devices. Flash controller devices are typically used in
20 The interface can support both LED and xenon flash devices. As of
21 writing this, there is no xenon flash driver using this interface.
24 .. _flash-controls-use-cases:
30 Unsynchronised LED flash (software strobe)
31 ------------------------------------------
33 Unsynchronised LED flash is controlled directly by the host as the
34 sensor. The flash must be enabled by the host before the exposure of the
35 image starts and disabled once it ends. The host is fully responsible
36 for the timing of the flash.
38 Example of such device: Nokia N900.
41 Synchronised LED flash (hardware strobe)
42 ----------------------------------------
44 The synchronised LED flash is pre-programmed by the host (power and
45 timeout) but controlled by the sensor through a strobe signal from the
48 The sensor controls the flash duration and timing. This information
49 typically must be made available to the sensor.
55 LED flash may be used as torch in conjunction with another use case
56 involving camera or individually.
64 ``V4L2_CID_FLASH_CLASS (class)``
65 The FLASH class descriptor.
67 ``V4L2_CID_FLASH_LED_MODE (menu)``
68 Defines the mode of the flash LED, the high-power white LED attached
69 to the flash controller. Setting this control may not be possible in
70 presence of some faults. See V4L2_CID_FLASH_FAULT.
78 * - ``V4L2_FLASH_LED_MODE_NONE``
80 * - ``V4L2_FLASH_LED_MODE_FLASH``
82 * - ``V4L2_FLASH_LED_MODE_TORCH``
83 - Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY.
87 ``V4L2_CID_FLASH_STROBE_SOURCE (menu)``
88 Defines the source of the flash LED strobe.
90 .. tabularcolumns:: |p{7.0cm}|p{10.5cm}|
96 * - ``V4L2_FLASH_STROBE_SOURCE_SOFTWARE``
97 - The flash strobe is triggered by using the
98 V4L2_CID_FLASH_STROBE control.
99 * - ``V4L2_FLASH_STROBE_SOURCE_EXTERNAL``
100 - The flash strobe is triggered by an external source. Typically
101 this is a sensor, which makes it possible to synchronises the
102 flash strobe start to exposure start.
106 ``V4L2_CID_FLASH_STROBE (button)``
107 Strobe flash. Valid when V4L2_CID_FLASH_LED_MODE is set to
108 V4L2_FLASH_LED_MODE_FLASH and V4L2_CID_FLASH_STROBE_SOURCE
109 is set to V4L2_FLASH_STROBE_SOURCE_SOFTWARE. Setting this
110 control may not be possible in presence of some faults. See
111 V4L2_CID_FLASH_FAULT.
113 ``V4L2_CID_FLASH_STROBE_STOP (button)``
114 Stop flash strobe immediately.
116 ``V4L2_CID_FLASH_STROBE_STATUS (boolean)``
117 Strobe status: whether the flash is strobing at the moment or not.
118 This is a read-only control.
120 ``V4L2_CID_FLASH_TIMEOUT (integer)``
121 Hardware timeout for flash. The flash strobe is stopped after this
122 period of time has passed from the start of the strobe.
124 ``V4L2_CID_FLASH_INTENSITY (integer)``
125 Intensity of the flash strobe when the flash LED is in flash mode
126 (V4L2_FLASH_LED_MODE_FLASH). The unit should be milliamps (mA)
129 ``V4L2_CID_FLASH_TORCH_INTENSITY (integer)``
130 Intensity of the flash LED in torch mode
131 (V4L2_FLASH_LED_MODE_TORCH). The unit should be milliamps (mA)
132 if possible. Setting this control may not be possible in presence of
133 some faults. See V4L2_CID_FLASH_FAULT.
135 ``V4L2_CID_FLASH_INDICATOR_INTENSITY (integer)``
136 Intensity of the indicator LED. The indicator LED may be fully
137 independent of the flash LED. The unit should be microamps (uA) if
140 ``V4L2_CID_FLASH_FAULT (bitmask)``
141 Faults related to the flash. The faults tell about specific problems
142 in the flash chip itself or the LEDs attached to it. Faults may
143 prevent further use of some of the flash controls. In particular,
144 V4L2_CID_FLASH_LED_MODE is set to V4L2_FLASH_LED_MODE_NONE
145 if the fault affects the flash LED. Exactly which faults have such
146 an effect is chip dependent. Reading the faults resets the control
147 and returns the chip to a usable state if possible.
149 .. tabularcolumns:: |p{8.0cm}|p{9.5cm}|
155 * - ``V4L2_FLASH_FAULT_OVER_VOLTAGE``
156 - Flash controller voltage to the flash LED has exceeded the limit
157 specific to the flash controller.
158 * - ``V4L2_FLASH_FAULT_TIMEOUT``
159 - The flash strobe was still on when the timeout set by the user ---
160 V4L2_CID_FLASH_TIMEOUT control --- has expired. Not all flash
161 controllers may set this in all such conditions.
162 * - ``V4L2_FLASH_FAULT_OVER_TEMPERATURE``
163 - The flash controller has overheated.
164 * - ``V4L2_FLASH_FAULT_SHORT_CIRCUIT``
165 - The short circuit protection of the flash controller has been
167 * - ``V4L2_FLASH_FAULT_OVER_CURRENT``
168 - Current in the LED power supply has exceeded the limit specific to
169 the flash controller.
170 * - ``V4L2_FLASH_FAULT_INDICATOR``
171 - The flash controller has detected a short or open circuit
172 condition on the indicator LED.
173 * - ``V4L2_FLASH_FAULT_UNDER_VOLTAGE``
174 - Flash controller voltage to the flash LED has been below the
175 minimum limit specific to the flash controller.
176 * - ``V4L2_FLASH_FAULT_INPUT_VOLTAGE``
177 - The input voltage of the flash controller is below the limit under
178 which strobing the flash at full current will not be possible.The
179 condition persists until this flag is no longer set.
180 * - ``V4L2_FLASH_FAULT_LED_OVER_TEMPERATURE``
181 - The temperature of the LED has exceeded its allowed upper limit.
185 ``V4L2_CID_FLASH_CHARGE (boolean)``
186 Enable or disable charging of the xenon flash capacitor.
188 ``V4L2_CID_FLASH_READY (boolean)``
189 Is the flash ready to strobe? Xenon flashes require their capacitors
190 charged before strobing. LED flashes often require a cooldown period
191 after strobe during which another strobe will not be possible. This
192 is a read-only control.