HowTo: ESPEasy – Connect VL53L0X / VL53L1X distance sensor to the ESP8266 / ESP32 and read its data

Posted on by

I recently stumbled across the VL53L0X and VL53L1X TOF distance sensors. These sensors can determine distances with millimeter accuracy using a laser. In addition, they have a range of up to 4m (VL53L1X9 or 2m (VL54L0X). I found the sensors very interesting and of course I ordered a few directly. It doesn't hurt to have something practical in stock. 🙂

After they had arrived and I played around with it, it struck me that it could also be used to detect the level of my coffee cup. A quick test at the sink and a further test at the rain barrel then showed that this also worked with clear liquids. And that gave me the first idea for practical use: a level sensor for the rain barrel.

I had never dared to do so because I found previous systems either too expensive, complicated or inaccurate. But now it was time.

I described what you need and how you can proceed when building your own laser level sensor in the following article. 🙂

Safety instructions

I know the following hints are always a bit annoying and seem unnecessary. But unfortunately, many people who knew it "better" from carelessness lost their eyes, fingers or other things or hurt themselves. In comparison, a loss of data is almost not worth mentioning, but even these can be really annoying. Therefore, please take five minutes to read the safety instructions. Even the coolest project is worth no injury or other annoyance. https://www.nerdiy.de/en/sicherheitshinweise/

Affiliate links / advertising links

The links to online stores listed here are so-called affiliate links. If you click on such an affiliate link and store via this link, Nerdiy.de receives a commission from the online store or provider concerned. The price doesn't change for you. If you do your purchases via these links, you will support Nerdiy.de in being able to offer further useful projects in the future. 🙂

Hints for our lovely english readers: Basically, many of the articles on Nerdiy.de are translations from the original german articles. Therefore, it may happen here and there that some illustrations are not available in english and that some translations are weird/strange/full of mistakes or generally totaly wrong. So if you find some obvious (or also not obvious) mistakes don't hesitate to leave us a hint about that in the comment section. 
Also please don't get confused, that instead of a "dot" often a "comma" is used as decimal separator. 🙂

Requirements

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

Tools required:

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

You need the parts shown below to build the level sensor.

A micro USB cable is missing in the picture. You need this to supply the sensor with power. In addition to WiFi, the data can also be received via the cable.

Print the required 3D parts

Download all required STL files:

Cut threads in the housing

So that the USB cable for the power supply can also be inserted watertight into the housing, you should use a cable gland. This is the only way to permanently prevent water from penetrating the housing over time.

To be able to mount this cable gland in the housing, a thread must first be cut into the housing. The cutting of internal threads is also explained in detail in the article Mechanics—Cut internal thread.

As usual, place the tap as straight as possible and cut the thread. Remember to turn back half a turn after each turn to break off the chip.

As soon as you have completely cut the thread with the tap, the whole …

… thing should look something like this.

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

This way you will quickly notice whether the thread is completely cut or not.

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

Outside view.

Inside view.

Prepare the distance sensor

Now it is 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 connection line by stripping the ends of the individual lines 5mm each and tin it with a little solder.

Then you can also 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 fully prepared, the whole thing should look something like this.

Connect the distance sensor to the Wemos D1 Mini

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

To do this, you should first prepare the contacts again. To do this, tin the contacts "5V", "G", "D2" and "D1".

Then you can solder the previously prepared connection cable to the microcontroller.

Set up this should roughly …

… look like this.

Install the distance sensor

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

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

… under the holder inside the housing.

The nuts should be positioned so that they …

… lie exactly under the holes through which the screws are later inserted.

Now the small sealing ring is inserted into the recess.

Then you can put the sensor on it and fix it with the M3 screws. Remember to tighten the screws but not too tight. Because after "fixed" comes "off"! 🙂

Now you can check again that the sensor has a clear view …

… to the outside.

Install the Wemos D1 Mini and insert the USB cable into the housing so that it is watertight

After the sensor is installed in the right place, all other components must now be stowed watertight in the housing.

That's how your sensor should look like so far. 🙂

The size of the micro USB connection is a bit 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 connector so that it fits through the nut.

As soon as the micro USB connector is pulled through the nut …

... and you start to tighten the nut ...

… you will quickly notice that there is still a lot of space between the rubber seal and the USB cable.

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

Therefore, you should unscrew the screw grommet again, pull out the USB cable approx. 2 cm and wrap this area tightly with self-sealing tape.

So you can enlarge the diameter of the USB cable …

… and thus fix the USB cable watertight in the screw sleeve. Now the USB cable should also be mechanically secured against being pulled out.

Front view.

Now you can deal with the rest of the installation: Before the microcontroller is stowed in the housing, you can secure the contacts of the sensor with a little hot glue against short circuits.

Of course you can do this later - after a first test - as soon as you are sure that everything is working correctly.

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

Then the microcontroller can be connected to the micro USB connector …

… and can be inserted into the housing as shown.

You may have to loosen the union nut of the screw socket again. 🙂

Finished the whole thing should look like this. 🙂 🙂

Seal the housing watertight

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

Currently your sensor should …

...look like this.

At this point you can of course jump one chapter further 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 them from below in the designated assembly spaces in the corners of the housing.

Then turn the housing over without the nuts falling out of their assembly locations.

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 cover is the same everywhere.

Programming the firmware

ESPEasy

In principle, you have many options with the 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 personable because you have more setting options here. For one or the other, however, this is exactly an argument to prefer the Tasmota firmware, which in my opinion comes with a little more "simply functioning" default settings. Currently (05/28/2020) there is also the problem that the plugin for ESPEasy does not work reliably. That's why I currently recommend using the Tasmota firmware if you don't want to install your own firmware. 🙂The ESPEasy plug-in for the VL53L0X now works quite reliably. Instructions on how to configure this plugin can be found in the following paragraph.

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

Tasmota

Unfortunately, the sensor is not included in any of the regular automatic builds of the Tasmota firmware. That means you have to compile the firmware yourself after you have activated the use of the sensor.

To save you this step, I have prepared the compiled .bin file and uploaded it into the Nerdiy.de-GitHub. You can find them under the following link: https://github.com/Nerdiyde/tasmotaBuilds/blob/master/tasmota_27052020_incl_vl53l0x.ino.bin

How you can flash.-Bin files on an ESP8266 is described in the article ESP8266 – with the “Esptool” flashing .bin files under Windows.

Assembly suggestion

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

You should definitely make sure that the sensor is not overwashed if the rain barrel overflows. Although the sensor is very well protected against splashing water, it is better not to immerse it in water. 🙂

The simplest is, of course, to drill a hole in the top of the barrel through which the sensor has a clear view of the water surface.

The sensor can also be attached to the edge and measure the distance to the water surface.

Evaluation in NodeRed

It is one thing to measure the level of your rain barrel. Another is to receive this data, prepare it and, if necessary, convert it.

Because so far you only get a distance from your sensor. This is not really a volume that you actually want to measure. Therefore the water level still has to be converted into a volume. This depends on the shape and dimensions of your rain barrel and is not always easy to calculate.

In the future I will add flows in this part that will simplify the conversion of these values. 🙂

Additional information

Have fun with the project

I hope everything worked as described. If not or you have any other questions or suggestions, please let me know in the comments. Also, ideas for new projects are always welcome. 🙂

P.S. 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 appreciate that I share this information with you, I would be happy about a small donation to the coffee box. 🙂

Buy Me a Coffee at ko-fi.com   

25 comments

  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

    Reply

    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 (https://nerdiy.de/howto-espeasy-nerdiyspanelmeter-plugin-installieren-und-konfigurieren/#Plugin_konfigurieren) in the paragraph "Configure 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
      Fabian

      Reply

  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 a 3D print available and have to "tinker" a housing. Is the opening shown watertight? With me, the tank occasionally gets full and the sensor can get a few drops. The photos show a hole where more than the openings for the light of the sensor goes through and so I think water can get in here? Is it possible to close this with a small disc? Would be important for me and think a decisive difference to ultrasonic measurement. There are currently (in the DIY area) only waterproof with a minimum distance of 20cm and some reported problems in tanks. Thus, the TOF solution would be ideal.
    Best regards
    Ralph

    Reply

    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
      Fabian

      Reply

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

    Reply

    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: https://nerdiy.de/news-sommer-2020/). 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
      Fabian

      Reply

      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'm also currently using ESPEasy with the ultrasonic sensor, but like the previous speakers, I'm more of a user and hoppy programmer and not so much a "plugin compiler". If you could give us a little help with the VL53L1X and ESPEasy, I would also be very grateful. 🙂
        Greetings
        erwin

        Reply

        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: https://github.com/Nerdiyde/pxlBlck/blob/main/plugin/bin/ESP8266_ESPEasy_incl_pxlBlck_4M.bin
          I have summarized information on how to program this on the Wemos D1 Mini or ESP8266 here: https://nerdiy.de/howto-esp8266-mit-dem-esptool-bin-dateien-unter-windows-flashen/

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

          Reply

          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
            erwin

          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
            Fabian

          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
            erwin

        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

          Reply

          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
            erwin

          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. https://forum.iobroker.net/assets/uploads/files/1604243665450-f%C3%BCllstandsmesser-per-pegelsonde.pdf

            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 fall back on it, but I'm also a big fan of explaining the principle to willing people with an example. With a bit of luck, the “in the know” will multiply and progress mini-step by mini-step and can also help others. Think you also want to do new things and not just always explain the same stuff in x versions 🙂
    Best regards
    Ralph

    Reply

    1. Hey Ralph,
      Yes, you're right. It's actually my "motto" to describe things in very small steps if necessary. 🙂 As soon as I have time I'll take care of it.
      Best regards
      Fabian

      Reply

  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

    Reply

  7. 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.

    Reply

    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.

      Reply

  8. 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.

    Reply

    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
      Fabian

      Reply

Kommentar hinterlassen

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