cancel
Showing results for 
Search instead for 
Did you mean: 

VL53L0X API: Usage of the 6 limit checks, Ambient SPAD damper, Dmax Cal, etc

DVile.2
Associate II

Hello,

I have spent some time reading through the VL53L0X API and all documentation related to this sensor.

I was hoping your team could clarify the usage of a few functions and features.

  • "Pre-Range" vs "Final-Range"
    • This distinction is made througout the API, but the two are never actually defined. I was reading this document on TOF principles and on pg.37/38 it mentions a technique where the integration period is divided into two halves, each with a different frequency. Is that what Pre/Final refers to? This is my first guess since the VCSEL periods are split like this (i.e. 14/10 or 18/14).

  • Scheduler Sequence Steps
    • Why are two of these disabled by default?

  • Limit Checks:
    • 0: SIGMA_FINAL_RANGE (mm)
    • 1: SIGNAL_RATE_FINAL_RANGE (Mcps)
    • 2: SIGNAL_REF_CLIP (????)
    • 3: RANGE_IGNORE_THRESHOLD (Mcps/SPAD)
    • 4: SIGNAL_RATE_MSRC (Mcps)
    • 5: SIGNAL_RATE_PRE_RANGE (Mcps)

  • What are the use cases for these, especially #2, #4, and #5?
    • For RANGE_IGNORE_THRESHOLD, is this limit check meant to be a constant rate like the other limit checks, or should it be implemented as a dynamic rate?
      • Specifically, is the RIT's XTalk rate meant to be the constant "XTalk Compensation rate" calculated by VL53L0X_PerformXTalkCalibration( ), or is it the variable rate which would need to be deducted from Total_Signal_Rate after each measurement?
      • Similarly, for the # active SPADs which the XTalk rate would be divided by, is that a constant number (i.e. the highest number we see when the sensor is struggling to collect enough photons, usually around 190) or should it also be a variable, equal to the EffectiveSpadRtnCount returned by each measurement?
      • Some of your staff have suggested normalizing this rate, which to me, suggests it is indeed meant to be a dynamic rate. So perhaps RIT ideally adjusts with each measurement, with a formula like:
        • RIT = (( N * (Xtalk rate/# active SPADs)) * 200)
    • Why is the limit check for SIGNAL_RATE_FINAL_RANGE enabled by default, but MSRC and PRE-RANGE limit checks are disabled by default

  • Ambient SPAD Damper Factor/Threshold
    • What are the use cases for these parameters?

  • Dmax Calibration
    • There isn't any documentation on why Dmax should be calibrated, but there are functions for doing this. What benefit would come of calibrating Dmax, and what is the proper procedure?
    • Xtalk must be calibrated after SPADs and offset. Does Dmax have a correct placement in the overall calibration sequence?

  • VL53L0X_GetMeasurementRefSignal( )
    • Does this function work? Are there special conditions to make it work? In api.c (@ line 2621) it looks like the SIGNAL_REF_CLIP limit check must be enabled or else it returns the ERROR_INVALID_COMMAND status code.
    • Why isn't MeasurementRefSignal / LastSignalRefMcps included in the RangingMeasurementData_t struct?

I have many, many more questions but if we could answer these it would be an terrific start.

Thank you!!

1 ACCEPTED SOLUTION

Accepted Solutions
John E KVAM
ST Employee

Wow - when you said you read the documentation, you weren't kidding.

I'll do my best - but I will probably miss some.

  • "Pre-Range" vs "Final-Range"
    • The two ranges use a different timing interval. It's to solve a problem called Radar Aliasing. Google it.

  • Scheduler Sequence Steps
    • Minimum Signal Rate Check was put in there to save power. If few photons were returned, shut down and return 'no signal'. Few people used it.
    • TCC was an idea that proved mostly useless. In theory if something was very near, just return a fixed value. By default an object at 2cm returns 2cm, but something at 1cm might return 2.2 cm. Turning this one would simply return 2cm in all close distance cases.

  • Limit Checks:
    • 0: SIGMA_FINAL_RANGE (mm) - if the standard deviation of the range data is greater than this, return an error (It's really a warning)
    • 1: SIGNAL_RATE_FINAL_RANGE (Mcps) - if the signal strength is less than this return an error (It's really a warning too.)
    • 2: SIGNAL_REF_CLIP (????) - Not used
    • 3: RANGE_IGNORE_THRESHOLD (Mcps/SPAD) - if you don't get at least this much signal (generally 1.5X crosstalk) don't return an answer. It's noise.
    • 4: SIGNAL_RATE_MSRC (Mcps) - if you don't get a big enough signal to get an accurate number, return a range, but warn the customer it might be iffy.
    • 5: SIGNAL_RATE_PRE_RANGE (Mcps) I don't think this is used any more either.

  • What are the use cases for these, especially #2, #4, and #5? See above.
  • For RANGE_IGNORE_THRESHOLD, is this limit check meant to be a constant rate like the other limit checks, or should it be implemented as a dynamic rate?
    • Set to 1.5 the crosstalk you calibrated. It keeps you from seeing your coverglass as a target.

  • Some of your staff have suggested normalizing this rate, which to me, suggests it is indeed meant to be a dynamic rate. So perhaps RIT ideally adjusts with each measurement, with a formula like:
    • That was me :) but the context is different.
    • The Range Ignore tells the hardware what to do.
    • But when trying to interpret the targets signal rate using the normalized Signal per SPAD gives a better indication.

  • Why is the limit check for SIGNAL_RATE_FINAL_RANGE enabled by default, but MSRC and PRE-RANGE limit checks are disabled by default
    • System works better this way - by experiment.

  • Ambient SPAD Damper Factor/Threshold
    • no idea where you got this. I don't know of a damper setting

  • Dmax Calibration
    • We made a horrible mistake when we released this chip to the mass market without re-examining all the deprecated features.
    • DMAX was to return to the sensor that distance the sensor could see in the given light settings if there were no target seen.
    • so if you don't get a target, you could start your auto-focus at the Dmax distance knowing there was no target closer than DMAX
    • It has no use other than autofocus and should have been removed.

  • VL53L0X_GetMeasurementRefSignal( )
    • I've never seen this function used for anything. Should have been removed


If this or any post solves your issue, please mark them as 'Accept as Solution' It really helps. And if you notice anything wrong do not hesitate to 'Report Inappropriate Content'. Someone will review it.

View solution in original post

6 REPLIES 6
John E KVAM
ST Employee

Wow - when you said you read the documentation, you weren't kidding.

I'll do my best - but I will probably miss some.

  • "Pre-Range" vs "Final-Range"
    • The two ranges use a different timing interval. It's to solve a problem called Radar Aliasing. Google it.

  • Scheduler Sequence Steps
    • Minimum Signal Rate Check was put in there to save power. If few photons were returned, shut down and return 'no signal'. Few people used it.
    • TCC was an idea that proved mostly useless. In theory if something was very near, just return a fixed value. By default an object at 2cm returns 2cm, but something at 1cm might return 2.2 cm. Turning this one would simply return 2cm in all close distance cases.

  • Limit Checks:
    • 0: SIGMA_FINAL_RANGE (mm) - if the standard deviation of the range data is greater than this, return an error (It's really a warning)
    • 1: SIGNAL_RATE_FINAL_RANGE (Mcps) - if the signal strength is less than this return an error (It's really a warning too.)
    • 2: SIGNAL_REF_CLIP (????) - Not used
    • 3: RANGE_IGNORE_THRESHOLD (Mcps/SPAD) - if you don't get at least this much signal (generally 1.5X crosstalk) don't return an answer. It's noise.
    • 4: SIGNAL_RATE_MSRC (Mcps) - if you don't get a big enough signal to get an accurate number, return a range, but warn the customer it might be iffy.
    • 5: SIGNAL_RATE_PRE_RANGE (Mcps) I don't think this is used any more either.

  • What are the use cases for these, especially #2, #4, and #5? See above.
  • For RANGE_IGNORE_THRESHOLD, is this limit check meant to be a constant rate like the other limit checks, or should it be implemented as a dynamic rate?
    • Set to 1.5 the crosstalk you calibrated. It keeps you from seeing your coverglass as a target.

  • Some of your staff have suggested normalizing this rate, which to me, suggests it is indeed meant to be a dynamic rate. So perhaps RIT ideally adjusts with each measurement, with a formula like:
    • That was me :) but the context is different.
    • The Range Ignore tells the hardware what to do.
    • But when trying to interpret the targets signal rate using the normalized Signal per SPAD gives a better indication.

  • Why is the limit check for SIGNAL_RATE_FINAL_RANGE enabled by default, but MSRC and PRE-RANGE limit checks are disabled by default
    • System works better this way - by experiment.

  • Ambient SPAD Damper Factor/Threshold
    • no idea where you got this. I don't know of a damper setting

  • Dmax Calibration
    • We made a horrible mistake when we released this chip to the mass market without re-examining all the deprecated features.
    • DMAX was to return to the sensor that distance the sensor could see in the given light settings if there were no target seen.
    • so if you don't get a target, you could start your auto-focus at the Dmax distance knowing there was no target closer than DMAX
    • It has no use other than autofocus and should have been removed.

  • VL53L0X_GetMeasurementRefSignal( )
    • I've never seen this function used for anything. Should have been removed


If this or any post solves your issue, please mark them as 'Accept as Solution' It really helps. And if you notice anything wrong do not hesitate to 'Report Inappropriate Content'. Someone will review it.

John,

Thank you for the thorough reply. This is very helpful.

I'd like to take a closer look at 2 topics in particular.

RIT

  • You said it works as such:
    • "if you don't get at least this much signal (generally 1.5X crosstalk) don't return an answer. It's noise."
  • I want to clarify, in these cases , does the sensor not return RangingMeasurementData at all? Or does the RangeStatus for that reading get marked as = 2, meaning 'Signal Fail'?

Histogram Data

  • I think I saw you once remark that the raw data for histogram binning can be returned by the VL53L0X.
  • Could this data be used to do histogram-based smudge detection on the VL53L0X? Is there any reason why it wouldn't work, if someone was adventurous enough to write the necessary code?

Thank you for engaging my questions,

David

John E KVAM
ST Employee

There is code in the VL53L0X software to get histograms, but there was a chip issue. Not all chips started the histogram in the same bin. And sadly we deprecated the feature from the VL53L0X. So you could possibly use the histogram data for smudge, but it would not be reliable in production.

When you set the minimum signal rate you will not get an answer until that signal is intensity is crossed. This is to prevent identifying false targets.

At the end of each range, you will have the range data, but if no signal crosses the threshold, the range will = 0.


If this or any post solves your issue, please mark them as 'Accept as Solution' It really helps. And if you notice anything wrong do not hesitate to 'Report Inappropriate Content'. Someone will review it.

John,

Thank you for the info on histogram data. This indicates to me it might be a fun project but since we're looking to deploy hundreds of these, it's not worth the time to develop on. We found out about the L3CX rather late and will be upgrading to it, but our first several hundred units will have this old model.

Regarding RIT and minimum signal rate, I think that in all of my tests, adjusting the signal rate limit checks generally didn't affect the number returned as RangeMilliMeter, rather, they changed the RangeStatus integer to "2" .... I am using API version 1.1; maybe there have been some changes over time?

Anyway that's likely semantics.

I have been most strongly pursuing RIT because I seen it mentioned here and in documentation as the best (software) tool for smudge compensation, but i'm having difficulty getting it to be effective against even minor smudges. I suspect I am implementing it incorrectly. We've had a couple of challenges.

Maybe one issue is my understanding of "xtalk/SPADs" is incorrect. Am I simply meant to enter the Xtalk comp rate from Xtalk calibration, choose a N scalar (starting with N=1.5 for starters, right) and hit the gas?

I have setting RIT to equal N * (Xtalk comp rate / y ) --> where y is the highest amount of active return spads I've seen from a given sensor on a part-to-part basis (It's usually between 185 and 195).

John, am I not supposed to divide by y? ... because that's what the sensor is doing behind the scenes?

Our other problem is xtalk calibration procedure itself. With our coverglass, we get "near ideal" ranging performance out to 100 cm, and we don't need anything further than that... so this does not call for xtalk calibration. Any time we add a comp rate, it worsens performance. However, the problem is that when a smudge is placed on the coverglass, all bets are off; performance nosedives.

How should we determine what Xtalk comp rate to use for RIT when, actually, we normally are better off without enabling a comp rate in the first place?

A related issue: even when we did tested older versions of our applications which were known to be "less than ideal", the comp rate calculated by the PerformXtalkCalibration( ) function was inappropriate. We built a testbed to recreate the calibration procedure detailed in the manual, but the comp rates that the API function gives us are generally 3 to 5 times stronger than necessary. That seems like a problem which would also affect trying to get an Xtalk comp rate to use for RIT.

Sorry this is so scattered. I know my best chance at getting the answers I want is asking clear, concise questions, but in truth we're pretty stumped by many things here.

Thank you a million for your support, let me know if I can provide any data to assist!

David

0693W00000FA8JGQA1.jpg

John E KVAM
ST Employee

Would you consider looking at the coverglass from Hornix.com.tw. if you go to the product page you will see some cover glass that looks like:

If you go to the product page all the way at the bottom, you will see a bit of coverglass with an opaque line in the center of 2 pieces of 'glass'. These sensor covers are impervious to crosstalk. Even a heavy dusting of coffee creamer will not give crosstalk.

I think this would guarantee a solution to your issue.

Would that be possible?


If this or any post solves your issue, please mark them as 'Accept as Solution' It really helps. And if you notice anything wrong do not hesitate to 'Report Inappropriate Content'. Someone will review it.

Hi John,

Thanks again for the quick reply!

Yes, we also started doing business with Hornix (and Giovanni from Gilisymo) this week and ordered their dual-window coverglass.

We tested the dual-window design and are excited to transition, however, all of our current inventory and units in the field / sold to customers were built with the old coverglass. We are trying to make the best out of those existing builds by deploying a software update featuring RIT and anything else that will help mitigate smudge crosstalk noise.

I can continue investigating software solutions here, but I wanted to see if we can get an authoritative clarification on how RIT should be configured.

  • For RIT, are we only supposed to input two numbers, N and XtalkCompRate? It's not three input numbers?