How to Perform Full VL53L1X Calibration Sequence Using ST Bare Driver in STM32CubeIDE

[MattH2]

Hi everyone,

I'm currently developing firmware for the VL53L1X Time-of-Flight sensor on a breakout board using STM32CubeIDE, and I’m working with the bare driver provided by ST (not the ULD). I’d like to implement the complete calibration sequence, but I’m unsure about the correct procedure and how to manage the physical steps during calibration.

Based on the documentation, the recommended calibration order is:

1. RefSPAD Calibration

2. Crosstalk Calibration

3. Offset Calibration

I have a few questions regarding the practical and programmatic steps for performing these calibrations using the bare driver functions:

---

1. RefSPAD Calibration

• Should this be performed with no target in the Field of View?

• What environmental conditions are ideal — e.g., should the sensor be facing open space, a dark surface, or something else?

---

2. Crosstalk Calibration

• I understand that a grey target should be placed at about 600 mm from the sensor for Full ROI crosstalk calibration.

  • How should I structure the calibration code to pause or wait after the RefSPAD calibration so I can manually reposition the target before starting this step?

  • Should the target completely fill the sensor’s FoV, or is partial coverage acceptable?

---

3. Offset Calibration

• For this step, I believe a grey target should be placed at approximately 140 mm.

  • Again, how can I separate these steps in code so I can manually set up the scene before continuing?

  • Are there specific target size or reflectivity requirements?

Could someone please provide a rough code layout or example of how the full calibration sequence should be structured in the STM32CubeIDE? Even a simple template showing where and how to position the target between steps would be incredibly helpful.

Thanks in advance,
Matthew Henderson

[John E KVAM]

1. RefSPAD Calibration

• Should this be performed with no target in the Field of View? - Doesn't matter. Just nothing within a few cm.

2. Crosstalk Calibration

• I understand that a grey target should be placed at about 600 mm from the sensor for Full ROI crosstalk calibration. - Through experimentation, place that target at a point where the system under-ranges by 10 or 20%. With a good coverglass that could be as farther. With a iffy coverglass, closer. Make the diameter of the target at least 1/2 of the distance. 

• How should I structure the calibration code to pause or wait after the RefSPAD calibration so I can manually reposition the target before starting this step? No need to wait. Doing the RefSPAD while looking at the cross-talk target is how most people do it.

• Should the target completely fill the sensor’s FoV, or is partial coverage acceptable? It Must be full coverage. Diameter of the target = 1/2 the distance to the target. 

3. Offset Calibration

• For this step, I believe a grey target should be placed at approximately 140 mm. - That's fine. 

  • Again, how can I separate these steps in code so I can manually set up the scene before continuing?

  • if you create a station where the sensor points at your crosstalk target, create mechanism so the offset target can be folded down and then you can do the offset calibration. boot the system expecting to see the crosstalk target, do the refSPAD, then the crosstalk. 
  • You can start ranging repeatedly after the crosstalk cal. When the sensor returns a range a lot closer to 140mm than 600mm, you know the target is in place. Stop ranging and call the offset cal function. Might want to wait a bit in case the offset flap does not fold down quickly. 

  • Are there specific target size or reflectivity requirements? A good target is 88% reflective and matte finish. White printer paper is perfect. And cheap. I'd use a few thicknesses of paper. At 140mm you only need a 70mm circle, but let's be generous and use 100mm to prevent any alignment issues.

[MattH2]

Thank you very much for your prompt and detailed reply — that clarifies a lot, especially regarding the setup and physical positioning during calibration. I really appreciate the tip about using white printer paper as a target — practical and effective!

I now have a follow-up question regarding how to handle the calibration data in code when using the bare driver.

For example, in the case of RefSPAD calibration:

• Should I explicitly call VL53L1_PerformRefSpadManagement(VL53L1_DEV Dev)

• Then call VL53L1_GetCalibrationData()

• And finally use VL53L1_SetCalibrationData()

Do these three functions need to be used in separate steps, or is there a single wrapper function that performs the calibration, retrieves, and stores the results for you?

Additionally, must I apply (set) the calibration data from the previous step (e.g., RefSPAD) before beginning the next calibration step (e.g., Crosstalk or Offset)? Or can all calibration steps be performed sequentially before saving/applying the full calibration block?

Thanks again for the valuable support.
— Matthew Henderson

[John E KVAM]

If you have your crosstalk target in position, then you can call

• RefSPAD
• Crosstalk

Then range until you are sure the offset target is in place and

• stop the ranging and 
• offset cal

Once you have done all 3 steps you can extract the cal data with 

• VL53L1_GetCalibrationData()

• And store that in your memory.

At all subsequent bootups, 

• read your cal data from your memory and call
• VL53L1_SetCalibrationData()

At each step, the cal data is stored in registers, and you can extract it at any point, but by doing all three and then extracting the data, you save a little work.