HowTo: ESPEasy – Connect the APDS-9960 gesture sensor to the ESP8266 / ESP32 and read its values

The APDS-9960 is a sensor that can be connected to a microcontroller such as the ESP8266 via the I2C bus.

With the help of the sensor it is possible to recognize simple gestures, to measure the brightness, the distance of an object to the sensor and the color of the light hitting the sensor.

The integration in ESPEasy is very easy thanks to the appropriate plug-in.

The steps necessary to integrate the APDS-9960 into your ESPEasy instance are described in the following article.

Safety instructions

I know the following hints are always a bit annoying and seem unnecessary. But unfortunately, many people who knew it "better" from carelessness lost their eyes, fingers or other things or hurt themselves. In comparison, a loss of data is almost not worth mentioning, but even these can be really annoying. Therefore, please take five minutes to read the safety instructions. Even the coolest project is worth no injury or other annoyance.

Affiliate links / advertising links

The links to online stores listed here are so-called affiliate links. If you click on such an affiliate link and store via this link, receives a commission from the online store or provider concerned. The price doesn't change for you. If you do your purchases via these links, you will support in being able to offer further useful projects in the future. 🙂


Helpful Articles:
You can find additional tips on ESPEasy in the following articles.

Required tools:

Required material:

Connect the APDS-9960 to the ESP8266

The APDS-9960 is connected to the ESP8266 or Wemos D1 Mini via the I2C bus.

If the I2C bus is configured as standard, you can use the circuit diagram shown as a guide.

Configuration of the APDS-9960 in ESPEasy

So that the APDS-9960 can be configured in ESPEasy, the ESPEasy firmware should already be installed and accessible on the ESP8266 or ESP32. You can find information on this in the article ESPEasy - Compiling, flashing and configuring WiFi access data.

First open the configuration website of your ESP8266 programmed with ESPEasy by entering its IP address in your web browser. Information on how you can find out the IP address is also summarized in the article Show / find out the IP address of the devices in the network.

As soon as you have opened the configuration website, you have to switch to the "Devices" tab. To do this, click on the "Devices" button.

In the "Devices" tab you now have to click on the "Add" button in one of the empty lines.

You will then be automatically redirected to the view shown and ...

... you can choose here which device you want to create.

Select the entry

  • Gesture – APDS9960 [DEVELOPMENT]

If the entry you are looking for is not visible to you, the plug-in is not included in your ESPEasy installation. A precompiled binary which also contains this plugin can be found under the following link.

This will redirect you to an overview page.

Here you can make all settings regarding the APDS-9960.

If you have used the circuit diagram shown above, you can use the settings shown.

It is important that you tick the box "Force Slow I2C Speed".

You also have to set in the "Plugin Mode" section whether the sensor should measure the gestures, approach and brightness values or the RGB color values of the incident light.

For RGB color measurement, the APDS-9960 must be configured as shown on the left.

To measure the gesture, approximation and brightness values, however, the APDS-9960 must be configured as shown here.

View of the other settings in the mode for measuring the gesture, approximation and brightness values.

Click on "Submit" to apply the settings.

View of the other settings in the mode for measuring the RGB color measurement

Click on "Submit" to apply the settings.

Display the measured values of the APDS-9960

After you have configured the APDS-9960 you can test it directly.

In the overview of the configured devices, the measured values can be seen in the line of the APDS-9960 on the right-hand side.

These are updated every 60 seconds at the latest. This interval can be set in the configuration of the APDS-9960 in the section "Interval".

If you have previously configured the APDS-9960 to measure the RGB color values, the view looks like the one shown on the left.

Use the brightness value of the APDS-9960 with the help of rules

If you use the APDS-9960 in the mode for measuring the gesture, approximation and brightness values, you can also use the measured brightness value to, for example, automatically adjust the brightness of a lamp to the ambient brightness. This is also useful for adjusting the brightness of the display, as the display is not too bright when the ambient brightness is dark and not too dark when the ambient brightness is bright.

An example of the automatic use of the brightness value measured by the APDS-9960 can be found in the following rules. The example shown means that the brightness of the LEDs which are controlled by the pxlBlck plugin is automatically adapted to the ambient brightness.

On gesture#Light do pbbr,0,[gesture#Light],1,1,15, endon

Send sensor data via MQTT

You can now also send the collected sensor data to your SmartHome via MQTT and process it there if necessary. What you have to configure is described in the following article.

Additional sensors for connection to the ESP8266 / ESP32

You can find an overview of other articles for connecting sensors and actuators to ESPEasy in the following category.

Have fun with the project

I hope everything worked as described. If not or you have any other questions or suggestions, please let me know in the comments. Also, ideas for new projects are always welcome. 🙂

P.S. Many of these projects - especially the hardware projects - cost a lot of time and money. Of course I do this because I enjoy it, but if you appreciate that I share this information with you, I would be happy about a small donation to the coffee box. 🙂

Buy Me a Coffee at   

Kommentar hinterlassen

Your email address will not be published. Erforderliche Felder sind mit * markiert