I2C device driver for the VL53L0X ToF ranging chip. More...

#include <fastarduino/devices/vl53l0x.h>

Inheritance diagram for devices::vl53l0x::VL53L0X< MANAGER >:

Collaboration diagram for devices::vl53l0x::VL53L0X< MANAGER >:

Classes
class	GetGPIOSettingsFuture
	Future to get device current GPIO settings. More...

class	SetGPIOSettingsFuture
	Future to set device GPIO settings. More...

Public Types
using	GetRangeStatusFuture = TReadRegisterFuture< Register::RESULT_RANGE_STATUS, DeviceStatus >
	Future to get device range status. More...

using	GetInterruptStatusFuture = TReadRegisterFuture< Register::RESULT_INTERRUPT_STATUS, InterruptStatus >
	Future to get device current interrupt status. More...

using	ClearInterruptFuture = TWriteRegisterFuture< Register::SYSTEM_INTERRUPT_CLEAR >
	Future to clear device interrupt status. More...

using	GetDirectRangeFuture = TReadRegisterFuture< Register::RESULT_RANGE_MILLIMETER, uint16_t >
	Future to get device current range measure. More...

Public Types inherited from i2c::I2CDevice< MANAGER >
using	MANAGER = MANAGER
	the type of I2C Manager that can handle this device. More...

Public Member Functions
	VL53L0X (MANAGER &manager)
	Create a new device driver for a VL53L0X chip. More...

bool	set_address (uint8_t device_address)
	Change the I2C address of this VL53L0X device. More...

bool	begin (Profile profile)
	Fully initialize this VL53L0X device and configures it with provided `profile`. More...

template<board::Timer TIMER>
bool	await_single_range (timer::RTT< TIMER > &rtt, uint16_t &range_mm, uint16_t timeout_ms=DEFAULT_TIMEOUT_MS)
	Perform a single range action on VL53L0X device, and wait for the measurement result. More...

bool	start_continuous_ranging (uint16_t period_ms=0)
	Start continuous ranging on this VL53L0X device. More...

template<board::Timer TIMER>
bool	await_continuous_range (timer::RTT< TIMER > &rtt, uint16_t &range_mm, uint16_t timeout_ms=DEFAULT_TIMEOUT_MS)
	Wait for the next continuous ranging measure on VL53L0X device to be ready and return the result. More...

bool	stop_continuous_ranging ()
	Stop continuous ranging on this VL53L0X device. More...

bool	reset_device ()
	Reset VL53L0X device. More...

bool	init_data_first ()
	Perform 1st stage initialization of this VL53L0X device. More...

bool	init_static_second (const GPIOSettings &settings, SequenceSteps steps=SequenceSteps::create().pre_range().final_range().dss())
	Perform 2nd stage initialization of this VL53L0X device. More...

bool	perform_ref_calibration ()
	Perform VL53L0X VHV and Phase calibration. More...

int	get_range_status (GetRangeStatusFuture &future)
	Get current `DeviceStatus` from this device. More...

bool	get_range_status (DeviceStatus &range_status)
	Get current `DeviceStatus` from this device. More...

int	get_GPIO_settings (GetGPIOSettingsFuture &future)
	Get current `GPIOSettings` from this device. More...

bool	get_GPIO_settings (GPIOSettings &settings)
	Get current `GPIOSettings` from this device. More...

int	set_GPIO_settings (SetGPIOSettingsFuture &future)
	Set new `GPIOSettings` for this device. More...

bool	set_GPIO_settings (const GPIOSettings &settings)
	Set new `GPIOSettings` for this device. More...

int	get_interrupt_status (GetInterruptStatusFuture &future)
	Get current `InterruptStatus` from this device. More...

bool	get_interrupt_status (InterruptStatus &status)
	Get current `InterruptStatus` from this device. More...

int	clear_interrupt (ClearInterruptFuture &future)
	Clear interrupt status from this device. More...

bool	clear_interrupt (uint8_t clear_mask=0x01)
	Clear interrupt status from this device. More...

template<board::Timer TIMER>
bool	await_interrupt (timer::RTT< TIMER > &rtt, uint16_t timeout_ms=DEFAULT_TIMEOUT_MS)
	Wait for an interrupt condition on VL53L0X device. More...

int	get_direct_range (GetDirectRangeFuture &future)
	Get range measured by this device. More...

bool	get_direct_range (uint16_t &range_mm)
	Get range measured by this device. More...

bool	set_measurement_timing_budget (uint32_t budget_us)
	Set new "measurement timing budget" for this device. More...

bool	get_measurement_timing_budget (uint32_t &budget_us)
	Get current "measurement timing budget" for this device. More...

bool	set_sequence_steps (SequenceSteps sequence_steps)
	Set measurement steps to be executed in sequence by the device during ranging. More...

bool	get_sequence_steps (SequenceSteps &sequence_steps)
	Get current measurement steps executed in sequence by the device during ranging. More...

template<VcselPeriodType TYPE>
bool	set_vcsel_pulse_period (uint8_t period)
	Set new pulse period of the VCSEL for pre-range or final-range step. More...

template<VcselPeriodType TYPE>
bool	get_vcsel_pulse_period (uint8_t &period)
	Get current pulse period of the VCSEL for pre-range or final-range step. More...

bool	set_signal_rate_limit (float signal_rate)
	Set new signal rate limit for ranging. More...

bool	get_signal_rate_limit (float &signal_rate)
	Get current signal rate limit for ranging. More...

bool	get_power_mode (PowerMode &power_mode)
	Get current power mode of this VL53L0X register. More...

bool	get_model (uint8_t &model)
	Get model of this VL53L0X register. More...

bool	get_revision (uint8_t &revision)
	Get revision of this VL53L0X register. More...

bool	await_interrupt (uint16_t loops=MAX_LOOP)
	Wait for an interrupt condition on VL53L0X device. More...

