API Reference

`adafruit_apds9999`

CircuitPython driver for Broadcom APDS-9999 Light + RGB + Proximity

Author(s): Tim Cocks

Implementation Notes

Hardware:

APDS9999

Software and Dependencies:

Adafruit CircuitPython firmware for the supported boards: https://circuitpython.org/downloads
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_apds9999.APDS9999(i2c_bus: I2C, address: int = _APDS9999_DEFAULT_ADDR)

CircuitPython driver for the Broadcom APDS-9999 Digital Proximity and RGB Color Sensor.

Parameters:

i2c_bus (I2C) – The I2C bus the device is connected to.
address (int) – The I2C device address. Defaults to 0x52.

Quickstart: Importing and using the device

Here is an example of using the APDS9999. First you will need to import the libraries to use the sensor
import board
from adafruit_apds9999 import APDS9999
Once this is done you can define your board.I2C object and define your sensor object
i2c = board.I2C()  # uses board.SCL and board.SDA
sensor = APDS9999(i2c)
Now you have access to the sensor data
r, g, b, ir = sensor.color_data
proximity = sensor.proximity

calculate_lux(green_count: int) → float

Calculate illuminance in lux from a raw green channel count.

Reads the current light_gain and light_resolution settings from the device and applies the appropriate scale factor from the lookup table below. RES_13BIT is not supported and will raise a ValueError.

Lux factor table (rows = gain, columns = resolution):

	20-bit	19-bit	18-bit	17-bit	16-bit
`GAIN_1X`	0.136	0.273	0.548	1.099	2.193
`GAIN_3X`	0.045	0.090	0.180	0.359	0.722
`GAIN_6X`	0.022	0.045	0.090	0.179	0.360
`GAIN_9X`	0.015	0.030	0.059	0.119	0.239
`GAIN_18X`	0.007	0.015	0.029	0.059	0.117

Parameters:: green_count (int) – Raw green channel value from rgb_ir.
Returns:: Illuminance in lux.
Return type:: float

property led_current: int

The IR LED drive current used during proximity measurements.

Must be a LedCurrent value:

LedCurrent.MA_10 10 mA
LedCurrent.MA_25 25 mA

property led_frequency: int

The IR LED pulse modulation frequency used during proximity measurements.

Must be a LedFrequency value:

LedFrequency.KHZ_60
LedFrequency.KHZ_70
LedFrequency.KHZ_80
LedFrequency.KHZ_90
LedFrequency.KHZ_100

led_pulses: number of LED pulses emitted per proximity measurement

property light_gain: int

The analogue gain applied to all light sensor channels.

Must be a LightGain value:

LightGain.GAIN_1X
LightGain.GAIN_3X
LightGain.GAIN_6X
LightGain.GAIN_9X
LightGain.GAIN_18X

property light_interrupt_channel: int

The light sensor channel compared against the interrupt thresholds.

Must be a LightInterruptChannel value:

LightInterruptChannel.IR
LightInterruptChannel.GREEN
LightInterruptChannel.RED
LightInterruptChannel.BLUE

light_interrupt_enabled: Enable or disable the light sensor interrupt

property light_measurement_rate: int

How frequently the light sensor takes a reading.

Must be a LightMeasurementRate value:

LightMeasurementRate.RATE_25MS
LightMeasurementRate.RATE_50MS
LightMeasurementRate.RATE_100MS (default)
LightMeasurementRate.RATE_200MS
LightMeasurementRate.RATE_500MS
LightMeasurementRate.RATE_1000MS
LightMeasurementRate.RATE_2000MS

property light_persistence: int

Number of consecutive out-of-threshold light readings before the interrupt flag is asserted.

Valid range is 0–15.

property light_resolution: int

The ADC resolution of the light sensor channels.

Must be a LightResolution value:

LightResolution.RES_20BIT 20-bit, 400 ms conversion
LightResolution.RES_19BIT 19-bit, 200 ms conversion
LightResolution.RES_18BIT 18-bit, 100 ms conversion
LightResolution.RES_17BIT 17-bit, 50 ms conversion
LightResolution.RES_16BIT 16-bit, 25 ms conversion
LightResolution.RES_13BIT 13-bit, 3.125 ms conversion

light_sensor_enabled: Enable or disable the light sensor

light_sleep_after_interrupt: Disable the light sensor after interrupt. You must also read main_status after the interrupt for the sleep to take effect. Once asleep, the sensor can be re-enabled with light_sensor_enabled

light_threshold_high: Light threshold high 20 bits

light_threshold_low: Light threshold low 20 bits

