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

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.

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 shop via this link, receives a commission from the online shop or provider concerned. The price doesn't change for you. If you do your purchases via these links, you will support in being able to offer further useful projects in the future. 🙂

Hints for our lovely english readers: Basically, many of the articles on 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. 🙂


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.

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

Möglicherweise müsst Ihr die Überwurfmutter der Schraubtülle dazu nochmal lösen. 🙂

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


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


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 You can find them under the following link:

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

Buy Me a Coffee at   


  1. Hallo

    Vielen Dank für die gelungene Anleitung!
    Mir ist nicht ganz klar wie ich den Sensor VL53L0X ins EspEasy einbinden kann.
    Muss ich da eine bestimmte Firmware laden, (hab da noch nicht so Erfahrung)

    Wäre Ihnen sehr Dankbar wenn Sie mir hier weiterhelfen können.

    Gruss Stefan Allenspach

    1. Hallo Herr Allenspach,
      stimmt, den Teil müsste ich in der Anleitung noch mal besser erklären. Danke für den Hinweis. 🙂
      Bis dahin: In diesem Artikel ( in dem Absatz “Plugin konfigurieren” ist der Vorgang für das device “Display – Nerdiys-PanelMeter” erklärt. Mit dem VL53L0X funktioniert dies genaus, nur dass natürlich das device “VL53L0X” ausgewählt werden muss. Lassen Sie mich gerne wissen ob es damit geklappt hat. 🙂
      Beste Grüße

  2. Hallo,
    toller Artikel und hierdurch bin ich auf die Lösungsmöglichkeit mit TOF-Sensoren erst aufmerksam geworden. Eine Frage die für meinen Tank sehr wichtig ist und ich habe kein 3D-Druck zur Verfügung und muß mir ein Gehäuse “basteln”. Ist Deine gezeigte Öffnung Wasserdicht? Bei mir wird der Tank Gelegentlich 100% voll und somit kann der Sensor schon mal ein paar Tropfen abbekommen. Die Fotos zeigen ein Loch wo auch mehr als die Öffnungen für das Licht des Sensors durchgeht und somit denke ich kann hier Wasser eintreten? Ist es möglich dies mit einer kleinen Scheibe zu verschließen? Wäre für mich wichtig und denke ein entscheidender Unterschied zu Ultraschallmessung. Hier gibt es derzeit (im DIY Bereich) nur Wasserdicht mit 20cm Mindesabstand und einigen berichteten Problem in Tanks. Somit wäre die TOF Lösung ideal.
    Beste Grüße

    1. Hallo Ralf,
      danke. 🙂 Meine Lösung ist höchstens Spritzwassergeschützt. Und das auch nur von oben. Der Deckel sollte dank des O-Rings ziemlich dicht sein. Aber wie du schon richtig gesehen hast, ist der Sensor nicht Wasserdicht verbaut. Ich habe leider erst später gelesen, dass der Sensor auch hinter einer Glasscheibe verbaut werden kann. Im Datenblatt des Sensors kannst du bestimmt noch mehr Infos dazu finden. 🙂 Wenn ich mal Zeit habe werde ich eine neue Version des Gehäuses designen. Falls du keine Lust auf Basteln hast: Es gibt auch online-druck-services, wo man sich die Teile ausdrucken und zusenden lassen kann. 🙂
      Beste Grüße

  3. Hallo Fabian,
    besten Dank für Deine Rückinfo. Habe jetzt mal einen VL53L0X mit dieser Abdeckkappe bestellt und glaube ihn in etwas wie einer AP-Abzweigdose montieren/verkleben zu können. Nichts gegen Dein Gehäuse, aber bei mir käme das in einem gebuddelten Loch eines Wassertanks im Garten zum Einsatz, was nie jemand sehen würde (Wie sagt man Perlen vor die Säu..). Wenn die Funktion erfüllt ist, bin ich schon sehr happy. Setze für meine bisherigen ESP8266 Geschichten auch ESPEasy ein und möchte dies auch hier wieder tun (Alleine die Rules um ein schwankendes Messergebnis zu filtern/beruhigen wäre copy&paste). Wie mein Vorkommentator sagt, ist mir auch leider nicht ganz klar wie ich das PlugIn P0133 für das Kompilieren von ESPEasy einbinde. Dein Link hilft, jedoch scheint sich die Aktivierung von PlugIns durch Löschung der Kommentarzeichen von der Struktur in ESPEasy geändert zu haben. Vermute dort eine zentrale Verwaltungsdatei. Hinzu kommt, dass P0133 nicht mehr in der “MEGA” Version von ESPEASY vorhanden zu sein scheint (bei P097 ist Ende). Für den VL53L0X sehe ich es noch optimistisch, dies irgendwie heraus zu bekommen, wenn das Plugin für die aktuelle Version denn noch funktioniert, aber wie geht dies für einen VL53L1X? Einfach die VL53L1X.h von Polulu ins Projekt einbinden und die ino Datei entsprechend anpassen?
    Es bleibt spannend und bleibe am Projekt dran.
    Beste Grüße

    1. Hi Ralf,
      Ach alles gut. Kann ich voll verstehen. Letztlich kommt es ja auf die zuverlässige Funktion an und weniger auf die Optik. 😀
      Was das Problem mit dem Plugin angeht: Ich bin aktuell bis kommenden Montag noch schwer damit beschäftigt die Dokumentation für WinDIY zu schreiben (Infos hier: Wenn ich damit durch bin, werde ich mich mal damit auseinandersetzen und ein Repository auf GitHub aufmachen, wo ich alle meine Plugins inkl. ESPEasy entsprechend konfiguriert anbiete. Dann muss man nicht mehr selber die Änderungen vornehmen und es sollte direkt funktionieren. 🙂
      Ich hoffe das ist okay. 🙂
      Beste Grüße

      1. Hello
        Super Beschreibung, super Projekt.
        Ich habe derzeit eine Messung mit Ultraschall, die aber im Brunnen (Tiefe bis zu 3,5 Meter) nur sehr schlecht funktioniert (schon alles mögliche probiert).
        Auf der Suche nach einer Alternative bin ich auf den VL53L1X und deine Seite gelangt.
        Ich verwende derzeit auch ESPEasy mit dem Ultraschallsensor, bin aber wie meine Vorredner mehr der Anwender und Hoppy-Programmierer, und nicht so sehr der “Plugin-Compiler”. Wenn du uns mit dem VL53L1X und ESPEasy etwas auf die Sprunge helfen könntest wäre auch ich sehr dankbar. 🙂

        1. Guten Abend Erwin,
          ja, diese Stelle ist leider etwas spärlich dokumentiert. Ich habe gerade mal geguckt und leider keine Anleitung gefunden die das beschreibt. Ich schreibe mir das auf und versuche Zeitnah eine Anleitung zu erstellen in der erklärt ist wie man den Sensor anschließt und das Plugin entsprechend konfiguriert.
          Als kleinen Workaround habe ich aber eine .bin Datei Erstellt die man auf den Wemos D1 Mini programmieren kann. Darin ist der VL53L0X bereits integriert. Du musst ihn (wie bei ESPEasy üblich) später nur noch aktivieren und entsprechend konfigurieren.
          Die bin-Datei findest du unter:
          Infos wie man diese auf den Wemos D1 Mini bzw. ESP8266 programmiert habe ich hier zusammengefasst:

          Ich hoffe das hilft schonmal. Ansonsten gib mir gerne bescheid. 🙂
          Beste Grüße

          1. Hallo Fabian
            Danke für deine schnelle und freundliche Hilfe.
            Ich habe mir vor ein paar Tagen mal ein paar VL53L0X und VL53L1X bestellt.
            Zur Sicherheit. Die werden jetzt mal ein bissl brauchen, bis sie von China da sind.
            Dann werde ich dein Image mal mit dem VL53L0X testen. Zum VL53L1X findet sich leider in Netz so gut wie gar nichts 🙁 Außer Ansätze, die mir etwas zu hoch sind.
            Danke & beste Grüße

          2. Guten Abend Erwin,
            alles klar. Das Problem (mit der langen Versanddauer) kenne ich. 😀 Vielleicht habe ich den Artikel bis dahin ja schon fertig. Ich versuche dran zu denken, dann auch hier bescheid zu geben. 🙂
            Beste Grüße

          3. Hallo Fabian
            Danke für deine Unterstützung. Ich werde mal weiterprobieren, wenn ich alles beieinander habe. Ich sage dir auf jeden Fall Bescheid wie es läuft. ggf. quäle ich dich nochmal. 😉
            Danke & beste Grüße

        2. Hallo Erwin,

          leider ist der LaserSensor von AliExpress nie bei mir angekommen und ähnlich wie bei Dir haben mich u.a. Ergebnisse mit einem Ultraschallsensor nicht überzeugt. Die Messungen sind sehr Fehleranfällig und jede Messung weicht voneinander ab auch wenn nichts passiert, ok dafür günstig und man kann mit Softwarefiltern arbeiten. Ich habe habe mal eine Füllstandssonde für ca. 20€ bestellt und diese gibt es in verschiedenen Ausführungen (Messebereiche zB 0-5m). Da ich schon ein gutes Stück Zuleitung verwende wollte ich keine Sonde mit Spannungmessignal verwenden sondern 4-20mA. Sowohl für die 4-20mA auf 0-3.3V(ESP8266 Analog Eingang) als auch für die 24VDC Versorgung gibt es fertige Module (ca. 1€) bei Ali-Express und ich bin super zufrieden damit. Software läuft ESPEasy in der Standardversion und werte einfach den Analogeingang aus. Viele Grüße Ralf

          1. Hallo Ralf
            Danke für deine freundliche Antwort.
            Davon habe ich auch schon gelesen. Geht das wirklich so gut/einfach?
            Mich hat abgeschreckt, dass man die Werte mal “einkalibrieren” muss.
            Also unterster und oberster Wert. Hab ich zu mindest irgendwo so gelesen.
            na vielleicht nehme ich mich dem Thema doch auch nochmal an.
            Danke & beste Grüße

          2. Hallo Fabian, hallo Ralf

            Danke für all eure Hilfe und Ideen, ich habe schlußendlich das Messen mit dem LaserSensor nach anfänglichen Versuchen auch beiseite gelegt, und mich an der Variante mit einer Füllstandssonde versucht. Und ich muss sagen: SUPER!! Es ist sicher der Aufwand an Hardware größer (aber durchaus überschaubar), aber in ESPEASY auch easy zu konfigurieren. Läuft zwar jetzt erst seit einigen Tagen, aber bin durchaus positiv überrascht. Die Messung funktioniert ohne nennenswerte Schwankungen. So bald ich Langzeit Erfahrung habe, kann ich das gerne noch mitteilen.
            @Ralf wie sind deine Erfahrungen bisher.?
            @Fabian: Musst du unbedingt ausprobieren. Ich habe mich an diese Anleitung gehalten, klappt tadellos.

            lg Erwin 🙂

          3. Hey Erwin,
            das sieht interessant aus! Vielen Dank für den Hinweis. 🙂
            Beste Grüße

  4. Hallo Fabian,
    vielen Dank und für mich alles prima. Ali-Express liefert langsam 🙂
    Dein Repository finde ich super und würde drauf zurück greifen, jedoch bin ich auch großer Freund davon willigen Leuten das Prinzip an einem Beispiel zu erlären. Mit etwas Glück potenzieren sich so die “Wissenden” und kommen Mini-Step per Mini-Step weiter und können auch Anderen helfen. Denke Du möchtest ja auch neue Dinge machen und nicht nur immer dasselbe Zeugs in x Ausführungen erklären 🙂
    Beste Grüße

    1. Hey Ralf,
      Ja da hast du recht. Ist ja eigentlich auch mein “Motto” Sachen wenn nötig auch sehr Kleinschrittig zu beschreiben. 🙂 Sobald ich Zeit habe kümmere ich mich darum.
      Beste Grüße

  5. hi
    kann mir einer mal sagen, welche tasmota bin ich auf den esp flashen muss?
    die sensor bin erkennt den vl53lox leider nicht, auch nicht die neuste tasmota bin
    danke schonmal im vorraus

  6. Hi,
    hat von euch sonst noch jemand das Problem, das wenn der Sensor eingebaut ist nur noch Werte unter 30cm angezeigt werden, obwohl es mehr sein sollten? Sobald er ausgebaut ist zeigt er die richtige Entfernung an.
    Freie Sicht hat der Sensor eigentlich.

    1. Hi, das kann ich bestätigen. Inzwischen habe ich herausgefunden, dass es einen Unterschied macht, ob der Sensor im Haus oder draußen betrieben wird. Ich habe einen Versuchsaufbau mit Laptop und sobald ich einen Schritt vor die Tür mache, werden nur noch Entfernungen von ca. 40 cm erfasst.

Leave a Reply

Your email address will not be published. Required fields are marked *