1  
  2  Introduction
  3  ============
  4  
  5  .. image:: https://readthedocs.org/projects/adafruit-circuitpython-APDS9960/badge/?version=latest
  6  
  7      :target: https://circuitpython.readthedocs.io/projects/apds/en/latest/
  8  
  9      :alt: Documentation Status
 10  
 11  .. image :: https://img.shields.io/discord/327254708534116352.svg
 12      :target: https://discord.gg/nBQh6qu
 13      :alt: Discord
 14  
 15  The APDS9960 is a specialize chip that detects hand gestures, proximity detection
 16  and ambient light color over I2C. Its available on
 17  `Adafruit as a breakout <https://www.adafruit.com/product/3595>`_.
 18  
 19  
 20  Dependencies
 21  =============
 22  This driver depends on:
 23  
 24  * `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_
 25  
 26  Please ensure all dependencies are available on the CircuitPython filesystem.
 27  This is easily achieved by downloading
 28  `the Adafruit library and driver bundle <https://github.com/adafruit/Adafruit_CircuitPython_Bundle>`_.
 29  
 30  Usage Example
 31  =============
 32  
 33  Hardware Set-up
 34  ---------------
 35  
 36  Connect Vin to 3.3 V or 5 V power source, GND to ground, SCL and SDA to the appropriate pins.
 37  
 38  Basics
 39  ------
 40  
 41  Of course, you must import i2c bus device, board pins, and the library:
 42  
 43  .. code:: python
 44  
 45  
 46    from board import SCL, SDA, A1
 47    from adafruit_apds9960.apds9960 import APDS9960
 48    import busio
 49    import digitalio
 50  
 51  To set-up the device to gather data, initialize the I2CDevice using SCL
 52  and SDA pins.   Then initialize the library.  Optionally provide an interrupt
 53  pin for proximity detection.
 54  
 55  .. code:: python
 56  
 57    int_pin = digitalio.DigitalInOut(A1)
 58    i2c = busio.I2C(SCL, SDA)
 59    apds = APDS9960(i2c, interrupt_pin=int_pin)
 60  
 61  Gestures
 62  --------
 63  
 64  To get a gesture, see if a gesture is available first, then get the gesture Code
 65  
 66  .. code:: python
 67  
 68    gesture = apds.gesture()
 69    if gesture == 1:
 70      print("up")
 71    if gesture == 2:
 72      print("down")
 73    if gesture == 3:
 74      print("left")
 75    if gesture == 4:
 76      print("right")
 77  
 78  Color Measurement
 79  -----------------
 80  
 81  To get a color measure, enable color measures, wait for color data,
 82  then get the color data.
 83  
 84  .. code:: python
 85  
 86    apds.enable_color = True
 87  
 88    while not apds.color_data_ready:
 89        time.sleep(0.005)
 90  
 91    r, g, b, c = apds.color_data
 92    print("r: {}, g: {}, b: {}, c: {}".format(r, g, b, c))
 93  
 94  Proximity Detection
 95  ---------------------
 96  
 97  To check for a object in proximity, see if a gesture is available first, then get the gesture Code
 98  
 99  .. code:: python
100  
101    apds.enable_proximity = True
102  
103    # set the interrupt threshold to fire when proximity reading goes above 175
104    apds.proximity_interrupt_threshold = (0, 175)
105  
106    # enable the proximity interrupt
107    apds.enable_proximity_interrupt = True
108  
109    while True:
110      if not interrupt_pin.value:
111        print(apds.proximity())
112  
113        # clear the interrupt
114        apds.clear_interrupt()
115  
116  
117  API Reference
118  =============
119  
120  .. toctree::
121     :maxdepth: 2
122  
123     api
124  
125  Contributing
126  ============
127  
128  Contributions are welcome! Please read our `Code of Conduct
129  <https://github.com/adafruit/Adafruit_CircuitPython_APDS9960/blob/master/CODE_OF_CONDUCT.md>`_
130  before contributing to help this project stay welcoming.
131  
132  Building locally
133  ================
134  
135  To build this library locally you'll need to install the
136  `circuitpython-travis-build-tools <https://github.com/adafruit/circuitpython-build-tools>`_ package.
137  
138  .. code-block::shell
139  
140      python3 -m venv .env
141      source .env/bin/activate
142      pip install -r requirements.txt
143  
144  Once installed, make sure you are in the virtual environment:
145  
146  .. code-block::shell
147  
148      source .env/bin/activate
149  
150  Then run the build:
151  
152  .. code-block::shell
153  
154      circuitpython-build-bundles --filename_prefix adafruit-circuitpython-apds --library_location .