property light_variance: int

The count variance required to trigger a light interrupt when light_variance_mode is enabled.

Must be a LightVariance value:

LightVariance.VAR_8
LightVariance.VAR_16
LightVariance.VAR_32
LightVariance.VAR_64
LightVariance.VAR_128
LightVariance.VAR_256
LightVariance.VAR_512
LightVariance.VAR_1024

light_variance_mode: Variance mode (True) vs threshold mode (False) for the light interrupt.

property main_status: Tuple[bool, bool, bool, bool, bool, bool]

Read all status flags from the MAIN_STATUS register in a single I2C transaction. Main status must be read after an interrupt is triggered to reset the interrupt.

Warning

Reading this register clears all status bits on the device.

Returns a tuple of six booleans: (proximity_data_ready, proximity_interrupt, proximity_logic, light_data_ready, light_interrupt, power_on_reset)

proximity_data_ready new proximity data is available
proximity_interrupt proximity interrupt has been triggered
proximity_logic current state of the proximity logic signal
light_data_ready new light sensor data is available
light_interrupt light sensor interrupt has been triggered
power_on_reset a power-on reset has occurred since last read

property proximity: int

The current proximity sensor reading as an 11-bit count (0–2047).

Each time this property is read the overflow flag is captured and can be checked immediately afterward via proximity_read_overflow.

proximity_analog_cancellation: Analog proximity cancellation level 5 bits

proximity_cancellation: Digital proximity cancellation level 11 bits

proximity_interrupt_enabled: Enable or disable the proximity interrupt. You must also read main_status after the interrupt is triggered to reset it.

property proximity_measurement_rate: int

How frequently the proximity sensor takes a reading.

Must be a ProximityMeasurementRate value:

ProximityMeasurementRate.RATE_6MS 6.25 ms
ProximityMeasurementRate.RATE_12MS 12.5 ms
ProximityMeasurementRate.RATE_25MS 25 ms
ProximityMeasurementRate.RATE_50MS 50 ms
ProximityMeasurementRate.RATE_100MS 100 ms (default)
ProximityMeasurementRate.RATE_200MS 200 ms
ProximityMeasurementRate.RATE_400MS 400 ms

Note

CircuitPython makes no guarantee about realtime behavior, the faster measurement rates may take longer than indicated.

property proximity_persistence: int

Number of consecutive out-of-threshold proximity readings before the interrupt flag is asserted.

Valid range is 0–15.

property proximity_read_overflow: bool: True if the proximity sensor was saturated during the last read of proximity. Updated on every proximity read; read-only.

property proximity_resolution: int

The ADC resolution of the proximity sensor.

Must be a ProximityResolution value:

ProximityResolution.RES_8BIT (hardware default)
ProximityResolution.RES_9BIT
ProximityResolution.RES_10BIT
ProximityResolution.RES_11BIT

proximity_sensor_enabled: Enable or disable the proximity sensor

proximity_sleep_after_interrupt: Disable the proximity sensor after interrupt. You must also read main_status after the interrupt for the sleep to take effect. Once asleep, the sensor can be re-enabled with proximity_sensor_enabled

proximity_threshold_high: Proximity threshold high 11 bits

proximity_threshold_low: Proximity threshold low 11 bits

reset(): Software reset the APDS9999

property rgb: Tuple[int, int, int]

