Proximity

The proximity sensor determines whether an object is close or far from the top of the device. This sensor is most commonly used to determine when a person is holding the device close to their head. For example, when a person is making/receiving a phone call, any touch events that occur are likely the result of the screen brushing against the user's head, and this unintentional input should be ignored. You can do this by programming your app to ignore touch events when the proximity sensor reports that something is close to the device.

A BPS event with the code SENSOR_PROXIMITY_READING is generated when a new proximity value is available.

BPS offers two functions to get information from a proximity sensor event: sensor_event_get_proximity() and sensor_event_get_proximity_normalized().

sensor_event_get_proximity() returns the distance in centimeters (cm) of the closest object to the device, which is a value between the minimum range and maximum range of the proximity sensor. On some devices, the proximity sensor can't provide an accurate distance, and returns either the range minimum value (0.0) to represent near or the range maximum value (1.0) to represent far. You can retrieve the minimum and maximum range values by using the following code:
sensor_info_t *sensorinfo;
int min_range, max_range;
                
if (sensor_info(SENSOR_TYPE_PROXIMITY, &sensorinfo) == BPS_SUCCESS)
{
  min_range = sensor_info_get_range_minimum(sensorinfo);
  max_range = sensor_info_get_range_maximum(sensorinfo);
  sensor_info_destroy(sensorinfo);
			        
  if ((min_range == 0) && (max_range == 1)
  {
    // Sensor only returns values of 0 or 1, 
    // representing near and far.
  }
}
            

sensor_event_get_proximity_normalized() returns the distance of the closest object to the device mapped to a range between 0.0 and 1.0 (near to far). The code sample below takes the value returned by this function and uses it to determine whether to handle or ignore screen events.

#include <stddef.h>
#include <bps/bps.h>
#include <bps/sensor.h>
#include <bps/screen.h>

// An (arbitrary) threshold under which we want to ignore touch events.
// Used with the normalized proximity value, this sets the threshold to
// be proximity events that fall in the lower 40% of the sensor's range.
#define FAR_THRESHOLD 0.4
#define DEVICE_IS_FAR(X) (X > FAR_THRESHOLD)

typedef struct sensor_info_t sensor_info_t;

int main(void)
{
  int event_domain;
  int min_range, max_range;
  unsigned int event_code;

  // Create a variable to store the current proximity sensor reading.
  float proximity;

  bps_initialize();

  if (sensor_is_supported(SENSOR_TYPE_PROXIMITY))
  {
    sensor_request_events(SENSOR_TYPE_PROXIMITY);
  }

  while (1)
  {
    bps_event_t *current_event = NULL;
    bps_get_event(&current_event, -1);

    event_domain = bps_event_get_domain(current_event);
    event_code = bps_event_get_code(current_event);

    if (event_domain == sensor_get_domain())
    {
      switch (event_code)
      {
        case SENSOR_PROXIMITY_READING:
        proximity = 
          sensor_event_get_proximity_normalized(current_event);
        break;

      default:
        break;
      }
    } else if ((event_domain == screen_get_domain()) && 
               (DEVICE_IS_FAR(proximity))) {
      // Handle touch events when device is not close to user.
    }
  }

  // Program cleanup
  sensor_stop_events(SENSOR_TYPE_PROXIMITY);
  bps_shutdown();

  return 0;
}                
            

Last modified: 2013-12-21

comments powered by Disqus