Is VL53L1X Long Range ToF Sensor (4m) Compatible with Home Assistant (ESPHome)?
Electrical Specifications
Always confirm pin assignments against the manufacturer datasheet before wiring.
Compatibility Overview
Long-range laser distance sensor measuring target distance up to 400cm regardless of surface color or reflectivity.
Wiring VL53L1X Long Range ToF Sensor (4m) to ESP32
| Module pin | ESP32 | Note |
|---|---|---|
| VIN | 3V3 | Adafruit and Pololu breakouts regulate to the sensor's 2.8V and accept 3–5V. A bare ST module wants 2.8V and nothing higher. |
| GND | GND | |
| SDA | GPIO21 | |
| SCL | GPIO22 | |
| XSHUT | GPIO19 | Optional. Only needed to hold one sensor in reset while a second one on the same bus is re-addressed, or to power-cycle the part from software. |
| GPIO1 (interrupt) | unconnected |
Host pins are the ESP32's usual defaults for this bus. Whatever YAML you end up with must name the pins you actually used.
Technical Specification Matrix
| Feature / Attribute | Specification / Status |
|---|---|
| Hardware Protocol | I2C Bus / 3.3V |
| Bridge Required | NO |
| Border Router Needed | None |
| Hardware Capabilities & Peripherals | Long Range Distance (mm) Region of Interest Note: these entities come from the ESPHome configuration you flash — each one needs its matching component in that YAML before it appears. |
| Pairing Complexity | Plug-and-Play |
| Factory Reset Instruction | Hold BOOT button for 3s. |
Wire, Flash, Adopt, Check
Wire it up
Follow the wiring table above. The host pins there are the board's usual defaults for this bus; the YAML you write for the external component has to name the same ones.
Add the external component and flash
Core ESPHome has no component for VL53L1X Long Range ToF Sensor (4m). Add one of the external components listed below with an external_components block pointing at its repository, follow that component's README for the YAML, then flash over USB as you would any ESPHome node. If it is not detected, hold BOOT button for 3s to put it in download mode.
Adopt it in Home Assistant
Settings → Devices & Services. A node on the same network shows up as a discovered ESPHome device within a minute of joining Wi-Fi; choose Configure and enter the API encryption key from your secrets.yaml. If discovery does not find it, add the ESPHome integration by hand with the node's IP address.
Check it works
With an external component loaded, the I2C scan at boot lists 0x29 and the distance entity moves as you pass a hand over the sensor. A scan that finds nothing usually means XSHUT is being pulled low, since the part sits in reset while that pin is held down.
ESPHome Configuration
No verified configuration for VL53L1X Long Range ToF Sensor (4m) yet.
ESPHome has no core VL53L1X component. The core vl53l0x component does not drive it: the VL53L1X uses 16-bit I2C registers where the VL53L0X uses 8-bit, so it needs its own driver (tracked in esphome/feature-requests#1697). Working external components exist and are loaded with an external_components block pointing at their repository.
- Averyy/esphome-custom-components — vl53l1x ↗
- Roode — VL53L1X people counter ↗
- Feature request #1697 ↗
External components are third-party code — we have not validated them the way we validate the configs on other pages, so check their issue trackers before building around one.
What Appears in Home Assistant
In millimetres, from whichever external component you load. Some also expose the range status and let you set the region of interest from YAML.
Known Problems and Fixes
The VL53L0X component does not drive it
Core ESPHome has vl53l0x and nothing for the L1X. The two chips share an address and a package and not a register map — the L1X uses 16-bit registers — so platform: vl53l0x finds a device at 0x29 and then reads nonsense from it. An external_components block pointing at one of the repositories in the configuration section is the route.
0x29 is a crowded address
The VL53L0X, TSL2591 and TCS34725 all boot at 0x29 too. Two of any of these on one bus need XSHUT: hold one in reset, re-address the other from software, then release. The new address does not survive a power cycle, so the sequence runs at every boot.
Four metres is a dark-room figure
The 4m range needs long-distance mode and low ambient light. Direct sunlight cuts it to around a metre and adds noise. The 27° field of view also means a long shot down a hallway sees the floor before it sees the far wall — mount it so nothing else is in the cone, or shrink the region of interest.
Timing budget sets the ceiling
The 20ms budget only works in short-distance mode (about 1.3m). Long mode needs 33ms or more, and 100–200ms is where the millimetre-grade repeatability in the datasheet comes from.
A cover window changes the calibration
Putting the sensor behind protective glass adds crosstalk. ST's driver has an offset and crosstalk calibration for exactly this; the external components expose it to varying degrees. Without it, readings behind glass are short by a fixed amount.
Report a Pinout Error or Submit Tested Code Snippets
Found a pin mapping quirk or built a custom ESPHome YAML driver for VL53L1X Long Range ToF Sensor (4m)? Submit a pull request or report corrections to our index.
Hardware Correction Reporter (emb-esp32-vl53l1x-esphome)
Frequently Asked Questions
Does VL53L1X Long Range ToF Sensor (4m) work without an internet connection?
How is VL53L1X Long Range ToF Sensor (4m) powered and wired to the host board?
How does the host board reach Home Assistant (ESPHome)?
Alternatives
VL53L0X Time-of-Flight Distance Sensor
Core-supported and identical to wire. Two metres instead of four; for most indoor jobs that is the one to start with.
VL53L3CX Multi-Target ToF Distance Sensor
Reports several targets in the beam at once — the part for detecting a person in front of a wall.
TOF10120 Laser Rangefinder Module
Another laser rangefinder module, with a UART option.
A02YYUW Waterproof Ultrasonic Sensor
Waterproof ultrasonic, for tank levels where a laser fogs up.