{"id":4287,"date":"2020-01-08T20:00:37","date_gmt":"2020-01-08T19:00:37","guid":{"rendered":"https:\/\/msalamon.pl\/?p=4287"},"modified":"2025-12-27T18:27:42","modified_gmt":"2025-12-27T17:27:42","slug":"low-cost-laser-distance-measurement-with-the-vl53l0x-tof-sensor","status":"publish","type":"post","link":"https:\/\/msalamon.pl\/en\/low-cost-laser-distance-measurement-with-the-vl53l0x-tof-sensor\/","title":{"rendered":"Low-Cost Laser Distance Measurement with the VL53L0X ToF Sensor"},"content":{"rendered":"\n

Anyone who has spent even a moment dealing with robotics knows that distance measurement plays an incredibly important role in this field. Practically everywhere we deal with devices that move, some kind of obstacle detection is advisable. This is often implemented by measuring distance.<\/p>\n\n\n\n\n\n\n\n

Such measurement can be done in many ways. The methods differ in operating speed, accuracy, and the maximum measurable distance that can be achieved.<\/p>\n\n\n\n

Among these solutions, ultrasonic sensors are incredibly popular. For just a few zlotys you can buy an HC-SR04<\/a>, which performs perfectly not only in hobby electronics. One of its drawbacks is size. It won\u2019t be suitable for a small robot, and it\u2019s also hard to hide.<\/p>\n\n\n\n

Small laser sensors come to the rescue. Today I took a closer look at an ST sensor labeled VL53L0X<\/a>.<\/p>\n\n\n\n

You can find the second part with interrupt handling here<\/a><\/p>\n\n\n\n

Micro ToF sensor VL53L0X<\/h1>\n\n\n
\n
\"\"<\/a><\/figure>\n<\/div>\n\n\n

<\/p>\n\n\n\n

This is a ToF<\/a> (Time-of-Flight) sensor, meaning that distance is measured by timing the flight of, in this case, a laser beam. The sensor checks how long it takes for light to reach the object, bounce off it, and return to the receiving sensor. Ultrasonic sensors work in a similar way.<\/p>\n\n\n\n

ST boasts that this is the smallest laser sensor in the world<\/strong>, and the dimensions are indeed impressive. The whole little chip measures only 4.4 x 2.4 x 1 mm, so it\u2019s just slightly larger than a resistor in a 1206 package. <\/p>\n\n\n\n

The laser used in the sensor, with a wavelength of 940 nm, is designed to meet standards for use around the \u201cnaked\u201d eye. Being around it should not pose any risk.<\/p>\n\n\n\n

Interestingly, such lasers are sometimes used to aid autofocus in digital cameras. Some older smartphones boasted laser autofocus\u2014I even had one. Now I don\u2019t recall any newer handsets having a laser. Maybe it wasn\u2019t that great.<\/p>\n\n\n\n

The sensor communicates with the host via the I\u00b2C interface. In addition to the standard bus pins, there\u2019s also an interrupt output and an input for turning the sensor off.<\/p>\n\n\n\n

ST includes a complete library with the sensor, which they proudly call an API. It contains probably everything you can do with the chip. This is quite a good move, because the chip is very complex for a simple sensor. It contains dozens of registers you can talk to. For beginners, this can cause quite a headache.<\/p>\n\n\n\n

However, simply using the library can also lead to a migraine. The library is written in a generic way, so it takes up a lot of code. It\u2019s no secret that lots of code means lots of Flash memory. I\u2019ll check how much it actually is.<\/p>\n\n\n\n

Additionally, it\u2019s very hard to find sensible descriptions of how to use this sensor. You have to dig through the inhumanly written API documentation and examples for Nucleo boards and shields with these sensors.<\/p>\n\n\n\n

The Getting Started guides I mostly found boil down to taking the same Nucleo as in the examples, flashing a prebuilt binary, and enjoying the results. No no no, ST\u2026<\/p>\n\n\n\n

Enough of my whining. Let\u2019s move on to how to run this bulky API on any microcontroller.<\/p>\n\n\n\n

What do you need?<\/h2>\n\n\n\n

You will of course need a microcontroller. Specifically, an STM32. Today I took the STM32F401CCU6<\/a> from the new items in my store. I wrote more broadly about these boards in one of the previous articles<\/a>.<\/p>\n\n\n\n

As development tools, I used STM32CubeIDE version 1.1.0, which has the integrated STM32CubeMX 5.4.0. The HAL libraries I use are F4 v1.24.2.<\/p>\n\n\n\n

Besides the board and the IDE, you also need the aforementioned API. You can find it here<\/a>.<\/p>\n\n\n\n

And finally, a package with an add-on for Cube<\/a> for the Nucleo shield with our sensor will come in handy. I\u2019ll explain in a moment why both the API and the Cube extension are needed.<\/p>\n\n\n\n

Project in Cube<\/h2>\n\n\n\n

Choose the F401CEU6 CPU, unless you have a different one. First, the clock. For tests I like to use the highest possible frequencies. I set 84 MHz HCLK using the external 25 MHz crystal found on the board. To use it, in the RCC tab you need to select High Speed Clock (HSE)<\/strong> as Crystal\/Ceramic Resonator<\/strong>. Then in Clock Configuration<\/strong> from the top menu, enter the number 84 in the HCLK field and press Enter<\/strong>. Cube will calculate everything for you \ud83d\ude42<\/p>\n\n\n\n

For communication you\u2019ll need I\u00b2C, so configure one of the available interfaces. I chose I2C1 on pins PB8 and PB9<\/strong>. The sensor supports 400 kHz, and you should stick to that. For comparison, leave me 100 kHz \ud83d\ude42<\/p>\n\n\n\n

I will send the measurement results via UART. Initially I wanted to use USB, but that\u2019s a bit more hassle. I\u2019ll cover USB another time \ud83d\ude42 I took USART2 as usual<\/strong>, like on every Nucleo, and connected to the PC through a converter. I set it to 115200 8n1. No surprises.<\/p>\n\n\n\n

Remember that the ToF sensor has two more pins \u2014 the interrupt called GPIO1 on the board and XSHUT<\/strong> for turning the sensor off. I connected both to the microcontroller<\/strong>. While I will definitely use the interrupt, XSHUT may not be needed right now.<\/p>\n\n\n\n

When would XSHUT be needed<\/strong>? The first thing that comes to mind is saving energy. That\u2019s true, but another situation where you can use it is connecting multiple sensors to one bus. Unfortunately, VL53L0X sensors don\u2019t have a configurable I\u00b2C address, so you have to get creative this way. XSHUT allows switching between sensors without reinitializing them.<\/p>\n\n\n\n

This is how the \u201cschematic\u201d from Cube looks.<\/p>\n\n\n

\n
\"\"<\/a><\/figure>\n<\/div>\n\n\n

<\/p>\n\n\n\n

Launching the VL53L0X API<\/h2>\n\n\n\n

I won\u2019t hide that it was hard for me to find on ST\u2019s pages how to use the API. Texts pointing to documentation describing the use of the API led to a pointless 2-page document that only showed the API directory structure. Who needs that? In the end I pieced together several different tips from the Internet, read some of the massive documentation, and it worked \ud83d\ude42 Here\u2019s what I did.<\/p>\n\n\n\n

Unpack the packages with the API and the Nucleo add-on. The first thing to do is copy the API into your project. It\u2019s the entire contents of ..\\VL53L0X_1.0.2\\Api\\<\/strong><\/p>\n\n\n\n

I put it into the Drivers<\/strong> directory in the project.<\/p>\n\n\n

\n
\"\"<\/a><\/figure>\n<\/div>\n\n\n

Now you need to add the header and source file paths to the project. Do this by going to Project > Properties > C\/C++ General > Paths and Symbols<\/strong>. In the Includes<\/strong> tab, add the inc folders from the API<\/strong>, and in the Source Location<\/strong> tab, add the src folders<\/strong><\/p>\n\n\n

\n
\"\"<\/a><\/figure>\n<\/div>\n\n
\n
\"\"<\/a><\/figure>\n<\/div>\n\n
\n
\"\"<\/a><\/figure>\n<\/div>\n\n\n

The header you need to include in main.c is vl53l0x_api.c<\/strong>. Unfortunately, attempting to compile with the API added will throw a few errors.The compiler tells us it\u2019s missing the file\u2026 windows.h?! It turns out that within the API there are files corresponding to the platform on which we want to use it. When downloading the API from ST\u2019s website, it\u2019s configured by default to work on Windows and includes such examples. In my opinion this is a bit strange, but OK. We need to make sure that the platform is configured as our microcontroller. <\/p>\n\n\n\n

For this we will use the Cube extension package for our sensor. As it happens, it\u2019s written using HAL, so no matter which Nucleo the examples were written for, porting will be simple.<\/p>\n\n\n\n

First, remove the file vl53l0x_i2c_win_serial_comms.c<\/strong> which is tied to Windows.<\/p>\n\n\n\n

Second, unpack X-CUBE-53L0A1<\/strong> and from the folder<\/strong> ..\\X-CUBE-53L0A1\\STM32CubeExpansion_VL53L0X_V1.2.0\\Drivers\\BSP\\X-NUCLEO-53L0A1<\/strong> copy the files vl53l0x_platform.h and vl53l0x_platform.c<\/strong> to the appropriate places in the project. Overwrite them.<\/strong><\/p>\n\n\n

\n
\"\"<\/figure>\n<\/div>\n\n\n

<\/p>\n\n\n\n

We\u2019re close \ud83d\ude42 Now similarly copy the pair vl53l0x_platform_log. h and .c <\/strong>this time from the path ..\\X-CUBE-53L0A1\\STM32CubeExpansion_VL53L0X_V1.2.0\\Drivers\\BSP\\Components\\vl53l0x.<\/strong><\/p>\n\n\n\n

These files are responsible for logging the API operation on the platform. By default they are disabled, and the ones from the API were written for Windows. I have not tested their operation.<\/p>\n\n\n\n

If you compile now, you will probably have one error left. The compiler cannot find stm32xxx_hal.h<\/strong> to include it in vl53l0x_platform.h and .c. The platform files were written some time ago when the HAL files were named slightly differently.<\/p>\n\n\n\n

It\u2019s enough to replace the line #include \u201cstm32xxx_hal.h\u201d in the files<\/strong> vl53l0x_platform.h and .c with the appropriate header for your microcontroller. In my case, for the F4 family it will be #include \u201cstm32f4xx_hal.h\u201d.<\/strong><\/p>\n\n\n\n

Now compilation went through without errors. We should also run a simple measurement.<\/p>\n\n\n\n

Using the API for a single measurement<\/h2>\n\n\n\n

If you haven\u2019t previously included the header vl53l0x_api.h in main.c, do it now. Then you will need a few variables for the sensor to work.<\/p>\n\n\n\n

VL53L0X_RangingMeasurementData_t RangingData;\nVL53L0X_Dev_t  vl53l0x_c; \/\/ center module\nVL53L0X_DEV    Dev = &amp;vl53l0x_c;<\/pre>\n\n\n\n
The first is the structure with measurements. The second is the device structure. The third is a pointer to the structure from point no. 2.<\/p>\n\n\n\n
For initialization you need a few helper variables. I put them in user section no. 1.<\/p>\n\n\n\n
  \/* USER CODE BEGIN 1 *\/\n\t\/\/\n\t\/\/ VL53L0X initialisation stuff\n\t\/\/\n    uint32_t refSpadCount;\n    uint8_t isApertureSpads;\n    uint8_t VhvSettings;\n    uint8_t PhaseCal;\n  \/* USER CODE END 1 *\/<\/pre>\n\n\n\n
and the sensor initialization<\/p>\n\n\n\n
  \/* USER CODE BEGIN 2 *\/\n  MessageLen = sprintf((char*)Message, \"msalamon.pl VL53L0X test\\n\\r\");\n  HAL_UART_Transmit(&amp;huart2, Message, MessageLen, 100);\n\n  Dev-&gt;I2cHandle = &amp;hi2c1;\n  Dev-&gt;I2cDevAddr = 0x52;\n\n  HAL_GPIO_WritePin(TOF_XSHUT_GPIO_Port, TOF_XSHUT_Pin, GPIO_PIN_RESET); \/\/ Disable XSHUT\n  HAL_Delay(20);\n  HAL_GPIO_WritePin(TOF_XSHUT_GPIO_Port, TOF_XSHUT_Pin, GPIO_PIN_SET); \/\/ Enable XSHUT\n  HAL_Delay(20);\n\n  \/\/\n  \/\/ VL53L0X init for Single Measurement\n  \/\/\n\n  VL53L0X_WaitDeviceBooted( Dev );\n  VL53L0X_DataInit( Dev );\n  VL53L0X_StaticInit( Dev );\n  VL53L0X_PerformRefCalibration(Dev, &amp;VhvSettings, &amp;PhaseCal);\n  VL53L0X_PerformRefSpadManagement(Dev, &amp;refSpadCount, &amp;isApertureSpads);\n  VL53L0X_SetDeviceMode(Dev, VL53L0X_DEVICEMODE_SINGLE_RANGING);\n\n  \/\/ Enable\/Disable Sigma and Signal check\n  VL53L0X_SetLimitCheckEnable(Dev, VL53L0X_CHECKENABLE_SIGMA_FINAL_RANGE, 1);\n  VL53L0X_SetLimitCheckEnable(Dev, VL53L0X_CHECKENABLE_SIGNAL_RATE_FINAL_RANGE, 1);\n  VL53L0X_SetLimitCheckValue(Dev, VL53L0X_CHECKENABLE_SIGNAL_RATE_FINAL_RANGE, (FixPoint1616_t)(0.1*65536));\n  VL53L0X_SetLimitCheckValue(Dev, VL53L0X_CHECKENABLE_SIGMA_FINAL_RANGE, (FixPoint1616_t)(60*65536));\n  VL53L0X_SetMeasurementTimingBudgetMicroSeconds(Dev, 33000);\n  VL53L0X_SetVcselPulsePeriod(Dev, VL53L0X_VCSEL_PERIOD_PRE_RANGE, 18);\n  VL53L0X_SetVcselPulsePeriod(Dev, VL53L0X_VCSEL_PERIOD_FINAL_RANGE, 14);\n  \/* USER CODE END 2 *\/<\/pre>\n\n\n\n
At the beginning I introduce myself \ud83d\ude09 Next it\u2019s important to initialize the fields in the Dev structure. You need to specify which I\u00b2C you\u2019re using by providing a reference to the HAL handle structure. You also provide the sensor address (which, in fact, cannot be changed).<\/p>\n\n\n\n
Then I toggle the XSHUT pin. It\u2019s a bit over the top, but I can.<\/p>\n\n\n\n
Finally, the sensor is initialized to operate in single-measurement mode. I took this from the examples for Windows \ud83d\ude42 They turned out to be useful after all. As you can see, we initialize some timing and range constants. These sensors are really quite elaborate, and I\u2019ll analyze this in more depth.<\/p>\n\n\n\n
After all this initialization, you can put the measurement in the main loop of the program.<\/p>\n\n\n\n
\t  VL53L0X_PerformSingleRangingMeasurement(Dev, &amp;RangingData);\n\n\t  if(RangingData.RangeStatus == 0)\n\t  {\n\t\t  MessageLen = sprintf((char*)Message, \"Measured distance: %i\\n\\r\", RangingData.RangeMilliMeter);\n\t\t  HAL_UART_Transmit(&amp;huart2, Message, MessageLen, 100);\n\t  }\n<\/pre>\n\n\n\n
Unfortunately, this is a blocking measurement<\/strong> that doesn\u2019t use the interrupt pin. However, it works! The measurement is in millimeters.<\/p>\n\n\n\n
The value RangingData.RangeStatus contains information on whether the measurement succeeded. A nice thing to filter out bad readings. <\/p>\n\n\n\n
You\u2019ll find the distance under RangingData.RangeMilliMeter.<\/strong><\/p>\n\n\n
\n
\"\"<\/a><\/figure>\n<\/div>\n\n\n
<\/p>\n\n\n\n
Some measurements and numbers<\/h2>\n\n\n\n
I wouldn\u2019t be myself if I didn\u2019t peek at the analyzer, right? First, the entire measurement \u201ccycle\u201d. Fortunately, the interrupt pin is toggling all the time, so it\u2019s easier for me to capture the appropriate timing.<\/p>\n\n\n\n
100 kHz<\/p>\n\n\n
\n
\"\"<\/a><\/figure>\n<\/div>\n\n\n
<\/p>\n\n\n\n
400 kHz<\/p>\n\n\n
\n
\"\"<\/a><\/figure>\n<\/div>\n\n\n
<\/p>\n\n\n\n
Between successive \u201cinterrupts\u201d there\u2019s 41 ms for 100 kHz and 36 ms for 400 kHz. According to the documentation, sampling and computing the distance takes ~31 ms, so adding I\u00b2C transmission time could fit. As you can see, quite a bit of data goes over the bus. The smaller bars are polling the sensor to check whether it\u2019s finished. That\u2019s obvious when we operate in polling mode. However, there are two wider bars. The first is the measurement start.<\/p>\n\n\n\n
100 kHz<\/p>\n\n\n
\n
\"\"<\/a><\/figure>\n<\/div>\n\n\n
400 kHz<\/p>\n\n\n
\n
\"\"<\/a><\/figure>\n<\/div>\n\n\n
3.14 ms for 100 kHz vs 0.84 ms for 400 kHz. That matches the theory \ud83d\ude42
All that remains is to check how long the MCU takes to collect the measurement.<\/p>\n\n\n
\n
\"\"<\/a><\/figure>\n<\/div>\n\n\n
100 kHz400 kHz<\/p>\n\n\n
\n
\"\"<\/a><\/figure>\n<\/div>\n\n\n
2.8 ms for 100 kHz vs 0.795 ms for 400 kHz.<\/p>\n\n\n\n
As you can see, there\u2019s quite a lot of data to collect from such a sensor. Ideally, you\u2019d bring in interrupt mode, and best together with DMA. For now, I don\u2019t know if the API supports this. I\u2019ve already spent some time wrestling with getting it to run.<\/p>\n\n\n\n
Code size<\/h2>\n\n\n\n
At the beginning I mentioned that this API is somewhat heavy. In the table I included bare code with configured peripherals without the API and code with the API. Both versions with optimization -O1 and without -O0. Here are the numbers.<\/p>\n\n\n\n
<\/td>-O0<\/th>-O1<\/th><\/tr><\/thead>
Bare code<\/td>8,73 KB<\/td>5,57 KB<\/td><\/tr>
with API<\/td>36 KB<\/td>22,52 KB<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
As you can see, this API weighs a bit\u2026 Is it worth it? I\u2019m not yet able to answer that. I\u2019ll try to do something with interrupts or DMA \ud83d\ude42<\/p>\n\n\n
\n
\"\"<\/a><\/figure>\n<\/div>\n\n\n
<\/p>\n\n\n\n
Summary<\/h2>\n\n\n\n
The VL53L0X<\/a> sensor is nice, small, but somewhat complicated. The API helps a lot, but it costs a lot of space on the microcontroller. I\u2019ll still check what possibilities there are for using this library with interrupts or DMA.<\/p>\n\n\n\n
There are also Arduino libraries written based on this API. I\u2019ve seen that they\u2019re a bit lighter. I might take a look at them as well.<\/p>\n\n\n\n
You can find the second part with interrupt handling here<\/a><\/p>\n\n\n\n
You can find the full project along with the library, as usual, on my GitHub: link<\/a><\/p>\n\n\n\n
If you\u2019ve noticed an error, disagree with something, would like to add something important, or simply feel like discussing this topic, write a comment. Remember that the discussion should be polite and in accordance with the rules of the Polish language.<\/span><\/p>\n\n\n
\n            \n
\n    \n
\n            
\n            \n\n
<\/div>\n        <\/div>\n            
\n            \n\n
<\/div>\n        <\/div>\n            
\n            \n\n
<\/div>\n        <\/div>\n            
\n            \n\n
<\/div>\n        <\/div>\n            
\n            \n\n
<\/div>\n        <\/div>\n    <\/div>\n    \n
\n            
\n            \n\n
<\/div>\n        <\/div>\n            
\n            \n\n
<\/div>\n        <\/div>\n            
\n            \n\n
<\/div>\n        <\/div>\n            
\n            \n\n
<\/div>\n        <\/div>\n            
\n            \n\n
<\/div>\n        <\/div>\n    <\/div>\n<\/div>\n                \n\n
\n            <\/span>\n    <\/div>\n    <\/div>\n","protected":false},"excerpt":{"rendered":"
Anyone who has spent even a moment dealing with robotics knows that distance measurement plays an incredibly important role in this field. Practically everywhere we deal with devices that move, some kind of obstacle detection is advisable. This is often implemented by measuring distance.<\/p>\n","protected":false},"author":1,"featured_media":3374,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":"","_links_to":"","_links_to_target":""},"categories":[160],"tags":[176,174,177],"class_list":["post-4287","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-stm32","tag-programming","tag-stm32","tag-stm32cubemx"],"_links":{"self":[{"href":"https:\/\/msalamon.pl\/en\/wp-json\/wp\/v2\/posts\/4287","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/msalamon.pl\/en\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/msalamon.pl\/en\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/msalamon.pl\/en\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/msalamon.pl\/en\/wp-json\/wp\/v2\/comments?post=4287"}],"version-history":[{"count":3,"href":"https:\/\/msalamon.pl\/en\/wp-json\/wp\/v2\/posts\/4287\/revisions"}],"predecessor-version":[{"id":4389,"href":"https:\/\/msalamon.pl\/en\/wp-json\/wp\/v2\/posts\/4287\/revisions\/4389"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/msalamon.pl\/en\/wp-json\/wp\/v2\/media\/3374"}],"wp:attachment":[{"href":"https:\/\/msalamon.pl\/en\/wp-json\/wp\/v2\/media?parent=4287"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/msalamon.pl\/en\/wp-json\/wp\/v2\/categories?post=4287"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/msalamon.pl\/en\/wp-json\/wp\/v2\/tags?post=4287"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}