bool	await_continuous_range (uint16_t &range_mm, uint16_t loops=MAX_LOOP)
	Wait for the next continuous ranging measure on VL53L0X device to be ready and return the result. More...

bool	await_single_range (uint16_t &range_mm, uint16_t loops=MAX_LOOP)
	Perform a single range action on VL53L0X device, and wait for the measurement result. More...

bool	get_reference_SPADs (SPADReference &spad_ref)
	Get the reference SPADs status (enabled or not). More...

bool	set_reference_SPADs (const SPADReference &spad_ref)
	Set the reference SPADs status (enabled or not). More...

bool	get_SPAD_info (SPADInfo &info)
	Get current SPAD information (number of SPAD aperture or not). More...

bool	get_sequence_steps_timeout (SequenceStepsTimeout &timeouts)
	Get current timeouts associated to each ranging step. More...

template<Register REGISTER, typename T = uint8_t>
int	get_register (TReadRegisterFuture< REGISTER, T > &future)
	Directly get value of a VL53L0X register. More...

template<Register REGISTER, typename T = uint8_t>
int	set_register (TWriteRegisterFuture< REGISTER, T > &future)
	Directly set value of a VL53L0X register. More...

template<Register REGISTER, typename T = uint8_t>
bool	get_register (T &value)
	Directly get value of a VL53L0X register. More...

template<Register REGISTER, typename T = uint8_t>
bool	set_register (T value)
	Directly set value of a VL53L0X register. More...

Additional Inherited Members
Protected Types inherited from i2c::I2CDevice< MANAGER >
using	ABSTRACT_FUTURE = typename MANAGER::ABSTRACT_FUTURE
	The abstract base class of all futures to be defined for a device. More...

using	FUTURE = typename MANAGER::template FUTURE< OUT, IN >
	The template base class of all futures to be defined for a device. More...

Protected Member Functions inherited from i2c::I2CDevice< MANAGER >
	I2CDevice (MANAGER &manager, uint8_t device, UNUSED Mode< MODE > mode, bool auto_stop)
	Create a new I2C device. More...

	I2CDevice (const I2CDevice &)=delete

I2CDevice &	operator= (const I2CDevice &)=delete

void	set_device (uint8_t device)
	Change the I2C address of this device. More...

int	launch_commands (ABSTRACT_FUTURE &future, utils::range< I2CLightCommand > commands)
	Launch execution (asynchronously or synchronously, depending on MANAGER) of a chain of I2CLightCommand items (constructed with `read()` and `write()` methods). More...

int	async_read (F &future, bool stop=true)
	Helper method that asynchronously launches I2C commands for a simple Future performing one write followed by one read (typically for device register reading). More...

bool	sync_read (T &result)
	Helper method that launches I2C commands for a simple Future performing one write followed by one read (typically for device register reading); the method blocks until the end of the I2C transaction. More...

int	async_write (F &future, bool stop=true)
	Helper method that asynchronously launches I2C commands for a simple Future performing only one write (typically for device register writing). More...

int	async_multi_write (F &future, bool stop=true)
	Helper method that asynchronously launches I2C commands for a simple Future performing several register writes. More...

bool	sync_write (const T &value)
	Helper method that launches I2C commands for a simple Future performing only one write (typically for device register writing); the method blocks until the end of the I2C transaction. More...

bool	sync_write ()
	Helper method that launches I2C commands for a simple Future performing only one write (typically for device register writing); the method blocks until the end of the I2C transaction. More...

Static Protected Member Functions inherited from i2c::I2CDevice< MANAGER >
static constexpr I2CLightCommand	read (uint8_t read_count=0, bool finish_future=false, bool stop=false)
	Build a read I2CLightCommand that can be later pushed to the I2C Manager for proper handling. More...

static constexpr I2CLightCommand	write (uint8_t write_count=0, bool finish_future=false, bool stop=false)
	Build a write I2CLightCommand that can be later pushed to the I2C Manager for proper handling. More...

Detailed Description

template<typename MANAGER>
class devices::vl53l0x::VL53L0X< MANAGER >

I2C device driver for the VL53L0X ToF ranging chip.

This chip supports both standard and fast I2C modes.

Several levels of API are provided:

low-level API : reserved to developers who know how the VL53L0X device works and know what they do
mid-level API : for common use where developers need fine level of detail on how the VL53L0X device shall work
high-level API : for simplest use of the VL53L0X device

Most API comes in synchronous mode only, although it can of course work with an asynchronous I2C Manager. This is due to the highly complex protocol of VL53L0X device where I2C transactions can be long and would have required highly complex Future classes to be defined with little added value. Only API that were deemed useful in non-blocking mode were also made asynchronous. Synchronous API are blocking until completion and should never be called from an ISR! Asynchronous API can be called from anywhere, but you must await their completion through a Future.

Note: The VL53L0X device is extremely complex and not well documented; its only complete reference is the bloated C code provided by STM which was not possible to directly use in FastArduino library. Hence it took a lot of experiments to make this device work. Not all original STM API is provided here.

Warning

This I2C device driver for VL53L0X requires you to call REGISTER_FUTURE_STATUS_LISTENERS() for the following classes:

i2c::I2CSameFutureGroup<MANAGER>: mandatory
VL53L0X::SetGPIOSettingsFuture: mandatory
VL53L0X::GetGPIOSettingsFuture: needed if you call API get_GPIO_settings()

Template Parameters

MANAGER one of FastArduino available I2C Manager

Definition at line 108 of file vl53l0x.h.

Member Typedef Documentation

◆ GetRangeStatusFuture

template<typename MANAGER >

using devices::vl53l0x::VL53L0X< MANAGER >::GetRangeStatusFuture = TReadRegisterFuture<Register::RESULT_RANGE_STATUS, DeviceStatus>

Future to get device range status.

See also: get_range_status()

Definition at line 525 of file vl53l0x.h.

◆ GetInterruptStatusFuture

template<typename MANAGER >

