HowTo: ESPEasy – level sensor with VL53L0X / VL53L1X

Recently I stumbled upon the VL53L0X and VL53L1X TOF distance sensors. These sensors can determine distances with millimeter precision using a laser. They have a range of up to 4 m (VL53L1X9) or 2 m (VL54L0X). I found the sensors very interesting and of course ordered a few straight away. I like to have practical things in stock 🙂

After they arrived and I played around with them, I noticed that they could also be used to determine the level of my coffee cup. A quick test on the sink and another test on the rain barrel showed that this also worked with clear liquids. That gave me my first idea for practical use: a level sensor for the rain barrel.

The following article describes what you need and how you can go about building your own level sensor. 🙂

Safety instructions

I know the following notes are always kind of annoying and seem unnecessary. Unfortunately, many people who knew "better" have lost eyes, fingers or other things due to carelessness or injured themselves. Data loss is almost negligible in comparison, but even these can be really annoying. Therefore, please take five minutes to read the safety instructions. Because even the coolest project is not worth injury or other trouble.

Affiliate links/advertising links

The links to online shops listed here are so-called affiliate links. If you click on such an affiliate link and make a purchase via this link, will receive a commission from the relevant online shop or provider. The price does not change for you. If you make your purchases via these links, you support in being able to offer other useful projects in the future. 🙂 


Helpful articles:
Before you start with this article, you should have dealt with the basics of soldering. You can find information about this in the following article.

Required tool:

In the following list you will find all the tools you need to implement this article.

Required material:

In the following list you will find all the parts you need to implement this article.

Collect required parts

In the following picture you can see the parts required to build your own level sensor.

A micro USB cable and a strip of self-welding adhesive tape are still missing from the picture.

Print the 3D parts you need

Download all the required STL files:

Cut threads into the housing

To ensure that the USB cable for the power supply can be routed into the housing in a waterproof manner, you should use a cable gland. This is the only way to permanently prevent water from penetrating the housing over time.

In order to be able to mount this cable gland in the housing, a thread must first be cut into the housing. Cutting internal threads is also discussed in the article Mechanics – cutting internal threads explained in detail.

As usual, place the tap as straight as possible. Also remember to turn back one revolution after each complete revolution to break off the chip.

As soon as you have cut the entire thread with the thread cutter, the whole thing should...

... look something like this.

Now you can screw the cable gland into the freshly cut thread.

In this way you will also quickly determine whether the thread is completely cut or not.

If you held the tap straight while cutting the thread, you can now see that the sealing ring is pressed evenly against the housing everywhere and therefore seals well.

View from the outside.

View from inside.

Prepare the distance sensor

Now it's time to prepare to install the actual sensor. This communicates with the microcontroller via the I2C bus and therefore requires a total of four lines.

Prepare the connecting cable by stripping 5 mm of insulation from the ends of the individual cables and tinning them with a little solder.

You can then prepare the actual sensor by first tinning the contacts “VCC”, “GND”, “SCL” and “SDA” with some solder.

At this point you can also remove the yellowish protective film from the sensor surface.

Now you can solder the cables to the corresponding contacts as shown.

When everything is fully prepared, it should look something like this.

Connect the distance sensor to the Wemos D1 Mini

Now of course the sensor has to be connected to the microcontroller.

To do this, you should first prepare the contacts again. For this purpose, the contacts “5V”, “G”, “D2” and “D1” are tinned.

You can then solder the previously prepared connecting cable to the microcontroller.

The whole thing should be ready…

... look something like this.

Install the distance sensor

The unit consisting of microcontroller and sensor must now of course be installed in the housing in a watertight manner.

To do this, position the M3 nuts as shown...

... under the holder in the housing.

The nuts should be positioned so that they…

... lie exactly under the holes through which the screws will later be inserted.

Now you can insert the small sealing ring into the recess.

The sensor is then placed on this as shown and screwed with the M3x10 screws.

Be careful not to tighten the screws too tightly. Because after “firm” comes “off”. 🙂

Now you can quickly check that the sensor also has a clear “view”... the outside.

Installing the Wemos D1 Mini and USB cable

After the sensor has been installed in the correct location, all other components must be stored waterproof in the housing.

This is what the sensor should currently look like. 🙂

