Skip to content

VCNL4040

Works with

Any CircuitPython board with I2C

What it does

The VCNL4040 combines a proximity sensor and an ambient light sensor in a single I2C package. The proximity sensor uses an infrared LED and photodiode to detect whether something is nearby — it does not return an accurate distance in millimeters, but returns a relative value that increases as objects get closer. The lux measurement works like any standard ambient light sensor. Good for "is something there" detection, gesture-based inputs, and applications that need both proximity and light in a small footprint.

Installing the library

Download adafruit_vcnl4040.mpy from the Adafruit CircuitPython Bundle and copy it to the lib/ folder on your board.

Quick start

import time
import board
import busio
import adafruit_vcnl4040

i2c = busio.I2C(board.SCL, board.SDA)
sensor = adafruit_vcnl4040.VCNL4040(i2c)

while True:
    print(f"Proximity: {sensor.proximity}  Lux: {sensor.lux:.1f}")
    time.sleep(0.1)

Key things you can do

What you want How to do it
Read proximity sensor.proximity — 0 to 65535; higher value means closer
Read lux sensor.lux
Increase proximity range sensor.led_current = adafruit_vcnl4040.LED_200MA — higher current drives the IR LED harder
Enable proximity interrupt sensor.proximity_high_threshold, sensor.proximity_low_threshold, sensor.proximity_interrupt_enabled
Enable light interrupt sensor.light_high_threshold, sensor.light_low_threshold, sensor.light_interrupt_enabled
Read interrupt status sensor.proximity_high_interrupt, sensor.proximity_low_interrupt

Reading the official docs

Full API reference: https://docs.circuitpython.org/projects/vcnl4040/en/latest/

Key things to look up:

  • Proximity values are relative, not absolute distances — calibrate your threshold empirically for your specific enclosure and target surface
  • led_current options range from 50mA to 200mA; higher current extends range but increases power draw
  • The interrupt thresholds let you trigger code only when the proximity crosses a set level, which is more efficient than polling continuously
  • Ambient light from strong IR sources (sunlight, incandescent bulbs) can interfere with proximity readings

Projects using this library