using devices::vl53l0x::VL53L0X< MANAGER >::GetInterruptStatusFuture = TReadRegisterFuture<Register::RESULT_INTERRUPT_STATUS, InterruptStatus>

Future to get device current interrupt status.

See also: get_interrupt_status()

Definition at line 756 of file vl53l0x.h.

◆ ClearInterruptFuture

template<typename MANAGER >

using devices::vl53l0x::VL53L0X< MANAGER >::ClearInterruptFuture = TWriteRegisterFuture<Register::SYSTEM_INTERRUPT_CLEAR>

Future to clear device interrupt status.

See also: clear_interrupt()

Definition at line 801 of file vl53l0x.h.

◆ GetDirectRangeFuture

template<typename MANAGER >

using devices::vl53l0x::VL53L0X< MANAGER >::GetDirectRangeFuture = TReadRegisterFuture<Register::RESULT_RANGE_MILLIMETER, uint16_t>

Future to get device current range measure.

See also: get_direct_range()

Definition at line 875 of file vl53l0x.h.

Constructor & Destructor Documentation

◆ VL53L0X()

template<typename MANAGER >

devices::vl53l0x::VL53L0X< MANAGER >::VL53L0X ( MANAGER & manager )

inlineexplicit

Create a new device driver for a VL53L0X chip.

Parameters

manager reference to a suitable MANAGER for this device

Definition at line 129 of file vl53l0x.h.

Member Function Documentation

◆ set_address()

template<typename MANAGER >

bool devices::vl53l0x::VL53L0X< MANAGER >::set_address ( uint8_t device_address )

inline

Change the I2C address of this VL53L0X device.

For this to work, other I2C devices with the same address shall be shut down during this method call.

Warning: Blocking API!

Note: High-level API

Parameters

device_address the new I2C address for this device; only 7 LSB are relevant.

Return values

true	if the operation succeeded
false	if the operation failed

Definition at line 143 of file vl53l0x.h.

◆ begin()

template<typename MANAGER >

bool devices::vl53l0x::VL53L0X< MANAGER >::begin ( Profile profile )

inline

Fully initialize this VL53L0X device and configures it with provided profile.

Once this method has been called successfully, you can start perform ranging (continuous or not). You may also want to set some GPIO interrupts before ranging.

Warning: Blocking API!

Note: High-level API If you need more custom settings to initalize the device you should turn to mid-level API.

Parameters

profile the pre-defined Profile to use on this sensor

Return values

true	if the operation succeeded
false	if the operation failed

See also: start_continuous_ranging(); await_single_range(); set_GPIO_settings(); init_data_first(); init_static_second()

Definition at line 175 of file vl53l0x.h.

◆ await_single_range() [1/2]

template<typename MANAGER >

template<board::Timer TIMER>

bool devices::vl53l0x::VL53L0X< MANAGER >::await_single_range	(	timer::RTT< TIMER > &	rtt,
		uint16_t &	range_mm,
		uint16_t	timeout_ms = `DEFAULT_TIMEOUT_MS`
	)

inline

Perform a single range action on VL53L0X device, and wait for the measurement result.

This shall be used when no continuous ranging is in effect.

Warning: Blocking API!

Note: High-level API; Mid-level API

Template Parameters

TIMER the Timer used for rtt; this template argument will be automatically deduced from rtt.

Parameters

rtt	the real-time timer to use to count elapsed time
range_mm	a reference to a variable that will receive the measurement result (in mm)
timeout_ms	the maximum amount of time to wait for a result; default is 100ms, but it should be higher than the measurement timing budget.

Return values

true	if the operation succeeded
false	if the operation failed or timed out

See also: set_measurement_timing_budget(); await_single_range(uint16_t&, uint16_t)

Definition at line 234 of file vl53l0x.h.

◆ start_continuous_ranging()

template<typename MANAGER >

bool devices::vl53l0x::VL53L0X< MANAGER >::start_continuous_ranging ( uint16_t period_ms = 0 )

inline

Start continuous ranging on this VL53L0X device.

This method shall not be called before the device has been properly initialized, either with high-level API begin() or mid-level API methods init_data_first(), init_static_second() and perform_ref_calibration(). Once this method has been called, continuous ranging starts on the device, at the given period. You can check when a sample is ready to read by examining interrupt status or reange status, then you can read the range and clear the interrupt. Or you may prefer just await for new range which is easier to code but will block your program.

Warning: Blocking API!

Note: High-level API; Mid-level API

Parameters

period_ms the period, in ms, between 2 consecutive ranging measures; if 0 (the default), then consecutive measures will follow each other with no delay ("back-to-back" mode).

Return values

true	if the operation succeeded
false	if the operation failed

See also: stop_continuous_range(); await_continuous_range(); get_interrupt_status(); get_range_status(); get_direct_range()

Definition at line 287 of file vl53l0x.h.

◆ await_continuous_range() [1/2]

template<typename MANAGER >

template<board::Timer TIMER>

bool devices::vl53l0x::VL53L0X< MANAGER >::await_continuous_range	(	timer::RTT< TIMER > &	rtt,
		uint16_t &	range_mm,
		uint16_t	timeout_ms = `DEFAULT_TIMEOUT_MS`
	)

inline

Wait for the next continuous ranging measure on VL53L0X device to be ready and return the result.

This shall be used only when continuous ranging is in effect.

Warning: Blocking API!

Note: High-level API; Mid-level API

Template Parameters

TIMER the Timer used for rtt; this template argument will be automatically deduced from rtt.

Parameters

rtt	the real-time timer to use to count elapsed time
range_mm	a reference to a variable that will receive the measurement result (in mm)
timeout_ms	the maximum amount of time to wait for a result; default is 100ms, but it should be higher than the measurement timing budget.

Return values

true	if the operation succeeded
false	if the operation failed or timed out

See also: start_continuous_ranging(); set_measurement_timing_budget(); await_continuous_range(uint16_t&, uint16_t)

Definition at line 329 of file vl53l0x.h.

◆ stop_continuous_ranging()

