edit this page

Modules Gesture sensor

Introduction

Smablo Gesture Shield is based on apds9960 sensor which is giving us ability to Gesture detection, Proximity detection, Digital Ambient Light Sense (ALS) and Color Sense (RGBC).

Applications

Gesture sensor can be used in applications that need gesture sensing, color sensing or ambient light sensing. Typical applications:

Gesture Detection
Color Sense
Ambient Light Sensing
Cell Phone Touch Screen Disable
Mechanical Switch Replacement

Getting started

To get started with Smablo Gesture Shield you will need :

Smablo Development Board
Smablo Gesture Shield
Smablo CPU
Smablo SDK
Visual Studio Code From Smablo development kit take Smablo CPU Shield and place it on Smablo Development board and do the same with Smablo Weather Shield just as you can see on the video below.

[plugin:youtube]()

{.force-inline} {.force-inline} {.force-inline}

When you’ve done connecting Shields you can connect Smablo Development board to your computer with USB cable.

Example programs

Smablo prepared four demo projects to show you how to use Smablo Weather Sensor. To see how to use run them open Visual Studio Code and Click file->Open folder and from your libsmablo/examples directory choose one of them just like it was shown on the videos below.

`gesture_proximity_interrupt_async`

Open gesture_proximity_interrupt_async demo code just like it was shown on the video below: Open proximity To see how the gesture_proximity_interrupt_async works compile and run the project by pressing F5 button just like on the video below: Run proximity And in the RTT Viewer window you should see proximity values if you get your hand close to the sensor.

`gesture_als_interrupt_async`

Open gesture_als_interrupt_async demo code just like it was shown on the video below:

[plugin:youtube]()

To see how the gesture_als_interrupt_async works compile and run the project by pressing F5 button just like on the video below:

[plugin:youtube]()

And in the RTT Viewer window you should see rgb color and als values.

`gesture`

Open gesture demo code just like it was shown on the video below:

[plugin:youtube]()

To see how the gesture works compile and run the project by pressing F5 button just like on the video below:

[plugin:youtube]()

And in the RTT Viewer window you should see gesture read after you swing your hand above the sensor.

Minimal code

To make your work with Smablo products easier and faster we prepared drv_apds9960 library for use with Gesture Shield. All of available functions and their descriptions can be found in drv_apds9960.h.

Initialization functions like apds9960_init() that should be used once at the beginning of your program,
Configuration functions like apds9960_configure_power() or apds9960_configure_proximity_mode() that will configure our shield, but remember it’s all they do, configure functions won’t change anything until we will use the next type of functions,
Commit functions like apds9960_commit_blocking() those functions will send all of the configurations made to shield. Only after executing this type of function you will see the change of behavior of the Gesture Shield.
The functions in this library can be divided into 3 groups and to always expect proper work of the Smablo Gesture Shield you should use them in this sequence:

The enumeration types and structures that will be required by the function are located on the top of the file, we will often come back to them to change the parameters of the on shield features.

#include "drv_apds9960.h"
#include "nrf_log.h"

//create shield instance
static apds9960_instance_t apds9960_instance=SM_APDS9960_INSTANCE_CREATE;

//this excecute every time the interrupt occur
static void proximity_handler(apds9960_instance_t * p_instance)
{
    //decode proximity value form instance
    uint8_t prox_value; 
    prox_value = apds9960_decode_proximity_data(&apds9960_instance);

    //print the value
    NRF_LOG_INFO("Proximity: %u\r\n",prox_value);
}

void example_code(void)
{
    //initialize the Shield 
    apds9960_init(&apds9960_instance, NULL);

    //create proximity feature configuration structure
    apds9960_proximity_mode_cfg_t prox_struct = APDS9960_PROXIMITY_DEFAULT;

    //change proximity parameters to suits your needs
    //turn proximity on 
    prox_struct.prox_enable = APDS9960_PROXIMITY_ON;

    //turn interrupt form proximity on 
    prox_struct.prox_interrupt = APDS9960_PROXIMITY_INTERRUPT_ON;   

    //interrupt generation after 4 consecutive proximity values are out of range
    prox_struct.prox_interrupt_rate=APDS9960_PROXIMITY_INTERRUPT_RATE_4;    

    //only values higher then 10 will generate the interrupt
    prox_struct.prox_high_tresh = 10;

    //configure instance with prox_struct structs
    apds9960_configure_proximity_mode(&apds9960_instance, &prox_struct);

    //turn the shield on 
    apds9960_configure_power(&apds9960_instance, APDS9960_POWER_ON);

    //attach interrupt to proximity handler proximity_handler with blocking type of update 
    apds9960_attach_pin_interrupt(&apds9960_instance , proximity_handler, APDS9960_INT_ACTION_UPDATE_BLOCKING);

    //Send the instance to the shield  
    apds9960_commit_blocking(&apds9960_instance);
}

