CircuitPython driver for APSD9960 Gesture breakout board
Project description
Introduction
The APDS-9960 is a specialized chip that detects hand gestures, proximity and ambient light color over I2C. Its available from Adafruit as a breakout and as a built-in sensor on several Adafruit development boards.
This 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 Dependencies
This driver depends on:
Please ensure all dependencies are available on the CircuitPython filesystem.
This is easily achieved by downloading the Adafruit library and driver bundle.
Installing from PyPI
On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally from PyPI.
To install for current user:
pip3 install adafruit-circuitpython-apds9960
To install system-wide (this may be required in some cases):
sudo pip3 install adafruit-circuitpython-apds9960
To install in a virtual environment in your current project:
mkdir project-name && cd project-name
python3 -m venv .venv
source .venv/bin/activate
pip3 install adafruit-circuitpython-apds9960
Usage Example
import board
import digitalio
from adafruit_apds9960.apds9960 import APDS9960
i2c = board.I2C()
int_pin = digitalio.DigitalInOut(board.D5)
int_pin.switch_to_input(pull=digitalio.Pull.UP)
apds = APDS9960(i2c)
apds.enable_proximity_interrupt = True
apds.proximity_interrupt_threshold = (0, 175)
apds.enable_proximity = True
while True:
if not int_pin.value:
print(apds.proximity)
apds.clear_interrupt()
Hardware Set-up
If 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, connect Vin to a 3.3 V or 5 V power source, connect GND to ground, then connect SCL and SDA to the appropriate pins.
Optionally, if you’d like to use the sensor’s interrupt pin connect INT to any available digital I/O pin.
Basics
To get started, import board and, and this library:
import board
from adafruit_apds9960.apds9960 import APDS9960
To set up the sensor to gather data, initialize the I2C bus via board.I2C() then initialize the APDS-9960 library.
i2c = board.I2C()
apds = APDS9960(i2c)
Proximity
To get a proximity result, enable the proximity engine then read the proximity value.
This will return a value between 0 and 255, with higher values indicating that something is close to the sensor.
apds.enable_proximity = True
while True:
print(apds.proximity)
Gestures
First, 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 the gesture() 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 CLUE
apds.enable_proximity = True
apds.enable_gesture = True
while True:
gesture = apds.gesture()
if gesture == 1:
print("up")
if gesture == 2:
print("down")
if gesture == 3:
print("left")
if gesture == 4:
print("right")
Color/Light Measurement
To get a color measurement, first enable the color/light engine, wait for color data to arrive, then read the color_data values.
apds.enable_color = True
while True:
while not apds.color_data_ready:
time.sleep(0.005)
r, g, b, c = apds.color_data
print("r: {}, g: {}, b: {}, c: {}".format(r, g, b, c))
Interrupt Pin
This 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 to board.PROXIMITY_LIGHT_INTERRUPT and on the Proximity Trinkey it is mapped to board.INTERRUPT.
int_pin = digitalio.DigitalInOut(board.D5)
int_pin.switch_to_input(pull=digitalio.Pull.UP)
Proximity Detection
With 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 using clear_interrupt()
apds.enable_proximity = True
# set the interrupt threshold to fire when proximity reading goes above 175
apds.proximity_interrupt_threshold = (0, 175)
# assert interrupt pin on internal proximity interrupt
apds.enable_proximity_interrupt = True
# enable the sensor's proximity engine
apds.enable_proximity = True
while True:
if not interrupt_pin.value:
print(apds.proximity)
# clear the interrupt
apds.clear_interrupt()
Initiaization Options
By 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)
Documentation
API documentation for this library can be found on Read the Docs.
For information on building library documentation, please check out this guide.
Contributing
Contributions are welcome! Please read our Code of Conduct before contributing to help this project stay welcoming.
Building locally
To build this library locally you’ll need to install the circuitpython-travis-build-tools package.
Once installed, make sure you are in the virtual environment:
Then run the build:
Sphinx documentation
Sphinx 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 -m venv .venv
source .venv/bin/activate
pip install Sphinx sphinx-rtd-theme
Now, once you have the virtual environment activated:
cd docs
sphinx-build -E -W -b html . _build/html
This will output the documentation to docs/_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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for adafruit-circuitpython-apds9960-3.1.11.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | c21703ebefb2e9141ba1f9eccc121166a5f5c80ff9f6d426d1da148981eb27ed |
|
MD5 | 1822dca7d9f327d8bbf90184d29147a3 |
|
BLAKE2b-256 | a76ec12b013151de94fd9c8a22b2dec60312a9d79127c0b8dbae706031914c87 |
Hashes for adafruit_circuitpython_apds9960-3.1.11-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 18a31130ec27eb873995ea940815278290b5108e729adf0c0ec2df7ae892855d |
|
MD5 | 522ed4bfdb6dac9170c9ca6ac59af1bc |
|
BLAKE2b-256 | a17410c519aef9420b967a41b8fece0a4d030c1669d8d54dcb8cd6e40aaffd0b |