apds9960 — Proximity, Gesture, and Color Sensor Driver

This module provides a driver for the Broadcom/Avago APDS9960 digital proximity, ambient-light, RGB color, and gesture sensor over I2C. The driver exposes per-feature enable/disable controls, raw channel reads (clear, R, G, B, proximity), and a software gesture-decoding state machine that classifies swipe up/down/left/right and near/far gestures from the on-chip 4-photodiode FIFO.

Example usage:

import time
from machine import I2C, Pin
from apds9960 import uAPDS9960 as APDS9960

bus = I2C(1, scl=Pin("P15"), sda=Pin("P14"))
sensor = APDS9960(bus)

sensor.enableLightSensor()
sensor.enableProximitySensor()

while True:
    r = sensor.readRedLight()
    g = sensor.readGreenLight()
    b = sensor.readBlueLight()
    c = sensor.readAmbientLight()
    p = sensor.readProximity()
    print(r, g, b, c, p)
    time.sleep_ms(100)

Classes

class apds9960.APDS9960(bus: machine.I2C, address: int = 0x39, valid_id: list = [0xAB, 0x9C, 0xA8, -0x55])

Construct an APDS9960 driver instance.

• bus is a configured I2C bus object used to communicate with the sensor. The base class issues SMBus-style read_byte_data, write_byte_data, and read_i2c_block_data calls; for MicroPython’s machine.I2C use uAPDS9960 instead.

• address is the 7-bit I2C address of the device. Defaults to APDS9960_I2C_ADDR (0x39).

• valid_id is a list of acceptable values returned by the chip’s ID register. Defaults to APDS9960_DEV_ID.

The constructor reads the device ID and raises ADPS9960InvalidDevId if it is not in valid_id. It then disables every feature, programs the default ATIME/WTIME/PPULSE values, and applies the default LED drive, proximity gain, ALS gain, proximity thresholds, ambient-light thresholds, persistence, and gesture-engine configuration (entry/exit thresholds, GCONF1, gesture gain, gesture LED drive, gesture wait time, gesture offsets, GPULSE, GCONF3, and gesture interrupt enable).

Mode and power control

getMode() → int

Return the raw value of the ENABLE register, encoding which features are currently enabled (power, ALS, proximity, wait, ALS interrupt, proximity interrupt, gesture).

setMode(mode: int, enable: bool = True) → None

Enable or disable an individual feature in the ENABLE register. mode must be one of the APDS9960_MODE_* values (APDS9960_MODE_POWER ..\ APDS9960_MODE_ALL). When mode is APDS9960_MODE_ALL, all bits are turned on or off at once. Raises ADPS9960InvalidMode for out-of-range values.

enablePower() → None

Power the APDS9960 on (sets the PON bit in ENABLE).

disablePower() → None

Power the APDS9960 off (clears the PON bit in ENABLE).

Ambient light / RGB sensor

enableLightSensor(interrupts: bool = True) → None

Restore the default ALS gain, configure the ALS interrupt enable bit, power the device on, and enable the ambient-light/color engine.

disableLightSensor() → None

Disable the ALS interrupt and stop the ambient-light/color engine.

readAmbientLight() → int

Read the clear-channel ambient-light level as a 16-bit unsigned value.

readRedLight() → int

Read the red-channel level as a 16-bit unsigned value.

readGreenLight() → int

Read the green-channel level as a 16-bit unsigned value.

readBlueLight() → int

Read the blue-channel level as a 16-bit unsigned value.

Proximity sensor

enableProximitySensor(interrupts: bool = True) → None

Restore the default proximity gain and LED drive, configure the proximity interrupt enable bit, power the device on, and enable the proximity engine.

disableProximitySensor() → None

Disable the proximity interrupt and stop the proximity engine.

readProximity() → int

Read the proximity level as an 8-bit unsigned value.

Gesture engine

enableGestureSensor(interrupts: bool = True) → None

Reset the gesture state, set WTIME and the gesture pulse count, boost the LED to 300%, configure the gesture interrupt enable bit, enter the gesture state machine, power the device on, and enable wait, proximity, and gesture modes.

disableGestureSensor() → None

Reset the gesture state, disable the gesture interrupt and state machine, and stop the gesture engine.

isGestureAvailable() → bool