The size of the micro USB plug is somewhat critical: it has to be small enough to fit through the nut of the cable gland.

If necessary, you can also use a file to edit the connection so that it fits through the nut.

As soon as the micro USB plug is pulled through the nut...

...and you start pulling the mother tight... will quickly notice that there is still a lot of space between the rubber seal of the cable gland and the USB cable.

This is clearly too much space to prevent water from entering the case.

Therefore, you should unscrew the cable gland again and pull out the USB cable by approx. 2 cm. Now wrap the area of the cable that was previously in the cable gland with a few wraps of self-welding adhesive tape.

This way you can increase the diameter of the cable at the relevant point...

... and thus secure the USB cable watertight in the cable gland. The USB cable should now also be mechanically secured against being pulled out.

Front view.

Now you can do the rest of the installation: Before the microcontroller is stored in the housing, you can secure the sensor contacts against short circuits with some hot glue.

Of course, you can also do this later - after an initial test - as soon as you are sure that everything is working properly.

You can also do the same with the contacts of the microcontroller.

The microcontroller can then be connected to the micro USB cable…

... and inserted into the housing.

You may have to loosen the union nut on the screw nozzle again. 🙂

When fully assembled, the whole thing should now look like this. 🙂

Seal the housing watertight

The almost final step: Now that all the components have been installed in the housing, you also have to seal it watertight.

Your sensor should currently be...

…be constructed.

At this point you can of course skip ahead to a chapter and program the microcontroller first. The housing can also be closed after programming and the first tests. 🙂

Four M3 nuts are now required to close the housing.

Place these from below in the designated mounting locations in the corners of the housing.

Then turn the housing over without the nuts falling out of their mounting positions.

Then you can insert the sealing ring into the bulge on the top.

Now put the cover plate on and guide the screws through the holes provided.

When tightening the screws, you should always tighten the opposite screws. For example, first at the top right, then at the bottom left, then at the top left and finally at the bottom right.

The screws should be tightened so that the gap between the housing and the cover is the same size everywhere.

Programming the firmware

In principle, you have many options when it comes to firmware. You can equip the ESP8266 installed on the Wemos D1 Mini with your own firmware, but you can also use the popular firmware “Tasmota” or “ESPEasy”.

Personally, I find ESPEasy the most pleasant because you have more setting options. For some, however, this may be an argument for preferring to use the Tasmota firmware, which, in my opinion, has a few more “simply functioning” presets.

How you can read the VL53L0X sensor with ESPEasy and the appropriate plugin is described in the following article.

Assembly suggestion

Here is a small installation suggestion on how you could mount the sensor on a rain barrel, for example.

You should definitely make sure that the sensor is not flooded if the rain barrel overflows. The sensor is very well protected against splash water, but it should not be immersed in water. 🙂

For example, the sensor can be installed so that it rests on the edge of the barrel.

If available, you can also drill a hole in the lid and align the sensor with the water surface. A step drill is very suitable for this.

Evaluation in NodeRed

It's one thing to record the level of your rain barrel. Another is to receive this data, process it and, if necessary, convert it.

Because so far you only get a distance from your sensor. That's not really a volume that you actually want to measure. Therefore, the water level still needs to be converted into a volume. This depends on the shape and dimensions of your rain barrel and is not always easy to calculate. So here are a few suggestions and a flow that visually prepares the whole thing a bit.

Further information

Have fun with the project

I hope everything worked as described for you. If not or you have questions or suggestions please let me know in the comments. I will then add this to the article if necessary.
Ideas for new projects are always welcome. 🙂

PS Many of these projects - especially the hardware projects - cost a lot of time and money. Of course I do this because I enjoy it, but if you think it's cool that I share the information with you, I would be happy about a small donation to the coffee fund. 🙂

