API Reference

adafruit_vcnl4030

CircuitPython driver library for VCNL4030X01 Proximity / Ambient Light sensor

  • Author(s): Tim Cocks

Implementation Notes

Hardware:

  • Adafruit VCNL4030X01 Proximity and Ambient Light Sensor Breakout

Software and Dependencies:

# * Adafruit’s Bus Device library: https://github.com/adafruit/Adafruit_CircuitPython_BusDevice # * Adafruit’s Register library: https://github.com/adafruit/Adafruit_CircuitPython_Register

class adafruit_vcnl4030.ALSIntegrationTime

ALS integration time settings for ALS_IT bits [7:5] of ALS_CONF.

Longer integration times give higher resolution (lower lux/step).

Setting

Time

Resolution

ALSIntegrationTime.MS_50

50 ms

0.064 lux/step

ALSIntegrationTime.MS_100

100 ms

0.032 lux/step

ALSIntegrationTime.MS_200

200 ms

0.016 lux/step

ALSIntegrationTime.MS_400

400 ms

0.008 lux/step

ALSIntegrationTime.MS_800

800 ms

0.004 lux/step
class adafruit_vcnl4030.ALSPersistence

ALS interrupt persistence settings for ALS_PERS bits [3:2] of ALS_CONF.

Number of consecutive out-of-threshold readings before an interrupt fires.

Setting

Readings

ALSPersistence.CYCLES_1

1 reading

ALSPersistence.CYCLES_2

2 readings

ALSPersistence.CYCLES_4

4 readings

ALSPersistence.CYCLES_8

8 readings
class adafruit_vcnl4030.CV

Constant-value helper for enum-like classes.

classmethod get_name(value: int) → str

Return the attribute name for value.

classmethod is_valid(value: int) → bool

Return True if value is a member of this CV class.

class adafruit_vcnl4030.ProxDuty

PS IRED duty ratio settings for PS_DUTY bits [7:6] of PS_CONF1.

Higher duty divisor = lower average LED power.

Setting

Duty cycle

ProxDuty.RATIO_40

1/40 (highest power)

ProxDuty.RATIO_80

1/80

ProxDuty.RATIO_160

1/160

ProxDuty.RATIO_320

1/320 (lowest power)
class adafruit_vcnl4030.ProxGain

PS gain settings for PS_GAIN bits [13:12] of PS_CONF2.

Setting

Description

ProxGain.TWO_STEP

Two-step mode (~4x single 1x)

ProxGain.SINGLE_8X

Single mode, 8x range

ProxGain.SINGLE_1X

Single mode, 1x range
class adafruit_vcnl4030.ProxIntegrationTime

PS integration time settings for PS_IT bits [3:1] of PS_CONF1.

Higher T values give higher sensitivity.

Setting

Period

ProxIntegrationTime.T_1

1T

ProxIntegrationTime.T_1_5

1.5T

ProxIntegrationTime.T_2

2T

ProxIntegrationTime.T_2_5

2.5T

ProxIntegrationTime.T_3

3T

ProxIntegrationTime.T_3_5

3.5T

ProxIntegrationTime.T_4

4T

ProxIntegrationTime.T_8

8T (highest sensitivity)
class adafruit_vcnl4030.ProxInterruptMode

PS interrupt mode settings for PS_INT bits [9:8] of PS_CONF2.

Setting

Description

ProxInterruptMode.DISABLED

Interrupt disabled

ProxInterruptMode.CLOSE

Interrupt on close

ProxInterruptMode.AWAY

Interrupt on away

ProxInterruptMode.BOTH

Interrupt on close and away
class adafruit_vcnl4030.ProxLEDCurrent

LED driving current settings for LED_I bits [10:8] of PS_MS.

Setting

Current

ProxLEDCurrent.MA_50

50 mA

ProxLEDCurrent.MA_75

75 mA

ProxLEDCurrent.MA_100

100 mA

ProxLEDCurrent.MA_120

120 mA

ProxLEDCurrent.MA_140

140 mA

ProxLEDCurrent.MA_160

160 mA

ProxLEDCurrent.MA_180

180 mA

ProxLEDCurrent.MA_200

200 mA
class adafruit_vcnl4030.ProxPersistence

PS interrupt persistence settings for PS_PERS bits [5:4] of PS_CONF1.

Setting

Readings

ProxPersistence.CYCLES_1

1 reading

ProxPersistence.CYCLES_2

2 readings

ProxPersistence.CYCLES_3

3 readings

ProxPersistence.CYCLES_4

4 readings
class adafruit_vcnl4030.SunlightCancelCurrent

Sunlight cancellation current multiplier for PS_SC_CUR bits [14:13] of PS_MS.

Setting

Multiplier

SunlightCancelCurrent.X1

1x typical

SunlightCancelCurrent.X2

2x typical

SunlightCancelCurrent.X4

4x typical

SunlightCancelCurrent.X8

