Source: https://mokxi.com/libraries/sparkfun-apds9960
Updated: 2026-11-22

Libraries / Sensors

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.

Run the example in Mokxi See the calls

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.

### 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

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

- I2C Explained: Addresses, Acknowledges and Pull-Ups
- I2C Scanner for Arduino and ESP32, and Fixes

### Parts

- APDS-9960 gesture sensor

### More sensors libraries

- DHT sensor library
- DHT20
- VL53L0X
- Adafruit_VL53L0X
- HX711 Arduino Library
- MPU6050
- Adafruit MPU6050
- BME280
- arduino-sht
- Sensirion I2C SHT3x
- SHT4x
- forcedBMX280
- BlueDot BME280 Library
- Grove - Barometer Sensor BME280

Every built-in library · Open the editor

## Try SparkFun APDS9960 RGB and Gesture Sensor without installing anything

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

Start building free

Open the editor
