Broadcom Avago APDS-9960 Ambient Light and RGB Color Sensing, Proximity Sensing and Gesture Detection Sensor

• Ambient Light and RGB Color Sensing

  • UV and IR blocking filters
  • Programmable gain and integration time
  • Very high sensitivity – Ideally suited for operation behind dark glass

• Proximity Sensing

  • Trimmed to provide consistent reading
  • Ambient light rejection
  • Offset compensation
  • Programmable driver for IR LED current
  • Saturation indicator bit

• Complex Gesture Sensing

  • Four separate diodes sensitive to different directions
  • Ambient light rejection
  • Offset compensation
  • Programmable driver for IR LED current
  • 32 dataset storage FIFO
  • Interrupt driven I2C communication

• I2C-bus Fast Mode Compatible Interface

  • Data Rates up to 400 kHz
  • Dedicated Interrupt Pin

• Small Package L 3.94 × W 2.36 × H 1.35 mm

• Break-out PCBs

  • ~ 2,- € at AliExpress
  • ~ 8,- $ at Adafruit

Technical Data from the manufacturer

• APDS-9960 Datasheet

Wiring breakout boards

Breakout	ESP8266
VCC/VIN	+3.3VDC
GND	GND
SCL	GPIO SCL
SDA	GPIO SDA
INT/IRQ	NC

Tasmota configuration

Compile Tasmota with #define USE_APDS9960 uncommented in user_config.h

The driver will detect the APDS-9960 automatically. The APDS-9960 chip (or breakout board) must be connected to the ESP8266 and the I2C GPIO pins must be configured:

MQTT commands

Command	Value	Description
Sensor27		Show APDS9960 gesture/RGBC mode
Sensor27	0 / off	Disable APDS9960 gesture mode/Enable RGBC mode
Sensor27	1 / on	Enable APDS9960 gesture mode/Disable RGBC mode
Sensor27	2 / on	Enable APDS9960 gesture mode/Disable RGBC mode with half gain
Sensor27	3 ...255	Set ATIME register for different integration times

Example rules

Power on light when ambient light is below 100 lux.

rule on APDS9960#Ambient<100 do power on endon on APDS9960#Ambient>110 do power off endon

Control ON/OFF, brightness and color temperature with gestures

rule on APDS9960#Long do power toggle endon on APDS9960#Up do dimmer + endon on APDS9960#Down do dimmer - endon on APDS9960#Left do ct + endon on APDS9960#Right do ct - endon

LONG:  toggle ON/OFF
UP:    increase brightness
DOWN:  decrease brightness
Left:  increase color temperature
Right: decrease color temperature

Generally available types of breakout boards

Known issues:

1. The different PCB’s on the market seem to differ quite substantially regarding to their electrical characteristics. We have at least one case report, where this led to a malfunction on an ESP8266-board within TASMOTA but in another library too. The exact technical reason can only be suspected, but it is probably related to electrical noise and/or power consumption.
   In the case from above the sensor measured an incorrect high proximity value, which resulted in repeated triggering of a „LONG“ gesture. The solution was to decrease the gain factor for proximity and gesture. Therefore the argument 2 (sensor27 2) was introduced to change this at runtime.
   
If you experience gesture sensing problems you could try this out, but if you measure proximity values <25 with nothing in front of the sensor (e.g. web interface after sensor27 0), then there is very likely another problem. It can be assumed, that the gesture sensitivity will suffer with reduced gain, so first try option 1 (=default).
   
Beside that an „as-good-as-possible“ wiring and maybe an additional capacitor over VCC and GROUND might be helpful.


2. The measurement of the light level is quite shortly described in the data sheet of the APDS9960 and the open-source-libraries use wether the ambient-light-value directly from the sensor or calculate a LUX-value from RGB. Both variants are usable and differentiate between low and strong light, but the absolute values are questionable and at the moment we have an uncalibrated sensor.

   All (known) solution use a fixed integration time, which is more or less the same as a fixed exposure time in photography. In contrast the TSL2561-library (from JOBA) uses various integration times and maybe this is possible on the APDS9960 too.
   To eventually achieve this in the future, the option to set this integration time at runtime was added. Every argument between 3 and 255 sets the ATIME-register. 
 The formula is: integration time = (256-ATIME)*2,78 ms, so with the default value of 219 we get (256-219)*2,78 = 102,86 ms. That means a smaller ATIME makes the integration time longer and more photons are captured, which might be usable for (very) low light conditions, because otherwise the sensor will saturate too early. The opposite is valid for a bigger ATIME value.
   The change of this value only makes sense for users, who wether need to change the sensitivity, if the sensor resides behind dark glass or want to contribute to the development of a new LUX-calculation in the driver. If we get enough feedback, this could lead to an improvement on the software side. Feel free to open (or search for) an issue, if you have measured the APDS9960 against other devices with different ATIME-values at different light levels. This is not a trivial task though.