APDS9960
¶
Driver class for the APDS9960 board. Supports gesture, proximity, and color detection.
Author(s): Michael McWethy, Erik Hess
Implementation Notes¶
Hardware:
Adafruit APDS9960 Proximity, Light, RGB, and Gesture Sensor (Product ID: 3595)
Adafruit CLUE (Product ID: 4500)
Adafruit Feather nRF52840 Sense (Product ID: 4516)
Adafruit Proximity Trinkey (Product ID: 5022)
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
- class adafruit_apds9960.apds9960.APDS9960(i2c: busio.I2C, *, rotation: int = 0, reset: bool = True, set_defaults: bool = True)[source]¶
Provide basic driver services for the APDS9960 breakout board
- Parameters
Quickstart: Importing and using the APDS9960
Here is an example of using the
APDS9960
class. First you will need to import the libraries to use the sensorimport board from adafruit_apds9960.apds9960 import APDS9960
Once this is done you can define your
board.I2C
object and define your sensor objecti2c = board.I2C() # uses board.SCL and board.SDA apds = APDS9960(i2c)
Now you have access to the
apds.proximity_enable
andapds.proximity
attributesapds.proximity_enable = True proximity = apds.proximity
Note
There is no
address
argument because the APDS-9960 only has one address and doesn’t offer any option to configure alternative addresses.- clear_interrupt() None [source]¶
Clears all non-gesture interrupts.
This includes all of the following internal interrupts:
Proximity Interrupt (
PINT
)Proximity Saturation Interrupt (
STATUS<PGSAT>
)Color/Light Interrupt (
STATUS<AINT>
)Color/Light Clear Saturation Interrupt (
STATUS<CPSAT>
)
- property color_data: Tuple[int, int, int, int]¶
Tuple containing red, green, blue, and clear light intensity values detected by the sensor during the latest color/light engine run.
Each value is a 16-bit integer with a possible value of
0
to65535
.Caution
Will always return
(0, 0, 0, 0)
ifenable_color
is not set toTrue
.Tip
To get useful, predictable
color_data
results it is important to tunecolor_gain
andcolor_integration_time
, to accommodate different lighting conditions, sensor placements, plastic/glass transparencies, expected object reflectivity, and environmental conditions.For instance, measuring color of objects close to the sensor with bright, nearby illumination (such as the white LEDs on the Adafruit Clue) may work well with a
color_gain
of0
and acolor_integration_time
of72
.However, measuring the intensity and color temperature of ambient light through difusion glass or plastic is likely to require experimenting with a wide range of
color_gain
andcolor_integration_time
settings before useful data can be obtained.
- property color_data_ready: int¶
Color data ready flag.
Returns
0
if no new data is ready,1
if new data is ready.This flag is reset when
color_data
is read.
- property color_gain: int¶
Color/light sensor gain value.
This sets the gain multiplier for the ADC during color/light engine operations.
color_gain
Gain Multiplier
Note
0
1x
Power-on Default
1
4x
Driver Default
2
16x
3
64x
Tip
To get useful, predictable
color_data
results it is important to tune this, along withcolor_integration_time
, to accommodate different lighting conditions, sensor placements, material transparencies, expected object reflectivity, and environmental conditions.For instance, measuring color of objects close to the sensor with bright, nearby illumination (such as the white LEDs on the Adafruit CLUE) may work well with a
color_gain
of0
and acolor_integration_time
of72
or lower.However, measuring the intensity and color temperature of ambient light through difusion glass or plastic is likely to require experimenting with a wide range of integration time and gain settings before useful data can be obtained.
- property color_integration_time: int¶
Color/light sensor gain.
Represents the integration time in number of 2.78 ms cycles for the ADC during color/light engine operations. This also effectively sets the maxmium value returned for each channel by
color_data
.color_integration_time
Time
Max Count
Note
1
2.78 ms
1025
Power-on Default
10
27.8 ms
10241
37
103 ms
37889
72
200 ms
65535
256
712 ms
65535
Driver Default
- property enable: bool¶
If
True
, the sensor is enabled.If set to
False
, the sensor will enter a low-power sleep stateWhen enabled, the sensor’s state machine will run through the following steps in sequence, repeating from the top after all states are run through.
Idle State
Will only remain in this state if all three sense engines are disabled.
Proximity Engine (if enabled)
Will only run if
enable_proximity
isTrue
.Will run once, storing fresh data in the sensor’s proximity data registers. If proximity data is is lower than or exceeds the configured proximity thresholds an internal persistence is incremented on each run as well.
Gesture Engine (if enabled)
Will only run if
enable_gesture
isTrue
and if entry threshold ofproximity
is greater or equal to the gesture proximity entry threshold of 5 counts.Will continuously loop, storing new results in the sensor’s gesture FIFO buffers, until one of four conditions occur.
Exit threshold is met. (all gesture measurements <= 30 counts)
The gesture engine or sensor are disabled. (`enable_gesture` or `enable` properties are set to ``False``)
The sensor is re-initalized by the driver
The sensor is power cycled
Wait Timer (set to 0 by default)
This driver does not set or make available the
WAIT
orWLONG
registers that control this function and, on intialization, leaves the timer at its power-on default state of0
, effectively disabling this timer.
Color/Light Engine (if enabled)
Will run start if
enable_color
isTrue
.Will run once, storing fresh data in the sensor’s color data registers on each run.
Note
Waking the sensor from its sleep state takes at least 7 ms. Disabling the sensor and entering a sleep state can take as little as 2.78 ms, more typically about 25 ms, or potentially quite a bit longer depending on what engines were enabled and what state was active at the time the disable command was received.
Hint
When in a sleep state the sensor’s power usage drops to as little as 1-10 uA, compared as much as 790 uA of power usage when enabled with proximity and/or gesture engines running. While in a sleep state, the sensor will still listen for and respond to I2C communication which can lead to minor increases in power usage.
- property enable_gesture: bool¶
If
True
, the sensor’s gesture engine is enabled.Note
The gesture engine will only operate if
enable_proximity
is also set toTrue
- property enable_proximity_interrupt: bool¶
If
True
, the internal proximity interrupt asserts the sensor’s interrupt pin.Internal proximity interrupt triggering is configured via
proximity_interrupt_threshold
.Tip
Using this interrupt will require attaching the sensor’s
INT
pin to an available digital I/O with an internal or external pull-up resistor.For boards with built-in sensors the pin is likely already mapped within
board
.Board
Pin Mapping
CLUE
board.PROXIMITY_LIGHT_INTERRUPT
Feather nRF52840 Sense
board.PROXIMITY_LIGHT_INTERRUPT
Proximity Trinkey
board.INTERRUPT
- gesture() int [source]¶
Gesture sensor data.
This checks the sensor for new gesture engine results and, if they are present, retrieves and processes the results to determine what, if any, gesture can be deduced from the sensor data.
Returns a gesture code indicating the direction of the gesture. Before returning the code, the
rotation
value is used to “rotate” the result as intended.Code
Direction
0
No gesture detected
1
Up
2
Down
3
Left
4
Right
Caution
Will always return
0
ifenable_proximity
andenable_gesture
are not set toTrue
.The data returned by the sensor is a continuous stream of four proximtiy measurements constrained to up/down/left/right dimensions by using four directionally-aligned sensors. The sensor itself doesn’t include any logic to determine the gesture, leaving that work to the implementer.
This driver implements an algorithm that reliably detects simple gestures in most scenarios while remaining small and efficient enough to work within the resource constraints of as many CircuitPython boards/platforms as possible.
Tip
Detecting gestures with this driver’s algorithm requires actively, continously polling for a gesture, with as little time as possible between
gesture()
calls. Even with continous polling, however, its possible that gestures may go undetected bygesture()
calls if they occurred between or on the edges ofgesture()
method execution.Warning
If gesture data becomes available from the sensor, this driver will continuously pull in that new data and analyze it until the sensor’s gesture engine exits and the sensor’s FIFO buffers are clear. This allows for much more reliable gesture detection by comparing the “first” to the “last” detected state at the cost of blocking until the FIFOs are all clear. This will only happen if all four gesture values drop below
30
.As a result, if an object is close to the sensor when
gesture()
is called, the method will not return until it moves away.Note
The sensor itself offers a very wide variety of configuration options for tuning the gesture engine, such as the LEDs (pulse count/length, drive power), the photosensors (gain, offsets, masking), the gesture engine’s entry/exit thresholds, wait time, and more. However, this driver does not make those readily available in order to keep file size and memory footprint to a minimum, which is critical for its use on more constrained platforms.
- property proximity: int¶
Proximity sensor data.
The proximity engine returns a number between
0
and255
which represents the intensity of the reflected IR light detected from the sensor’s internal LEDs, which pulse continously during proximity engine operation.A value of
0
indicates no reflected IR light was received. This typically indicates that no object(s) were in the sensor’s line of sight and within detectable range of its IR LED pulses.A value of
255
indicates that the maximum detectable amount of reflected IR light was received. This typically indicates that an object was detected very close to the sensor.Caution
Will always return
0
ifenable_proximity
is not setTrue
.Note
The sensor itself offers a very wide variety of configuration options for tuning the proximity engine, such as the LEDs (pulse count/length, drive power) and the photosensors (gain, offsets, masking). However, this driver does not make those readily available in order to keep file size and memory footprint to a minimum, which is critical for its use on more constrained platforms.
- property proximity_interrupt_threshold: Tuple[int, int, int]¶
Tuple representing proximity engine low/high threshold and persistence, which determine when the sensor’s proximity interrupt is asserted.
Low Threshold (
PILT
)High Threshold (
PIHT
) (optional)Proximity Persistence (
PERS<PPERS>
) (optional)
The first two items are the “low threshold” and “high threshold” values. These can be set to any number between
0
and255
. If the proximity value is lower than the low threshold or higher than the high threshold for enough cycles, an interrupt will be asserted.The third item is the “persistence” value. This can be set to any value between
0
to15
. This represents the number of 2.78 ms out-of-threshold cycles to wait for before asserting the interrupt. This is basically a filter to prevent premature/false interrupts.Hint
For example, setting a low threshold of
0
and a high threshold of5
will cause the interrupt to be asserted very early when an object enters the sensor’s line of sight. Coversely, a low threshold of5
and a high threshold of255
will trigger an interrupt only if an object is removed from the sensor’s line of sight.Hint
Tuning the persistence value can be useful in some use cases but for most situations the driver’s default value of 4 should provide for stable results without much delay in interrupt triggering.
- property rotation: int¶
Clock-wise offset to apply to gesture results.
Acceptable values are
0
,90
,180
,270
.Tip
The sensor’s “top” end is the one with the larger of the two circular windows.
Some rotation examples for various boards with the APS-9960 built in:
Board
Rotation
CLUE
270
Feather nRF52840 Sense, with USB port to the left
270
Proximity Trinkey, plugged into right-side laptop USB port
270
Proximity Trinkey, plugged into left-side laptop USB port
90
colorutility
¶
Helper functions for color calculations
Author(s): Michael McWethy