The RGB light sensor channels as a tuple (red, green, blue) mapped to the range 0-255. For full 20bit resolution set light_resolution to LightResolution.RES_20BIT and use rgb_ir instead of rgb`

Returns:: (red, gree, blue)

property rgb_ir: Tuple[int, int, int, int]

All four light sensor channels as a tuple (red, green, blue, ir).

Each value is up to 20-bit count (0–1048575) read in a single 12-byte burst starting at the IR data register. See light_resolution for bit depth setting, lower resolution will result in lower maximum values.

rgb_mode: Enable or disable RGB mode. True is RGB mode, False is ALS mode

class adafruit_apds9999.CV

Constant value class helper for enums.

classmethod get_name(value: int) → str: Get the name for a given value.

classmethod is_valid(value: int) → bool: Validate that a given value is a member.

class adafruit_apds9999.LedCurrent

LED drive current settings for the PS_VCSEL register (0x01), bits 2:0.

Controls the IR LED current used during proximity measurements.

Setting	Current
`LedCurrent.MA_10`	10 mA
`LedCurrent.MA_25`	25 mA

class adafruit_apds9999.LedFrequency

LED pulse frequency settings for the PS_VCSEL register (0x01), bits 6:4.

Controls the modulation frequency of the IR LED pulses used during proximity measurements.

Setting	Frequency
`LedFrequency.KHZ_60`	60 kHz
`LedFrequency.KHZ_70`	70 kHz
`LedFrequency.KHZ_80`	80 kHz
`LedFrequency.KHZ_90`	90 kHz
`LedFrequency.KHZ_100`	100 kHz

class adafruit_apds9999.LightGain

Light sensor gain settings for the LS_GAIN register (0x05).

Controls the analogue gain applied to the light sensor channels.

Setting	Gain
`LightGain.GAIN_1X`	1x gain
`LightGain.GAIN_3X`	3x gain
`LightGain.GAIN_6X`	6x gain
`LightGain.GAIN_9X`	9x gain
`LightGain.GAIN_18X`	18x gain

class adafruit_apds9999.LightInterruptChannel

Light sensor interrupt channel settings for the INT_CFG register (0x19), bits 5:4.

Selects which light sensor channel is compared against the interrupt thresholds.

Setting	Channel
`LightInterruptChannel.IR`	IR channel
`LightInterruptChannel.GREEN`	Green channel
`LightInterruptChannel.RED`	Red channel
`LightInterruptChannel.BLUE`	Blue channel

class adafruit_apds9999.LightMeasurementRate

Light sensor measurement rate settings for the LS_MEAS_RATE register (0x04), bits 2:0.

Controls how frequently the light sensor takes a reading. The measurement rate should be set equal to or slower than the resolution’s conversion time to avoid reading stale data.

Setting	Rate
`LightMeasurementRate.RATE_25MS`	25 ms
`LightMeasurementRate.RATE_50MS`	50 ms
`LightMeasurementRate.RATE_100MS`	100 ms (default)
`LightMeasurementRate.RATE_200MS`	200 ms
`LightMeasurementRate.RATE_500MS`	500 ms
`LightMeasurementRate.RATE_1000MS`	1000 ms
`LightMeasurementRate.RATE_2000MS`	2000 ms

class adafruit_apds9999.LightResolution

Light sensor ADC resolution settings for the LS_MEAS_RATE register (0x04), bits 6:4.

Higher resolution increases accuracy but also increases conversion time.

Setting	Resolution	Conversion time
`LightResolution.RES_20BIT`	20-bit	400 ms
`LightResolution.RES_19BIT`	19-bit	200 ms
`LightResolution.RES_18BIT`	18-bit	100 ms
`LightResolution.RES_17BIT`	17-bit	50 ms
`LightResolution.RES_16BIT`	16-bit	25 ms
`LightResolution.RES_13BIT`	13-bit	3.125 ms

class adafruit_apds9999.LightVariance

Light sensor variance threshold settings for the LS_THRES_VAR register (0x27), bits 2:0.

Sets the count variance required to trigger a light interrupt when light_variance_mode is enabled.

Setting	Variance count
`LightVariance.VAR_8`	8
`LightVariance.VAR_16`	16
`LightVariance.VAR_32`	32
`LightVariance.VAR_64`	64
`LightVariance.VAR_128`	128
`LightVariance.VAR_256`	256
`LightVariance.VAR_512`	512
`LightVariance.VAR_1024`	1024

class adafruit_apds9999.ProximityMeasurementRate

Proximity sensor measurement rate settings for the PS_MEAS_RATE register (0x03), bits 2:0.

Controls how frequently the proximity sensor takes a reading.

Note

CircuitPython makes no guarantee about realtime behavior, the faster measurement rates may take longer than indicated.

Setting	Rate
`ProximityMeasurementRate.RATE_6MS`	6.25 ms
`ProximityMeasurementRate.RATE_12MS`	12.5 ms
`ProximityMeasurementRate.RATE_25MS`	25 ms
`ProximityMeasurementRate.RATE_50MS`	50 ms
`ProximityMeasurementRate.RATE_100MS`	100 ms (default)
`ProximityMeasurementRate.RATE_200MS`	200 ms
`ProximityMeasurementRate.RATE_400MS`	400 ms

class adafruit_apds9999.ProximityResolution

Proximity sensor ADC resolution settings for the PS_MEAS_RATE register (0x03), bits 4:3.

Higher resolution increases accuracy at the cost of a longer conversion time.

Setting	Resolution
`ProximityResolution.RES_8BIT`	8-bit
`ProximityResolution.RES_9BIT`	9-bit
`ProximityResolution.RES_10BIT`	10-bit
`ProximityResolution.RES_11BIT`	11-bit

API Reference

adafruit_apds9999

Implementation Notes

`adafruit_apds9999`