Return True if the GVALID bit of the gesture status register is set, indicating that gesture FIFO data is ready to be read.

readGesture() → int

Drain the gesture FIFO, run the on-board gesture decoder, and return one of the APDS9960_DIR_* direction constants. Returns APDS9960_DIR_NONE if the engine is not running, no valid data is available, or the data did not resolve to a recognized gesture.

resetGestureParameters() → None

Clear the internal gesture FIFO buffer, deltas, counts, near/far counters, state, and last-decoded motion.

processGestureData() → bool

Process the raw U/D/L/R FIFO samples currently buffered to update the U/D and L/R deltas and the near/far counters. Returns True if a near or far event was detected, False otherwise.

decodeGesture() → bool

Convert the current U/D and L/R counts and accumulated deltas into a direction stored in the internal gesture_motion_ field. Returns True when a direction is recognized, False otherwise.

Proximity thresholds

getProxIntLowThresh() → int

Return the low proximity-interrupt threshold (PILT register).

setProxIntLowThresh(threshold: int) → None

Set the low proximity-interrupt threshold.

getProxIntHighThresh() → int

Return the high proximity-interrupt threshold (PIHT register).

setProxIntHighThresh(threshold: int) → None

Set the high proximity-interrupt threshold.

getProximityIntLowThreshold() → int

Alias for getProxIntLowThresh().

setProximityIntLowThreshold(threshold: int) → None

Alias for setProxIntLowThresh().

getProximityIntHighThreshold() → int

Alias for getProxIntHighThresh().

setProximityIntHighThreshold(threshold: int) → None

Alias for setProxIntHighThresh().

LED drive, gain, and boost

getLEDDrive() → int

Return the LED drive strength used for proximity and ALS. Encoded as one of the APDS9960_LED_DRIVE_* values (0 = 100 mA, 1 = 50 mA, 2 = 25 mA, 3 = 12.5 mA).

setLEDDrive(drive: int) → None

Set the LED drive strength used for proximity and ALS. drive is one of the APDS9960_LED_DRIVE_* values.

getProximityGain() → int

Return the proximity-receiver gain. Encoded as one of the APDS9960_PGAIN_* values (0 = 1x, 1 = 2x, 2 = 4x, 3 = 8x).

setProximityGain(drive: int) → None

Set the proximity-receiver gain. drive is one of the APDS9960_PGAIN_* values.

getAmbientLightGain() → int

Return the ambient-light-sensor gain. Encoded as one of the APDS9960_AGAIN_* values (0 = 1x, 1 = 4x, 2 = 16x, 3 = 64x).

setAmbientLightGain(drive: int) → None

Set the ambient-light-sensor gain. drive is one of the APDS9960_AGAIN_* values.

getLEDBoost() → int

Return the LED current boost. Encoded as one of the APDS9960_LED_BOOST_* values (0 = 100%, 1 = 150%, 2 = 200%, 3 = 300%).

setLEDBoost(boost: int) → None

Set the LED current boost. boost is one of the APDS9960_LED_BOOST_* values.

Proximity gain compensation and photodiode mask

getProxGainCompEnable() → bool

Return True if proximity gain compensation is enabled.

setProxGainCompEnable(enable: bool) → None

Enable or disable proximity gain compensation.

getProxPhotoMask() → int

Return the 4-bit mask of disabled proximity photodiodes. Bits map as 3=UP, 2=DOWN, 1=LEFT, 0=RIGHT; 1 disables a photodiode and 0 enables it.

setProxPhotoMask(mask: int) → None

Set the 4-bit mask of disabled proximity photodiodes (see encoding above).

Gesture configuration

getGestureEnterThresh() → int

Return the proximity threshold required to enter gesture mode.

setGestureEnterThresh(threshold: int) → None

Set the proximity threshold required to enter gesture mode.

getGestureExitThresh() → int

Return the proximity threshold required to exit gesture mode.

setGestureExitThresh(threshold: int) → None

Set the proximity threshold required to exit gesture mode.

getGestureGain() → int

Return the photodiode gain used during gesture mode. Encoded as one of the APDS9960_GGAIN_* values (0 = 1x, 1 = 2x, 2 = 4x, 3 = 8x).

setGestureGain(gain: int) → None