Basic code snippet shows you how you should program with Smablo apds9960 library. To use Smablo drv_apds9960 library you need to include it first with #include "drv_apds9960.h". Then you need to create the instance of the shield you are using which was done with static apds9960_instance_t apds9960_instance=SM_APDS9960_INSTANCE_CREATE;.

Before configurating our shield we need to initialize it first with apds9960_init() . Then we can start configuring the shield and we do that with use of apds9960_proximity_mode_cfg_t type structure prox_struct that will hold all the default proximity parameters with help of APDS9960_PROXIMITY_DEFAULT macro.

Then we can change only those parameters that are important to us . You can see all of the parameters of proximity feature in the drv_apds9960 library. So if we want to use proximity feature and interrupt from it we need to configure those parameters .

After all necessary parameters was configured in prox_struct structure we can configure our instance with those parameters and we can do that with apds9960_configure_proximity_mode() function.

The Gesture shield to save power is by default set in low power sleep mode and to use it we need to turn the power off thus we need to use apds9960_configure_power() function.

If we want to use interrupt driven events from Smablo Gesture Shield we need to attach the interrupt to the events from shield and we do that with use of apds9960_attach_pin_interrupt() function.in the second parameter we give the user interrupt handler function which is user defined function that will be called every time the interrupt will be generated from the shield. The third parameter set the type of the proximity data.

To make actual changes to the shield we need to use apds9960_commit_blocking() function that will send the instance to the shield. In user defined handler function which in this example is called proximity_handler() we are decoding the proximity from the instance with apds9960_decode_proximity_data() function and then printing them on the screen with NRF_LOG_INFO macro.

How do I?

How to increase proximity range

#include "proximity_interrupt_demo.h"

//create shield instance
static apds9960_instance_t apds9960_instance=SM_APDS9960_INSTANCE_CREATE;

//this excecute every time the interrupt occur
static void proximity_handler(apds9960_instance_t * p_instance)
{
    //decode proximity value form instance
    uint8_t prox_value; 
    prox_value = apds9960_decode_proximity_data(&apds9960_instance);

    //print the value
    NRF_LOG_INFO("Proximity: %u\r\n",prox_value);
}

void example_code(void)
{
    //initialize the Shield 
    apds9960_init(&apds9960_instance, NULL);

    //create proximity feature configuration structure
    apds9960_proximity_mode_cfg_t prox_struct = APDS9960_PROXIMITY_DEFAULT;

    //change proximity parameters 
    //turn proximity on 
    prox_struct.prox_enable = APDS9960_PROXIMITY_ON;

    //turn interrupt form proximity on 
    prox_struct.prox_interrupt = APDS9960_PROXIMITY_INTERRUPT_ON;   

    //interrupt generation after 4 consecutive proximity values are out of range
    prox_struct.prox_interrupt_rate=APDS9960_PROXIMITY_INTERRUPT_RATE_4;    

    //only values higher then 10 will generate the interrupt
    prox_struct.prox_high_tresh = 40;
    prox_struct.prox_pulse_count =50;
    prox_struct.prox_pulse_length = APDS9960_PULSE_LENGTH_32;

    //configure instance with prox_struct structs
    apds9960_configure_proximity_mode(&apds9960_instance, &prox_struct);

    //turn the shield on 
    apds9960_configure_power(&apds9960_instance, APDS9960_POWER_ON);

    //attach interrupt to proximity handler proximity_handler with blocking type of update 
    apds9960_attach_pin_interrupt(&apds9960_instance , proximity_handler, APDS9960_INT_ACTION_UPDATE_BLOCKING);

    //Send the instance to the shield  
    apds9960_commit_blocking(&apds9960_instance);

}

The code above is mostly the same as in the minimal code snippet. The main difference is that the proximity parameters was configure that the range of the feature increases.

`apds9960` library reference

`apds9960_init`

Prototype:

void apds9960_init(apds9960_instance_t* const p_instance, apds9960_fifo_ctx_t* const p_fifo_ctx)

Function is used for initialize the shield. Use it once at the beginning of our program like in code snippet above. Function takes 2 parameters:

p_instance which is pointer to apds9960_instance_t type instance.
p_fifo_ctx type apds9960_fifo_ctx_t structure which is necessary when we want to use the asynchronous type of communication with the gesture shield. If only blocking version of the communication is needed this can bee NULL.

`apds9960_reset`

Prototype:

void apds9960_reset(apds9960_instance_t* const p_instance)

