SparkFun APDS9960: gestures, color and proximity
Yes. You can use the SparkFun APDS9960 RGB and Gesture Sensor library online in Mokxi with nothing to install, and the sketch runs in your browser against the simulated part (APDS-9960 gesture sensor). The example below, "Swipe lamp", runs on the Arduino Uno R3.
Built in on Mokxi: #include <SparkFun_APDS9960.h> and it builds, with nothing to install. Free, and no account needed.
What SparkFun APDS9960 RGB and Gesture Sensor does
The APDS-9960 puts several sensors behind one small window: ambient light and RGB color, proximity, and gesture sensing, with an infrared LED to light a hand. It is the chip behind many touchless switch builds. SparkFun’s library reaches every part of it over I2C at 0x39.
Each function is switched on by itself with enableLightSensor(), enableProximitySensor() or enableGestureSensor(), each taking a flag for whether it should pull the INT pin low. Gestures come from four directional photodiodes: the order in which they see a hand pass tells which way it moved. isGestureAvailable() says a gesture is waiting and readGesture() returns DIR_UP, DIR_DOWN, DIR_LEFT, DIR_RIGHT, DIR_NEAR, DIR_FAR or DIR_NONE.
The swipe lamp below powers the sensor from 3.3 V and dims an LED on pin 9 with up and down swipes, turning it off and on with left and right. In Mokxi the apds9960 part has arrow buttons that sweep a hand across it, and sliders and a C button for the room’s light. Gestures are decided by comparing which side saw the hand first and last, which is simpler than Broadcom’s full state machine, so gesture thresholds you tune there may behave differently on a real chip.
| Library Manager name | SparkFun APDS9960 RGB and Gesture Sensor |
|---|---|
| Author | SparkFun |
| Include | #include <SparkFun_APDS9960.h> |
| Boards | every board Mokxi compiles for but ATtiny85 |
| In the simulator | Simulated: it runs against the part the way it does on the bench. |
| Parts it drives | APDS-9960 gesture sensor |
Install it
It builds on every board Mokxi compiles for but ATtiny85.
In Mokxi it is built in: #include <SparkFun_APDS9960.h> and the sketch compiles, with no download, no zip and no Library Manager.
On a real board, install "SparkFun APDS9960 RGB and Gesture Sensor" by SparkFun from the Arduino IDE’s Library Manager (Sketch, Include Library, Manage Libraries), or add SparkFun APDS9960 RGB and Gesture Sensor to lib_deps in PlatformIO. Mokxi follows the calls of release 1.4.3, so a sketch written here builds there too.
What to know in the simulator: Gestures are decided by a simple first-to-last comparison, not Broadcom’s full state machine.
- ESP32-C3
- Arduino Uno
- Arduino Nano
- Arduino Mega 2560
- Arduino Leonardo
- SparkFun Pro Micro
- Arduino Micro
- ESP32-C6
- WCH CH32V003
- Raspberry Pi Pico
- Raspberry Pi Pico W
- Seeed XIAO SAMD21
- STM32
- STM32 Nucleo-F411RE
- STM32 Blue Pill
- micro:bit V2
- Arduino Uno R4
- ESP32 DevKit
- ESP32-S3-DevKitC-1
- ESP8266 NodeMCU
- Arduino Pro Mini 3.3 V
- Seeed XIAO ESP32-C3
- ESP32-C3 SuperMini
- Seeed XIAO ESP32-C6
- ESP32-DevKitC V4
- LOLIN32 Lite
- Wemos D1 R32
- Cheap Yellow Display
- TTGO T-Display
- Seeed XIAO ESP32-S3
- ESP32-S3-CAM
- Arduino Nano ESP32
- Arduino Nano RP2040 Connect
- Seeed XIAO RP2040
- Waveshare RP2040-Zero
- Arduino Uno R4 WiFi
The calls you will use
In the order a sketch meets them.
SparkFun_APDS9960 apds = SparkFun_APDS9960()
Creates the driver on the default Wire bus.
apds.init()
Checks the chip ID at 0x39 and loads the library’s default gains and LED drive. Returns false when the chip is missing.
apds.enableGestureSensor(true)
Starts the gesture engine; true also asks for an INT pulse per gesture. Polling still works with the pin left unconnected.
apds.isGestureAvailable()
True when a finished gesture is waiting to be read.
apds.readGesture()
Returns the direction as one of the DIR_ values and clears it.
switch (apds.readGesture()) {
case DIR_UP: Serial.println("UP"); break;
case DIR_DOWN: Serial.println("DOWN"); break;
default: break;
}apds.enableLightSensor(false)
Starts the light and color channels without the interrupt.
apds.readAmbientLight(ambient)
Fills a uint16_t passed by reference with the clear count and returns false on a failed read. readRedLight(), readGreenLight() and readBlueLight() work the same way.
apds.readProximity(proximity)
Fills a uint8_t from 0 to 255, larger when something is closer. Needs enableProximitySensor() first.
apds.setProximityGain(PGAIN_2X)
Changes the proximity gain; setAmbientLightGain() and setLEDDrive() adjust the light gain and the LED current.
Example: Swipe lamp
On the Arduino Uno R3. It runs in the browser exactly as printed.
// Swipe lamp: an APDS-9960 watches for a hand swiping over it, read with
// SparkFun's library, and dims an LED to match.
//
// APDS-9960 VCC -> 3.3 V GND -> GND SDA -> A4 SCL -> A5
// LED pin 9 -> 220 ohm -> LED -> GND
//
// Four photodiodes sit behind the sensor's window, one on each side, and an
// infrared LED lights the hand. A hand swiping up reaches the up diode first
// and the down one last, so the order the four light up in says which way it
// went. Swipe up for brighter, down for dimmer, left for off and right for on.
// Every two seconds it also prints the light it sees.
//
// The arrows on the sensor swipe a hand across it; the sliders and the C
// button set the room's light.
#include <Wire.h>
#include <SparkFun_APDS9960.h>
const int LAMP_PIN = 9;
SparkFun_APDS9960 apds;
int level = 128;
bool on = true;
unsigned long lastLight = 0;
void show() {
analogWrite(LAMP_PIN, on ? level : 0);
Serial.print("lamp ");
Serial.println(on ? level : 0);
}
void setup() {
Serial.begin(9600);
pinMode(LAMP_PIN, OUTPUT);
if (!apds.init()) {
Serial.println("Something went wrong during APDS-9960 init!");
while (1) {
}
}
apds.enableLightSensor(false);
apds.enableGestureSensor(true);
Serial.println("Swipe lamp ready");
show();
}
void loop() {
if (apds.isGestureAvailable()) {
switch (apds.readGesture()) {
case DIR_UP:
Serial.println("UP");
level = min(level + 64, 255);
break;
case DIR_DOWN:
Serial.println("DOWN");
level = max(level - 64, 0);
break;
case DIR_LEFT:
Serial.println("LEFT");
on = false;
break;
case DIR_RIGHT:
Serial.println("RIGHT");
on = true;
break;
default:
Serial.println("NONE");
return;
}
show();
}
if (millis() - lastLight > 2000) {
lastLight = millis();
uint16_t c, r, g, b;
apds.readAmbientLight(c);
apds.readRedLight(r);
apds.readGreenLight(g);
apds.readBlueLight(b);
Serial.print("light ");
Serial.print(c);
Serial.print(" red ");
Serial.print(r);
Serial.print(" green ");
Serial.print(g);
Serial.print(" blue ");
Serial.println(b);
}
}Open it in the editor, wired and ready to run · Swipe lamp: the project page
Common errors and how to fix them
Something went wrong during APDS-9960 init!
init() did not find the expected ID at 0x39. Check SDA, SCL and the 3.3 V supply, then run an I2C scanner to see whether the module answers at all.
readGesture() keeps returning DIR_NONE
Read only after isGestureAvailable() is true. On hardware, sweep the hand across the whole window at a steady pace a few centimeters above it; a hand that stops over the sensor gives no direction.
readProximity() is always 0
The proximity engine was never started. Call enableProximitySensor(false) once in setup(), and declare the variable as uint8_t, since the call writes into it by reference.
Questions and answers
Do I have to wire the APDS-9960 INT pin?
No. Polling isGestureAvailable() in loop(), as the swipe lamp does, works without it. INT lets a sleeping board wake on a gesture or a light threshold.
Can I read color and gestures in the same sketch?
Yes. The swipe lamp enables both and prints the clear, red, green and blue counts every two seconds between gestures.
Keep going
Learn
Try SparkFun APDS9960 RGB and Gesture Sensor without installing anything
Open the example, change the sketch, and keep your version in a free account.