template<typename MANAGER >

bool devices::vl53l0x::VL53L0X< MANAGER >::stop_continuous_ranging ( )

inline

Stop continuous ranging on this VL53L0X device.

Warning: Blocking API!

Note: High-level API; Mid-level API

Return values

true	if the operation succeeded
false	if the operation failed

See also: start_continuous_range()

Definition at line 348 of file vl53l0x.h.

◆ reset_device()

template<typename MANAGER >

bool devices::vl53l0x::VL53L0X< MANAGER >::reset_device ( )

inline

Reset VL53L0X device.

After this method is called, the device is in the same state as after power-up, hence device must be reinitialized from scratch.

Warning: Blocking API!

Note: High-level API; Mid-level API

Return values

true	if the operation succeeded
false	if the operation failed

See also: begin(); init_data_first(); init_static_second(); perform_ref_calibration()

Definition at line 370 of file vl53l0x.h.

◆ init_data_first()

template<typename MANAGER >

bool devices::vl53l0x::VL53L0X< MANAGER >::init_data_first ( )

inline

Perform 1st stage initialization of this VL53L0X device.

VL53L0X initialization is made of 3 steps before it can perform any ranging:

data init: must be performed once only after device power-up
static init: must be performed at least once, after data init, but can be called several times to changes ranging steps sequence
reference calibration: must be performed once One method exists for each stage.

After initalization, you may call methods changing all kinds of settings. Finally, you may then perform ranging, continuously or not.

Warning: Blocking API!

Note: Mid-level API If you want simpler initialization of the device, you should turn to high-level API.

Return values

true	if the operation succeeded
false	if the operation failed

See also: init_static_second(); perform_ref_calibration(); begin()

Definition at line 422 of file vl53l0x.h.

◆ init_static_second()

template<typename MANAGER >

bool devices::vl53l0x::VL53L0X< MANAGER >::init_static_second	(	const GPIOSettings &	settings,
		SequenceSteps	steps = `SequenceSteps::create().pre_range().final_range().dss()`
	)

inline

Perform 2nd stage initialization of this VL53L0X device.

This must be called once, or more, after init_data_first() has been called. It allows you to select which ranging steps shall be used afterwards.

Warning: Blocking API!

Note: Mid-level API If you want simpler initialization of the device, you should turn to high-level API.

Parameters

settings	intial GPIO settings to set on the device; these settings can be changed anytime later.
steps	the ranging steps sequence

Return values

true	if the operation succeeded
false	if the operation failed

See also: set_GPIO_settings(); set_sequence_steps(); init_data_first(); perform_ref_calibration(); begin()

Definition at line 460 of file vl53l0x.h.

◆ perform_ref_calibration()

template<typename MANAGER >

bool devices::vl53l0x::VL53L0X< MANAGER >::perform_ref_calibration ( )

inline

Perform VL53L0X VHV and Phase calibration.

This must be called once before any measurement, but after data and static initalization.

Warning: Blocking API!

Note: Mid-level API If you want simpler initialization of the device, you should turn to high-level API.

Return values

true	if the operation succeeded
false	if the operation failed

See also: init_data_first(); init_static_second(); begin()

Definition at line 501 of file vl53l0x.h.

◆ get_range_status() [1/2]

template<typename MANAGER >

int devices::vl53l0x::VL53L0X< MANAGER >::get_range_status ( GetRangeStatusFuture & future )

inline

Get current DeviceStatus from this device.

Warning: Asynchronous API!

Note: Mid-level API

Parameters

future a GetRangeStatusFuture passed by the caller, that will be updated once the current I2C action is finished.

Return values

0	if no problem occurred during the preparation of I2C transaction

Returns: an error code if something bad happened; for an asynchronous I2C Manager, this typically happens when its queue of I2CCommand is full; for a synchronous I2C Manager, any error on the I2C bus or on the target device will trigger an error here. the list of possible errors

See also: get_range_status(DeviceStatus&)

Definition at line 542 of file vl53l0x.h.

◆ get_range_status() [2/2]

template<typename MANAGER >

bool devices::vl53l0x::VL53L0X< MANAGER >::get_range_status ( DeviceStatus & range_status )

inline

Get current DeviceStatus from this device.

Warning: Blocking API!

Note: Mid-level API

Parameters

range_status a reference to a variable that will receive the device status

Return values

true	if the operation succeeded
false	if the operation failed

See also: get_range_status()

Definition at line 559 of file vl53l0x.h.

◆ get_GPIO_settings() [1/2]

template<typename MANAGER >

int devices::vl53l0x::VL53L0X< MANAGER >::get_GPIO_settings ( GetGPIOSettingsFuture & future )

inline

Get current GPIOSettings from this device.

Warning: Asynchronous API!

Note: Mid-level API

Parameters

future a GetGPIOSettingsFuture passed by the caller, that will be updated once the current I2C action is finished.

Return values

0	if no problem occurred during the preparation of I2C transaction

Returns: an error code if something bad happened; for an asynchronous I2C Manager, this typically happens when its queue of I2CCommand is full; for a synchronous I2C Manager, any error on the I2C bus or on the target device will trigger an error here. the list of possible errors

See also: set_GPIO_settings(); get_GPIO_settings(GPIOSettings&)

Definition at line 637 of file vl53l0x.h.

◆ get_GPIO_settings() [2/2]

template<typename MANAGER >

bool devices::vl53l0x::VL53L0X< MANAGER >::get_GPIO_settings ( GPIOSettings & settings )

inline

Get current GPIOSettings from this device.

Warning: Blocking API!

Note: Mid-level API

Parameters

settings a reference to a variable that will receive the current GPIO settings for this device

Return values

true	if the operation succeeded
false	if the operation failed

See also: set_GPIO_settings(const GPIOSettings&); get_GPIO_settings()

Definition at line 655 of file vl53l0x.h.

◆ set_GPIO_settings() [1/2]

template<typename MANAGER >

