0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002
0003 .. _flash-controls:
0004
0005 ***********************
0006 Flash Control Reference
0007 ***********************
0008
0009 The V4L2 flash controls are intended to provide generic access to flash
0010 controller devices. Flash controller devices are typically used in
0011 digital cameras.
0012
0013 The interface can support both LED and xenon flash devices. As of
0014 writing this, there is no xenon flash driver using this interface.
0015
0016
0017 .. _flash-controls-use-cases:
0018
0019 Supported use cases
0020 ===================
0021
0022
0023 Unsynchronised LED flash (software strobe)
0024 ------------------------------------------
0025
0026 Unsynchronised LED flash is controlled directly by the host as the
0027 sensor. The flash must be enabled by the host before the exposure of the
0028 image starts and disabled once it ends. The host is fully responsible
0029 for the timing of the flash.
0030
0031 Example of such device: Nokia N900.
0032
0033
0034 Synchronised LED flash (hardware strobe)
0035 ----------------------------------------
0036
0037 The synchronised LED flash is pre-programmed by the host (power and
0038 timeout) but controlled by the sensor through a strobe signal from the
0039 sensor to the flash.
0040
0041 The sensor controls the flash duration and timing. This information
0042 typically must be made available to the sensor.
0043
0044
0045 LED flash as torch
0046 ------------------
0047
0048 LED flash may be used as torch in conjunction with another use case
0049 involving camera or individually.
0050
0051
0052 .. _flash-control-id:
0053
0054 Flash Control IDs
0055 -----------------
0056
0057 ``V4L2_CID_FLASH_CLASS (class)``
0058 The FLASH class descriptor.
0059
0060 ``V4L2_CID_FLASH_LED_MODE (menu)``
0061 Defines the mode of the flash LED, the high-power white LED attached
0062 to the flash controller. Setting this control may not be possible in
0063 presence of some faults. See V4L2_CID_FLASH_FAULT.
0064
0065
0066 .. tabularcolumns:: |p{5.7cm}|p{11.8cm}|
0067
0068 .. flat-table::
0069 :header-rows: 0
0070 :stub-columns: 0
0071
0072 * - ``V4L2_FLASH_LED_MODE_NONE``
0073 - Off.
0074 * - ``V4L2_FLASH_LED_MODE_FLASH``
0075 - Flash mode.
0076 * - ``V4L2_FLASH_LED_MODE_TORCH``
0077 - Torch mode.
0078
0079 See V4L2_CID_FLASH_TORCH_INTENSITY.
0080
0081
0082
0083 ``V4L2_CID_FLASH_STROBE_SOURCE (menu)``
0084 Defines the source of the flash LED strobe.
0085
0086 .. tabularcolumns:: |p{7.5cm}|p{7.5cm}|
0087
0088 .. flat-table::
0089 :header-rows: 0
0090 :stub-columns: 0
0091
0092 * - ``V4L2_FLASH_STROBE_SOURCE_SOFTWARE``
0093 - The flash strobe is triggered by using the
0094 V4L2_CID_FLASH_STROBE control.
0095 * - ``V4L2_FLASH_STROBE_SOURCE_EXTERNAL``
0096 - The flash strobe is triggered by an external source. Typically
0097 this is a sensor, which makes it possible to synchronise the
0098 flash strobe start to exposure start.
0099
0100
0101
0102 ``V4L2_CID_FLASH_STROBE (button)``
0103 Strobe flash. Valid when V4L2_CID_FLASH_LED_MODE is set to
0104 V4L2_FLASH_LED_MODE_FLASH and V4L2_CID_FLASH_STROBE_SOURCE
0105 is set to V4L2_FLASH_STROBE_SOURCE_SOFTWARE. Setting this
0106 control may not be possible in presence of some faults. See
0107 V4L2_CID_FLASH_FAULT.
0108
0109 ``V4L2_CID_FLASH_STROBE_STOP (button)``
0110 Stop flash strobe immediately.
0111
0112 ``V4L2_CID_FLASH_STROBE_STATUS (boolean)``
0113 Strobe status: whether the flash is strobing at the moment or not.
0114 This is a read-only control.
0115
0116 ``V4L2_CID_FLASH_TIMEOUT (integer)``
0117 Hardware timeout for flash. The flash strobe is stopped after this
0118 period of time has passed from the start of the strobe.
0119
0120 ``V4L2_CID_FLASH_INTENSITY (integer)``
0121 Intensity of the flash strobe when the flash LED is in flash mode
0122 (V4L2_FLASH_LED_MODE_FLASH). The unit should be milliamps (mA)
0123 if possible.
0124
0125 ``V4L2_CID_FLASH_TORCH_INTENSITY (integer)``
0126 Intensity of the flash LED in torch mode
0127 (V4L2_FLASH_LED_MODE_TORCH). The unit should be milliamps (mA)
0128 if possible. Setting this control may not be possible in presence of
0129 some faults. See V4L2_CID_FLASH_FAULT.
0130
0131 ``V4L2_CID_FLASH_INDICATOR_INTENSITY (integer)``
0132 Intensity of the indicator LED. The indicator LED may be fully
0133 independent of the flash LED. The unit should be microamps (uA) if
0134 possible.
0135
0136 ``V4L2_CID_FLASH_FAULT (bitmask)``
0137 Faults related to the flash. The faults tell about specific problems
0138 in the flash chip itself or the LEDs attached to it. Faults may
0139 prevent further use of some of the flash controls. In particular,
0140 V4L2_CID_FLASH_LED_MODE is set to V4L2_FLASH_LED_MODE_NONE
0141 if the fault affects the flash LED. Exactly which faults have such
0142 an effect is chip dependent. Reading the faults resets the control
0143 and returns the chip to a usable state if possible.
0144
0145 .. tabularcolumns:: |p{8.4cm}|p{9.1cm}|
0146
0147 .. flat-table::
0148 :header-rows: 0
0149 :stub-columns: 0
0150
0151 * - ``V4L2_FLASH_FAULT_OVER_VOLTAGE``
0152 - Flash controller voltage to the flash LED has exceeded the limit
0153 specific to the flash controller.
0154 * - ``V4L2_FLASH_FAULT_TIMEOUT``
0155 - The flash strobe was still on when the timeout set by the user ---
0156 V4L2_CID_FLASH_TIMEOUT control --- has expired. Not all flash
0157 controllers may set this in all such conditions.
0158 * - ``V4L2_FLASH_FAULT_OVER_TEMPERATURE``
0159 - The flash controller has overheated.
0160 * - ``V4L2_FLASH_FAULT_SHORT_CIRCUIT``
0161 - The short circuit protection of the flash controller has been
0162 triggered.
0163 * - ``V4L2_FLASH_FAULT_OVER_CURRENT``
0164 - Current in the LED power supply has exceeded the limit specific to
0165 the flash controller.
0166 * - ``V4L2_FLASH_FAULT_INDICATOR``
0167 - The flash controller has detected a short or open circuit
0168 condition on the indicator LED.
0169 * - ``V4L2_FLASH_FAULT_UNDER_VOLTAGE``
0170 - Flash controller voltage to the flash LED has been below the
0171 minimum limit specific to the flash controller.
0172 * - ``V4L2_FLASH_FAULT_INPUT_VOLTAGE``
0173 - The input voltage of the flash controller is below the limit under
0174 which strobing the flash at full current will not be possible.The
0175 condition persists until this flag is no longer set.
0176 * - ``V4L2_FLASH_FAULT_LED_OVER_TEMPERATURE``
0177 - The temperature of the LED has exceeded its allowed upper limit.
0178
0179
0180
0181 ``V4L2_CID_FLASH_CHARGE (boolean)``
0182 Enable or disable charging of the xenon flash capacitor.
0183
0184 ``V4L2_CID_FLASH_READY (boolean)``
0185 Is the flash ready to strobe? Xenon flashes require their capacitors
0186 charged before strobing. LED flashes often require a cooldown period
0187 after strobe during which another strobe will not be possible. This
0188 is a read-only control.