Set the photodiode gain used during gesture mode.

getGestureLEDDrive() → int

Return the LED drive current used during gesture mode. Encoded as one of the APDS9960_LED_DRIVE_* values.

setGestureLEDDrive(drive: int) → None

Set the LED drive current used during gesture mode.

getGestureWaitTime() → int

Return the low-power wait time between gesture detections. Encoded as one of the APDS9960_GWTIME_* values (0 = 0 ms .. 7 = 39.2 ms).

setGestureWaitTime(time: int) → None

Set the low-power wait time between gesture detections.

getGestureMode() → bool

Return True if the gesture state machine is currently running.

setGestureMode(enable: bool) → None

Enter or leave the gesture state machine.

Ambient-light interrupt thresholds

getLightIntLowThreshold() → int

Return the 16-bit low threshold used for the ambient-light interrupt.

setLightIntLowThreshold(threshold: int) → None

Set the 16-bit low threshold used for the ambient-light interrupt.

getLightIntHighThreshold() → int

Return the 16-bit high threshold used for the ambient-light interrupt.

setLightIntHighThreshold(threshold: int) → None

Set the 16-bit high threshold used for the ambient-light interrupt.

Interrupt enables and clears

getAmbientLightIntEnable() → bool

Return True if ambient-light interrupts are enabled.

setAmbientLightIntEnable(enable: bool) → None

Enable or disable ambient-light interrupts.

getProximityIntEnable() → bool

Return True if proximity interrupts are enabled.

setProximityIntEnable(enable: bool) → None

Enable or disable proximity interrupts.

getGestureIntEnable() → bool

Return True if gesture interrupts are enabled.

setGestureIntEnable(enable: bool) → None

Enable or disable gesture interrupts.

clearAmbientLightInt() → None

Clear a pending ambient-light interrupt.

clearProximityInt() → None

Clear a pending proximity interrupt.

class apds9960.uAPDS9960(bus: machine.I2C, address: int = 0x39, valid_id: list = [0xAB, 0x9C, 0xA8, -0x55])

MicroPython subclass of APDS9960. Identical public API, but the underlying register access uses machine.I2C-style readfrom_mem and writeto_mem calls rather than SMBus-style methods. This is the class to use on OpenMV / MicroPython targets.

Exceptions

exception apds9960.ADPS9960InvalidDevId(id: int, valid_ids: list)

Subclass of ValueError. Raised by the APDS9960 constructor when the value read from the chip’s ID register is not present in the valid_id list.

exception apds9960.ADPS9960InvalidMode(mode: int)

Subclass of ValueError. Raised by APDS9960.setMode() when the mode argument is outside the range APDS9960_MODE_POWER..\ APDS9960_MODE_ALL.

Constants

I2C address and device IDs

apds9960.APDS9960_I2C_ADDR: int

Default 7-bit I2C address of the APDS9960 (0x39).

apds9960.APDS9960_DEV_ID: list

Default list of valid device-ID register values ([0xAB, 0x9C, 0xA8, -0x55]).

Gesture tuning

apds9960.APDS9960_GESTURE_THRESHOLD_OUT: int

Minimum sample magnitude (per photodiode) used by the gesture decoder when searching for the first/last in-range FIFO samples.

apds9960.APDS9960_GESTURE_SENSITIVITY_1: int

Threshold on the accumulated U/D and L/R deltas above which the decoder commits to a swipe direction.

apds9960.APDS9960_GESTURE_SENSITIVITY_2: int

Threshold on the per-step U/D and L/R deltas under which the decoder considers a sample to be a near/far candidate rather than a swipe.

apds9960.APDS9960_TIME_FIFO_PAUSE: int

Milliseconds the gesture loop sleeps between FIFO drains.

Feature modes

These values are passed to APDS9960.setMode().

apds9960.APDS9960_MODE_POWER: int

Power-on bit (0).

apds9960.APDS9960_MODE_AMBIENT_LIGHT: int

Ambient-light/color engine enable bit (1).

apds9960.APDS9960_MODE_PROXIMITY: int

Proximity engine enable bit (2).

apds9960.APDS9960_MODE_WAIT: int

Wait-state enable bit (3).

apds9960.APDS9960_MODE_AMBIENT_LIGHT_INT: int