int devices::vl53l0x::VL53L0X< MANAGER >::set_GPIO_settings ( SetGPIOSettingsFuture & future )

inline

Set new GPIOSettings for this device.

Warning: Asynchronous API!

Note: Mid-level API

Parameters

future a SetGPIOSettingsFuture passed by the caller, that will be updated once the current I2C action is finished.

Return values

0	if no problem occurred during the preparation of I2C transaction

Returns: an error code if something bad happened; for an asynchronous I2C Manager, this typically happens when its queue of I2CCommand is full; for a synchronous I2C Manager, any error on the I2C bus or on the target device will trigger an error here. the list of possible errors

See also: get_GPIO_settings(); set_GPIO_settings(const GPIOSettings&)

Definition at line 728 of file vl53l0x.h.

◆ set_GPIO_settings() [2/2]

template<typename MANAGER >

bool devices::vl53l0x::VL53L0X< MANAGER >::set_GPIO_settings ( const GPIOSettings & settings )

inline

Set new GPIOSettings for this device.

Warning: Blocking API!

Note: Mid-level API

Parameters

settings new GPIO settings to write to this device

Return values

true	if the operation succeeded
false	if the operation failed

See also: set_GPIO_settings(); get_GPIO_settings(GPIOSettings&)

Definition at line 745 of file vl53l0x.h.

◆ get_interrupt_status() [1/2]

template<typename MANAGER >

int devices::vl53l0x::VL53L0X< MANAGER >::get_interrupt_status ( GetInterruptStatusFuture & future )

inline

Get current InterruptStatus from this device.

Warning: Asynchronous API!

Note: Mid-level API

Parameters

future a GetInterruptStatusFuture passed by the caller, that will be updated once the current I2C action is finished.

Return values

0	if no problem occurred during the preparation of I2C transaction

Returns: an error code if something bad happened; for an asynchronous I2C Manager, this typically happens when its queue of I2CCommand is full; for a synchronous I2C Manager, any error on the I2C bus or on the target device will trigger an error here. the list of possible errors

See also: clear_interrupt(); get_interrupt_status(InterruptStatus&)

Definition at line 774 of file vl53l0x.h.

◆ get_interrupt_status() [2/2]

template<typename MANAGER >

bool devices::vl53l0x::VL53L0X< MANAGER >::get_interrupt_status ( InterruptStatus & status )

inline

Get current InterruptStatus from this device.

Warning: Blocking API!

Note: Mid-level API

Parameters

status a reference to a variable that will receive the current interrupt status of this device

Return values

true	if the operation succeeded
false	if the operation failed

See also: clear_interrupt(uint8_t); get_interrupt_status()

Definition at line 792 of file vl53l0x.h.

◆ clear_interrupt() [1/2]

template<typename MANAGER >

int devices::vl53l0x::VL53L0X< MANAGER >::clear_interrupt ( ClearInterruptFuture & future )

inline

Clear interrupt status from this device.

Warning: Asynchronous API!

Note: Mid-level API

Parameters

future a ClearInterruptFuture passed by the caller, that will be updated once the current I2C action is finished.

Return values

0	if no problem occurred during the preparation of I2C transaction

Returns: an error code if something bad happened; for an asynchronous I2C Manager, this typically happens when its queue of I2CCommand is full; for a synchronous I2C Manager, any error on the I2C bus or on the target device will trigger an error here. the list of possible errors

See also: clear_interrupt(uint8_t); get_interrupt_status()

Definition at line 819 of file vl53l0x.h.

◆ clear_interrupt() [2/2]

template<typename MANAGER >

bool devices::vl53l0x::VL53L0X< MANAGER >::clear_interrupt ( uint8_t clear_mask = 0x01 )

inline

Clear interrupt status from this device.

Warning: Blocking API!

Note: Mid-level API

Parameters

clear_mask the mask of the interrupts to be cleared

Return values

true	if the operation succeeded
false	if the operation failed

See also: get_interrupt_status(); clear_interrupt()

Definition at line 836 of file vl53l0x.h.

◆ await_interrupt() [1/2]

template<typename MANAGER >

template<board::Timer TIMER>

bool devices::vl53l0x::VL53L0X< MANAGER >::await_interrupt	(	timer::RTT< TIMER > &	rtt,
		uint16_t	timeout_ms = `DEFAULT_TIMEOUT_MS`
	)

inline

Wait for an interrupt condition on VL53L0X device.

Warning: Blocking API!

Note: Mid-level API

Template Parameters

TIMER the Timer used for rtt; this template argument will be automatically deduced from rtt.

Parameters

rtt	the real-time timer to use to count elapsed time
timeout_ms	the maximum amount of time to wait for a result; default is 100ms, but it should be higher than the measurement timing budget.

Return values

true	if the operation succeeded
false	if the operation failed or timed out

See also: await_continuous_range()

Definition at line 858 of file vl53l0x.h.

◆ get_direct_range() [1/2]

template<typename MANAGER >

int devices::vl53l0x::VL53L0X< MANAGER >::get_direct_range ( GetDirectRangeFuture & future )

inline

Get range measured by this device.

This method does not wait for anything, it just gets the current value in the range register. This is useful only when you know a range is ready to read. In general, this method shall be used only after device interrupt status != 0, then interrupt status should be cleared immediately after. You would probably prefer to use methods that first await for range measure to be ready before returning its value.

Warning: Asynchronous API!

Note: Mid-level API

Parameters

future a GetDirectRangeFuture passed by the caller, that will be updated once the current I2C action is finished.

Return values

0	if no problem occurred during the preparation of I2C transaction

Returns: an error code if something bad happened; for an asynchronous I2C Manager, this typically happens when its queue of I2CCommand is full; for a synchronous I2C Manager, any error on the I2C bus or on the target device will trigger an error here. the list of possible errors

See also: await_single_range(); await_continuous_range(); get_direct_range(uint16_t&)

Definition at line 902 of file vl53l0x.h.