Function is used for performing a reset of the Gesture Shield to the default values. Function takes one parameter which is pointer to apds9960_instance_t t type instance.

`apds9960_configure_proximity_mode`

Prototype:

void apds9960_configure_proximity_mode(apds9960_instance_t* const p_instance, const apds9960_proximity_mode_cfg_t* apds9960_proximity_mode_cfg)

Function is used for configurating the instance of the shield with the proximity configuration structure. Function takes 2 parameters:

p_instance which is pointer to apds9960_instance_t type instance that we want to configure with apds9960_proximity_mode_cfg structure
apds9960_proximity_mode_cfg type apds9960_proximity_mode_cfg_t structure that we want to configure the instance with.

`apds9960_configure_als_mode`

Prototype:

void apds9960_configure_als_mode(apds9960_instance_t* const p_instance, const apds9960_als_mode_cfg_t* apds9960_als_mode_cfg)

Function is used for configurating the instance of the shield with the ALS configuration structure. Function takes 2 parameters:

p_instance which is pointer to apds9960_instance_t type instance that we want to configure with apds9960_als_mode_cfg structure
apds9960_als_mode_cfg type apds9960_als_mode_cfg_t structure that we want to configure the instance with.

`apds9960_configure_gesture_mode`

Prototype:

void apds9960_configure_gesture_mode(apds9960_instance_t* const p_instance, const apds9960_gesture_mode_cfg_t* apds9960_gesture_mode_cfg)

Function is used for configurating the instance of the shield with the gesture configuration structure. Function takes 2 parameters:

p_instance which is pointer to apds9960_instance_t type instance that we want to configure with apds9960_gesture_mode_cfg structure
apds9960_gesture_mode_cfg type apds9960_gesture_mode_cfg_t structure that we want to configure the instance with.

`apds9960_get_measurement_data_blocking`

Prototype:

void apds9960_get_measurement_data_blocking(apds9960_instance_t* const p_instance)

Function is used for getting the proximity, ALS and gesture measurements from the shield if those features were turned on blocking version. Function takes one parameter p_instance which is pointer to apds9960_instance_t type instance that is instance we want to put those measurement in.

`apds9960_get_measurement_data_async`

Prototype:

void apds9960_get_measurement_data_async(apds9960_instance_t* const p_instance, const apds9960_interrupt_handler_t handler)

Function is used for getting the proximity, ALS and gesture measurements from the shield if those features were turned on asynchronous version. Function takes 2 parameters:

p_instance which is pointer to apds9960_instance_t type instance that is instance we want to put those measurement in
handler type apds9960_interrupt_handler_t function which is user defined function that will execute after apds9960_get_measurement_data_async function will get all the measurements.

`apds9960_commit_blocking`

Prototype:

void apds9960_commit_blocking(apds9960_instance_t* const p_instance)

Function is used for sending the configuration we made to the shield in blocking manner. Function takes one parameter: p_instance type apds9960_instance_t which is the instance configuration we want to send to the shield .

`apds9960_attach_pin_interrupt`

Prototype:

void apds9960_attach_pin_interrupt(apds9960_instance_t* const instance, const apds9960_interrupt_handler_t handler,const apds9960_interrupt_action_t int_action)

Function is used for attaching user defined handler to the interrupt event from the Gesture shield. This function is also performing measurement to all turned on features. Function takes 3 parameters:

p_instance which is pointer to apds9960_instance_t type instance that is we want to configure
handler type apds9960_interrupt_handler_t function which is user defined handler function which will execute when interrupt will come from the Gesture Shield.
int_action type apds9960_interrupt_action_t parameter which determine what type of measurement we want from the shield. We can choose between APDS9960_INT_ACTION_UPDATE_BLOCKING and APDS9960_INT_ACTION_UPDATE_ASYNC type of measurements.

`apds9960_decode_proximity_data`

Prototype:

uint8_t apds9960_decode_proximity_data(apds9960_instance_t* const p_instance)

Function is used for decoding the proximity value from the Gesture Shield. Function takes 1 parameters: p_instance type apds9960_instance_t which is the instance we want to decode the proximity from. Function returns uint8_t value of the decoded proximity.

`apds9960_decode_colors_channel_data`

Prototype:

void apds9960_decode_colors_channel_data(apds9960_instance_t* const p_instance, apds9960_colors_state_t* const apds9960_colors_state );void apds9960_decode_colors_channel_data(apds9960_instance_t* const p_instance, apds9960_colors_state_t* const apds9960_colors_state )

Function is used for decoding colors and ALS values from the Gesture Shield. Function takes 2 parameters:

p_instance type apds9960_instance_t which is the instance we want to decode the proximity from.
apds9960_colors_state type apds9960_colors_state_t structure that we need to create before and in which the decoded values of the red, green and ALS values are decoded from the instance.

