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 (menu)`` 62 Defines the mode of the flash LED, the high-power white LED attached 63 to the flash controller. Setting this control may not be possible in 64 presence of some faults. See V4L2_CID_FLASH_FAULT. 65 66 67.. tabularcolumns:: |p{5.7cm}|p{11.8cm}| 68 69.. flat-table:: 70 :header-rows: 0 71 :stub-columns: 0 72 73 * - ``V4L2_FLASH_LED_MODE_NONE`` 74 - Off. 75 * - ``V4L2_FLASH_LED_MODE_FLASH`` 76 - Flash mode. 77 * - ``V4L2_FLASH_LED_MODE_TORCH`` 78 - Torch mode. 79 80 See V4L2_CID_FLASH_TORCH_INTENSITY. 81 82 83 84``V4L2_CID_FLASH_STROBE_SOURCE (menu)`` 85 Defines the source of the flash LED strobe. 86 87.. tabularcolumns:: |p{7.5cm}|p{7.5cm}| 88 89.. flat-table:: 90 :header-rows: 0 91 :stub-columns: 0 92 93 * - ``V4L2_FLASH_STROBE_SOURCE_SOFTWARE`` 94 - The flash strobe is triggered by using the 95 V4L2_CID_FLASH_STROBE control. 96 * - ``V4L2_FLASH_STROBE_SOURCE_EXTERNAL`` 97 - The flash strobe is triggered by an external source. Typically 98 this is a sensor, which makes it possible to synchronise the 99 flash strobe start to exposure start. 100 101 102 103``V4L2_CID_FLASH_STROBE (button)`` 104 Strobe flash. Valid when V4L2_CID_FLASH_LED_MODE is set to 105 V4L2_FLASH_LED_MODE_FLASH and V4L2_CID_FLASH_STROBE_SOURCE 106 is set to V4L2_FLASH_STROBE_SOURCE_SOFTWARE. Setting this 107 control may not be possible in presence of some faults. See 108 V4L2_CID_FLASH_FAULT. 109 110``V4L2_CID_FLASH_STROBE_STOP (button)`` 111 Stop flash strobe immediately. 112 113``V4L2_CID_FLASH_STROBE_STATUS (boolean)`` 114 Strobe status: whether the flash is strobing at the moment or not. 115 This is a read-only control. 116 117``V4L2_CID_FLASH_TIMEOUT (integer)`` 118 Hardware timeout for flash. The flash strobe is stopped after this 119 period of time has passed from the start of the strobe. 120 121``V4L2_CID_FLASH_INTENSITY (integer)`` 122 Intensity of the flash strobe when the flash LED is in flash mode 123 (V4L2_FLASH_LED_MODE_FLASH). The unit should be milliamps (mA) 124 if possible. 125 126``V4L2_CID_FLASH_TORCH_INTENSITY (integer)`` 127 Intensity of the flash LED in torch mode 128 (V4L2_FLASH_LED_MODE_TORCH). The unit should be milliamps (mA) 129 if possible. Setting this control may not be possible in presence of 130 some faults. See V4L2_CID_FLASH_FAULT. 131 132``V4L2_CID_FLASH_INDICATOR_INTENSITY (integer)`` 133 Intensity of the indicator LED. The indicator LED may be fully 134 independent of the flash LED. The unit should be microamps (uA) if 135 possible. 136 137``V4L2_CID_FLASH_FAULT (bitmask)`` 138 Faults related to the flash. The faults tell about specific problems 139 in the flash chip itself or the LEDs attached to it. Faults may 140 prevent further use of some of the flash controls. In particular, 141 V4L2_CID_FLASH_LED_MODE is set to V4L2_FLASH_LED_MODE_NONE 142 if the fault affects the flash LED. Exactly which faults have such 143 an effect is chip dependent. Reading the faults resets the control 144 and returns the chip to a usable state if possible. 145 146.. tabularcolumns:: |p{8.4cm}|p{9.1cm}| 147 148.. flat-table:: 149 :header-rows: 0 150 :stub-columns: 0 151 152 * - ``V4L2_FLASH_FAULT_OVER_VOLTAGE`` 153 - Flash controller voltage to the flash LED has exceeded the limit 154 specific to the flash controller. 155 * - ``V4L2_FLASH_FAULT_TIMEOUT`` 156 - The flash strobe was still on when the timeout set by the user --- 157 V4L2_CID_FLASH_TIMEOUT control --- has expired. Not all flash 158 controllers may set this in all such conditions. 159 * - ``V4L2_FLASH_FAULT_OVER_TEMPERATURE`` 160 - The flash controller has overheated. 161 * - ``V4L2_FLASH_FAULT_SHORT_CIRCUIT`` 162 - The short circuit protection of the flash controller has been 163 triggered. 164 * - ``V4L2_FLASH_FAULT_OVER_CURRENT`` 165 - Current in the LED power supply has exceeded the limit specific to 166 the flash controller. 167 * - ``V4L2_FLASH_FAULT_INDICATOR`` 168 - The flash controller has detected a short or open circuit 169 condition on the indicator LED. 170 * - ``V4L2_FLASH_FAULT_UNDER_VOLTAGE`` 171 - Flash controller voltage to the flash LED has been below the 172 minimum limit specific to the flash controller. 173 * - ``V4L2_FLASH_FAULT_INPUT_VOLTAGE`` 174 - The input voltage of the flash controller is below the limit under 175 which strobing the flash at full current will not be possible.The 176 condition persists until this flag is no longer set. 177 * - ``V4L2_FLASH_FAULT_LED_OVER_TEMPERATURE`` 178 - The temperature of the LED has exceeded its allowed upper limit. 179 180 181 182``V4L2_CID_FLASH_CHARGE (boolean)`` 183 Enable or disable charging of the xenon flash capacitor. 184 185``V4L2_CID_FLASH_READY (boolean)`` 186 Is the flash ready to strobe? Xenon flashes require their capacitors 187 charged before strobing. LED flashes often require a cooldown period 188 after strobe during which another strobe will not be possible. This 189 is a read-only control. 190