◆ get_direct_range() [2/2]

template<typename MANAGER >

bool devices::vl53l0x::VL53L0X< MANAGER >::get_direct_range ( uint16_t & range_mm )

inline

Get range measured by this device.

This method does not wait for anything, it just gets the current value in the range register. This is useful only when you know a range is ready to read. You would probably prefer to use methods that first await for range measure to be ready before returning its value.

Warning: Blocking API!

Note: Mid-level API

Parameters

range_mm a reference to a variable that will receive the current range (in mm) stored in the device

Return values

true	if the operation succeeded
false	if the operation failed

See also: await_single_range(); await_continuous_range(); get_direct_range()

Definition at line 926 of file vl53l0x.h.

◆ set_measurement_timing_budget()

template<typename MANAGER >

bool devices::vl53l0x::VL53L0X< MANAGER >::set_measurement_timing_budget ( uint32_t budget_us )

inline

Set new "measurement timing budget" for this device.

This is the amount of time (in us) that is used to perform a range.

Warning: Blocking API!

Note: Mid-level API

Parameters

budget_us the new measurement timing budget to use for ranging; it must be bigger than 20000us; the actual minimum value also depends on other device settings, in particular the SequenceSteps used for ranging. The bigger the budget, the higher the accuracy of measurements.

Return values

true	if the operation succeeded
false	if the operation failed

See also: get_measurement_timing_budget()

Definition at line 947 of file vl53l0x.h.

◆ get_measurement_timing_budget()

template<typename MANAGER >

bool devices::vl53l0x::VL53L0X< MANAGER >::get_measurement_timing_budget ( uint32_t & budget_us )

inline

Get current "measurement timing budget" for this device.

This is the amount of time (in us) that is used to perform a range. This amount is calculated based on other settings of the device.

Warning: Blocking API!

Note: Mid-level API

Parameters

budget_us a reference to a variable that will receive the current measurement timing budget for this device

Return values

true	if the operation succeeded
false	if the operation failed

See also: set_measurement_timing_budget()

Definition at line 975 of file vl53l0x.h.

◆ set_sequence_steps()

template<typename MANAGER >

bool devices::vl53l0x::VL53L0X< MANAGER >::set_sequence_steps ( SequenceSteps sequence_steps )

inline

Set measurement steps to be executed in sequence by the device during ranging.

Warning: Blocking API!

Note: Mid-level API

Parameters

sequence_steps the sequence steps to use for ranging

Return values

true	if the operation succeeded
false	if the operation failed

See also: get_sequence_steps(); SequenceSteps

Definition at line 1000 of file vl53l0x.h.

◆ get_sequence_steps()

template<typename MANAGER >

bool devices::vl53l0x::VL53L0X< MANAGER >::get_sequence_steps ( SequenceSteps & sequence_steps )

inline

Get current measurement steps executed in sequence by the device during ranging.

Warning: Blocking API!

Note: Mid-level API

Parameters

sequence_steps a reference to a variable that will receive the sequence steps

Return values

true	if the operation succeeded
false	if the operation failed

See also: set_sequence_steps(); SequenceSteps

Definition at line 1020 of file vl53l0x.h.

◆ set_vcsel_pulse_period()

template<typename MANAGER >

template<VcselPeriodType TYPE>

bool devices::vl53l0x::VL53L0X< MANAGER >::set_vcsel_pulse_period ( uint8_t period )

inline

Set new pulse period of the VCSEL for pre-range or final-range step.

Pulse period is expressed in PCLK, whatever that really means. Changing pulse periods has an impact on range distance.

Warning: Blocking API!

Note: Mid-level API

Template Parameters

TYPE	the type of pulse period we want to set (pre-range or final-range)

Parameters

period the new pulse period to use for TYPE step; for pre-range, possible values are 12, 14, 16, 18; for final-range these are 8, 10, 12, 14.

Return values

true	if the operation succeeded
false	if the operation failed

See also: get_vcsel_pulse_period(); VcselPeriodType

Definition at line 1045 of file vl53l0x.h.

◆ get_vcsel_pulse_period()

template<typename MANAGER >

template<VcselPeriodType TYPE>

bool devices::vl53l0x::VL53L0X< MANAGER >::get_vcsel_pulse_period ( uint8_t & period )

inline

Get current pulse period of the VCSEL for pre-range or final-range step.

Pulse period is expressed in PCLK, whatever that really means.

Warning: Blocking API!

Note: Mid-level API

Template Parameters

TYPE	the type of pulse period we want to read

Parameters

period a reference to a variable that will receive the pulse period

Return values

true	if the operation succeeded
false	if the operation failed

See also: set_vcsel_pulse_period(); VcselPeriodType

Definition at line 1066 of file vl53l0x.h.

◆ set_signal_rate_limit()

template<typename MANAGER >

bool devices::vl53l0x::VL53L0X< MANAGER >::set_signal_rate_limit ( float signal_rate )

inline

Set new signal rate limit for ranging.

This is a ratio between 0.0 and 1.0; lower values will allow ranging in long distance or in a noisy environment; default is normally 0.25.

Warning: Blocking API!

Note: Mid-level API

Parameters

signal_rate the new signal rate limit to use for ranging; must be between 0.0 and 1.0.

Return values

true	if the operation succeeded
false	if the operation failed

See also: get_signal_rate_limit()

Definition at line 1089 of file vl53l0x.h.

◆ get_signal_rate_limit()

template<typename MANAGER >

bool devices::vl53l0x::VL53L0X< MANAGER >::get_signal_rate_limit ( float & signal_rate )

inline

Get current signal rate limit for ranging.

This is a ratio between 0.0 and 1.0; lower values will allow ranging in long distance or in a noisy environment; default is normally 0.25.

Warning: Blocking API!

Note: Mid-level API

Parameters

signal_rate a reference to a variable that will receive the current signal rate limit

Return values

true	if the operation succeeded
false	if the operation failed

See also: set_signal_rate_limit()

