It's easy to use the APDS9960 sensor with CircuitPython or Python and the Adafruit CircuitPython APDS9960 module. This module allows you to easily write Python code that reads the proximity and other readings from the sensor.
You can use this sensor with any CircuitPython microcontroller board or with a computer that has GPIO and Python thanks to Adafruit_Blinka, our CircuitPython-for-Python compatibility library.
First wire up a APDS9960 breakout to your board exactly as shown below. Here's an example of wiring a Feather M4 to the sensor with I2C:
- Board GND to sensor GND (black wire)
- Board 3V to sensor VIN (red wire)
- Board SDA to sensor SDA (blue wire)
- Board SCL to sensor SCL (yellow wire)
Or you can wire up the APDS9960 to your board exactly as shown on the previous pages for Arduino using an I2C connection. Here's an example of wiring a Feather M0 to the sensor with I2C:
Since there's dozens of Linux computers/boards you can use we will show wiring for Raspberry Pi. For other platforms, please visit the guide for CircuitPython on Linux to see whether your platform is supported.
-
Pi GND to sensor GND (black wire)
- Pi 3V3 to sensor VIN (red wire)
- Pi SDA to sensor SDA (blue wire)
-
Pi SCL to sensor SCL (yellow wire)
Next you'll need to install the Adafruit CircuitPython APDS9960 library on your CircuitPython board.
First make sure you are running the latest version of Adafruit CircuitPython for your board.
Next you'll need to install the necessary libraries to use the hardware--carefully follow the steps to find and install these libraries from Adafruit's CircuitPython library bundle. Our introduction guide has a great page on how to install the library bundle for both express and non-express boards.
Remember for non-express boards like the, you'll need to manually install the necessary libraries from the bundle:
- adafruit_apds9960
- adafruit_bus_device
- adafruit_register
You can also download the adafruit_apds9960 folder from its releases page on Github.
Before continuing make sure your board's lib folder or root filesystem has the adafruit_apds9960, adafruit_bus_device, adafruit_register folders copied over.
Next connect to the board's serial REPL so you are at the CircuitPython >>> prompt.
You'll need to install the Adafruit_Blinka library that provides the CircuitPython support in Python. This may also require enabling I2C on your platform and verifying you are running Python 3. Since each platform is a little different, and Linux changes often, please visit the CircuitPython on Linux guide to get your computer ready!
Once that's done, from your command line run the following command:
sudo pip3 install adafruit-circuitpython-apds9960
If your default Python is version 3 you may need to run 'pip' instead. Just make sure you aren't trying to use CircuitPython on Python 2.x, it isn't supported!
CircuitPython & Python Usage
To demonstrate the usage of the sensor we'll initialize it and read the proximity and more from the board's Python REPL. Run the following code to import the necessary modules to initialize the I2C bus and sensor:
import board import busio import adafruit_apds9960.apds9960 i2c = busio.I2C(board.SCL, board.SDA) sensor = adafruit_apds9960.apds9960.APDS9960(i2c)
sensor.enable_proximity = True
Then call the proximity() function to retrieve the currently sensed proximity value. This is a number from 0 to 255 where the higher the number the closer an object is to the sensor. You won't be able to translate this into an absolute value in units like inches or millimeters, you can only see how it changes relative to other values.
sensor.proximity()
Color Reading
In addition to proximity you can also measure the color of an object directly in front of the sensor. Like with proximity you must enable it first:
sensor.enable_color = True
Then read the color_data property to retrieve the red, green, blue, and clear color values as a 4-tuple of 16-bit values:
r, g, b, c = sensor.color_data
print('Red: {0}, Green: {1}, Blue: {2}, Clear: {3}'.format(r, g, b, c))
Remember these are 16-bit values that will range from 0 to 65535. A value of 0 means the minimum amount of color and a value of 65535 is the maximum amount of color.
Gesture Reading
Finally you can read simple up, down, left, right gestures that are sensed by the chip too. Again first you enable gesture sensing:
sensor.enable_gesture = True
Now you can call the gesture() function to read if a gesture was detected and what gesture it was. However you probably want to call this function over and over until it returns a non-zero value, this way you can 'catch' when a gesture happens and remember it.
Run the following code that will wait in a loop for a gesture to be detected:
gesture = sensor.gesture()
while gesture == 0:
gesture = sensor.gesture()
print('Saw gesture: {0}'.format(gesture))
Wave a finger very closely in front of the sensor and you should see the REPL return so you can print out the gesture value.
You can convert the gesture value into its meaning with these numbers:
- 0 = No gesture detected
- 1 = Up gesture detected
- 2 = Down gesture detected
- 3 = Left gesture detected
- 4 = Right gesture detected
That's all there is to using the APDS9960 with CircuitPython!
For a complete example of sensing gesture and printing the direction see the gesture.py example from the library (or see all the examples in the library for more usage). Save this as main.py on your board and view the output in the REPL. As you move a finger in front of the sensor it will print out the direction of the gesture!
# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT
import board
from adafruit_apds9960.apds9960 import APDS9960
i2c = board.I2C() # uses board.SCL and board.SDA
# i2c = board.STEMMA_I2C() # For using the built-in STEMMA QT connector on a microcontroller
apds = APDS9960(i2c)
apds.enable_proximity = True
apds.enable_gesture = True
# Uncomment and set the rotation if depending on how your sensor is mounted.
# apds.rotation = 270 # 270 for CLUE
while True:
gesture = apds.gesture()
if gesture == 0x01:
print("up")
elif gesture == 0x02:
print("down")
elif gesture == 0x03:
print("left")
elif gesture == 0x04:
print("right")
Text editor powered by tinymce.
