189 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2 3.. _flash-controls:4 5***********************6Flash Control Reference7***********************8 9The V4L2 flash controls are intended to provide generic access to flash10controller devices. Flash controller devices are typically used in11digital cameras.12 13The interface can support both LED and xenon flash devices. As of14writing this, there is no xenon flash driver using this interface.15 16 17.. _flash-controls-use-cases:18 19Supported use cases20===================21 22 23Unsynchronised LED flash (software strobe)24------------------------------------------25 26Unsynchronised LED flash is controlled directly by the host as the27sensor. The flash must be enabled by the host before the exposure of the28image starts and disabled once it ends. The host is fully responsible29for 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 and38timeout) but controlled by the sensor through a strobe signal from the39sensor to the flash.40 41The sensor controls the flash duration and timing. This information42typically must be made available to the sensor.43 44 45LED flash as torch46------------------47 48LED flash may be used as torch in conjunction with another use case49involving camera or individually.50 51 52.. _flash-control-id:53 54Flash Control IDs55-----------------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 attached62 to the flash controller. Setting this control may not be possible in63 presence of some faults. See V4L2_CID_FLASH_FAULT.64 65 66.. tabularcolumns:: |p{5.7cm}|p{11.8cm}|67 68.. flat-table::69 :header-rows: 070 :stub-columns: 071 72 * - ``V4L2_FLASH_LED_MODE_NONE``73 - Off.74 * - ``V4L2_FLASH_LED_MODE_FLASH``75 - Flash mode.76 * - ``V4L2_FLASH_LED_MODE_TORCH``77 - Torch mode.78 79 See V4L2_CID_FLASH_TORCH_INTENSITY.80 81 82 83``V4L2_CID_FLASH_STROBE_SOURCE (menu)``84 Defines the source of the flash LED strobe.85 86.. tabularcolumns:: |p{7.5cm}|p{7.5cm}|87 88.. flat-table::89 :header-rows: 090 :stub-columns: 091 92 * - ``V4L2_FLASH_STROBE_SOURCE_SOFTWARE``93 - The flash strobe is triggered by using the94 V4L2_CID_FLASH_STROBE control.95 * - ``V4L2_FLASH_STROBE_SOURCE_EXTERNAL``96 - The flash strobe is triggered by an external source. Typically97 this is a sensor, which makes it possible to synchronise the98 flash strobe start to exposure start.99 100 101 102``V4L2_CID_FLASH_STROBE (button)``103 Strobe flash. Valid when V4L2_CID_FLASH_LED_MODE is set to104 V4L2_FLASH_LED_MODE_FLASH and V4L2_CID_FLASH_STROBE_SOURCE105 is set to V4L2_FLASH_STROBE_SOURCE_SOFTWARE. Setting this106 control may not be possible in presence of some faults. See107 V4L2_CID_FLASH_FAULT.108 109``V4L2_CID_FLASH_STROBE_STOP (button)``110 Stop flash strobe immediately.111 112``V4L2_CID_FLASH_STROBE_STATUS (boolean)``113 Strobe status: whether the flash is strobing at the moment or not.114 This is a read-only control.115 116``V4L2_CID_FLASH_TIMEOUT (integer)``117 Hardware timeout for flash. The flash strobe is stopped after this118 period of time has passed from the start of the strobe.119 120``V4L2_CID_FLASH_INTENSITY (integer)``121 Intensity of the flash strobe when the flash LED is in flash mode122 (V4L2_FLASH_LED_MODE_FLASH). The unit should be milliamps (mA)123 if possible.124 125``V4L2_CID_FLASH_TORCH_INTENSITY (integer)``126 Intensity of the flash LED in torch mode127 (V4L2_FLASH_LED_MODE_TORCH). The unit should be milliamps (mA)128 if possible. Setting this control may not be possible in presence of129 some faults. See V4L2_CID_FLASH_FAULT.130 131``V4L2_CID_FLASH_INDICATOR_INTENSITY (integer)``132 Intensity of the indicator LED. The indicator LED may be fully133 independent of the flash LED. The unit should be microamps (uA) if134 possible.135 136``V4L2_CID_FLASH_FAULT (bitmask)``137 Faults related to the flash. The faults tell about specific problems138 in the flash chip itself or the LEDs attached to it. Faults may139 prevent further use of some of the flash controls. In particular,140 V4L2_CID_FLASH_LED_MODE is set to V4L2_FLASH_LED_MODE_NONE141 if the fault affects the flash LED. Exactly which faults have such142 an effect is chip dependent. Reading the faults resets the control143 and returns the chip to a usable state if possible.144 145.. tabularcolumns:: |p{8.4cm}|p{9.1cm}|146 147.. flat-table::148 :header-rows: 0149 :stub-columns: 0150 151 * - ``V4L2_FLASH_FAULT_OVER_VOLTAGE``152 - Flash controller voltage to the flash LED has exceeded the limit153 specific to the flash controller.154 * - ``V4L2_FLASH_FAULT_TIMEOUT``155 - The flash strobe was still on when the timeout set by the user ---156 V4L2_CID_FLASH_TIMEOUT control --- has expired. Not all flash157 controllers may set this in all such conditions.158 * - ``V4L2_FLASH_FAULT_OVER_TEMPERATURE``159 - The flash controller has overheated.160 * - ``V4L2_FLASH_FAULT_SHORT_CIRCUIT``161 - The short circuit protection of the flash controller has been162 triggered.163 * - ``V4L2_FLASH_FAULT_OVER_CURRENT``164 - Current in the LED power supply has exceeded the limit specific to165 the flash controller.166 * - ``V4L2_FLASH_FAULT_INDICATOR``167 - The flash controller has detected a short or open circuit168 condition on the indicator LED.169 * - ``V4L2_FLASH_FAULT_UNDER_VOLTAGE``170 - Flash controller voltage to the flash LED has been below the171 minimum limit specific to the flash controller.172 * - ``V4L2_FLASH_FAULT_INPUT_VOLTAGE``173 - The input voltage of the flash controller is below the limit under174 which strobing the flash at full current will not be possible.The175 condition persists until this flag is no longer set.176 * - ``V4L2_FLASH_FAULT_LED_OVER_TEMPERATURE``177 - The temperature of the LED has exceeded its allowed upper limit.178 179 180 181``V4L2_CID_FLASH_CHARGE (boolean)``182 Enable or disable charging of the xenon flash capacitor.183 184``V4L2_CID_FLASH_READY (boolean)``185 Is the flash ready to strobe? Xenon flashes require their capacitors186 charged before strobing. LED flashes often require a cooldown period187 after strobe during which another strobe will not be possible. This188 is a read-only control.189