API Reference

class qwiic_vl53l1x.QwiicVL53L1X(address=None, debug=None, i2c_driver=None)

SparkFunVL53L1X Initialise the VL53L1X chip at address with i2c_driver.

Parameters

• address –

  The I2C address to use for the device.

  • If not provided, the default address is used.

• i2c_driver –

  An existing i2c driver object.

  • If not provided a driver object is created.

Returns

Constructor Initialization -

• True- Successful

• False- Issue loading I2C driver

Return type

Bool

boot_state()

This function returns the boot state of the device (1:booted, 0:not booted)

Returns

• 1- booted

• 0- not booted

Return type

Integer

calibrate_offset(TargetDistInMm)

This function performs the offset calibration. The function returns the offset value found and programs the offset compensation into the device.

Parameters

TargetDistInMm –

• Target distance in mm, ST recommended 100 mm

• Target reflectance = grey17%

Return status

• 0- success

• !=0- failed

Return offset

offset found in mm #?

calibrate_xtalk(TargetDistInMm)

This function performs the xtalk calibration. The function returns the xtalk value found and programs the xtalk compensation to the device

Parameters

TargetDistInMm –

Target distance in mm

• The target distancethe distance where the sensor start to “under range” due to the influence of the photons reflected back from the cover glass becoming strong (also called the inflection point).

  • Target reflectance = grey 17%

Return status

• 0- success

• !=0- failed

Return xtalk

xtalk value found in cps (number of photons in count per second) #?

check_for_data_ready()

This function checks if the new ranging data is available by polling the dedicated register.

Return isDataReady

• 0 -> not ready

• 1 -> ready

clear_interrupt()

This function clears the interrupt, to be called after a ranging data reading to arm the interrupt for the next data ready event.

get_ambient_per_spad()

This function returns the ambient per SPAD in kcps/SPAD

Returns

Ambient per SPAD

get_ambient_rate()

This function returns the ambient rate in kcps

Returns

Ambient rate in kcps

get_distance()

This function returns the distance measured by the sensor in mm

Returns

Distance measured by the sensor in mm

Return type

Integer

get_distance_mode()

This function returns the current distance mode (1=short, 2=long).

Returns

• 1- Short mode max distance is limited to 1.3 m but better ambient immunity.

• 2- Long mode can range up to 4 m in the dark with 200 ms timing budget (default).

get_distance_threshold_high()

This function returns the high threshold in mm

Returns

High threshold in mm

Return type

Integer

get_distance_threshold_low()

This function returns the low threshold in mm

Returns

Low threshold in mm

Return type

Integer

get_distance_threshold_window()

This function returns the window detection mode (0=below 1=above 2=out 3=in)

Returns

Window detection mode:

• 0- below

• 1- above

• 2- out

• 3- in

Return type

Integer

get_inter_measurement_in_ms()

This function returns the Intermeasurement period in ms.

Returns

Intermeasurement period in ms

Return type

Integer

get_interrupt_polarity()

This function returns the current interrupt polarity

Returns

• 1 = active high (default)

• 0 = active low

Rtypye

Integer

get_offset()

This function returns the programmed offset correction value in mm

Returns

Offset correction value in mm

Return type

Integer

get_range_status()

This function returns the ranging status error

Returns

Ranging status error

• 0- no error

• 1- sigma failed

• 2- signal failed

• 7- wrap-around

get_roi_xy()

This function returns width X and height Y

Returns

Region of Interest Width (X) and Height (Y)

Return type

List

get_sensor_id()

This function returns the sensor id, sensor Id must be 0xEEAC

Returns

Sensor ID

Return type

Integer

get_sigma_threshold()

This function returns the current sigma threshold in mm

Returns

Sigma threshold in mm

Return type

Integer

get_signal_per_spad()

This function returns the returned signal per SPAD in kcps/SPAD (kcps stands for Kilo Count Per Second).

Returns

Signal per SPAD (Kilo Count Per Second/SPAD).

get_signal_rate()

This function returns the returned signal in kcps.

Returns

signal in kcps

get_signal_threshold()

This function returns the current signal threshold in kcps

Returns

Signal threshold in kcps

get_spad_nb()

This function returns the current number of enabled SPADs

Returns

Number of enabled SPADs

get_sw_version()

This function returns the SW driver version

Returns

[major, minor, build, revision] numbers

Return type

List

get_timing_budget_in_ms()

This function returns the current timing budget in ms.

get_xtalk()

This function returns the current programmed xtalk correction value in cps

Returns

xtalk correction value in cps

init_sensor(address)

Initialize the sensor with default values

Parameters

address – Device address

Returns

0 on Success

sensor_init()

This function loads the 135 bytes default values to initialize the sensor.

Returns

• 0:success

• != 0:failed

set_distance_mode(DM)

This function programs the distance mode (1=short, 2=long(default)).

Parameters