8x typical
class adafruit_vcnl4030.VCNL4030(i2c_bus: I2C, address: int = _VCNL4030_DEFAULT_ADDR)

CircuitPython driver for the Vishay VCNL4030X01 proximity and ambient light sensor.

Parameters:

  • i2c_bus (I2C) – The I2C bus the device is connected to.

  • address (int) – The I2C device address. Defaults to 0x60.

property als: int

Raw 16-bit ambient light sensor reading.

property als_enabled: bool

Enable or disable the ambient light sensor. True = enabled.

als_high_dynamic_range

Enable ALS high dynamic range mode (2x range, halves sensitivity). True to enable.

property als_high_flag: bool

True if the ALS high-threshold flag was set in the last interrupt_flags read.

property als_integration_time: int

ALS integration time.

Must be an ALSIntegrationTime value, e.g. ALSIntegrationTime.MS_100.

als_interrupt_enabled

Enable or disable the ALS interrupt. True to enable.

property als_low_flag: bool

True if the ALS low-threshold flag was set in the last interrupt_flags read.

als_low_sensitivity

Enable ALS low sensitivity mode (1x vs 2x). True for lower sensitivity.

property als_persistence: int

ALS interrupt persistence.

Must be an ALSPersistence value, e.g. ALSPersistence.CYCLES_1.

als_threshold_high

ALS interrupt high threshold (16-bit).

als_threshold_low

ALS interrupt low threshold (16-bit).

property interrupt_flags: int

Read and return the interrupt flags byte.

Reading this register clears all flags on the device. Use the returned byte with the VCNL4030_ALS_IF_H, VCNL4030_ALS_IF_L, VCNL4030_PROX_IF_CLOSE, VCNL4030_PROX_IF_AWAY, and VCNL4030_PROX_SPFLAG bitmask constants, or check the individual flag properties.

property led_current: int

LED driving current.

Must be a ProxLEDCurrent value, e.g. ProxLEDCurrent.MA_200.

led_low_current

Reduce LED current to 1/10 of normal. True to enable.

property lux: float

Ambient light in lux, computed from the raw ALS reading.

Resolution is determined by the current als_integration_time, als_high_dynamic_range, and als_low_sensitivity settings.

property proximity: int

Raw PS reading (12-bit or 16-bit depending on proximity_resolution_16bit).

proximity_active_force_mode

Enable PS active force mode (manual trigger). True to enable.

property proximity_away_flag: bool

True if the PS away (receding) flag was set in the last interrupt_flags read.

proximity_cancellation

PS crosstalk cancellation level (subtracted from raw PS reading).

property proximity_close_flag: bool

True if the PS close (approaching) flag was set in the last interrupt_flags read.

property proximity_duty: int

PS IRED duty ratio.

Must be a ProxDuty value, e.g. ProxDuty.RATIO_40.

property proximity_enabled: bool

Enable or disable the proximity sensor. True = enabled.

property proximity_gain: int

PS gain setting.

Must be a ProxGain value, e.g. ProxGain.TWO_STEP.

property proximity_integration_time: int

PS integration time.

Must be a ProxIntegrationTime value, e.g. ProxIntegrationTime.T_1.

property proximity_interrupt_mode: int

PS interrupt mode.

Must be a ProxInterruptMode value, e.g. ProxInterruptMode.DISABLED.

proximity_logic_mode

Enable PS logic output mode. True for logic output, False for normal+interrupt.

proximity_low_sensitivity

Enable PS low sensitivity mode. True for lower sensitivity.

property proximity_persistence: int

PS interrupt persistence.

Must be a ProxPersistence value, e.g. ProxPersistence.CYCLES_1.

proximity_resolution_16bit

Enable 16-bit PS output resolution (False = 12-bit). True for 16-bit.

proximity_smart_persistence

Enable PS smart persistence. True to enable.

property proximity_sunlight_flag: bool

True if the PS sunlight protection flag was set in the last interrupt_flags read.

proximity_threshold_high

PS interrupt high threshold (16-bit).

proximity_threshold_low

PS interrupt low threshold (16-bit).

reset()

Reset the sensor back to its initial configuration state.

property sunlight_cancel_current: int

Sunlight cancellation current multiplier.

Must be a SunlightCancelCurrent value, e.g. SunlightCancelCurrent.X1.

sunlight_cancellation_enabled

Enable sunlight cancellation feature. True to enable.

sunlight_protect_output_high

Sunlight protect output level. True for 0xFF output, False for 0x00.

sunlight_protection_enhanced

Enable enhanced sunlight protection (1.5x capability). True to enable.

trigger_proximity() → None

Trigger a single PS measurement in active force mode.

Has no effect unless proximity_active_force_mode is True. The PS_TRIG bit is self-clearing.

property white: int

Raw 16-bit white channel reading.

property white_channel_enabled: bool

Enable or disable the white channel. True = enabled.