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
from apds9960 import uAPDS9960 as APDS9960
bus = I2C(1)
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.
busis a configured I2C bus object used to communicate with the sensor. The base class issues SMBus-styleread_byte_data,write_byte_data, andread_i2c_block_datacalls; for MicroPython’smachine.I2CuseuAPDS9960instead.addressis the 7-bit I2C address of the device. Defaults toAPDS9960_I2C_ADDR(0x39).valid_idis a list of acceptable values returned by the chip’s ID register. Defaults toAPDS9960_DEV_ID.
The constructor reads the device ID and raises
ADPS9960InvalidDevIdif it is not invalid_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.
modemust be one of theAPDS9960_MODE_*values (APDS9960_MODE_POWER..\APDS9960_MODE_ALL). WhenmodeisAPDS9960_MODE_ALL, all bits are turned on or off at once. RaisesADPS9960InvalidModefor out-of-range values.
Ambient light / RGB sensor
Proximity sensor
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
Trueif 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. ReturnsAPDS9960_DIR_NONEif 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.
Proximity thresholds
- 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.
driveis one of theAPDS9960_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.
driveis one of theAPDS9960_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.
driveis one of theAPDS9960_AGAIN_*values.
Proximity gain compensation and photodiode mask
Gesture configuration
- setGestureEnterThresh(threshold: int) None
Set the proximity threshold required to enter 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).
- getGestureLEDDrive() int
Return the LED drive current used during gesture mode. Encoded as one of the
APDS9960_LED_DRIVE_*values.
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.
Interrupt enables and clears
- 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 usesmachine.I2C-stylereadfrom_memandwriteto_memcalls 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 theAPDS9960constructor when the value read from the chip’s ID register is not present in thevalid_idlist.
- exception apds9960.ADPS9960InvalidMode(mode: int)
Subclass of
ValueError. Raised byAPDS9960.setMode()when themodeargument is outside the rangeAPDS9960_MODE_POWER..\APDS9960_MODE_ALL.
Constants
I2C address and device IDs
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.
Feature modes
These values are passed to APDS9960.setMode().
- apds9960.APDS9960_MODE_ALL: int
Sentinel value (
7) tellingAPDS9960.setMode()to enable or disable every bit in the ENABLE register at once.
LED drive currents
Proximity gain (PGAIN)
Ambient-light gain (AGAIN)
Gesture gain (GGAIN)
LED boost
- apds9960.APDS9960_LED_BOOST_300: int
300% LED boost (
3). Applied automatically byAPDS9960.enableGestureSensor().
Gesture wait times
Gesture directions
These values are returned by APDS9960.readGesture().
Gesture states
Internal state values reported via the gesture state machine.