vl53l1x

Overview

The vl53l1x node measures distance using the STMicroelectronics VL53L1X long-range Time-of-Flight laser ranging sensor via I2C. It offers up to 4 meters of range with configurable Region of Interest (ROI), timing budgets, and distance modes. The sensor uses a 940nm VCSEL (eye-safe class 1 laser) for fast, accurate measurements unaffected by target color or reflectivity.

Properties

Output

{
  "distance_mm": 1542,
  "status": "valid",
  "signalRate": 6.24,
  "ambientRate": 0.15,
  "roi": "16x16",
  "mode": "long",
  "timestamp": 1640000000000
}

Wiring (I2C)

  VL53L1X          Raspberry Pi
  --------          ------------
  VIN  ──────────── 3.3V (Pin 1)
  GND  ──────────── GND  (Pin 6)
  SDA  ──────────── SDA  (Pin 3)
  SCL  ──────────── SCL  (Pin 5)
  XSHUT ─────────── GPIO (optional)
  GPIO1 ─────────── GPIO (optional)

Example: Multi-Zone Proximity Detection

Use the ROI feature to create proximity zones for interactive displays or smart doorways.

// Function node: Classify distance into zones
var distance = msg.distance_mm;
var zone = "unknown";

if (distance < 500) {
    zone = "immediate";    // 0-50cm
} else if (distance < 1500) {
    zone = "near";         // 50-150cm
} else if (distance < 3000) {
    zone = "mid";          // 150-300cm
} else {
    zone = "far";          // 300cm+
}

msg.payload = {
    distance_mm: distance,
    distance_cm: (distance / 10).toFixed(1),
    zone: zone,
    signal: msg.signalRate,
    timestamp: msg.timestamp
};

return msg;

Example: Doorway People Counter

Mount the sensor above a doorway to count people passing through using distance threshold detection.

// Function node: People counter with direction
var distance = msg.distance_mm;
var doorHeight = 2100;       // mm from sensor to floor
var personThreshold = 1800;  // mm - detect heads below this
var prevState = flow.get('personPresent') || false;
var count = flow.get('peopleCount') || 0;

var personPresent = distance < personThreshold;

// Rising edge: person enters detection zone
if (personPresent && !prevState) {
    count++;
    flow.set('peopleCount', count);
}

flow.set('personPresent', personPresent);

msg.payload = {
    distance_mm: distance,
    headHeight: doorHeight - distance,
    personPresent: personPresent,
    totalCount: count,
    mode: msg.mode
};

return msg;

Example: Precision Liquid Level Monitoring

Use the long-range mode for large tank level monitoring with millimeter precision.

// Function node: Tank level with filtering
var distance = msg.distance_mm;
var tankDepth = 3500;  // mm total depth
var readings = flow.get('readings') || [];

// Rolling average filter (5 samples)
readings.push(distance);
if (readings.length > 5) readings.shift();
flow.set('readings', readings);

var avgDistance = readings.reduce(function(a, b) {
    return a + b;
}, 0) / readings.length;

var level = tankDepth - avgDistance;
level = Math.max(0, Math.min(tankDepth, level));
var percent = (level / tankDepth) * 100;

msg.payload = {
    raw_mm: distance,
    filtered_mm: avgDistance.toFixed(0),
    level_mm: level.toFixed(0),
    percent: percent.toFixed(1),
    liters: (level * 0.785).toFixed(1),
    status: msg.status
};

return msg;

Common Use Cases