API Reference

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

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()[source]

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)[source]

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)[source]

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 distance : the 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()[source]

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

Return isDataReady:
 
  • 0 -> not ready
  • 1 -> ready
clear_interrupt()[source]

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()[source]

This function returns the ambient per SPAD in kcps/SPAD

Returns:Ambient per SPAD
get_ambient_rate()[source]

This function returns the ambient rate in kcps

Returns:Ambient rate in kcps
get_distance()[source]

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()[source]

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()[source]

This function returns the high threshold in mm

Returns:High threshold in mm
Return type:Integer
get_distance_threshold_low()[source]

This function returns the low threshold in mm

Returns:Low threshold in mm
Return type:Integer
get_distance_threshold_window()[source]

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()[source]

This function returns the Intermeasurement period in ms.

Returns:Intermeasurement period in ms
Return type:Integer
get_interrupt_polarity()[source]

This function returns the current interrupt polarity

Returns:
  • 1 = active high (default)
  • 0 = active low
Rtypye:Integer
get_offset()[source]

This function returns the programmed offset correction value in mm

Returns:Offset correction value in mm
Return type:Integer
get_range_status()[source]

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()[source]

This function returns width X and height Y

Returns:Region of Interest Width (X) and Height (Y)
Return type:List
get_sensor_id()[source]

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

Returns:Sensor ID
Return type:Integer
get_sigma_threshold()[source]

This function returns the current sigma threshold in mm

Returns:Sigma threshold in mm
Return type:Integer
get_signal_per_spad()[source]

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()[source]

This function returns the returned signal in kcps.

Returns:signal in kcps
get_signal_threshold()[source]

This function returns the current signal threshold in kcps

Returns:Signal threshold in kcps
get_spad_nb()[source]

This function returns the current number of enabled SPADs

Returns:Number of enabled SPADs
get_sw_version()[source]

This function returns the SW driver version

Returns:[major, minor, build, revision] numbers
Return type:List
get_timing_budget_in_ms()[source]

This function returns the current timing budget in ms.

get_xtalk()[source]

This function returns the current programmed xtalk correction value in cps

Returns:xtalk correction value in cps
init_sensor(address)[source]

Initialize the sensor with default values

Parameters:address – Device address
Returns:0 on Success
sensor_init()[source]

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

Returns:
  • 0:success
  • != 0:failed
set_distance_mode(DM)[source]

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)[source]

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)[source]

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)[source]

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)[source]

This function programs the interrupt polarity

Parameters:NewPolarity
  • 1 = active high (default)
  • 0 = active low
set_offset(OffsetValue)[source]

This function programs the offset correction in mm

Parameters:OffsetValue – The offset correction value to program in mm
set_roi(X, Y, OpticalCenter=199)[source]

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)[source]

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)[source]

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)[source]

This function programs the timing budget in ms.

Parameters:TimingBudgetInMs – Predefined values = 15, 20, 33, 50, 100 (default), 200, 500.
set_xtalk(XtalkValue)[source]

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()[source]

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()[source]

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()[source]

This function stops the ranging.