Ambient-light interrupt enable bit (4).

apds9960.APDS9960_MODE_PROXIMITY_INT: int

Proximity interrupt enable bit (5).

apds9960.APDS9960_MODE_GESTURE: int

Gesture engine enable bit (6).

apds9960.APDS9960_MODE_ALL: int

Sentinel value (7) telling APDS9960.setMode() to enable or disable every bit in the ENABLE register at once.

LED drive currents

apds9960.APDS9960_LED_DRIVE_100MA: int

100 mA LED drive (0).

apds9960.APDS9960_LED_DRIVE_50MA: int

50 mA LED drive (1).

apds9960.APDS9960_LED_DRIVE_25MA: int

25 mA LED drive (2).

apds9960.APDS9960_LED_DRIVE_12_5MA: int

12.5 mA LED drive (3).

Proximity gain (PGAIN)

apds9960.APDS9960_PGAIN_1X: int

1x proximity gain (0).

apds9960.APDS9960_PGAIN_2X: int

2x proximity gain (1).

apds9960.APDS9960_PGAIN_4X: int

4x proximity gain (2). Default applied by the constructor.

apds9960.APDS9960_PGAIN_8X: int

8x proximity gain (3).

Ambient-light gain (AGAIN)

apds9960.APDS9960_AGAIN_1X: int

1x ALS gain (0).

apds9960.APDS9960_AGAIN_4X: int

4x ALS gain (1). Default applied by the constructor.

apds9960.APDS9960_AGAIN_16X: int

16x ALS gain (2).

apds9960.APDS9960_AGAIN_64X: int

64x ALS gain (3).

Gesture gain (GGAIN)

apds9960.APDS9960_GGAIN_1X: int

1x gesture gain (0).

apds9960.APDS9960_GGAIN_2X: int

2x gesture gain (1).

apds9960.APDS9960_GGAIN_4X: int

4x gesture gain (2). Default applied by the constructor.

apds9960.APDS9960_GGAIN_8X: int

8x gesture gain (3).

LED boost

apds9960.APDS9960_LED_BOOST_100: int

100% LED boost (0).

apds9960.APDS9960_LED_BOOST_150: int

150% LED boost (1).

apds9960.APDS9960_LED_BOOST_200: int

200% LED boost (2).

apds9960.APDS9960_LED_BOOST_300: int

300% LED boost (3). Applied automatically by APDS9960.enableGestureSensor().

Gesture wait times

apds9960.APDS9960_GWTIME_0MS: int

0 ms (0).

apds9960.APDS9960_GWTIME_2_8MS: int

2.8 ms (1). Default applied by the constructor.

apds9960.APDS9960_GWTIME_5_6MS: int

5.6 ms (2).

apds9960.APDS9960_GWTIME_8_4MS: int

8.4 ms (3).

apds9960.APDS9960_GWTIME_14_0MS: int

14.0 ms (4).

apds9960.APDS9960_GWTIME_22_4MS: int

22.4 ms (5).

apds9960.APDS9960_GWTIME_30_8MS: int

30.8 ms (6).

apds9960.APDS9960_GWTIME_39_2MS: int

39.2 ms (7).

Gesture directions

These values are returned by APDS9960.readGesture().

apds9960.APDS9960_DIR_NONE: int

No gesture detected (0).

apds9960.APDS9960_DIR_LEFT: int

Left swipe (1).

apds9960.APDS9960_DIR_RIGHT: int

Right swipe (2).

apds9960.APDS9960_DIR_UP: int

Up swipe (3).

apds9960.APDS9960_DIR_DOWN: int

Down swipe (4).

apds9960.APDS9960_DIR_NEAR: int

Near event (5).

apds9960.APDS9960_DIR_FAR: int

Far event (6).

apds9960.APDS9960_DIR_ALL: int

Sentinel value (7) used internally to represent “any direction”.

Gesture states

Internal state values reported via the gesture state machine.

apds9960.APDS9960_STATE_NA: int

No state (0).

apds9960.APDS9960_STATE_NEAR: int

Near state detected (1).

apds9960.APDS9960_STATE_FAR: int

Far state detected (2).

apds9960.APDS9960_STATE_ALL: int

Sentinel value (3) used internally to represent “any state”.