Arduino library · Sensors

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 nameSparkFun APDS9960 RGB and Gesture Sensor
AuthorSparkFun
Include#include <SparkFun_APDS9960.h>
Boardsevery board Mokxi compiles for but ATtiny85
In the simulatorSimulated: it runs against the part the way it does on the bench.
Parts it drivesAPDS-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.

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.

sketch.ino · Arduino Uno R3
// 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.

Try SparkFun APDS9960 RGB and Gesture Sensor without installing anything

Open the example, change the sketch, and keep your version in a free account.