File content as of revision 1:b4bdb0356af0:

/*******************************************************************************
Copyright © 2019, STMicroelectronics International N.V.
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.
    * Neither the name of STMicroelectronics nor the
      names of its contributors may be used to endorse or promote products
      derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
NON-INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS ARE DISCLAIMED.
IN NO EVENT SHALL STMICROELECTRONICS INTERNATIONAL N.V. BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
********************************************************************************/


#ifndef VL6180_API_H_
#define VL6180_API_H_

#include "vl6180_platform.h"

#ifdef __cplusplus
extern "C" {
#endif

/** @defgroup api_ll API Low Level Functions
 *  @brief    API Low level functions
 */

/** @defgroup api_hl API High Level Functions
 *  @brief    API High level functions
 */


/*
 * Check and set default platform dependent configuration
 */
#ifndef VL6180_SINGLE_DEVICE_DRIVER
#error "VL6180_SINGLE_DEVICE_DRIVER not defined"
/* TODO you may remove or comment these #error but it is best you update your vl6180_platform.h file to define it*/
#endif


#ifndef VL6180_RANGE_STATUS_ERRSTRING
#warning "VL6180_RANGE_STATUS_ERRSTRING not defined ?"
/* TODO you may remove or comment these #warning and keep the default below to keep compatibility
   or update your vl6180_platform.h file */
/**
 * force VL6180_RANGE_STATUS_ERRSTRING to not supported when not part of any cfg file
 */
#define VL6180_RANGE_STATUS_ERRSTRING  0
#endif

#ifndef VL6180_SAFE_POLLING_ENTER
#warning "VL6180_SAFE_POLLING_ENTER not defined, likely old vl6180_cfg.h file ?"
/* TODO you may remove or comment these #warning and keep the default below to keep compatibility
   or update your vl6180_platform.h file */
/**
 * force VL6180_SAFE_POLLING_ENTER to off when not in cfg file
 */
#define VL6180_SAFE_POLLING_ENTER 0 /* off by default as in api 2.0 */
#endif

#ifndef VL6180_LOG_ENABLE
/**
 * Force VL6180_LOG_ENABLE to none as default
 */
#define VL6180_LOG_ENABLE  0
#endif

#if VL6180_RANGE_STATUS_ERRSTRING
/**@def VL6180_HAVE_RANGE_STATUS_ERRSTRING
 * @brief is defined when @a #VL6180_RANGE_STATUS_ERRSTRING is enable
 */
#define  VL6180_HAVE_RANGE_STATUS_ERRSTRING
#endif


/** @brief Get API version as "hex integer" 0xMMnnss
 */
#define VL6180_ApiRevInt  ((VL6180_API_REV_MAJOR<<24)+(VL6180_API_REV_MINOR<<16)+VL6180_API_REV_SUB)

/** Get API version as string for exe "2.1.12" "
 */
#define VL6180_ApiRevStr  VL6180_STR(VL6180_API_REV_MAJOR) "." VL6180_STR(VL6180_API_REV_MINOR) "." VL6180_STR(VL6180_API_REV_SUB)

#ifndef VL6180_API
#   define VL6180_API
#endif

/** @defgroup api_init Init functions
 *  @brief    API init functions
 *  @ingroup api_hl
 *  @{
 */
/**
 * @brief Wait for device booted after chip enable (hardware standby)
 * @par Function Description
 * After Chip enable Application you can also simply wait at least 1ms to ensure device is ready
 * @warning After device chip enable (gpio0) de-asserted  user must wait gpio1 to get asserted (hardware standby).
 * or wait at least 400usec prior to do any low level access or api call .
 *
 * This function implements polling for standby but you must ensure 400usec from chip enable passed\n
 * @warning Calling this function if device is not fresh out of reset will  result in an indefinite loop\n
 *
 * @param dev  The device
 * @return     0 on success
 */
VL6180_API int VL6180_WaitDeviceBooted(VL6180Dev_t dev);

/**
 *
 * @brief One time device initialization
 *
 * To be called once and only once after device is brought out of reset (Chip enable) and booted see @a VL6180_WaitDeviceBooted()
 *
 * @par Function Description
 * When not used after a fresh device "power up" or reset, it may return @a #CALIBRATION_WARNING
 * meaning wrong calibration data may have been fetched from device that can result in unpredictable and wrong ranging values\n
 *
 * @param dev  The device
 * @return     0 on success,  @a #CALIBRATION_WARNING if failed
 */
VL6180_API int VL6180_InitData(VL6180Dev_t dev);

/**
 * @brief Configure GPIO1 function and set polarity.
 * @par Function Description
 * To be used prior to arm single shot measure or start  continuous mode.
 *
 * The function uses @a VL6180_SetupGPIOx() for setting gpio 1.
 * @warning  changing polarity can generate a spurious interrupt on pins.
 * It sets an interrupt flags condition that must be cleared to avoid polling hangs. \n
 * It is safe to run VL6180_ClearAllInterrupt() just after.
 *
 * @param dev           The device
 * @param IntFunction   The interrupt functionality to use one of :\n
 *  @a #GPIOx_SELECT_OFF \n
 *  @a #GPIOx_SELECT_GPIO_INTERRUPT_OUTPUT
 * @param ActiveHigh  The interrupt line polarity see ::IntrPol_e
 *      use @a #INTR_POL_LOW (falling edge) or @a #INTR_POL_HIGH (rising edge)
 * @return 0 on success
 */
VL6180_API int VL6180_SetupGPIO1(VL6180Dev_t dev, uint8_t IntFunction, int ActiveHigh);

 /**
  * @brief  Prepare device for operation
  * @par Function Description
  * Does static initialization and reprogram common default settings \n
  * Device is prepared for new measure, ready single shot ranging typical polling operation\n
  * After prepare user can : \n
  * @li Call other API function to set other settings\n
  * @li Configure the interrupt pins, etc... \n
  * @li Then start ranging operations in single shot or continuous mode
  *
  * @param dev   The device
  * @return      0 on success
  */
VL6180_API int VL6180_Prepare(VL6180Dev_t dev);

 /** @}  */


/** @defgroup api_hl_range Ranging functions
 *  @brief    Ranging functions
 *  @ingroup api_hl
 *  @{
 */

/**
 * @brief Start continuous ranging mode
 *
 * @details End user should ensure device is in idle state and not already running
 */
VL6180_API int VL6180_RangeStartContinuousMode(VL6180Dev_t dev);

/**
 * @brief Start single shot ranging measure
 *
 * @details End user should ensure device is in idle state and not already running
 */
VL6180_API int VL6180_RangeStartSingleShot(VL6180Dev_t dev);

/**
 * @brief Set maximum convergence time
 *
 * @par Function Description
 * Setting a low convergence time can impact maximal detectable distance.
 * Refer to VL6180 Datasheet Table 7 : Typical range convergence time.
 * A typical value for up to x3 scaling is 50 ms
 *
 * @param dev
 * @param MaxConTime_msec
 * @return 0 on success. <0 on error. >0 for calibration warning status
 */
VL6180_API int VL6180_RangeSetMaxConvergenceTime(VL6180Dev_t dev, uint8_t  MaxConTime_msec);

/**
  * @brief Single shot Range measurement in polling mode.
  *
  * @par Function Description
  * Kick off a new single shot range  then wait for ready to retrieve it by polling interrupt status \n
  * Ranging must be prepared by a first call to  @a VL6180_Prepare() and it is safer to clear  very first poll call \n
  * This function reference VL6180_PollDelay(dev) porting macro/call on each polling loop,
  * but PollDelay(dev) may never be called if measure in ready on first poll loop \n
  * Should not be use in continuous mode operation as it will stop it and cause stop/start misbehaviour \n
  * \n This function clears Range Interrupt status , but not error one. For that uses  @a VL6180_ClearErrorInterrupt() \n
  * This range error is not related VL6180_RangeData_t::errorStatus that refer measure status \n
  *
  * @param dev          The device
  * @param pRangeData   Will be populated with the result ranging data @a  VL6180_RangeData_t
  * @return 0 on success , @a #RANGE_ERROR if device reports an error case in it status (not cleared) use
  *
  * \sa ::VL6180_RangeData_t
  */
VL6180_API int VL6180_RangePollMeasurement(VL6180Dev_t dev, VL6180_RangeData_t *pRangeData);

/**
 * @brief Check for measure readiness and get it if ready
 *
 * @par Function Description
 * Using this function is an alternative to @a VL6180_RangePollMeasurement() to avoid polling operation. This is suitable for applications
 * where host CPU is triggered on a interrupt (not from VL6180) to perform ranging operation. In this scenario, we assume that the very first ranging
 * operation is triggered by a call to @a VL6180_RangeStartSingleShot(). Then, host CPU regularly calls @a VL6180_RangeGetMeasurementIfReady() to
 * get a distance measure if ready. In case the distance is not ready, host may get it at the next call.\n
 *
 * @warning
 * This function does not re-start a new measurement : this is up to the host CPU to do it.\n
 * This function clears Range Interrupt for measure ready , but not error interrupts. For that, uses  @a VL6180_ClearErrorInterrupt() \n
 *
 * @param dev  The device
 * @param pRangeData  Will be populated with the result ranging data if available
 * @return  0 on success and <0 in case of error. Please check pRangeData.errorStatus to check is new measurement is ready or not.
 */
VL6180_API int VL6180_RangeGetMeasurementIfReady(VL6180Dev_t dev, VL6180_RangeData_t *pRangeData);

/**
 * @brief Retrieve range measurements set  from device
 *
 * @par Function Description
 * The measurement is made of range_mm status and error code @a VL6180_RangeData_t \n
 * Based on configuration selected extra measures are included.
 *
 * @warning should not be used in continuous if wrap around filter is active \n
 * Does not perform any wait nor check for result availability or validity.
 *\sa VL6180_RangeGetResult for "range only" measurement
 *
 * @param dev         The device
 * @param pRangeData  Pointer to the data structure to fill up
 * @return            0 on success
 */
VL6180_API int VL6180_RangeGetMeasurement(VL6180Dev_t dev, VL6180_RangeData_t *pRangeData);

/**
 * @brief Get ranging result and only that
 *
 * @par Function Description
 * Unlike @a VL6180_RangeGetMeasurement() this function only retrieves the range in millimeter \n
 * It does any required up-scale translation\n
 * It can be called after success status polling or in interrupt mode \n
 * @warning these function is not doing wrap around filtering \n
 * This function doesn't perform any data ready check!
 *
 * @param dev        The device
 * @param pRange_mm  Pointer to range distance
 * @return           0 on success
 */
VL6180_API int VL6180_RangeGetResult(VL6180Dev_t dev, int32_t *pRange_mm);

/**
 * @brief Configure ranging interrupt reported to application
 *
 * @param dev            The device
 * @param ConfigGpioInt  Select ranging report\n select one (and only one) of:\n
 *   @a #CONFIG_GPIO_INTERRUPT_DISABLED \n
 *   @a #CONFIG_GPIO_INTERRUPT_LEVEL_LOW \n
 *   @a #CONFIG_GPIO_INTERRUPT_LEVEL_HIGH \n
 *   @a #CONFIG_GPIO_INTERRUPT_OUT_OF_WINDOW \n
 *   @a #CONFIG_GPIO_INTERRUPT_NEW_SAMPLE_READY
 * @return   0 on success
 */
VL6180_API int VL6180_RangeConfigInterrupt(VL6180Dev_t dev, uint8_t ConfigGpioInt);


/**
 * @brief Clear range interrupt
 *
 * @param dev    The device
 * @return  0    On success
 */
#define VL6180_RangeClearInterrupt(dev) VL6180_ClearInterrupt(dev, INTERRUPT_CLEAR_RANGING)

/**
 * @brief Return ranging error interrupt status
 *
 * @par Function Description
 * Appropriate Interrupt report must have been selected first by @a VL6180_RangeConfigInterrupt() or @a  VL6180_Prepare() \n
 *
 * Can be used in polling loop to wait for a given ranging event or in interrupt to read the trigger \n
 * Events triggers are : \n
 * @a #RES_INT_STAT_GPIO_LOW_LEVEL_THRESHOLD \n
 * @a #RES_INT_STAT_GPIO_HIGH_LEVEL_THRESHOLD \n
 * @a #RES_INT_STAT_GPIO_OUT_OF_WINDOW \n (RES_INT_STAT_GPIO_LOW_LEVEL_THRESHOLD|RES_INT_STAT_GPIO_HIGH_LEVEL_THRESHOLD)
 * @a #RES_INT_STAT_GPIO_NEW_SAMPLE_READY \n
 *
 * @sa IntrStatus_t
 * @param dev        The device
 * @param pIntStatus Pointer to status variable to update
 * @return           0 on success
 */
VL6180_API int VL6180_RangeGetInterruptStatus(VL6180Dev_t dev, uint8_t *pIntStatus);

#if VL6180_RANGE_STATUS_ERRSTRING

extern const char *ROMABLE_DATA VL6180_RangeStatusErrString[];
/**
 * @brief Human readable error string for range error status
 *
 * @param RangeErrCode  The error code as stored on @a VL6180_RangeData_t::errorStatus
 * @return  error string , NULL for invalid RangeErrCode
 * @sa ::RangeError_u
 */
const char *VL6180_RangeGetStatusErrString(uint8_t RangeErrCode);
#else
#define VL6180_RangeGetStatusErrString(...) NULL
#endif

/** @}  */


/** @defgroup api_ll_init Init functions
 *  @brief    Init functions
 *  @ingroup api_ll
 *  @{
 */

/**
 * @brief Low level ranging register static settings (you should call @a VL6180_Prepare() function instead)
 *
 * @param dev
 * @return 0 on success
 */
VL6180_API int VL6180_StaticInit(VL6180Dev_t dev);

 /** @}  */

/** @defgroup api_ll_range Ranging functions
 *  @brief    Ranging Low Level functions
 *  @ingroup api_ll
 *  @{
 */

/**
 * @brief Wait for device to be ready (before a new ranging command can be issued by application)
 * @param dev        The device
 * @param MaxLoop    Max Number of i2c polling loop see @a #msec_2_i2cloop
 * @return           0 on success. <0 when fail \n
 *                   @ref VL6180_ErrCode_t::TIME_OUT for time out \n
 *                   @ref VL6180_ErrCode_t::INVALID_PARAMS if MaxLop<1
 */
VL6180_API int VL6180_RangeWaitDeviceReady(VL6180Dev_t dev, int MaxLoop);

/**
 * @brief Program Inter measurement period (used only in continuous mode)
 *
 * @par Function Description
 * When trying to set too long time, it returns #INVALID_PARAMS
 *
 * @param dev     The device
 * @param InterMeasTime_msec Requires inter-measurement time in msec
 * @return 0 on success
 */
VL6180_API int VL6180_RangeSetInterMeasPeriod(VL6180Dev_t dev, uint32_t  InterMeasTime_msec);


/**
 * @brief Set device ranging scaling factor
 *
 * @par Function Description
 * The ranging scaling factor is applied on the raw distance measured by the device to increase operating ranging at the price of the precision.
 * Changing the scaling factor when device is not in f/w standby state (free running) is not safe.
 * It can be source of spurious interrupt, wrongly scaled range etc ...
 * @warning __This  function doesns't update high/low threshold and other programmed settings linked to scaling factor__.
 *  To ensure proper operation, threshold and scaling changes should be done following this procedure: \n
 *  @li Set Group hold  : @a VL6180_SetGroupParamHold() \n
 *  @li Get Threshold @a VL6180_RangeGetThresholds() \n
 *  @li Change scaling : @a VL6180_UpscaleSetScaling() \n
 *  @li Set Threshold : @a VL6180_RangeSetThresholds() \n
 *  @li Unset Group Hold : @a VL6180_SetGroupParamHold()
 *
 * @param dev      The device
 * @param scaling  Scaling factor to apply (1,2 or 3)
 * @return          0 on success when up-scale support is not configured it fail for any
 *                  scaling than the one statically configured.
 */
VL6180_API int VL6180_UpscaleSetScaling(VL6180Dev_t dev, uint8_t scaling);

/**
 * @brief Get current ranging scaling factor
 *
 * @param dev The device
 * @return    The current scaling factor
 */
VL6180_API int VL6180_UpscaleGetScaling(VL6180Dev_t dev);


/**
 * @brief Give filtered state (wrap-around filter) of a range measurement
 * @param pRangeData  Range measurement data
 * @return  0 means measure was not filtered,  when not 0 range from device got filtered by filter post processing
 */
#define VL6180_RangeIsFilteredMeasurement(pRangeData) ((pRangeData)->errorStatus == RangingFiltered)

/**
 * @brief Get the maximal distance for actual scaling
 * @par Function Description
 * Do not use prior to @a VL6180_Prepare() or at least @a VL6180_InitData()
 *
 * Any range value more than the value returned by this function is to be considered as "no target detected"
 * or "no target in detectable range"
 * @warning The maximal distance depends on the scaling
 *
 * @param dev The device
 * @return    The maximal range limit for actual mode and scaling
 */
uint16_t VL6180_GetUpperLimit(VL6180Dev_t dev);

/**
 * @brief Apply low and high ranging thresholds that are considered only in continuous mode
 *
 * @par Function Description
 * This function programs low and high ranging thresholds that are considered in continuous mode :
 * interrupt will be raised only when an object is detected at a distance inside this [low:high] range.
 * The function takes care of applying current scaling factor if any.\n
 * To be safe, in continuous operation, thresholds must be changed under "group parameter hold" cover.
 * Group hold can be activated/deactivated directly in the function or externally (then set 0)
 * using /a VL6180_SetGroupParamHold() function.
 *
 * @param dev      The device
 * @param low      Low threshold in mm
 * @param high     High threshold in mm
 * @param SafeHold  Use of group parameters hold to surround threshold programming.
 * @return  0 On success
 */
VL6180_API int VL6180_RangeSetThresholds(VL6180Dev_t dev, uint16_t low, uint16_t high, int SafeHold);

/**
 * @brief  Get scaled high and low threshold from device
 *
 * @par Function Description
 * Due to scaling factor, the returned value may be different from what has been programmed first (precision lost).
 * For instance VL6180_RangeSetThresholds(dev,11,22) with scale 3
 * will read back 9 ((11/3)x3) and 21 ((22/3)x3).

 * @param dev  The device
 * @param low  scaled low Threshold ptr  can be NULL if not needed
 * @param high scaled High Threshold ptr can be NULL if not needed
 * @return 0 on success, return value is undefined if both low and high are NULL
 * @warning return value is undefined if both low and high are NULL
 */
VL6180_API int VL6180_RangeGetThresholds(VL6180Dev_t dev, uint16_t *low, uint16_t *high);

/**
 * @brief Set ranging raw thresholds (scaling not considered so not recommended to use it)
 *
 * @param dev  The device
 * @param low  raw low threshold set to raw register
 * @param high raw high threshold set to raw  register
 * @return 0 on success
 */
VL6180_API int VL6180_RangeSetRawThresholds(VL6180Dev_t dev, uint8_t low, uint8_t high);

/**
 * @brief Set Early Convergence Estimate ratio
 * @par Function Description
 * For more information on ECE check datasheet
 * @warning May return a calibration warning in some use cases
 *
 * @param dev        The device
 * @param FactorM    ECE factor M in M/D
 * @param FactorD    ECE factor D in M/D
 * @return           0 on success. <0 on error. >0 on warning
 */
VL6180_API int VL6180_RangeSetEceFactor(VL6180Dev_t dev, uint16_t  FactorM, uint16_t FactorD);

/**
 * @brief Set Early Convergence Estimate state (See #SYSRANGE_RANGE_CHECK_ENABLES register)
 * @param dev       The device
 * @param enable    State to be set 0=disabled, otherwise enabled
 * @return          0 on success
 */
VL6180_API int VL6180_RangeSetEceState(VL6180Dev_t dev, int enable);

/**
 * @brief Set activation state of the wrap around filter
 * @param dev   The device
 * @param state New activation state (0=off,  otherwise on)
 * @return      0 on success
 */
VL6180_API int VL6180_FilterSetState(VL6180Dev_t dev, int state);

/**
 * Get activation state of the wrap around filter
 * @param dev  The device
 * @return     Filter enabled or not, when filter is not supported it always returns 0S
 */
VL6180_API int VL6180_FilterGetState(VL6180Dev_t dev);


/**
 * @brief Set activation state of  DMax computation
 * @param dev   The device
 * @param state New activation state (0=off,  otherwise on)
 * @return      0 on success
 */
VL6180_API int VL6180_DMaxSetState(VL6180Dev_t dev, int state);

/**
 * Get activation state of DMax computation
 * @param dev  The device
 * @return     Filter enabled or not, when filter is not supported it always returns 0S
 */
VL6180_API int VL6180_DMaxGetState(VL6180Dev_t dev);


/**
 * @brief Set ranging mode and start/stop measure (use high level functions instead : @a VL6180_RangeStartSingleShot() or @a VL6180_RangeStartContinuousMode())
 *
 * @par Function Description
 * When used outside scope of known polling single shot stopped state, \n
 * user must ensure the device state is "idle" before to issue a new command.
 *
 * @param dev   The device
 * @param mode  A combination of working mode (#MODE_SINGLESHOT or #MODE_CONTINUOUS) and start/stop condition (#MODE_START_STOP) \n
 * @return      0 on success
 */
VL6180_API int VL6180_RangeSetSystemMode(VL6180Dev_t dev, uint8_t mode);

/**
 * @brief Enable/disable range ignore feature
 *
 * @par  Function Description
 * Enable range ignore feature to ensure that the device does not range on the cover glass because of cross-talk. 
 * @a VL6180_RangeIgnoreConfigure() should be run first to configure feature prior to enable it.
 *
 * @param dev             The Device
 * @param EnableState     Feature state to set 0= off else =on
 * @return                0 on success
 */
VL6180_API int VL6180_RangeIgnoreSetEnable(VL6180Dev_t dev, int EnableState);

/**
 * @brief Configure Range ignore feature
 *
 * @par  Function Description
 * When return signal rate is below the IgnoreThreshold and return distance is below the ValidHeight, the distance will be ignored 
 * @warning It is recommended to enable range ignore feature and configure it only when device is in stop or idle state
 * @warning Once this function is called, next call to @a VL6180_InitData() function without reseting the device will result in wrong ranging operation
 * @param dev				The Device
 * @param ValidHeight_mm    Valid height in mm (unscaled ie not raw  value before scaling)
 * @param IgnoreThreshold	Ignore threshold in fixpoint 9.7 MegaCount/sec
 * @return
 */
VL6180_API int VL6180_RangeIgnoreConfigure(VL6180Dev_t dev, uint16_t ValidHeight_mm, uint16_t IgnoreThreshold);
/** @}  */

/** @defgroup api_ll_range_calibration Ranging calibration functions
 *  @brief    Ranging calibration functions
 *  @ingroup api_ll
 *  @{
 */
/**
 * @brief Get part to part calibration offset
 *
 * @par Function Description
 * Should only be used after a successful call to @a VL6180_InitData to backup device nvm value
 *
 * @param dev  The device
 * @return part to part calibration offset from device
 */
VL6180_API int8_t VL6180_GetOffsetCalibrationData(VL6180Dev_t dev);

/**
 * Set or over-write part to part calibration offset and apply it immediately
 * \sa VL6180_InitData(), VL6180_GetOffsetCalibrationData()
 * @param dev     The device
 * @param offset   Offset
 * @return  0 on success
 */
VL6180_API int  VL6180_SetOffsetCalibrationData(VL6180Dev_t dev, int8_t offset);

/**
 * @brief Set Cross talk compensation rate
 *
 * @par Function Description
 * It programs register @a #SYSRANGE_CROSSTALK_COMPENSATION_RATE
 *
 * @param dev  The device
 * @param Rate Compensation rate (9.7 fix point) see datasheet for details
 * @return     0 on success
 */
VL6180_API int  VL6180_SetXTalkCompensationRate(VL6180Dev_t dev, FixPoint97_t Rate);

/** @}  */




/** @defgroup api_ll_misc Misc functions
 *  @brief    Misc functions
 *  @ingroup api_ll
 *  @{
 */

/**
 * Set Group parameter Hold state
 *
 * @par Function Description
 * Group parameter holds @a #SYSTEM_GROUPED_PARAMETER_HOLD enable safe update (non atomic across multiple measure) by host
 * \n The critical register group is composed of: \n
 * #SYSTEM_INTERRUPT_CONFIG_GPIO \n
 * #SYSRANGE_THRESH_HIGH \n
 * #SYSRANGE_THRESH_LOW
 *
 *
 * @param dev   The device
 * @param Hold  Group parameter Hold state to be set (on/off)
 * @return      0 on success
 */
VL6180_API int VL6180_SetGroupParamHold(VL6180Dev_t dev, int Hold);

/**
 * @brief Set new device i2c address
 *
 * After completion the device will answer to the new address programmed.
 *
 * @sa AN4478: Using multiple VL6180's in a single design
 * @param dev       The device
 * @param NewAddr   The new i2c address (8 bits)
 * @return          0 on success
 */
VL6180_API int VL6180_SetI2CAddress(VL6180Dev_t dev, uint8_t NewAddr);

/**
 * @brief Fully configure gpio 0/1 pin : polarity and functionality
 *
 * @param dev          The device
 * @param pin          gpio pin 0 or 1
 * @param IntFunction  Pin functionality : either #GPIOx_SELECT_OFF or #GPIOx_SELECT_GPIO_INTERRUPT_OUTPUT (refer to #SYSTEM_MODE_GPIO1 register definition)
 * @param ActiveHigh   Set active high polarity, or active low see @a ::IntrPol_e
 * @return             0 on success
 */
VL6180_API int VL6180_SetupGPIOx(VL6180Dev_t dev, int pin, uint8_t IntFunction, int ActiveHigh);


/**
 * @brief Set interrupt pin polarity for the given GPIO
 *
 * @param dev          The device
 * @param pin          Pin 0 or 1
 * @param active_high  select active high or low polarity using @ref IntrPol_e
 * @return             0 on success
 */
VL6180_API int VL6180_SetGPIOxPolarity(VL6180Dev_t dev, int pin, int active_high);

/**
 * Select interrupt functionality for the given GPIO
 *
 * @par Function Description
 * Functionality refer to @a SYSTEM_MODE_GPIO0
 *
 * @param dev            The device
 * @param pin            Pin to configure 0 or 1 (gpio0 or gpio1)Note that gpio0 is chip enable at power up !
 * @param functionality  Pin functionality : either #GPIOx_SELECT_OFF or #GPIOx_SELECT_GPIO_INTERRUPT_OUTPUT (refer to #SYSTEM_MODE_GPIO1 register definition)
 * @return              0 on success
 */
VL6180_API int VL6180_SetGPIOxFunctionality(VL6180Dev_t dev, int pin, uint8_t functionality);

/**
 * @brief Disable and turn to Hi-Z gpio output pin
 *
 * @param dev  The device
 * @param pin  The pin number to disable 0 or 1
 * @return     0 on success
 */
VL6180_API int VL6180_DisableGPIOxOut(VL6180Dev_t dev, int pin);

/**
 * @def msec_2_i2cloop
 * @brief  Number of I2C polling loop (an 8 bit register) to run for maximal wait time.
 *
 * @par Function Description
 * When polling via I2C the overall time is mainly the I2C transaction time because it is a slow bus
 *   one 8 bit register poll on I2C bus timing is shown below: \n
 *   start + addr_w(a)  + 2x8bit index(a)  + stop  + start  + addr_rd(a)  + 1x8bit data_rd(a) + stop \n
 *   1        8   1        2*(8+1)           1       1          8     1        8           1    1 \n
 *  so 49 serial bits
 *
 * @param  time_ms  Time to wait in milli second 10
 * @param  i2c_khz  I2C bus frequencies in KHz  for instance 400
 * @return The number of loops (at least 1)
 */
#define msec_2_i2cloop(time_ms, i2c_khz) (((time_ms) * (i2c_khz) / 49) + 1)

/** @}  */



/**
 * polarity use in @a VL6180_SetupGPIOx() , @a VL6180_SetupGPIO1()
 */
typedef enum {
	INTR_POL_LOW = 0, /*!< set active low polarity best setup for falling edge */
	INTR_POL_HIGH = 1, /*!< set active high polarity best setup for rising edge */
} IntrPol_e;

/** @defgroup api_ll_intr Interrupts management functions
 *  @brief    Interrupts management functions
 *  @ingroup api_ll
 *  @{
 */

/**
 * @brief     Get all interrupts cause
 *
 * @param dev    The device
 * @param status Ptr to interrupt status. You can use @a IntrStatus_t::val
 * @return 0 on success
 */
VL6180_API int VL6180_GetInterruptStatus(VL6180Dev_t dev, uint8_t *status);

/**
 * @brief Clear given system interrupt condition
 *
 * @par Function Description
 * Clear given interrupt cause by writing into register #SYSTEM_INTERRUPT_CLEAR register.
 * @param dev       The device
 * @param IntClear  Which interrupt source to clear. Use any combinations of #INTERRUPT_CLEAR_RANGING , #INTERRUPT_CLEAR_ERROR.
 * @return  0       On success
 */
VL6180_API int VL6180_ClearInterrupt(VL6180Dev_t dev, uint8_t IntClear);

/**
 * @brief Clear error interrupt
 *
 * @param dev    The device
 * @return  0    On success
 */
 #define VL6180_ClearErrorInterrupt(dev) VL6180_ClearInterrupt(dev, INTERRUPT_CLEAR_ERROR)

/**
 * @brief Clear All interrupt causes (range+error)
 *
 * @param dev    The device
 * @return  0    On success
 */
#define VL6180_ClearAllInterrupt(dev) VL6180_ClearInterrupt(dev, INTERRUPT_CLEAR_ERROR|INTERRUPT_CLEAR_RANGING)

/** @}  */


/** @defgroup api_reg API Register access functions
 *  @brief    Registers access functions called by API core functions
 *  @ingroup api_ll
 *  @{
 */

/**
 * Write VL6180 single byte register
 * @param dev   The device
 * @param index The register index
 * @param data  8 bit register data
 * @return success
 */
VL6180_API int VL6180_WrByte(VL6180Dev_t dev, uint16_t index, uint8_t data);
/**
 * Thread safe VL6180 Update (rd/modify/write) single byte register
 *
 * Final_reg = (Initial_reg & and_data) |or_data
 *
 * @param dev   The device
 * @param index The register index
 * @param AndData  8 bit and data
 * @param OrData   8 bit or data
 * @return 0 on success
 */
VL6180_API int VL6180_UpdateByte(VL6180Dev_t dev, uint16_t index, uint8_t AndData, uint8_t OrData);
/**
 * Write VL6180 word register
 * @param dev   The device
 * @param index The register index
 * @param data  16 bit register data
 * @return  0 on success
 */
VL6180_API int VL6180_WrWord(VL6180Dev_t dev, uint16_t index, uint16_t data);
/**
 * Write VL6180 double word (4 byte) register
 * @param dev   The device
 * @param index The register index
 * @param data  32 bit register data
 * @return  0 on success
 */
VL6180_API int VL6180_WrDWord(VL6180Dev_t dev, uint16_t index, uint32_t data);

/**
 * Read VL6180 single byte register
 * @param dev   The device
 * @param index The register index
 * @param data  pointer to 8 bit data
 * @return 0 on success
 */
VL6180_API int VL6180_RdByte(VL6180Dev_t dev, uint16_t index, uint8_t *data);

/**
 * Read VL6180 word (2byte) register
 * @param dev   The device
 * @param index The register index
 * @param data  pointer to 16 bit data
 * @return 0 on success
 */
VL6180_API int VL6180_RdWord(VL6180Dev_t dev, uint16_t index, uint16_t *data);

/**
 * Read VL6180 dword (4byte) register
 * @param dev   The device
 * @param index The register index
 * @param data  pointer to 32 bit data
 * @return 0 on success
 */
VL6180_API int VL6180_RdDWord(VL6180Dev_t dev, uint16_t index, uint32_t *data);


/**
 * Read VL6180 multiple bytes
 * @note required only if #VL6180_HAVE_MULTI_READ is set
 * @param dev   The device
 * @param index The register index
 * @param data  pointer to 8 bit data
 * @param nData number of data bytes to read
 * @return 0 on success
 */
VL6180_API int VL6180_RdMulti(VL6180Dev_t dev, uint16_t index, uint8_t *data, int nData);

/** @}  */




#ifdef __cplusplus
}
#endif

#endif /* VL6180_API_H_ */