VL6180X Time-of-Flight Sensor
The VL6180X is a short-range proximity and ambient light sensor that combines a 3-in-1 system: IR emitter, sensor, and ranging processor. It is ideal for gesture recognition, presence detection, and compact robotics applications.
VL6180X pinout
The VL6180X pinout includes I2C communication pins (SDA, SCL), power supply (VIN, GND), shutdown pin (SHDN), interrupt pin (GPIO), and 2.8V regulator output for short-range proximity sensing and ambient light detection.
| Pin | Type | Description | Notes |
|---|---|---|---|
| VIN | Power | Power supply input (2.8V to 5V) | Onboard regulator supports wide voltage |
| GND | Ground | Ground connection | Common ground |
| SDA | I2C Data | I2C Serial Data line | Bidirectional data (requires pull-up) |
| SCL | I2C Clock | I2C Serial Clock line | Clock signal (requires pull-up) |
| SHDN | Control | Shutdown pin (active low) | Tie high to enable sensor |
| GPIO | Interrupt | Interrupt or general I/O pin | Optional for interrupts or alerts |
| 2v8 | Power Out | Regulated 2.8V output | Can power external components |
Short-range Time-of-Flight (ToF) proximity sensor
Measurement range: 0 mm to 200 mm (20 cm max)
Resolution: 1 mm precision
Field of View: 25°
Operating voltage: 2.8V to 5V (via onboard regulator)
3-in-1 system: IR emitter, sensor, and ranging processor
Integrated ambient light sensor (ALS)
I2C address: 0x29 (default)
IR wavelength: 850 nm
Current consumption: ~20-30 mA during operation
Wiring the VL6180X to ESP32
Connect the VL6180X to your ESP32 via I2C (SDA and SCL pins). This sensor combines short-range ToF distance measurement (up to 20 cm) with an integrated ambient light sensor. The onboard regulator accepts 2.8V to 5V input.
| VL6180X pin | ESP32 pin | Purpose |
|---|---|---|
| VIN | 3.3V or 5V | Power supply (2.8V to 5V) |
| GND | GND | Ground connection |
| SDA | GPIO21 | I2C data line (with pull-up) |
| SCL | GPIO22 | I2C clock line (with pull-up) |
| SHDN | 3.3V or GPIO | Shutdown control (tie high to enable) · optional |
| GPIO | GPIO (optional) | Interrupt/alert output · optional |
Short-range sensor: 0-20 cm (best for proximity detection)
I2C address: 0x29 (same as VL53L0X and VL53L1X)
Integrated ambient light sensor (ALS) for light measurement
Onboard regulator: 2.8V to 5V input (flexible power)
2v8 pin provides regulated 2.8V output
Pull-up resistors typically included on module
SHDN pin: Tie high (3.3V/5V) to enable sensor
GPIO pin can signal measurement ready or threshold alerts
Use Adafruit_VL6180X library for Arduino/ESP32
Ideal for gesture recognition and presence detection
Better in close-range applications than VL53L0X
850 nm IR wavelength (different from VL53 series 940 nm)
VL6180X code examples
// Requires library: "VL6180X"
#include <Wire.h>
#include <VL6180X.h>
VL6180X sensor;
void setup() {
Serial.begin(115200);
Wire.begin(); // SDA=GPIO21, SCL=GPIO22
sensor.init();
sensor.configureDefault();
sensor.setTimeout(500);
}
void loop() {
uint8_t range = sensor.readRangeSingleMillimeters(); // 0-200 mm typical
uint16_t ambient = sensor.readAmbientSingle(); // ambient light
if (sensor.timeoutOccurred()) {
Serial.println("Timeout - check wiring");
} else {
Serial.print("Range: ");
Serial.print(range);
Serial.print(" mm, Ambient: ");
Serial.println(ambient);
}
delay(500);
}The example uses Pololu's VL6180X library (install "VL6180X" from the Library Manager). configureDefault() applies ST's recommended register settings, then each loop reads a single-shot range (the VL6180X is a short-range sensor - about 0-20 cm) and the ambient light level, which this chip measures as well.
// Requires the VL6180X driver (ESP Component Registry):
// idf.py add-dependency "nestorit/vl6180x"
#include <stdio.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/i2c_master.h"
#include "vl6180x.h"
#define SDA_GPIO GPIO_NUM_21
#define SCL_GPIO GPIO_NUM_22
void app_main(void)
{
i2c_master_bus_config_t bus_config = {
.clk_source = I2C_CLK_SRC_DEFAULT,
.i2c_port = I2C_NUM_0,
.sda_io_num = SDA_GPIO,
.scl_io_num = SCL_GPIO,
.flags.enable_internal_pullup = true,
};
i2c_master_bus_handle_t bus = NULL;
ESP_ERROR_CHECK(i2c_new_master_bus(&bus_config, &bus));
vl6180x_handle_t sensor = NULL;
ESP_ERROR_CHECK(vl6180x_create(bus, 0x29, NULL, &sensor)); // default address, documented defaults
while (1) {
uint8_t range_mm;
float lux;
if (vl6180x_range_read(sensor, &range_mm) == ESP_OK)
printf("Range: %u mm", range_mm);
else
printf("Range read failed");
if (vl6180x_als_read(sensor, VL6180X_ALS_GAIN_1, &lux) == ESP_OK)
printf(", Ambient: %.1f lux\n", lux);
else
printf("\n");
vTaskDelay(pdMS_TO_TICKS(500));
}
}The example uses the nestorit/vl6180x component from the ESP Component Registry with ESP-IDF's modern i2c_master API: vl6180x_create() applies ST's documented default settings at address 0x29, vl6180x_range_read() performs a single-shot range measurement (0-20 cm class sensor) and vl6180x_als_read() returns the ambient light in lux, which this chip measures as well.
external_components:
- source: github://thedayowl/esphome-vl6180x
components: [vl6180x]
i2c:
sda: GPIO21
scl: GPIO22
vl6180x:
- id: tof_sensor
address: 0x29
update_interval: 2s
range:
name: "VL6180X Range"
lux:
name: "VL6180X Ambient Light"Core ESPHome has no VL6180X platform, but the dedicated thedayowl/esphome-vl6180x external component covers both the VL6180X (range + ambient light) and the range-only VL6180 - omit the lux: entry for the latter. It also supports multiple sensors on one bus via XSHUT-sequenced address assignment.
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
lib_deps =
pololu/VL6180X @ ^1.3.1#include <Arduino.h>
#include <Wire.h>
#include <VL6180X.h>
VL6180X sensor;
void setup() {
Serial.begin(115200);
Wire.begin(); // SDA=GPIO21, SCL=GPIO22
sensor.init();
sensor.configureDefault();
sensor.setTimeout(500);
}
void loop() {
uint8_t range = sensor.readRangeSingleMillimeters(); // 0-200 mm typical
uint16_t ambient = sensor.readAmbientSingle(); // ambient light
if (sensor.timeoutOccurred()) {
Serial.println("Timeout - check wiring");
} else {
Serial.print("Range: ");
Serial.print(range);
Serial.print(" mm, Ambient: ");
Serial.println(ambient);
}
delay(500);
}Same as the Arduino example, with Pololu's VL6180X library pinned in lib_deps: single-shot range (0-20 cm class sensor) plus ambient light readings.
# Requires driver: vl6180x.py from https://github.com/Ledbelly2142/VL6180X
# Copy it to the board: mpremote cp vl6180x.py :
from machine import I2C, Pin
import vl6180x
import time
i2c = I2C(0, scl=Pin(22), sda=Pin(21))
sensor = vl6180x.Sensor(i2c)
while True:
print("Range: {} mm".format(sensor.range()))
time.sleep(0.5)The example uses the Ledbelly2142/VL6180X driver (copy vl6180x.py to the board), which applies ST's recommended init settings; range() returns the distance in millimeters. The VL6180X is a short-range (0-20 cm) sensor that also measures ambient light.
About the VL6180X
The VL6180X is STMicroelectronics’s short-range FlightSense part, and it is a different tool from the VL53 family rather than just a smaller version of it: the same package integrates an 850 nm IR emitter, a time-of-flight range detector and a separate ambient light sensor (ALS), all read over I2C at the fixed address 0x29. The 850 nm wavelength (versus 940 nm on the VL53L0X and VL53L1X) and the built-in light sensor - rated from under 1 lux to 100,000 lux across 8 gain settings - are what actually set it apart, not just a shorter tape measure.
Range is where buyers most often get the spec wrong: ST’s own datasheet describes reliable absolute distance measurement out to a little over 10 cm, with the maximum reportable value capped at 200 mm (1 mm resolution) in the chip’s default scaling mode, or 400 mm at coarser 2 mm resolution if the “2x scaler” is enabled. Modules and listings that advertise 50 cm ranges for VL6180X-based boards are extending well past what the chip itself is specified to do reliably - treat anything past roughly 20-40 cm as best-effort, not a guaranteed reading.
Within that shorter envelope the VL6180X is genuinely good at what it does: gesture sensing, proximity wake-up, and any project that also wants a simple lux reading without a second sensor. The TOF050C breakout carries this exact chip under a different name; for real range past 20 cm, the VL53L0X (about 2 m) or VL53L1X (about 4 m) are the sensors to reach for instead.
VL6180X troubleshooting
Sensor Not Detected
›
Issue: Sensor not responding or Adafruit library cannot detect it.
Solution: Verify wiring, power level, and ensure SHDN is pulled high.
Distance Stuck at Zero or Max
›
Issue: Only returns 0mm or 50mm constantly.
Solution: Ensure target is in range and sensor is facing it directly. Check for surface reflectivity.
Unstable Power Supply
›
Issue: Fluctuating or erratic readings.
Solution: Use a clean 3.3V/5V supply and decoupling capacitor. Avoid connecting SHDN to a floating pin.
Where to buy the VL6180X
Resources
Similar sensors
