Ambient Light - Gesture Module

Last updated 12 days ago

This documentation includes hardware info, installation guidelines and sample code for your hardware.

Overall Info

Turta ALS & Gesture module carries Broadcom APDS-9960 multifunctional sensor which is capable of ambient light and RGB light sensing, proximity sensing, and gesture detection.

Illustration

Top
Bottom

Module Connections

  • I2C: SCL and SDA.

  • INT: INT.

  • POWER: +3.3V and GND.

Specifications

APDS-9960's technical specifications are as follows:

  • IR LED Peak Wavelength: 950nm.

  • IR LED Spectrum Width: 30nm.

  • UV and IR Blocking filters.

  • 32 Dataset storage FIFO for gesture sensing.

Prerequisites

To get maximum performance from your hardware, please make sure you'll meet the following requirements.

Hardware

ALS & Gesture Module is an add-in board for Turta Modular System. You'll need a compatible host device for your module. The following devices support ALS & Gesture Module:

  • Turta IoT Node - ESP32

Software

For ESP32 based systems, we're currently supporting Arduino core. Please make sure you've installed the following:

  • Arduino IDE.

  • ESP32 Hardware libraries for the Arduino IDE.

  • Python for the compilation of Arduino projects.

  • Drivers for your host device, e.g., USB Virtual Serial Port driver.

Installation

You'll need to install a library to make Arduino IDE support the module. This library includes drivers for the APDS-9960 and sample code for you to jumpstart your project.

Libraries

Please download the library archive from https://github.com/Turta-io/Modular

Then, copy its contents to your Arduino Libraries folder.

You can find the Arduino Libraries folder inside your Arduino sketch directory. It is generally located inside the My Documents folder.

Samples

The library comes with included samples. There is no need to download additional files for the examples.

Source Code

The hardware, its drivers and the sample code are open source. You can use them under the terms of the MIT license. Please feel free to customize and prototype them for your projects.

Arduino Library

Turta_ALSGesture_Module library is responsible for reading sensor data.

To use the library on Arduino IDE, add the following #include statement to the top of your sketch.

#include <Turta_ALSGesture_Module.h>

Then, create an instance of the Turta_ALSGesture_Module class.

Turta_ALSGesture_Module als

Now you're ready to access the library by calling the als instance.

Initialization

To initialize the module, call the begin method.

begin()

This method configures the I2C bus and INT pin to read sensor data.

Basic Members

Read Ambient Light

Returns the ambient light value.

int readAmbientLight()
  • Parameters

    • None

  • Returns

    • Int: Ambient light value

Read Ambient and RGB Light

Returns the ambient and RGB light.

void readARGBLight(int a, int r, int g, int b)
  • Parameters

    • Int: a out

    • Int: r out

    • Int: g out

    • Int: b out

  • Returns

    • None

Read Proximity

Returns the raw proximity value.

short readProximity()
  • Parameters

    • None

  • Returns

    • Short: Proximity value

Examples

You can open the example from Arduino IDE > File > Examples > Examples from Custom Libraries > Turta ALS & Gesture Module. There are two examples of this sensor.

ARGB

This application demonstrates reading ambient light and RGB light values from the sensor.

To run the example:

  1. Open the IoT_Node_ALSGesture_ARGB sketch from the examples menu.

  2. Select Turta IoT Node from the Tools > Board menu.

  3. Select your device's COM port from Tools > Port menu.

  4. Open Serial Monitor from Tools > Serial Monitor.

  5. Select 115.200 baud from the Serial Monitor's status bar.

  6. Upload the code to your device.

Sample Code

IoT_Node_ALSGesture_ARGB.ino
#include <Turta_ALSGesture_Module.h>
// Create ALS Gesture Sensor instance.
Turta_ALSGesture_Module als;
void setup() {
// Initialize ALS Gesture Sensor.
als.begin();
// Configure serial port.
Serial.begin(115200);
delay(200);
}
void loop() {
// Read ambient light.
int resultA = als.readAmbientLight();
Serial.print("Ambient light: ");
Serial.println(resultA);
// Read ARGB light.
// A: Ambient, R: Red, G: Green, B: Blue light.
int a, r, g, b;
als.readARGBLight(a, r, g, b);
Serial.print("A: ");
Serial.print(a);
Serial.print(", R: ");
Serial.print(r);
Serial.print(", G: ");
Serial.print(g);
Serial.print(", B: ");
Serial.println(b);
// Print an empty line.
Serial.println("");
// Delay 1000ms = 1 seconds.
delay(1000);
}

Result

After the application is uploaded to the device, it writes ambient light and RGB light values to the Serial Monitor. The example output should be like this:

Ambient light: 156
A: 156, R: 52, G: 57, B: 51

The application runs forever until you clear it from memory.

Proximity

This application demonstrates reading proximity data from the sensor.

To run the example:

  1. Open the IoT_Node_ALSGesture_Proximity sketch from the examples menu.

  2. Select Turta IoT Node from the Tools > Board menu.

  3. Select your device's COM port from Tools > Port menu.

  4. Open Serial Monitor from Tools > Serial Monitor.

  5. Select 115.200 baud from the Serial Monitor's status bar.

  6. Upload the code to your device.

Sample Code

IoT_Node_ALSGesture_Proximity.ino
#include <Turta_ALSGesture_Module.h>
// Create ALS Gesture Sensor instance.
Turta_ALSGesture_Module als;
void setup() {
// Initialize ALS Gesture Sensor.
als.begin();
// Configure serial port.
Serial.begin(115200);
delay(200);
}
void loop() {
// Read proximity.
short resultP = als.readProximity();
Serial.print("Proximity: ");
Serial.println(resultP);
// Print an empty line.
Serial.println("");
// Delay 1000ms = 1 seconds.
delay(1000);
}

Result

After the application is uploaded to the device, it writes proximity data to the Serial Monitor. The example output should be like this:

Proximity: 123

The application runs forever until you clear it from memory.

Troubleshooting

If you're experiencing difficulties while working with your device, please try the following steps.

Problem: You're reading NaN instead of sensor data. Cause: The host device does not communicate with the sensor over the I2C protocol. There is a software bug on the ESP32 Arduino hardware library which prevents I2C communication. Solution: Please update the ESP32 hardware library.