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