Buy Me a Coffee at       


  1. Hello

    Thank you for the successful guide!
    It is not entirely clear to me how I can integrate the VL53L0X sensor into the EspEasy.
    Do I have to load a certain firmware (I don't have that much experience yet)

    I would be very grateful if you could help me here.

    Greetings Stefan Allenspach

    1. Hello Mr. Allenspach,
      That's right, I should explain that part better in the manual. Thanks for the hint. 🙂
      Until then: In this article ( in the paragraph “Configure the plugin” the process for the device “Display – Nerdiys-PanelMeter” is explained. This works exactly with the VL53L0X, except that of course the device “VL53L0X” has to be selected. Please let me know if it worked. 🙂
      Best regards

  2. Hello,
    Great article and this is how I first became aware of the possible solution with TOF sensors. A question that is very important for my tank and I don't have 3D printing available and have to “make” a housing for myself. Is the opening shown waterproof? In my case, the tank occasionally gets 100% full and so the sensor can get a few drops. The photos show a hole where more than the openings for the sensor's light passes through, so I think water can get in here? Is it possible to close this with a small disc? Would be important to me and I think it would be a crucial difference to ultrasound measurement. Currently (in the DIY area) there is only waterproof with a minimum distance of 20cm and some reported problems in tanks. The TOF solution would therefore be ideal.
    Best regards

    1. Hello Ralf,
      Thanks. 🙂 My solution is at most splash-proof. And only from above. The lid should be fairly tight thanks to the O-ring. But as you have already seen correctly, the sensor is not waterproof. Unfortunately, I only read later that the sensor can also be installed behind a pane of glass. You can probably find more information about this in the data sheet for the sensor. 🙂 When I have time I will design a new version of the case. If you don't feel like tinkering: There are also online printing services where you can print out the parts and have them sent to you. 🙂
      Best regards

  3. Hello Fabian,
    Thank you very much for your feedback. I have now ordered a VL53L0X with this cover cap and believe I can mount/glue it into something like an AP junction box. Nothing against your housing, but for me it would be used in a dug hole in a water tank in the garden, which no one would ever see (as they say, pearls before swine...). When the function is fulfilled, I'm very happy. I also use ESPEasy for my previous ESP8266 stories and would like to do so again here (the rules alone to filter/calm down a fluctuating measurement result would be copy & paste). As my previous commenter says, unfortunately it's not entirely clear to me how to integrate the P0133 plug-in for compiling ESPEasy. Your link helps, but the activation of plugins seems to have changed by deleting the comment characters from the structure in ESPEasy. I assume there is a central administration file there. In addition, P0133 no longer seems to be present in the “MEGA” version of ESPEASY (it ends at P097). For the VL53L0X, I'm still optimistic about getting this out somehow if the plugin for the current version still works, but how does this work for a VL53L1X? Simply integrate the VL53L1X.h from Polulu into the project and adapt the ino file accordingly?
    Keep it exciting and stay tuned to the project.
    Best regards

    1. Hi Ralph,
      Oh all good. I can fully understand. Ultimately, it's all about the reliable function and less about the optics. 😀
      As far as the problem with the plugin is concerned: I am currently still very busy writing the documentation for WinDIY until next Monday (information here: When I'm done with that, I'll deal with it and open a repository on GitHub, where I offer all my plugins, including ESPEasy, configured accordingly. Then you no longer have to make the changes yourself and it should work straight away. 🙂
      I hope that's okay. 🙂
      Best regards

      1. Hello
        Great description, great project.
        I currently have an ultrasound measurement, but it works very poorly in the well (up to 3.5 meters deep) (I've tried everything possible).
        In search of an alternative, I came across the VL53L1X and your site.
        I am currently also using ESPEasy with the ultrasonic sensor, but like the previous speakers I am more of a user and Hoppy programmer and not so much a “plug-in compiler”. If you could help us with the VL53L1X and ESPEasy, I would also be very grateful. 🙂

        1. Good evening Erwin,
          yes, this place is unfortunately a little sparsely documented. I just looked and couldn't find any instructions that describe it. I'll write that down and try to create instructions as soon as possible that explain how to connect the sensor and configure the plugin accordingly.
          As a small workaround, I created a .bin file that can be programmed on the Wemos D1 Mini. The VL53L0X is already integrated in it. You only have to activate it later (as usual with ESPEasy) and configure it accordingly.
          You can find the bin file at:
          I have summarized information on how to program this on the Wemos D1 Mini or ESP8266 here:

          I hope that helps. Otherwise please let me know. 🙂
          Best regards

          1. Hello Fabian
            Thanks for your quick and friendly help.
            I ordered a couple of VL53L0X and VL53L1X a few days ago.
            For safety. They will now need a little bit until they are there from China.
            Then I will test your image with the VL53L0X. Unfortunately, there is almost nothing on the net about the VL53L1X 🙁 Except for approaches that are a bit too high for me.
            Thank you & best regards

          2. Good evening Erwin,
            understood. I know the problem (with the long shipping time). 😀 Maybe I'll have finished the article by then. I'll try to think of it, then let you know here as well. 🙂
            Best regards

          3. Hello Fabian
            Thank you for your support. I'll try again when I've got everything together. I'll definitely let you know how it goes. if necessary I will torment you again. 😉
            Thank you & best regards

        2. Hello Ervin,

          Unfortunately, the LaserSensor from AliExpress never got to me and similar to yours, results with an ultrasonic sensor, among other things, did not convince me. The measurements are very error-prone and each measurement deviates from each other even if nothing happens, ok cheap and you can work with software filters. I once ordered a fill level probe for around €20 and these are available in different versions (measuring ranges e.g. 0-5m). Since I'm already using a good piece of cable, I didn't want to use a probe with a voltage measurement signal, but 4-20mA. For the 4-20mA to 0-3.3V (ESP8266 analog input) as well as for the 24VDC supply there are ready-made modules (about 1€) at Ali-Express and I am super happy with them. Software runs ESPEasy in the standard version and simply evaluates the analog input. Greetings Ralph

          1. Hello Ralf
            Thank you for your kind reply.
            I've read about that too. Is it really that good/easy?
            I was put off by the fact that you have to “calibrate” the values.
            So bottom and top value. At least that's what I read somewhere.
            Well, maybe I'll take up the topic again.
            Thank you & best regards

          2. Hello Fabian, hello Ralf

            Thank you for all your help and ideas, I finally put aside measuring with the LaserSensor after initial attempts and tried the variant with a level probe. And I have to say: SUPER!! The hardware effort is certainly greater (but quite manageable), but it is also easy to configure in ESPEASY. It's only been running for a few days, but I'm pleasantly surprised. The measurement works without significant fluctuations. As soon as I have long-term experience, I'll be happy to share it with you.
            @ Ralf how are your experiences so far.?
            @Fabian: You absolutely have to try it. I followed this guide, works perfectly.

            Cheers Erwin 🙂

  4. Hello Fabian,
    Thank you and everything is fine for me. Ali-Express is slow to deliver 🙂
    I think your repository is great and would use it, but I'm also a big fan of explaining the principle to willing people using an example. With a bit of luck, the “knowledgeables” increase their power and progress mini-step by mini-step and can also help others. I think you also want to do new things and not just explain the same stuff over and over again 🙂
    Best regards

    1. Hey Ralph,
      Yes, you're right. Actually, my “motto” is to describe things in very small steps if necessary. 🙂 As soon as I have time I'll take care of it.
      Best regards

  5. Hi
    can someone tell me which tasmota I have to flash on the esp?
    Unfortunately, the sensor bin does not recognize the vl53lox, not even the latest tasmota bin
    thanks in advance

  6. Hi,
    Does anyone else have the problem that when the sensor is installed, only values below 30cm are displayed, although there should be more? As soon as it is expanded, it shows the correct distance.
    The sensor actually has a clear view.

    1. Hi, I can confirm that. In the meantime I found out that it makes a difference whether the sensor is operated indoors or outdoors. I have an experimental setup with a laptop and as soon as I step in front of the door, distances of only approx. 40 cm are recorded.

  7. Good bye

    I have the problem that no values are displayed under Tasmota (12.0.2). The VL53L0X is connected to D1 (SCL) and D2 (SDA). Tasmota is also configured in the same way (D1 - I2C SCL and D2 - I2C SDA).

    When I use ESPEasy everything works.

    1. Hi Norbert,
      Sorry for the late reply. I got through your comment. The problem is probably that the VL53L0X is not supported by default. You would then have to compile the firmware yourself after you have activated the corresponding option beforehand. 🙂
      Best regards

  8. Great instructions, I will definitely build that too. Since I have several rain barrels next to each other that I would like to monitor: Can I connect and read out three more VL53L1X (i.e. a total of 4 per Wemos D1 mini) via pins D3/D4, D5/D6 and D7/D8?

Kommentar hinterlassen

Your email address will not be published. Erforderliche Felder sind mit * markiert

This site uses Akismet to reduce spam. Learn how your comment data is processed.