Definition at line 1113 of file vl53l0x.h.

◆ get_power_mode()

template<typename MANAGER >

bool devices::vl53l0x::VL53L0X< MANAGER >::get_power_mode ( PowerMode & power_mode )

inline

Get current power mode of this VL53L0X register.

Warning: Blocking API!

Note: Mid-level API

Parameters

power_mode a reference to a variable that will receive the revision

Return values

true	if the operation succeeded
false	if the operation failed

Definition at line 1132 of file vl53l0x.h.

◆ get_model()

template<typename MANAGER >

bool devices::vl53l0x::VL53L0X< MANAGER >::get_model ( uint8_t & model )

inline

Get model of this VL53L0X register.

This is normally a constant (0xEE).

Warning: Blocking API!

Note: Mid-level API

Parameters

model a reference to a variable that will receive the model

Return values

true	if the operation succeeded
false	if the operation failed

See also: get_revision()

Definition at line 1149 of file vl53l0x.h.

◆ get_revision()

template<typename MANAGER >

bool devices::vl53l0x::VL53L0X< MANAGER >::get_revision ( uint8_t & revision )

inline

Get revision of this VL53L0X register.

This is normally a constant (0x10).

Warning: Blocking API!

Note: Mid-level API

Parameters

revision a reference to a variable that will receive the revision

Return values

true	if the operation succeeded
false	if the operation failed

See also: get_model()

Definition at line 1166 of file vl53l0x.h.

◆ await_interrupt() [2/2]

template<typename MANAGER >

bool devices::vl53l0x::VL53L0X< MANAGER >::await_interrupt ( uint16_t loops = MAX_LOOP )

inline

Wait for an interrupt condition on VL53L0X device.

Wait is performed based on a maximum number of loops, not on actual time. This is more difficult to use than await_interrupt(timer::RTT<TIMER>&, uint16_t)

Warning: Blocking API!

Note: Low-level API! Generally you shall not use this API unless you know what you are doing.

Parameters

loops the maximum number of waiting loops before timeout; default is 2000, but it may not be suitable in every situation.

Return values

true	if the operation succeeded
false	if the operation failed or timed out

See also: await_interrupt(timer::RTT<TIMER>&, uint16_t)

Definition at line 1188 of file vl53l0x.h.

◆ await_continuous_range() [2/2]

template<typename MANAGER >

bool devices::vl53l0x::VL53L0X< MANAGER >::await_continuous_range	(	uint16_t &	range_mm,
		uint16_t	loops = `MAX_LOOP`
	)

inline

Wait for the next continuous ranging measure on VL53L0X device to be ready and return the result.

This shall be used only when continuous ranging is in effect. Wait is performed based on a maximum number of loops, not on actual time. This is more difficult to use than await_continuous_range(timer::RTT<TIMER>&, uint16_t&, uint16_t)

Warning: Blocking API!

Note: Low-level API! Generally you shall not use this API unless you know what you are doing.

Parameters

range_mm	a reference to a variable that will receive the measurement result (in mm)
loops	the maximum number of waiting loops before timeout; default is 2000, but it may not be suitable in every situation.

Return values

true	if the operation succeeded
false	if the operation failed or timed out

See also: start_continuous_ranging(); set_measurement_timing_budget(); await_continuous_range(timer::RTT<TIMER>&, uint16_t&, uint16_t)

Definition at line 1223 of file vl53l0x.h.

◆ await_single_range() [2/2]

template<typename MANAGER >

bool devices::vl53l0x::VL53L0X< MANAGER >::await_single_range	(	uint16_t &	range_mm,
		uint16_t	loops = `MAX_LOOP`
	)

inline

Perform a single range action on VL53L0X device, and wait for the measurement result.

This shall be used when no continuous ranging is in effect. Wait is performed based on a maximum number of loops, not on actual time. This is more difficult to use than await_single_range(timer::RTT<TIMER>&, uint16_t&, uint16_t)

Warning: Blocking API!

Note: Low-level API! Generally you shall not use this API unless you know what you are doing.

Parameters

range_mm	a reference to a variable that will receive the measurement result (in mm)
loops	the maximum number of waiting loops before timeout; default is 2000, but it may not be suitable in every situation.

Return values

true	if the operation succeeded
false	if the operation failed or timed out

See also: await_single_range(timer::RTT<TIMER>&, uint16_t&, uint16_t)

Definition at line 1250 of file vl53l0x.h.

◆ get_reference_SPADs()

template<typename MANAGER >

bool devices::vl53l0x::VL53L0X< MANAGER >::get_reference_SPADs ( SPADReference & spad_ref )

inline

Get the reference SPADs status (enabled or not).

Warning: Blocking API!

Note: Low-level API! Generally you shall not use this API unless you know what you are doing.

Parameters

spad_ref a reference to a variable that will receive the current reference SPADs status

Return values

true	if the operation succeeded
false	if the operation failed

See also: set_reference_SPADs()

Definition at line 1280 of file vl53l0x.h.

◆ set_reference_SPADs()

template<typename MANAGER >

bool devices::vl53l0x::VL53L0X< MANAGER >::set_reference_SPADs ( const SPADReference & spad_ref )

inline

Set the reference SPADs status (enabled or not).

Warning: Blocking API!

Note: Low-level API! Generally you shall not use this API unless you know what you are doing.

Parameters

spad_ref the new reference SPADs status to set

Return values

true	if the operation succeeded
false	if the operation failed

See also: set_reference_SPADs()

Definition at line 1299 of file vl53l0x.h.

◆ get_SPAD_info()

template<typename MANAGER >

bool devices::vl53l0x::VL53L0X< MANAGER >::get_SPAD_info ( SPADInfo & info )

inline

Get current SPAD information (number of SPAD aperture or not).

Warning: Blocking API!

Note: Low-level API! Generally you shall not use this API unless you know what you are doing.

Parameters

info	a reference to a variable that will receive the current reference SPAD information

Return values

