argus_dca.h

Go to the documentation of this file.

/*************************************************************************/
#ifndef ARGUS_DCA_H
#define ARGUS_DCA_H
#ifdef __cplusplus
extern "C" {
#endif
 
/*!***************************************************************************
 * @defgroup    argus_dca Dynamic Configuration Adaption
 * @ingroup     argus_api
 *
 * @brief       Dynamic Configuration Adaption (DCA) parameter definitions and API functions.
 *
 * @details     The DCA contains an algorithms that detect ambient conditions
 *              and adopt the device configuration to the changing parameters
 *              dynamically while operating the sensor. This is achieved by
 *              rating the currently received signal quality and changing the
 *              device configuration accordingly to the gathered information
 *              from the current measurement frame results before the next
 *              integration cycle starts.
 *
 *              The DCA consists of the following features:
 *              - Static or Dynamic mode. The first is utilizing the nominal
 *                values while the latter is dynamically adopting between min.
 *                and max. value and starting from the nominal values.
 *              - Analog Integration Depth Adaption (from multiple patterns down to single pulses)
 *              - Optical Output Power Adaption
 *              - Pixel Input Gain Adaption (w/ ambient light rejection)
 *              - ADC Sensitivity (i.e. ADC Range) Adaption
 *              - Power Saving Ratio (to decrease the average output power and thus the current consumption)
 *              - All that features are heeding the Laser Safety limits.
 *              .
 *
 * @addtogroup  argus_dca
 * @{
 *****************************************************************************/
 
#include "argus_def.h"
 
 
 
#define ARGUS_CFG_DCA_ATH_MIN       (1U << 6U)
 
#define ARGUS_CFG_DCA_ATH_MAX       (0xFFFFU)
 
 
#define ARGUS_CFG_DCA_PXTH_MIN      (1U)
 
#define ARGUS_CFG_DCA_PXTH_MAX      (33U)
 
 
#define ARGUS_CFG_DCA_DEPTH_MAX     ((uq10_6_t)(0xFFC0U))
 
#define ARGUS_CFG_DCA_DEPTH_MIN     ((uq10_6_t)(1U)) // 1/64, i.e. 1/2 nibble
 
 
#define ARGUS_DCA_GAIN_STAGE_COUNT (4U)
 
#define ARGUS_STATE_DCA_GAIN_MASK (0x03U)
 
#define ARGUS_STATE_DCA_GAIN_SHIFT (14U)
 
#define ARGUS_STATE_DCA_GAIN_GET(state) \
    (((state) >> ARGUS_STATE_DCA_GAIN_SHIFT) & ARGUS_STATE_DCA_GAIN_MASK)
 
 
#define ARGUS_DCA_POWER_STAGE_COUNT (2U)
 
#define ARGUS_STATE_DCA_POWER_MASK (0x01U)
 
#define ARGUS_STATE_DCA_POWER_SHIFT (13U)
 
#define ARGUS_STATE_DCA_POWER_GET(state) \
    (((state) >> ARGUS_STATE_DCA_POWER_SHIFT) & ARGUS_STATE_DCA_POWER_MASK)
 
 
 
 
/*!***************************************************************************
 * @brief   The dynamic configuration algorithm enable flags.
 *****************************************************************************/
typedef enum argus_dca_enable_t
{
    DCA_ENABLE_OFF = 0,
 
    DCA_ENABLE_DYNAMIC = 1,
 
    DCA_ENABLE_STATIC = -1,
 
} argus_dca_enable_t;
 
/*!***************************************************************************
 * @brief   The DCA amplitude evaluation method.
 *****************************************************************************/
typedef enum argus_dca_amplitude_mode_t
{
    DCA_AMPLITUDE_MAX = 1U,
 
    DCA_AMPLITUDE_AVG = 2U,
 
} argus_dca_amplitude_mode_t;
 
/*!***************************************************************************
 * @brief   The dynamic configuration algorithm Optical Output Power stages enumerator.
 *****************************************************************************/
typedef enum argus_dca_power_t
{
    DCA_POWER_LOW = 0,
 
    DCA_POWER_HIGH = 1,
 
    DCA_POWER_AUTO = 2
 
} argus_dca_power_t;
 
/*!***************************************************************************
 * @brief   The dynamic configuration algorithm Pixel Input Gain stages enumerator.
 *****************************************************************************/
typedef enum argus_dca_gain_t
{
    DCA_GAIN_LOW = 0,
 
    DCA_GAIN_MEDIUM_LOW = 1,
 
    DCA_GAIN_MEDIUM_HIGH = 2,
 
    DCA_GAIN_HIGH = 3
 
} argus_dca_gain_t;
 
 
/*!***************************************************************************
 * @brief   State flags for the current frame.
 * @details State flags determine the current state of the measurement frame:
 *          - [0]: #ARGUS_STATE_XTALK_MONITOR_ACTIVE
 *          - [1]: #ARGUS_STATE_DUAL_FREQ_MODE
 *          - [2]: #ARGUS_STATE_MEASUREMENT_FREQ
 *          - [3]: #ARGUS_STATE_DEBUG_MODE
 *          - [4]: #ARGUS_STATE_WEAK_SIGNAL
 *          - [5]: #ARGUS_STATE_BGL_WARNING
 *          - [6]: #ARGUS_STATE_BGL_ERROR
 *          - [7]: #ARGUS_STATE_PLL_LOCKED
 *          - [8]: #ARGUS_STATE_LASER_WARNING
 *          - [9]: #ARGUS_STATE_LASER_ERROR
 *          - [10]: #ARGUS_STATE_HAS_DATA
 *          - [11]: #ARGUS_STATE_HAS_AUX_DATA
 *          - [12]: #ARGUS_STATE_SATURATED_PIXELS
 *          - [13]: DCA Power Stage
 *          - [14-15]: DCA Gain Stages
 *          - [16]: #ARGUS_STATE_DCA_MIN
 *          - [17]: #ARGUS_STATE_DCA_MAX
 *          - [18]: #ARGUS_STATE_DCA_RESET
 *          - [18-31]: not used
 *          .
 *****************************************************************************/
typedef enum argus_state_t
{
    ARGUS_STATE_NONE = 0,
 
    ARGUS_STATE_XTALK_MONITOR_ACTIVE = 1U << 0U,
 
    ARGUS_STATE_DUAL_FREQ_MODE = 1U << 1U,
 
    ARGUS_STATE_MEASUREMENT_FREQ = 1U << 2U,
 
    ARGUS_STATE_DEBUG_MODE = 1U << 3U,
 
    ARGUS_STATE_WEAK_SIGNAL = 1U << 4U,
 
    ARGUS_STATE_BGL_WARNING = 1U << 5U,
 
    ARGUS_STATE_BGL_ERROR = 1U << 6U,
 
    ARGUS_STATE_PLL_LOCKED = 1U << 7U,
 
    ARGUS_STATE_LASER_WARNING = 1U << 8U,
 
    ARGUS_STATE_LASER_ERROR = 1U << 9U,
 
    ARGUS_STATE_HAS_DATA = 1U << 10U,
 
    ARGUS_STATE_HAS_AUX_DATA = 1U << 11U,
 
    ARGUS_STATE_SATURATED_PIXELS = 1U << 12U,
 
    ARGUS_STATE_DCA_POWER_HIGH = DCA_POWER_HIGH << ARGUS_STATE_DCA_POWER_SHIFT,
 
    ARGUS_STATE_DCA_GAIN_LOW = DCA_GAIN_LOW << ARGUS_STATE_DCA_GAIN_SHIFT,
 
    ARGUS_STATE_DCA_GAIN_MED_LOW = DCA_GAIN_MEDIUM_LOW << ARGUS_STATE_DCA_GAIN_SHIFT,
 
    ARGUS_STATE_DCA_GAIN_MED_HIGH = DCA_GAIN_MEDIUM_HIGH << ARGUS_STATE_DCA_GAIN_SHIFT,
 
    ARGUS_STATE_DCA_GAIN_HIGH = DCA_GAIN_HIGH << ARGUS_STATE_DCA_GAIN_SHIFT,
 
    ARGUS_STATE_DCA_MIN = 1U << 16U,
 
    ARGUS_STATE_DCA_MAX = 1U << 17U,
 
    ARGUS_STATE_DCA_RESET = 1U << 18U,
 
} argus_state_t;
 
/*!***************************************************************************
 * @brief   Dynamic Configuration Adaption (DCA) Parameters.
 * @details DCA contains:
 *           - Static or dynamic mode. The first is utilizing the nominal values
 *             while the latter is dynamically adopting between min. and max.
 *             value and starting form the nominal values.
 *           - Analog Integration Depth Adaption down to single pulses.
 *           - Optical Output Power Adaption
 *           - Pixel Input Gain Adaption
 *           - Digital Integration Depth Adaption
 *           - Dynamic Global Phase Shift Injection.
 *           - All that features are heeding the Laser Safety limits.
 *           .
 *****************************************************************************/
typedef struct argus_cfg_dca_t
{
    argus_dca_enable_t Enabled;
 
    uint8_t SatPxThLin;
 
    uint8_t SatPxThExp;
 
    uint8_t SatPxThRst;
 
    uq12_4_t Atarget;
 
    uq12_4_t AthLow;
 
    uq12_4_t AthHigh;
 
    argus_dca_amplitude_mode_t AmplitudeMode;
 
    argus_dca_power_t Power;
 
    uq10_6_t DepthNom;
 
    uq10_6_t DepthMin_LowPower;
 
    uq10_6_t DepthMin_HighPower;
 
    uq10_6_t DepthMax;
 
    argus_dca_gain_t GainNom;
 
    argus_dca_gain_t GainMin;
 
    argus_dca_gain_t GainMax;
 
    uq0_8_t PowerSavingRatio;
 
    uint8_t DisablePowerSaveInLowPowerStage;
 
} argus_cfg_dca_t;
 
#ifdef __cplusplus
} // extern "C"
#endif
#endif /* ARGUS_DCA_H */