Package: adafruit-circuitpython-apds9960
IntroductionThe APDS-9960 is a specialized chip that detects hand gestures, proximity
and ambient light color over I2C. Its available fromAdafruit as a breakoutand as a built-in sensor on
several Adafruit development boards.Adafruit CLUEAdafruit Feather nRF52840 SenseAdafruit Proximity TrinkeyThis driver provides easy access to proximity, gesture and color data from the APDS-9960 sensor
with a minimal footprint to allow it to work on all CircuitPython platforms.Installation and DependenciesThis driver depends on:Adafruit CircuitPythonPlease ensure all dependencies are available on the CircuitPython filesystem.This is easily achieved by downloadingthe Adafruit library and driver bundle.Installing from PyPIOn supported GNU/Linux systems like the Raspberry Pi, you can install the driver locallyfrom PyPI.To install for current user:pip3installadafruit-circuitpython-apds9960To install system-wide (this may be required in some cases):sudopip3installadafruit-circuitpython-apds9960To install in a virtual environment in your current project:mkdirproject-name&&cdproject-namepython3-mvenv.venvsource.venv/bin/activatepip3installadafruit-circuitpython-apds9960Usage Exampleimportboardimportdigitaliofromadafruit_apds9960.apds9960importAPDS9960i2c=board.I2C()int_pin=digitalio.DigitalInOut(board.D5)int_pin.switch_to_input(pull=digitalio.Pull.UP)apds=APDS9960(i2c)apds.enable_proximity_interrupt=Trueapds.proximity_interrupt_threshold=(0,175)apds.enable_proximity=TruewhileTrue:ifnotint_pin.value:print(apds.proximity)apds.clear_interrupt()Hardware Set-upIf you’re using a board with a built-in APDS-9960, no hardware setup will be required.If you’re using a breakout board via the pin header, connectVinto a 3.3 V or 5 V power source,
connectGNDto ground, then connectSCLandSDAto the appropriate pins.Optionally, if you’d like to use the sensor’s interrupt pin connectINTto any available
digital I/O pin.BasicsTo get started, importboardand, and this library:importboardfromadafruit_apds9960.apds9960importAPDS9960To set up the sensor to gather data, initialize the I2C bus viaboard.I2C()then initialize the APDS-9960 library.i2c=board.I2C()apds=APDS9960(i2c)ProximityTo get a proximity result, enable the proximity engine then read theproximityvalue.This will return a value between 0 and 255, with higher values indicating that something is close
to the sensor.apds.enable_proximity=TruewhileTrue:print(apds.proximity)GesturesFirst, enable both the proximity and gesture engines. The gesture engine relies on the proximity
engine to determine when to start itself up and, as a result, proximity readings won’t be reliable
while the gesture engine is enabled.To get a gesture, use thegesture()function to see if a gesture has been detected. If a value
greater than 0 is returned, a gesture has been detected.# Uncomment and set the rotation if depending on how your sensor is mounted.# apds.rotation = 270 # 270 for CLUEapds.enable_proximity=Trueapds.enable_gesture=TruewhileTrue:gesture=apds.gesture()ifgesture==1:print("up")ifgesture==2:print("down")ifgesture==3:print("left")ifgesture==4:print("right")Color/Light MeasurementTo get a color measurement, first enable the color/light engine, wait for color data to arrive,
then read thecolor_datavalues.apds.enable_color=TruewhileTrue:whilenotapds.color_data_ready:time.sleep(0.005)r,g,b,c=apds.color_dataprint("r:{}, g:{}, b:{}, c:{}".format(r,g,b,c))Interrupt PinThis sensor has an interrupt pin can be asserted (pulled low) if proximity is detected outside of a
specified window of values.For boards with a built-in APDS-9960 this interupt pin will already be defined. For example, on the
Clue and Feather nRF52840 Sense boards this pin is mapped toboard.PROXIMITY_LIGHT_INTERRUPTand on the Proximity Trinkey it is mapped toboard.INTERRUPT.int_pin=digitalio.DigitalInOut(board.D5)int_pin.switch_to_input(pull=digitalio.Pull.UP)Proximity DetectionWith the interrupt pin set up we can define a threshold and enable the assertion of the sensor’s
interrupt pin by the proximity engine before enabling the proximity engine itself.In this configuration, the sensor’s interrupt pin will be asserted when an object is close to the
sensor. After checking on the interrupt it can be cleared usingclear_interrupt()apds.enable_proximity=True# set the interrupt threshold to fire when proximity reading goes above 175apds.proximity_interrupt_threshold=(0,175)# assert interrupt pin on internal proximity interruptapds.enable_proximity_interrupt=True# enable the sensor's proximity engineapds.enable_proximity=TruewhileTrue:ifnotinterrupt_pin.value:print(apds.proximity)# clear the interruptapds.clear_interrupt()Initiaization OptionsBy default, when the driver is initialized, the APDS-9960 sensor’s internal settings are reset and
sensible defaults are applied to several low-level settings that should work well for most use cases.If either the “reset” or “set defaults” behaviors (or both) aren’t desired, they can be individually
disabled via init kwargs.apds=APDS9960(i2c,reset=False,set_defaults=False)DocumentationAPI documentation for this library can be found onRead the Docs.For information on building library documentation, please check outthis guide.ContributingContributions are welcome! Please read ourCode of Conductbefore contributing to help this project stay welcoming.Building locallyTo build this library locally you’ll need to install thecircuitpython-travis-build-toolspackage.Once installed, make sure you are in the virtual environment:Then run the build:Sphinx documentationSphinx is used to build the documentation based on rST files and comments in the code. First,
install dependencies (feel free to reuse the virtual environment from above):python3-mvenv.venvsource.venv/bin/activatepipinstallSphinxsphinx-rtd-themeNow, once you have the virtual environment activated:cddocssphinx-build-E-W-bhtml._build/htmlThis will output the documentation todocs/_build/html. Open the index.html in your browser to
view them. It will also (due to -W) error out on any warning like Travis will. This is a good way to
locally verify it will pass.