ST Expansion SW Team
Updates to follow mbed SDK coding style guidelines.
Dependencies: ST_INTERFACES X_NUCLEO_COMMON
Dependents: 53L0A1_Satellites_with_Interrupts_OS5 Display_53L0A1_OS5
Fork of
X_NUCLEO_53L0A1
by 
ST
Revision 19:7f104764f458, committed 2017-06-26
- Comitter:
- JerrySzczurak
- Date:
- Mon Jun 26 13:40:27 2017 +0000
- Parent:
- 18:12995674c3a7
- Child:
- 20:cf211a3b3d9e
- Commit message:
- Added comments to functions derived from vl53l0x_api
Changed in this revision
| Components/VL53L0X/vl53l0x_class.h | Show annotated file Show diff for this revision Revisions of this file |
--- a/Components/VL53L0X/vl53l0x_class.h Mon Jun 26 08:26:08 2017 +0000
+++ b/Components/VL53L0X/vl53l0x_class.h Mon Jun 26 13:40:27 2017 +0000
@@ -1,5 +1,5 @@
/*******************************************************************************
- Copyright © 2016, STMicroelectronics International N.V.
+ Copyright © 2016, STMicroelectronics International N.V.
All rights reserved.
Redistribution and use in source and binary forms, with or without
@@ -1131,98 +1131,795 @@
private:
/* api.h functions */
+
+ /**
+ *
+ * @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 VL53L0X_WaitDeviceBooted()
+ *
+ * @par Function Description
+ * When not used after a fresh device "power up" or reset, it may return
+ * @a #VL53L0X_ERROR_CALIBRATION_WARNING meaning wrong calibration data
+ * may have been fetched from device that can result in ranging offset error\n
+ * If application cannot execute device reset or need to run VL53L0X_DataInit
+ * multiple time then it must ensure proper offset calibration saving and
+ * restore on its own by using @a VL53L0X_GetOffsetCalibrationData() on first
+ * power up and then @a VL53L0X_SetOffsetCalibrationData() in all subsequent init
+ * This function will change the VL53L0X_State from VL53L0X_STATE_POWERDOWN to
+ * VL53L0X_STATE_WAIT_STATICINIT.
+ *
+ * @note This function Access to the device
+ *
+ * @param dev Device Handle
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_data_init(VL53L0X_DEV dev);
+ /**
+ * @brief Get part to part calibration offset
+ *
+ * @par Function Description
+ * Should only be used after a successful call to @a VL53L0X_DataInit to backup
+ * device NVM value
+ *
+ * @note This function Access to the device
+ *
+ * @param dev Device Handle
+ * @param p_offset_calibration_data_micro_meter Return part to part
+ * calibration offset from device (microns)
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_get_offset_calibration_data_micro_meter(VL53L0X_DEV dev, int32_t *p_offset_calibration_data_micro_meter);
+ /**
+ * Set or over-hide part to part calibration offset
+ * \sa VL53L0X_DataInit() VL53L0X_GetOffsetCalibrationDataMicroMeter()
+ *
+ * @note This function Access to the device
+ *
+ * @param dev Device Handle
+ * @param p_offset_calibration_data_micro_meter Offset (microns)
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_set_offset_calibration_data_micro_meter(VL53L0X_DEV dev,
int32_t offset_calibration_data_micro_meter);
+ /**
+ * @brief Retrieve current device parameters
+ * @par Function Description
+ * Get actual parameters of the device
+ * @li Then start ranging operation.
+ *
+ * @note This function Access to the device
+ *
+ * @param dev Device Handle
+ * @param p_device_parameters Pointer to store current device parameters.
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_get_device_parameters(VL53L0X_DEV dev,
VL53L0X_DeviceParameters_t *p_device_parameters);
+ /**
+ * @brief Get current new device mode
+ * @par Function Description
+ * Get actual mode of the device(ranging, histogram ...)
+ *
+ * @note This function doesn't Access to the device
+ *
+ * @param dev Device Handle
+ * @param p_device_mode Pointer to current apply mode value
+ * Valid values are:
+ * VL53L0X_DEVICEMODE_SINGLE_RANGING
+ * VL53L0X_DEVICEMODE_CONTINUOUS_RANGING
+ * VL53L0X_DEVICEMODE_CONTINUOUS_TIMED_RANGING
+ * VL53L0X_DEVICEMODE_SINGLE_HISTOGRAM
+ * VL53L0X_HISTOGRAMMODE_REFERENCE_ONLY
+ * VL53L0X_HISTOGRAMMODE_RETURN_ONLY
+ * VL53L0X_HISTOGRAMMODE_BOTH
+ *
+ * @return VL53L0X_ERROR_NONE Success
+ * @return VL53L0X_ERROR_MODE_NOT_SUPPORTED This error occurs when
+ * DeviceMode is not in the supported list
+ */
VL53L0X_Error vl53l0x_get_device_mode(VL53L0X_DEV dev,
VL53L0X_DeviceModes *p_device_mode);
+ /**
+ * Get continuous mode Inter-Measurement period in milliseconds
+ *
+ * @par Function Description
+ * When trying to set too short time return INVALID_PARAMS minimal value
+ *
+ * @note This function Access to the device
+ *
+ * @param dev Device Handle
+ * @param p_inter_measurement_period_milli_seconds Pointer to programmed
+ * Inter-Measurement Period in milliseconds.
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_get_inter_measurement_period_milli_seconds(VL53L0X_DEV dev,
uint32_t *p_inter_measurement_period_milli_seconds);
+ /**
+ * @brief Get Cross talk compensation rate
+ *
+ * @par Function Description
+ * Get Cross talk compensation rate.
+ *
+ * @note This function Access to the device
+ *
+ * @param dev Device Handle
+ * @param p_xtalk_compensation_rate_mega_cps Pointer to Compensation rate
+ in Mega counts per second (16.16 fix point) see datasheet for details
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_get_x_talk_compensation_rate_mega_cps(VL53L0X_DEV dev,
FixPoint1616_t *p_xtalk_compensation_rate_mega_cps);
+ /**
+ * @brief Get a specific limit check value
+ *
+ * @par Function Description
+ * This function get a specific limit check value from device then it updates
+ * internal values and check enables.
+ * The limit check is identified with the LimitCheckId.
+ *
+ * @note This function Access to the device
+ *
+ * @param dev Device Handle
+ * @param limit_check_id Limit Check ID
+ * (0<= LimitCheckId < VL53L0X_GetNumberOfLimitCheck() ).
+ * @param p_limit_check_value Pointer to Limit
+ * check Value for a given LimitCheckId.
+ * @return VL53L0X_ERROR_NONE Success
+ * @return VL53L0X_ERROR_INVALID_PARAMS This error is returned
+ * when LimitCheckId value is out of range.
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_get_limit_check_value(VL53L0X_DEV dev, uint16_t limit_check_id,
FixPoint1616_t *p_limit_check_value);
+ /**
+ * @brief Get specific limit check enable state
+ *
+ * @par Function Description
+ * This function get the enable state of a specific limit check.
+ * The limit check is identified with the LimitCheckId.
+ *
+ * @note This function Access to the device
+ *
+ * @param dev Device Handle
+ * @param limit_check_id Limit Check ID
+ * (0<= LimitCheckId < VL53L0X_GetNumberOfLimitCheck() ).
+ * @param p_limit_check_enable Pointer to the check limit enable
+ * value.
+ * if 1 the check limit
+ * corresponding to LimitCheckId is Enabled
+ * if 0 the check limit
+ * corresponding to LimitCheckId is disabled
+ * @return VL53L0X_ERROR_NONE Success
+ * @return VL53L0X_ERROR_INVALID_PARAMS This error is returned
+ * when LimitCheckId value is out of range.
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_get_limit_check_enable(VL53L0X_DEV dev, uint16_t limit_check_id,
uint8_t *p_limit_check_enable);
+ /**
+ * @brief Get setup of Wrap around Check
+ *
+ * @par Function Description
+ * This function get the wrapAround check enable parameters
+ *
+ * @note This function Access to the device
+ *
+ * @param dev Device Handle
+ * @param p_wrap_around_check_enable Pointer to the Wrap around Check state
+ * 0=disabled or 1 = enabled
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_get_wrap_around_check_enable(VL53L0X_DEV dev,
uint8_t *p_wrap_around_check_enable);
+ /**
+ * @brief Get Ranging Timing Budget in microseconds
+ *
+ * @par Function Description
+ * Returns the programmed the maximum time allowed by the user to the
+ * device to run a full ranging sequence for the current mode
+ * (ranging, histogram, ASL ...)
+ *
+ * @note This function Access to the device
+ *
+ * @param dev Device Handle
+ * @param p_measurement_timing_budget_micro_seconds Max measurement time in
+ * microseconds.
+ * Valid values are:
+ * >= 17000 microsecs when wraparound enabled
+ * >= 12000 microsecs when wraparound disabled
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_get_measurement_timing_budget_micro_seconds(VL53L0X_DEV dev,
uint32_t *p_measurement_timing_budget_micro_seconds);
+
+ /**
+ * @brief Gets the (on/off) state of all sequence steps.
+ *
+ * @par Function Description
+ * This function retrieves the state of all sequence step in the scheduler.
+ *
+ * @note This function Accesses the device
+ *
+ * @param dev Device Handle
+ * @param p_scheduler_sequence_steps Pointer to struct containing result.
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_get_sequence_step_enables(VL53L0X_DEV dev,
VL53L0X_SchedulerSequenceSteps_t *p_scheduler_sequence_steps);
- VL53L0X_Error sequence_step_enabled(VL53L0X_DEV dev,
- VL53L0X_SequenceStepId sequence_step_id, uint8_t sequence_config,
- uint8_t *p_sequence_step_enabled);
+ /**
+ * @brief Gets the VCSEL pulse period.
+ *
+ * @par Function Description
+ * This function retrieves the VCSEL pulse period for the given period type.
+ *
+ * @note This function Accesses the device
+ *
+ * @param dev Device Handle
+ * @param vcsel_period_type VCSEL period identifier (pre-range|final).
+ * @param p_vcsel_pulse_period_pclk Pointer to VCSEL period value.
+ * @return VL53L0X_ERROR_NONE Success
+ * @return VL53L0X_ERROR_INVALID_PARAMS Error VcselPeriodType parameter not
+ * supported.
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_get_vcsel_pulse_period(VL53L0X_DEV dev,
VL53L0X_VcselPeriod vcsel_period_type, uint8_t *p_vcsel_pulse_period_pclk);
+ /**
+ * @brief Reads the Device information for given Device
+ *
+ * @note This function Access to the device
+ *
+ * @param dev Device Handle
+ * @param p_vl53l0x_device_info Pointer to current device info for a given
+ * Device
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_get_device_info(VL53L0X_DEV dev,
VL53L0X_DeviceInfo_t *p_vl53l0x_device_info);
+ /**
+ * @brief Do basic device init (and eventually patch loading)
+ * This function will change the VL53L0X_State from
+ * VL53L0X_STATE_WAIT_STATICINIT to VL53L0X_STATE_IDLE.
+ * In this stage all default setting will be applied.
+ *
+ * @note This function Access to the device
+ *
+ * @param dev Device Handle
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_static_init(VL53L0X_DEV dev);
+
+ /**
+ * @brief Return Measurement Data Ready
+ *
+ * @par Function Description
+ * This function indicate that a measurement data is ready.
+ * This function check if interrupt mode is used then check is done accordingly.
+ * If perform function clear the interrupt, this function will not work,
+ * like in case of @a VL53L0X_PerformSingleRangingMeasurement().
+ * The previous function is blocking function, VL53L0X_GetMeasurementDataReady
+ * is used for non-blocking capture.
+ *
+ * @note This function Access to the device
+ *
+ * @param dev Device Handle
+ * @param p_measurement_data_ready Pointer to Measurement Data Ready.
+ * 0=data not ready, 1 = data ready
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_get_measurement_data_ready(VL53L0X_DEV dev,
uint8_t *p_measurement_data_ready);
+ /**
+ * @brief Return device interrupt status
+ *
+ * @par Function Description
+ * Returns currently raised interrupts by the device.
+ * User shall be able to activate/deactivate interrupts through
+ * @a VL53L0X_SetGpioConfig()
+ *
+ * @note This function Access to the device
+ *
+ * @param dev Device Handle
+ * @param p_interrupt_mask_status Pointer to status variable to update
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_get_interrupt_mask_status(VL53L0X_DEV dev,
uint32_t *p_interrupt_mask_status);
+ /**
+ * @brief Clear given system interrupt condition
+ *
+ * @par Function Description
+ * Clear given interrupt(s).
+ *
+ * @note This function Access to the device
+ *
+ * @param dev Device Handle
+ * @param interrupt_mask Mask of interrupts to clear
+ * @return VL53L0X_ERROR_NONE Success
+ * @return VL53L0X_ERROR_INTERRUPT_NOT_CLEARED Cannot clear interrupts
+ *
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_clear_interrupt_mask(VL53L0X_DEV dev, uint32_t interrupt_mask);
+ /**
+ * @brief Performs a single ranging measurement and retrieve the ranging
+ * measurement data
+ *
+ * @par Function Description
+ * This function will change the device mode to VL53L0X_DEVICEMODE_SINGLE_RANGING
+ * with @a VL53L0X_SetDeviceMode(),
+ * It performs measurement with @a VL53L0X_PerformSingleMeasurement()
+ * It get data from last successful Ranging measurement with
+ * @a VL53L0X_GetRangingMeasurementData.
+ * Finally it clear the interrupt with @a VL53L0X_ClearInterruptMask().
+ *
+ * @note This function Access to the device
+ *
+ * @note This function change the device mode to
+ * VL53L0X_DEVICEMODE_SINGLE_RANGING
+ *
+ * @param dev Device Handle
+ * @param p_ranging_measurement_data Pointer to the data structure to fill up.
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_perform_single_ranging_measurement(VL53L0X_DEV dev,
VL53L0X_RangingMeasurementData_t *p_ranging_measurement_data);
+ /**
+ * @brief Set a new device mode
+ * @par Function Description
+ * Set device to a new mode (ranging, histogram ...)
+ *
+ * @note This function doesn't Access to the device
+ *
+ * @param dev Device Handle
+ * @param device_mode New device mode to apply
+ * Valid values are:
+ * VL53L0X_DEVICEMODE_SINGLE_RANGING
+ * VL53L0X_DEVICEMODE_CONTINUOUS_RANGING
+ * VL53L0X_DEVICEMODE_CONTINUOUS_TIMED_RANGING
+ * VL53L0X_DEVICEMODE_SINGLE_HISTOGRAM
+ * VL53L0X_HISTOGRAMMODE_REFERENCE_ONLY
+ * VL53L0X_HISTOGRAMMODE_RETURN_ONLY
+ * VL53L0X_HISTOGRAMMODE_BOTH
+ *
+ *
+ * @return VL53L0X_ERROR_NONE Success
+ * @return VL53L0X_ERROR_MODE_NOT_SUPPORTED This error occurs when DeviceMode is
+ * not in the supported list
+ */
VL53L0X_Error vl53l0x_set_device_mode(VL53L0X_DEV dev, VL53L0X_DeviceModes device_mode);
+ /**
+ * @brief Single shot measurement.
+ *
+ * @par Function Description
+ * Perform simple measurement sequence (Start measure, Wait measure to end,
+ * and returns when measurement is done).
+ * Once function returns, user can get valid data by calling
+ * VL53L0X_GetRangingMeasurement or VL53L0X_GetHistogramMeasurement
+ * depending on defined measurement mode
+ * User should Clear the interrupt in case this are enabled by using the
+ * function VL53L0X_ClearInterruptMask().
+ *
+ * @warning This function is a blocking function
+ *
+ * @note This function Access to the device
+ *
+ * @param dev Device Handle
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_perform_single_measurement(VL53L0X_DEV dev);
+ /**
+ * @brief Start device measurement
+ *
+ * @details Started measurement will depend on device parameters set through
+ * @a VL53L0X_SetParameters()
+ * This is a non-blocking function.
+ * This function will change the VL53L0X_State from VL53L0X_STATE_IDLE to
+ * VL53L0X_STATE_RUNNING.
+ *
+ * @note This function Access to the device
+ *
+
+ * @param dev Device Handle
+ * @return VL53L0X_ERROR_NONE Success
+ * @return VL53L0X_ERROR_MODE_NOT_SUPPORTED This error occurs when
+ * DeviceMode programmed with @a VL53L0X_SetDeviceMode is not in the supported
+ * list:
+ * Supported mode are:
+ * VL53L0X_DEVICEMODE_SINGLE_RANGING,
+ * VL53L0X_DEVICEMODE_CONTINUOUS_RANGING,
+ * VL53L0X_DEVICEMODE_CONTINUOUS_TIMED_RANGING
+ * @return VL53L0X_ERROR_TIME_OUT Time out on start measurement
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_start_measurement(VL53L0X_DEV dev);
- VL53L0X_Error vl53l0x_check_and_load_interrupt_settings(VL53L0X_DEV dev,
- uint8_t start_not_stopflag);
+
+ /**
+ * @brief Set low and high Interrupt thresholds for a given mode
+ * (ranging, ALS, ...) for a given device
+ *
+ * @par Function Description
+ * Set low and high Interrupt thresholds for a given mode (ranging, ALS, ...)
+ * for a given device
+ *
+ * @note This function Access to the device
+ *
+ * @note DeviceMode is ignored for the current device
+ *
+ * @param dev Device Handle
+ * @param device_mode Device Mode for which change thresholds
+ * @param threshold_low Low threshold (mm, lux ..., depending on the mode)
+ * @param threshold_high High threshold (mm, lux ..., depending on the mode)
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_set_interrupt_thresholds(VL53L0X_DEV dev,
VL53L0X_DeviceModes device_mode, FixPoint1616_t threshold_low,
FixPoint1616_t threshold_high);
+ /**
+ * @brief Get high and low Interrupt thresholds for a given mode
+ * (ranging, ALS, ...) for a given device
+ *
+ * @par Function Description
+ * Get high and low Interrupt thresholds for a given mode (ranging, ALS, ...)
+ * for a given device
+ *
+ * @note This function Access to the device
+ *
+ * @note DeviceMode is ignored for the current device
+ *
+ * @param dev Device Handle
+ * @param device_mode Device Mode from which read thresholds
+ * @param p_threshold_low Low threshold (mm, lux ..., depending on the mode)
+ * @param p_threshold_high High threshold (mm, lux ..., depending on the mode)
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_get_interrupt_thresholds(VL53L0X_DEV dev,
VL53L0X_DeviceModes device_mode, FixPoint1616_t *p_threshold_low,
FixPoint1616_t *p_threshold_high);
+
+ /**
+ * @brief Retrieve the measurements from device for a given setup
+ *
+ * @par Function Description
+ * Get data from last successful Ranging measurement
+ * @warning USER should take care about @a VL53L0X_GetNumberOfROIZones()
+ * before get data.
+ * PAL will fill a NumberOfROIZones times the corresponding data
+ * structure used in the measurement function.
+ *
+ * @note This function Access to the device
+ *
+ * @param dev Device Handle
+ * @param p_ranging_measurement_data Pointer to the data structure to fill up.
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_get_ranging_measurement_data(VL53L0X_DEV dev,
VL53L0X_RangingMeasurementData_t *p_ranging_measurement_data);
+ /**
+ * @brief Get Cross talk compensation rate
+ *
+ * @note This function is not Implemented.
+ * Enable/Disable Cross Talk by set to zero the Cross Talk value by
+ * using @a VL53L0X_SetXTalkCompensationRateMegaCps().
+ *
+ * @param dev Device Handle
+ * @param p_x_talk_compensation_enable Pointer to the Cross talk compensation
+ * state 0=disabled or 1 = enabled
+ * @return VL53L0X_ERROR_NOT_IMPLEMENTED Not implemented
+ */
VL53L0X_Error vl53l0x_get_x_talk_compensation_enable(VL53L0X_DEV dev,
uint8_t *p_x_talk_compensation_enable);
+ /**
+ * @brief Wait for device booted after chip enable (hardware standby)
+ * This function can be run only when VL53L0X_State is VL53L0X_STATE_POWERDOWN.
+ *
+ * @note This function is not Implemented
+ *
+ * @param dev Device Handle
+ * @return VL53L0X_ERROR_NOT_IMPLEMENTED Not implemented
+ *
+ */
VL53L0X_Error vl53l0x_wait_device_booted(VL53L0X_DEV dev);
+ /**
+ * @brief Perform Reference Calibration
+ *
+ * @details Perform a reference calibration of the Device.
+ * This function should be run from time to time before doing
+ * a ranging measurement.
+ * This function will launch a special ranging measurement, so
+ * if interrupt are enable an interrupt will be done.
+ * This function will clear the interrupt generated automatically.
+ *
+ * @warning This function is a blocking function
+ *
+ * @note This function Access to the device
+ *
+ * @param dev Device Handle
+ * @param p_vhv_settings Pointer to vhv settings parameter.
+ * @param p_phase_cal Pointer to PhaseCal parameter.
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_perform_ref_calibration(VL53L0X_DEV dev, uint8_t *p_vhv_settings,
uint8_t *p_phase_cal);
+ /**
+ * @brief Performs Reference Spad Management
+ *
+ * @par Function Description
+ * The reference SPAD initialization procedure determines the minimum amount
+ * of reference spads to be enables to achieve a target reference signal rate
+ * and should be performed once during initialization.
+ *
+ * @note This function Access to the device
+ *
+ * @note This function change the device mode to
+ * VL53L0X_DEVICEMODE_SINGLE_RANGING
+ *
+ * @param dev Device Handle
+ * @param ref_spad_count Reports ref Spad Count
+ * @param is_aperture_spads Reports if spads are of type
+ * aperture or non-aperture.
+ * 1:=aperture, 0:=Non-Aperture
+ * @return VL53L0X_ERROR_NONE Success
+ * @return VL53L0X_ERROR_REF_SPAD_INIT Error in the Ref Spad procedure.
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_perform_ref_spad_management(VL53L0X_DEV dev,
uint32_t *ref_spad_count, uint8_t *is_aperture_spads);
+ /**
+ * @brief Set new device address
+ *
+ * After completion the device will answer to the new address programmed.
+ * This function should be called when several devices are used in parallel
+ * before start programming the sensor.
+ * When a single device us used, there is no need to call this function.
+ *
+ * @note This function Access to the device
+ *
+ * @param dev Device Handle
+ * @param device_address The new Device address
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_set_device_address(VL53L0X_DEV dev, uint8_t device_address);
+ /**
+ * @brief Set the configuration of GPIO pin for a given device
+ *
+ * @note This function Access to the device
+ *
+ * @param dev Device Handle
+ * @param pin ID of the GPIO Pin
+ * @param functionality Select Pin functionality.
+ * Refer to ::VL53L0X_GpioFunctionality
+ * @param device_mode Device Mode associated to the Gpio.
+ * @param polarity Set interrupt polarity. Active high
+ * or active low see ::VL53L0X_InterruptPolarity
+ * @return VL53L0X_ERROR_NONE Success
+ * @return VL53L0X_ERROR_GPIO_NOT_EXISTING Only Pin=0 is accepted.
+ * @return VL53L0X_ERROR_GPIO_FUNCTIONALITY_NOT_SUPPORTED This error occurs
+ * when Functionality programmed is not in the supported list:
+ * Supported value are:
+ * VL53L0X_GPIOFUNCTIONALITY_OFF,
+ * VL53L0X_GPIOFUNCTIONALITY_THRESHOLD_CROSSED_LOW,
+ * VL53L0X_GPIOFUNCTIONALITY_THRESHOLD_CROSSED_HIGH,
+ VL53L0X_GPIOFUNCTIONALITY_THRESHOLD_CROSSED_OUT,
+ * VL53L0X_GPIOFUNCTIONALITY_NEW_MEASURE_READY
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_set_gpio_config(VL53L0X_DEV dev, uint8_t pin,
VL53L0X_DeviceModes device_mode, VL53L0X_GpioFunctionality functionality,
VL53L0X_InterruptPolarity polarity);
+ /**
+ * @brief Gets the fraction enable parameter indicating the resolution of
+ * range measurements.
+ *
+ * @par Function Description
+ * Gets the fraction enable state, which translates to the resolution of
+ * range measurements as follows :Enabled:=0.25mm resolution,
+ * Not Enabled:=1mm resolution.
+ *
+ * @note This function Accesses the device
+ *
+ * @param dev Device Handle
+ * @param p_enabled Output Parameter reporting the fraction enable state.
+ *
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_get_fraction_enable(VL53L0X_DEV dev, uint8_t *p_enabled);
+
+ /**
+ * @brief Sets the (on/off) state of a requested sequence step.
+ *
+ * @par Function Description
+ * This function enables/disables a requested sequence step.
+ *
+ * @note This function Accesses the device
+ *
+ * @param dev Device Handle
+ * @param sequence_step_id Sequence step identifier.
+ * @param sequence_step_enabled Demanded state {0=Off,1=On}
+ * is enabled.
+ * @return VL53L0X_ERROR_NONE Success
+ * @return VL53L0X_ERROR_INVALID_PARAMS Error SequenceStepId parameter not
+ * supported.
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_set_sequence_step_enable(VL53L0X_DEV dev,
VL53L0X_SequenceStepId sequence_step_id, uint8_t sequence_step_enabled);
+ /**
+ * @brief Set Ranging Timing Budget in microseconds
+ *
+ * @par Function Description
+ * Defines the maximum time allowed by the user to the device to run a
+ * full ranging sequence for the current mode (ranging, histogram, ASL ...)
+ *
+ * @note This function Access to the device
+ *
+ * @param dev Device Handle
+ * @param measurement_timing_budget_micro_seconds Max measurement time in
+ * microseconds.
+ * Valid values are:
+ * >= 17000 microsecs when wraparound enabled
+ * >= 12000 microsecs when wraparound disabled
+ * @return VL53L0X_ERROR_NONE Success
+ * @return VL53L0X_ERROR_INVALID_PARAMS This error is returned if
+ MeasurementTimingBudgetMicroSeconds out of range
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_set_measurement_timing_budget_micro_seconds(VL53L0X_DEV dev,
uint32_t measurement_timing_budget_micro_seconds);
+ /**
+ * @brief Enable/Disable a specific limit check
+ *
+ * @par Function Description
+ * This function Enable/Disable a specific limit check.
+ * The limit check is identified with the LimitCheckId.
+ *
+ * @note This function doesn't Access to the device
+ *
+ * @param dev Device Handle
+ * @param limit_check_id Limit Check ID
+ * (0<= LimitCheckId < VL53L0X_GetNumberOfLimitCheck() ).
+ * @param limit_check_enable if 1 the check limit
+ * corresponding to LimitCheckId is Enabled
+ * if 0 the check limit
+ * corresponding to LimitCheckId is disabled
+ * @return VL53L0X_ERROR_NONE Success
+ * @return VL53L0X_ERROR_INVALID_PARAMS This error is returned
+ * when LimitCheckId value is out of range.
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_set_limit_check_enable(VL53L0X_DEV dev, uint16_t limit_check_id,
uint8_t limit_check_enable);
+ /**
+ * @brief Set a specific limit check value
+ *
+ * @par Function Description
+ * This function set a specific limit check value.
+ * The limit check is identified with the LimitCheckId.
+ *
+ * @note This function Access to the device
+ *
+ * @param dev Device Handle
+ * @param limit_check_id Limit Check ID
+ * (0<= LimitCheckId < VL53L0X_GetNumberOfLimitCheck() ).
+ * @param limit_check_value Limit check Value for a given
+ * LimitCheckId
+ * @return VL53L0X_ERROR_NONE Success
+ * @return VL53L0X_ERROR_INVALID_PARAMS This error is returned when either
+ * LimitCheckId or LimitCheckValue value is out of range.
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_set_limit_check_value(VL53L0X_DEV dev, uint16_t limit_check_id,
FixPoint1616_t limit_check_value);
+ /**
+ * @brief Stop device measurement
+ *
+ * @details Will set the device in standby mode at end of current measurement\n
+ * Not necessary in single mode as device shall return automatically
+ * in standby mode at end of measurement.
+ * This function will change the VL53L0X_State from VL53L0X_STATE_RUNNING
+ * to VL53L0X_STATE_IDLE.
+ *
+ * @note This function Access to the device
+ *
+ * @param dev Device Handle
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_stop_measurement(VL53L0X_DEV dev);
+ /**
+ * @brief Return device stop completion status
+ *
+ * @par Function Description
+ * Returns stop completiob status.
+ * User shall call this function after a stop command
+ *
+ * @note This function Access to the device
+ *
+ * @param dev Device Handle
+ * @param p_stop_status Pointer to status variable to update
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_get_stop_completed_status(VL53L0X_DEV dev,
uint32_t *p_stop_status);
+ /**
+ * @brief Sets the VCSEL pulse period.
+ *
+ * @par Function Description
+ * This function retrieves the VCSEL pulse period for the given period type.
+ *
+ * @note This function Accesses the device
+ *
+ * @param dev Device Handle
+ * @param vcsel_period_type VCSEL period identifier (pre-range|final).
+ * @param vcsel_pulse_period VCSEL period value
+ * @return VL53L0X_ERROR_NONE Success
+ * @return VL53L0X_ERROR_INVALID_PARAMS Error VcselPeriodType parameter not
+ * supported.
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_set_vcsel_pulse_period(VL53L0X_DEV dev,
VL53L0X_VcselPeriod vcsel_period_type, uint8_t vcsel_pulse_period);
+
+ VL53L0X_Error sequence_step_enabled(VL53L0X_DEV dev,
+ VL53L0X_SequenceStepId sequence_step_id, uint8_t sequence_config,
+ uint8_t *p_sequence_step_enabled);
+
+ VL53L0X_Error vl53l0x_check_and_load_interrupt_settings(VL53L0X_DEV dev,
+ uint8_t start_not_stopflag);
+
+
/* api_core.h functions */
+
VL53L0X_Error vl53l0x_get_info_from_device(VL53L0X_DEV dev, uint8_t option);
+
VL53L0X_Error vl53l0x_device_read_strobe(VL53L0X_DEV dev);
+
VL53L0X_Error wrapped_vl53l0x_get_measurement_timing_budget_micro_seconds(VL53L0X_DEV dev,
uint32_t *p_measurement_timing_budget_micro_seconds);
+
VL53L0X_Error wrapped_vl53l0x_get_vcsel_pulse_period(VL53L0X_DEV dev,
VL53L0X_VcselPeriod vcsel_period_type, uint8_t *p_vcsel_pulse_period_pclk);
+
uint8_t vl53l0x_decode_vcsel_period(uint8_t vcsel_period_reg);
+
uint32_t vl53l0x_decode_timeout(uint16_t encoded_timeout);
+
uint32_t vl53l0x_calc_timeout_us(VL53L0X_DEV dev,
uint16_t timeout_period_mclks,
uint8_t vcsel_period_pclks);
+
uint32_t vl53l0x_calc_macro_period_ps(VL53L0X_DEV dev, uint8_t vcsel_period_pclks);
+
VL53L0X_Error vl53l0x_measurement_poll_for_completion(VL53L0X_DEV dev);
+
VL53L0X_Error vl53l0x_load_tuning_settings(VL53L0X_DEV dev,
uint8_t *p_tuning_setting_buffer);
+
VL53L0X_Error vl53l0x_get_pal_range_status(VL53L0X_DEV dev,
uint8_t device_range_status,
FixPoint1616_t signal_rate,
@@ -1321,24 +2018,134 @@
virtual int read_id(uint8_t *id);
VL53L0X_Error wait_measurement_data_ready(VL53L0X_DEV dev);
+
VL53L0X_Error wait_stop_completed(VL53L0X_DEV dev);
/* Write and read functions from I2C */
-
+ /**
+ * Write single byte register
+ * @param dev Device Handle
+ * @param index The register index
+ * @param data 8 bit register data
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_write_byte(VL53L0X_DEV dev, uint8_t index, uint8_t data);
+ /**
+ * Write word register
+ * @param dev Device Handle
+ * @param index The register index
+ * @param data 16 bit register data
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_write_word(VL53L0X_DEV dev, uint8_t index, uint16_t data);
+ /**
+ * Write double word (4 byte) register
+ * @param dev Device Handle
+ * @param index The register index
+ * @param data 32 bit register data
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_write_dword(VL53L0X_DEV dev, uint8_t index, uint32_t data);
+ /**
+ * Read single byte register
+ * @param dev Device Handle
+ * @param index The register index
+ * @param data pointer to 8 bit data
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_read_byte(VL53L0X_DEV dev, uint8_t index, uint8_t *p_data);
+ /**
+ * Read word (2byte) register
+ * @param dev Device Handle
+ * @param index The register index
+ * @param data pointer to 16 bit data
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_read_word(VL53L0X_DEV dev, uint8_t index, uint16_t *p_data);
+ /**
+ * Read dword (4byte) register
+ * @param dev Device Handle
+ * @param index The register index
+ * @param data pointer to 32 bit data
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_read_dword(VL53L0X_DEV dev, uint8_t index, uint32_t *p_data);
+ /**
+ * Threat safe Update (read/modify/write) single byte register
+ *
+ * Final_reg = (Initial_reg & and_data) |or_data
+ *
+ * @param dev Device Handle
+ * @param index The register index
+ * @param and_data 8 bit and data
+ * @param or_data 8 bit or data
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_update_byte(VL53L0X_DEV dev, uint8_t index, uint8_t and_data, uint8_t or_data);
-
+ /**
+ * Writes the supplied byte buffer to the device
+ * @param dev Device Handle
+ * @param index The register index
+ * @param p_data Pointer to uint8_t buffer containing the data to be written
+ * @param count Number of bytes in the supplied byte buffer
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_write_multi(VL53L0X_DEV dev, uint8_t index, uint8_t *p_data, uint32_t count);
+ /**
+ * Reads the requested number of bytes from the device
+ * @param dev Device Handle
+ * @param index The register index
+ * @param p_data Pointer to the uint8_t buffer to store read data
+ * @param count Number of uint8_t's to read
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_read_multi(VL53L0X_DEV dev, uint8_t index, uint8_t *p_data, uint32_t count);
+ /**
+ * @brief Writes a buffer towards the I2C peripheral device.
+ * @param dev Device Handle
+ * @param p_data pointer to the byte-array data to send
+ * @param number_of_bytes number of bytes to be written.
+ * @retval 0 if ok,
+ * @retval -1 if an I2C error has occured
+ * @note On some devices if NumByteToWrite is greater
+ * than one, the RegisterAddr must be masked correctly!
+ */
VL53L0X_Error vl53l0x_i2c_write(uint8_t dev, uint8_t index, uint8_t *p_data, uint16_t number_of_bytes);
+
+ /**
+ * @brief Reads a buffer from the I2C peripheral device.
+ * @param dev Device Handle
+ * @param p_data pointer to the byte-array to read data in to
+ * @param number_of_bytes number of bytes to be read.
+ * @retval 0 if ok,
+ * @retval -1 if an I2C error has occured
+ * @note On some devices if NumByteToWrite is greater
+ * than one, the RegisterAddr must be masked correctly!
+ */
VL53L0X_Error vl53l0x_i2c_read(uint8_t dev, uint8_t index, uint8_t *p_data, uint16_t number_of_bytes);
+ /**
+ * @brief execute delay in all polling API call
+ *
+ * A typical multi-thread or RTOs implementation is to sleep the task for some 5ms (with 100Hz max rate faster polling is not needed)
+ * if nothing specific is need you can define it as an empty/void macro
+ * @code
+ * #define VL53L0X_PollingDelay(...) (void)0
+ * @endcode
+ * @param dev Device Handle
+ * @return VL53L0X_ERROR_NONE Success
+ * @return "Other error code" See ::VL53L0X_Error
+ */
VL53L0X_Error vl53l0x_polling_delay(VL53L0X_DEV dev); /* usually best implemented as a real function */
int is_present()
@@ -1380,7 +2187,3 @@
#endif /* _VL53L0X_CLASS_H_ */
-
-
-
-