DM –

• 1- Short mode max distance is limited to 1.3 m but better ambient immunity.

• 2- Long mode can range up to 4 m in the dark with 200 ms timing budget (default).

set_distance_threshold(ThreshLow, ThreshHigh, Window, IntOnNoTarget)

This function programs the threshold detection mode Example:

• self.set_distance_threshold(100,300,0,1): Below 100

• self.set_distance_threshold(100,300,1,1): Above 300

• self.set_distance_threshold(100,300,2,1): Out of window

• self.set_distance_threshold(100,300,3,1): In window

Parameters

• ThreshLow (mm) – The threshold under which one the device raises an interrupt if Window = 0

• ThreshHigh (mm) – The threshold above which one the device raises an interrupt if Window = 1

• Window –

  Window detection mode:

  • 0- below

  • 1- above

  • 2- out

  • 3- in

• IntOnNoTarget – = 1 (No longer used - just set to 1)

set_i2c_address(new_address)

This function sets the sensor I2C address used in case multiple devices application, default address 0x29 (0x52 >> 1)

Parameters

new_address – I2C address to change device to

set_inter_measurement_in_ms(InterMeasMs)

This function programs the Intermeasurement period in ms.

Parameters

InterMeasMs – Intermeasurement period must be >/= timing budget. This condition is not checked by the API, the customer has the duty to check the condition. Default = 100 ms

set_interrupt_polarity(NewPolarity)

This function programs the interrupt polarity

Parameters

NewPolarity –

• 1 = active high (default)

• 0 = active low

set_offset(OffsetValue)

This function programs the offset correction in mm

Parameters

OffsetValue – The offset correction value to program in mm

set_roi(X, Y, OpticalCenter=199)

This function programs the ROI (Region of Interest). The height and width of the ROI (X, Y) are set in SPADs; the smallest acceptable ROI size = 4 (4 x 4). The optical center is set based on table below. To set the center, use the pad that is to the right and above (i.e. upper right of) the exact center of the region you’d like to measure as your optical center.

Table of Optical Centers:

128,136,144,152,160,168,176,184, 192,200,208,216,224,232,240,248 129,137,145,153,161,169,177,185, 193,201,209,217,225,233,241,249 130,138,146,154,162,170,178,186, 194,202,210,218,226,234,242,250 131,139,147,155,163,171,179,187, 195,203,211,219,227,235,243,251 132,140,148,156,164,172,180,188, 196,204,212,220,228,236,244,252 133,141,149,157,165,173,181,189, 197,205,213,221,229,237,245,253 134,142,150,158,166,174,182,190, 198,206,214,222,230,238,246,254 135,143,151,159,167,175,183,191, 199,207,215,223,231,239,247,255

127,119,111,103,095,087,079,071, 063,055,047,039,031,023,015,007 126,118,110,102,094,086,078,070, 062,054,046,038,030,022,014,006 125,117,109,101,093,085,077,069, 061,053,045,037,029,021,013,005 124,116,108,100,092,084,076,068, 060,052,044,036,028,020,012,004 123,115,107,099,091,083,075,067, 059,051,043,035,027,019,011,003 122,114,106,098,090,082,074,066, 058,050,042,034,026,018,010,002 121,113,105,097,089,081,073,065, 057,049,041,033,025,017,009,001 120,112,104,096,088,080,072,064, 056,048,040,032,024,016,008,0 Pin 1

(Each SPAD has a number which is not obvious.)

Parameters

• X – ROI Width

• Y – ROI Height

• OpticalCenter – The pad that is to the upper right of the exact center of the ROI (see table above). Default = 199

set_sigma_threshold(Sigma)

This function programs a new sigma threshold in mm (default=15 mm)

Parameters

Sigma – Sigma threshold in mm (default=15 mm)

set_signal_threshold(Signal)

This function programs a new signal threshold in kcps (default=1024 kcps)

Parameters

Signal – Signal threshold in kcps (default=1024 kcps)

set_timing_budget_in_ms(TimingBudgetInMs)

This function programs the timing budget in ms.

Parameters

TimingBudgetInMs – Predefined values = 15, 20, 33, 50, 100 (default), 200, 500.

set_xtalk(XtalkValue)

This function programs the xtalk correction value in cps (Count Per Second). This is the number of photons reflected back from the cover glass in cps.

Parameters

XTalkValue – xtalk correction value in count per second to avoid float type

start_ranging()

This function starts the ranging distance operation The ranging operation is continuous. The clear interrupt has to be done after each get data to allow the interrupt to raise when the next data is ready 1=active high (default), 0=active low, use set_interrupt_polarity() to change the interrupt polarity if required.

start_temperature_update()

This function performs the temperature calibration. It is recommended to call this function any time the temperature might have changed by more than 8 deg C without sensor ranging activity for an extended period.

stop_ranging()

This function stops the ranging.