`apds9960_configure_power`

Prototype:

void apds9960_configure_power(apds9960_instance_t* const p_instance,const apds9960_pon_state_t apds9960_pon_state);

Function is used for configuring the power state of the shield. We can turn the shield on or off. Function takes 2 parameters:

p_instance type apds9960_instance_t which is the instance we want configure the power state
apds9960_pon_state type of apds9960_pon_state_t parameter which determines the state of the shield we can turn the shield on with APDS9960_POWER_ON or off with APDS9960_POWER_OFF.

`apds9960_configure_led_boost`

Prototype:

void apds9960_configure_led_boost(apds9960_instance_t* const p_instance,const apds9960_led_boost_state_t led_boost)

Function is used for configuring the power boost of the IR LED on the shield. Function takes 2 parameters:

p_instance type apds9960_instance_t which is the instance we want configure the LED boost
led_boost type apds9960_led_boost_state_t which determines the led boost state of the IR LED

`apds9960_configure_wait_time_ms`

Prototype:

void apds9960_configure_wait_time_ms(apds9960_instance_t* const p_instance, const float wait_time_ms, const apds9960_wait_timer_state_t wait_enable)

Function is used for enabling or disabling wait feature and configurating the amount of time we want to have between measurements. Function takes 3 parameters:

p_instance type apds9960_instance_t which is the instance we want enable and configure the wait feature
wait_time_ms type float which is amount of time in ms we want to wait between measurements, this parameter can take values from range (2.78- 8540)
wait_enable type apds9960_wait_timer_state_t parameters which enables or disables the wait feature

`apds9960_configure_sleep_after_interrupt`

Prototype:

void apds9960_configure_sleep_after_interrupt(apds9960_instance_t* const p_instance,const apds9960_sai_state_t sleep)

Function is used for power saving state after the interrupt occurs. Function takes 2 parameters:

p_instance type apds9960_instance_t which is the instance we want to configure sleep after interrupt feature.
sleep type apds9960_sai_state_t parameter which determines the on or off state of the feature

Advanced

6 different gesture types

Smablo Gesture Shield provides 6 different gesture recognition:

Up,
Down,
Left,
Right,
Far,
Near.

Smablo gesture recognition is done with Smablo gesture algorithm but it is possible to create your own.

Blocking and async

Apds9960 library provides functions for blocking and asynchronous measurements performing and it is recommended to use the asynchronous ones. It will makes your code more optimized and power efficient

Proximity als gesture configuration structures are recommended to use

Apds9960 library prepared for you structures and macros for every feature Gesture Shield is equipped with. For example for proximity feature it is recommended to use with apds9960_proximity_mode_cfg_t type structure. For the convenience of using this structure the APDS9960_PROXIMITY_DEFAULT macro was created. Macro sets all the parameters in apds9960_proximity_mode_cfg_t type structure to the default values so you do not have to set all of the parameters but only those necessary for your project. All of the parameters and their value are available in the drv_apds9960.h and drv_apds9960_reg.h files.

The shield can be used with protection shield to cover the Gesture Shield. More information you can find in 18 page in the datasheet.

Introduction

Applications

Getting started

Example programs

gesture_proximity_interrupt_async

gesture_als_interrupt_async

gesture

Minimal code

How do I?

How to increase proximity range

apds9960 library reference

apds9960_init

apds9960_reset

apds9960_configure_proximity_mode

apds9960_configure_als_mode

apds9960_configure_gesture_mode

apds9960_get_measurement_data_blocking

apds9960_get_measurement_data_async

apds9960_commit_blocking

apds9960_attach_pin_interrupt

apds9960_decode_proximity_data

apds9960_decode_colors_channel_data

apds9960_configure_power

apds9960_configure_led_boost

apds9960_configure_wait_time_ms

apds9960_configure_sleep_after_interrupt

Advanced

6 different gesture types

Blocking and async

`gesture_proximity_interrupt_async`

`gesture_als_interrupt_async`

`gesture`

`apds9960` library reference

`apds9960_init`

`apds9960_reset`

`apds9960_configure_proximity_mode`

`apds9960_configure_als_mode`

`apds9960_configure_gesture_mode`

`apds9960_get_measurement_data_blocking`

`apds9960_get_measurement_data_async`

`apds9960_commit_blocking`

`apds9960_attach_pin_interrupt`

`apds9960_decode_proximity_data`

`apds9960_decode_colors_channel_data`

`apds9960_configure_power`

`apds9960_configure_led_boost`

`apds9960_configure_wait_time_ms`

`apds9960_configure_sleep_after_interrupt`