true	if the operation succeeded
false	if the operation failed

Definition at line 1320 of file vl53l0x.h.

◆ get_sequence_steps_timeout()

template<typename MANAGER >

bool devices::vl53l0x::VL53L0X< MANAGER >::get_sequence_steps_timeout ( SequenceStepsTimeout & timeouts )

inline

Get current timeouts associated to each ranging step.

Warning: Blocking API!

Note: Low-level API! Generally you shall not use this API unless you know what you are doing.

Parameters

timeouts a reference to a variable that will receive the current timeouts associated to ranging steps

Return values

true	if the operation succeeded
false	if the operation failed

Definition at line 1363 of file vl53l0x.h.

◆ get_register() [1/2]

template<typename MANAGER >

template<Register REGISTER, typename T = uint8_t>

int devices::vl53l0x::VL53L0X< MANAGER >::get_register ( TReadRegisterFuture< REGISTER, T > & future )

inline

Directly get value of a VL53L0X register.

Warning: Asynchronous API!

Note: Low-level API! Generally you shall not use this API unless you know what you are doing.

Template Parameters

REGISTER	the register to read from VL53l)X device
T	the type of value stored in `REGISTER`

Parameters

future a Future passed by the caller, that will be updated once the current I2C action is finished.

Return values

0	if no problem occurred during the preparation of I2C transaction

Returns: an error code if something bad happened; for an asynchronous I2C Manager, this typically happens when its queue of I2CCommand is full; for a synchronous I2C Manager, any error on the I2C bus or on the target device will trigger an error here. the list of possible errors

See also: set_register(); get_register(T& value)

Definition at line 1408 of file vl53l0x.h.

◆ set_register() [1/2]

template<typename MANAGER >

template<Register REGISTER, typename T = uint8_t>

int devices::vl53l0x::VL53L0X< MANAGER >::set_register ( TWriteRegisterFuture< REGISTER, T > & future )

inline

Directly set value of a VL53L0X register.

Warning: Asynchronous API!

Note: Low-level API! Generally you shall not use this API unless you know what you are doing.

Template Parameters

REGISTER	the register to write to VL53l)X device
T	the type of value stored in `REGISTER`

Parameters

future a Future passed by the caller, that will be updated once the current I2C action is finished.

Return values

0	if no problem occurred during the preparation of I2C transaction

Returns: an error code if something bad happened; for an asynchronous I2C Manager, this typically happens when its queue of I2CCommand is full; for a synchronous I2C Manager, any error on the I2C bus or on the target device will trigger an error here. the list of possible errors

See also: get_register(); set_register(T value)

Definition at line 1434 of file vl53l0x.h.

◆ get_register() [2/2]

template<typename MANAGER >

template<Register REGISTER, typename T = uint8_t>

bool devices::vl53l0x::VL53L0X< MANAGER >::get_register ( T & value )

inline

Directly get value of a VL53L0X register.

Warning: Blocking API!

Note: Low-level API! Generally you shall not use this API unless you know what you are doing.

Template Parameters

REGISTER	the register to read from VL53l)X device
T	the type of value stored in `REGISTER`

Parameters

value a reference to a variable of type T, that will receive the value in register REGISTER

Return values

true	if the operation succeeded
false	if the operation failed

See also: set_register(T); get_register()

Definition at line 1457 of file vl53l0x.h.

◆ set_register() [2/2]

template<typename MANAGER >

template<Register REGISTER, typename T = uint8_t>

bool devices::vl53l0x::VL53L0X< MANAGER >::set_register ( T value )

inline

Directly set value of a VL53L0X register.

Warning: Blocking API!

Note: Low-level API! Generally you shall not use this API unless you know what you are doing.

Template Parameters

REGISTER	the register to write to VL53l)X device
T	the type of value stored in `REGISTER`

Parameters

value a value of type T that will be written to register REGISTER

Return values

true	if the operation succeeded
false	if the operation failed

See also: get_register(T& value); set_register()

Definition at line 1480 of file vl53l0x.h.

The documentation for this class was generated from the following file:

fastarduino/devices/vl53l0x.h

Classes

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ GetRangeStatusFuture

◆ GetInterruptStatusFuture

◆ ClearInterruptFuture

◆ GetDirectRangeFuture

Constructor & Destructor Documentation

◆ VL53L0X()

Member Function Documentation

◆ set_address()

◆ begin()

◆ await_single_range() [1/2]

◆ start_continuous_ranging()

◆ await_continuous_range() [1/2]

◆ stop_continuous_ranging()

◆ reset_device()

◆ init_data_first()

◆ init_static_second()

◆ perform_ref_calibration()

◆ get_range_status() [1/2]

◆ get_range_status() [2/2]

◆ get_GPIO_settings() [1/2]

◆ get_GPIO_settings() [2/2]

◆ set_GPIO_settings() [1/2]

◆ set_GPIO_settings() [2/2]

◆ get_interrupt_status() [1/2]

◆ get_interrupt_status() [2/2]

◆ clear_interrupt() [1/2]

◆ clear_interrupt() [2/2]

◆ await_interrupt() [1/2]

◆ get_direct_range() [1/2]

◆ get_direct_range() [2/2]

◆ set_measurement_timing_budget()

◆ get_measurement_timing_budget()

◆ set_sequence_steps()

◆ get_sequence_steps()

◆ set_vcsel_pulse_period()

◆ get_vcsel_pulse_period()

◆ set_signal_rate_limit()

◆ get_signal_rate_limit()

◆ get_power_mode()

◆ get_model()

◆ get_revision()

◆ await_interrupt() [2/2]

◆ await_continuous_range() [2/2]

◆ await_single_range() [2/2]

◆ get_reference_SPADs()

◆ set_reference_SPADs()

◆ get_SPAD_info()

◆ get_sequence_steps_timeout()

◆ get_register() [1/2]

◆ set_register() [1/2]

◆ get_register() [2/2]

◆ set_register() [2/2]